Suggestion to make function HAL internal and Interface HAL public

Author: FilipVranesevic

dht/thermometer.go

@@ -9,9 +9,12 @@
 package dht // import "tinygo.org/x/drivers/dht"
 
 import (
-	"machine"
 	"runtime/interrupt"
 	"time"
+
+	"tinygo.org/x/drivers"
+	"tinygo.org/x/drivers/internal/legacy"
+	"tinygo.org/x/drivers/internal/pin"
 )
 
 // DummyDevice provides a basic interface for DHT devices.
@@ -30,7 +33,8 @@ type DummyDevice interface {
 // Since taking measurements from the sensor is time consuming procedure and blocks interrupts,
 // user can avoid any hidden calls to the sensor.
 type device struct {
-	pin machine.Pin
+	set pin.OutputFn
+	get pin.InputFn
 
 	measurements DeviceType
 	initialized  bool
@@ -43,8 +47,8 @@ type device struct {
 // According to documentation pin should be always, but the t *device restores pin to the state before call.
 func (t *device) ReadMeasurements() error {
 	// initial waiting
-	state := powerUp(t.pin)
-	defer t.pin.Set(state)
+	state := powerUp(t.set, t.get)
+	defer t.set(state)
 	err := t.read()
 	if err == nil {
 		t.initialized = true
@@ -93,14 +97,11 @@ func (t *device) HumidityFloat() (float32, error) {
 // Perform initialization of the communication protocol.
 // Device lowers the voltage on pin for startingLow=20ms and starts listening for response
 // Section 5.2 in [1]
-func initiateCommunication(p machine.Pin) {
-	// Send low signal to the device
-	p.Configure(machine.PinConfig{Mode: machine.PinOutput})
-	p.Low()
+func initiateCommunication(set pin.OutputFn) {
+	set.Low()
 	time.Sleep(startingLow)
 	// Set pin to high and wait for reply
-	p.High()
-	p.Configure(machine.PinConfig{Mode: machine.PinInput})
+	set.High()
 }
 
 // Measurements returns both measurements: temperature and humidity as they sent by the device.
@@ -131,14 +132,14 @@ func (t *device) read() error {
 	signals := signalsData[:]
 
 	// Start communication protocol with sensor
-	initiateCommunication(t.pin)
+	initiateCommunication(t.set)
 	// Wait for sensor's response and abort if sensor does not reply
-	err := waitForDataTransmission(t.pin)
+	err := waitForDataTransmission(t.get)
 	if err != nil {
 		return err
 	}
 	// count low and high cycles for sensor's reply
-	receiveSignals(t.pin, signals)
+	receiveSignals(t.get, signals)
 
 	// process received signals and store the result in the buffer. Abort if data transmission was interrupted and not
 	// all 40 bits were received
@@ -158,13 +159,13 @@ func (t *device) read() error {
 
 // receiveSignals counts number of low and high cycles. The execution is time critical, so the function disables
 // interrupts
-func receiveSignals(pin machine.Pin, result []counter) {
+func receiveSignals(get pin.InputFn, result []counter) {
 	i := uint8(0)
 	mask := interrupt.Disable()
 	defer interrupt.Restore(mask)
 	for ; i < 40; i++ {
-		result[i*2] = expectChange(pin, false)
-		result[i*2+1] = expectChange(pin, true)
+		result[i*2] = expectChange(get, false)
+		result[i*2+1] = expectChange(get, true)
 	}
 }
 
@@ -189,33 +190,59 @@ func (t *device) extractData(signals []counter, buf []uint8) error {
 // waitForDataTransmission waits for reply from the sensor.
 // If no reply received, returns NoSignalError.
 // For more details, see section 5.2 in [1]
-func waitForDataTransmission(p machine.Pin) error {
+func waitForDataTransmission(get pin.InputFn) error {
 	// wait for thermometer to pull down
-	if expectChange(p, true) == timeout {
+	if expectChange(get, true) == timeout {
 		return NoSignalError
 	}
 	//wait for thermometer to pull up
-	if expectChange(p, false) == timeout {
+	if expectChange(get, false) == timeout {
 		return NoSignalError
 	}
 	// wait for thermometer to pull down and start sending the data
-	if expectChange(p, true) == timeout {
+	if expectChange(get, true) == timeout {
 		return NoSignalError
 	}
 	return nil
 }
 
-// Constructor function for a DummyDevice implementation.
-// This device provides full control to the user.
-// It does not do any hidden measurements calls and does not check
-// for 2 seconds delay between measurements.
-func NewDummyDevice(pin machine.Pin, deviceType DeviceType) DummyDevice {
-	pin.High()
+func newDevice(pin drivers.Pin, deviceType DeviceType) *device {
+	pin.Set(true)
+	// Pins are configured to maintain backward compatibility,
+	// When writing new drivers we assume that pins are configured in user code
+	// so the device initialization could be simplified like this:
+	// return &device{
+	// 	set:          pin.Set,
+	// 	get:          pin.Get,
+	//  ...
+	// }
+	isOutput := true
 	return &device{
-		pin:          pin,
+		set: func(level bool) {
+			if !isOutput {
+				legacy.ConfigurePinOut(pin)
+				isOutput = true
+			}
+			pin.Set(level)
+		},
+		get: func() bool {
+			if isOutput {
+				legacy.ConfigurePinInput(pin)
+				isOutput = false
+			}
+			return pin.Get()
+		},
 		measurements: deviceType,
 		initialized:  false,
 		temperature:  0,
 		humidity:     0,
 	}
 }
+
+// Constructor function for a DummyDevice implementation.
+// This device provides full control to the user.
+// It does not do any hidden measurements calls and does not check
+// for 2 seconds delay between measurements.
+func NewDummyDevice(pin drivers.Pin, deviceType DeviceType) DummyDevice {
+	return newDevice(pin, deviceType)
+}

dht/timesafethermometer.go

@@ -9,8 +9,9 @@
 package dht // import "tinygo.org/x/drivers/dht"
 
 import (
-	"machine"
 	"time"
+
+	"tinygo.org/x/drivers"
 )
 
 // Device interface provides main functionality of the DHTXX sensors.
@@ -124,14 +125,10 @@ func (m *managedDevice) Configure(policy UpdatePolicy) {
 
 // Constructor of the Device implementation.
 // This implementation updates data every 2 seconds during data access.
-func New(pin machine.Pin, deviceType DeviceType) Device {
-	pin.High()
+func New(pin drivers.Pin, deviceType DeviceType) Device {
+	pin.Set(true)
 	return &managedDevice{
-		t: device{
-			pin:          pin,
-			measurements: deviceType,
-			initialized:  false,
-		},
+		t:          *newDevice(pin, deviceType),
 		lastUpdate: time.Time{},
 		policy: UpdatePolicy{
 			UpdateTime:          time.Second * 2,
@@ -141,14 +138,10 @@ func New(pin machine.Pin, deviceType DeviceType) Device {
 }
 
 // Constructor of the Device implementation with given UpdatePolicy
-func NewWithPolicy(pin machine.Pin, deviceType DeviceType, updatePolicy UpdatePolicy) Device {
-	pin.High()
+func NewWithPolicy(pin drivers.Pin, deviceType DeviceType, updatePolicy UpdatePolicy) Device {
+	pin.Set(true)
 	result := &managedDevice{
-		t: device{
-			pin:          pin,
-			measurements: deviceType,
-			initialized:  false,
-		},
+		t:          *newDevice(pin, deviceType),
 		lastUpdate: time.Time{},
 	}
 	result.Configure(updatePolicy)

dht/util.go

@@ -3,23 +3,24 @@
 package dht // import "tinygo.org/x/drivers/dht"
 
 import (
-	"machine"
 	"time"
+
+	"tinygo.org/x/drivers/internal/pin"
 )
 
 // Check if the pin is disabled
-func powerUp(p machine.Pin) bool {
-	state := p.Get()
+func powerUp(set pin.OutputFn, get pin.InputFn) bool {
+	state := get()
 	if !state {
-		p.High()
+		set.High()
 		time.Sleep(startTimeout)
 	}
 	return state
 }
 
-func expectChange(p machine.Pin, oldState bool) counter {
+func expectChange(get pin.InputFn, oldState bool) counter {
 	cnt := counter(0)
-	for ; p.Get() == oldState && cnt != timeout; cnt++ {
+	for ; get() == oldState && cnt != timeout; cnt++ {
 	}
 	return cnt
 }

internal/legacy/pinconfig.go

@@ -3,7 +3,7 @@ package legacy
 import (
 	"errors"
 
-	"tinygo.org/x/drivers/internal/pin"
+	"tinygo.org/x/drivers"
 )
 
 // The pingconfig group of files serve to abstract away
@@ -19,7 +19,7 @@ import (
 // Deprecated: Do not configure pins in drivers.
 // This is a legacy feature and should only be used by drivers that
 // previously configured pins in initialization to avoid breaking users.
-func ConfigurePinOut(po pin.Output) {
+func ConfigurePinOut(po drivers.OutputPin) {
 	configurePinOut(po)
 }
 
@@ -28,7 +28,7 @@ func ConfigurePinOut(po pin.Output) {
 // Deprecated: Do not configure pins in drivers.
 // This is a legacy feature and should only be used by drivers that
 // previously configured pins in initialization to avoid breaking users.
-func ConfigurePinInputPulldown(pi pin.Input) {
+func ConfigurePinInputPulldown(pi drivers.InputPin) {
 	configurePinInputPulldown(pi)
 }
 
@@ -37,7 +37,7 @@ func ConfigurePinInputPulldown(pi pin.Input) {
 // Deprecated: Do not configure pins in drivers.
 // This is a legacy feature and should only be used by drivers that
 // previously configured pins in initialization to avoid breaking users.
-func ConfigurePinInput(pi pin.Input) {
+func ConfigurePinInput(pi drivers.InputPin) {
 	configurePinInput(pi)
 }
 
@@ -46,7 +46,7 @@ func ConfigurePinInput(pi pin.Input) {
 // Deprecated: Do not configure pins in drivers.
 // This is a legacy feature and should only be used by drivers that
 // previously configured pins in initialization to avoid breaking users.
-func ConfigurePinInputPullup(pi pin.Input) {
+func ConfigurePinInputPullup(pi drivers.InputPin) {
 	configurePinInputPullup(pi)
 }
 

internal/legacy/pinconfig_tinygo.go

@@ -5,22 +5,22 @@ package legacy
 import (
 	"machine"
 
-	"tinygo.org/x/drivers/internal/pin"
+	"tinygo.org/x/drivers"
 )
 
-func configurePinOut(po pin.Output) {
+func configurePinOut(po drivers.OutputPin) {
 	configurePin(po, machine.PinOutput)
 }
 
-func configurePinInputPulldown(pi pin.Input) {
+func configurePinInputPulldown(pi drivers.InputPin) {
 	configurePin(pi, pulldown) // some chips do not have pull down, in which case pulldown==machine.PinInput.
 }
 
-func configurePinInput(pi pin.Input) {
+func configurePinInput(pi drivers.InputPin) {
 	configurePin(pi, machine.PinInput)
 }
 
-func configurePinInputPullup(pi pin.Input) {
+func configurePinInputPullup(pi drivers.InputPin) {
 	configurePin(pi, pullup) // some chips do not have pull up, in which case pullup==machine.PinInput.
 }
 

internal/pin/internalpin.go

@@ -1,28 +1,17 @@
 package pin
 
-import "tinygo.org/x/drivers"
+// OutputFn is a function that sets the underlying pin's level.
+type OutputFn func(level bool)
 
-// This file contains interface-style Pin HAL definition.
-// It serves to eliminate machine.Pin from driver constructors
-// so that drivers can be used in "big" Go projects where
-// there is no machine package.
-
-// Here to aid relevant documentation links of [drivers.PinOutput] and [drivers.PinInput].
-var _ drivers.PinOutput
-
-// Output represents a pin hardware abstraction layer for a pin that can output a digital signal.
-//
-// This is an alternative to [drivers.PinOutput] abstraction which is a function type and has
-// not been standardized as of yet as a standard HAL in the drivers package,
-// [discussion ongoing here].
-//
-// [discussion ongoing here]: https://github.com/orgs/tinygo-org/discussions/5043
-type Output interface {
-	Set(level bool)
+// High sets the underlying pin's level to high. This is equivalent to calling PinOutput(true).
+func (setPin OutputFn) High() {
+	setPin(true)
 }
 
-// Input represents a pin hardware abstraction layer.
-// See [Output] for more information on why this type exists separate to drivers.
-type Input interface {
-	Get() (level bool)
+// Low sets the underlying pin's level to low. This is equivalent to calling PinOutput(false).
+func (setPin OutputFn) Low() {
+	setPin(false)
 }
+
+// InputFn is a function that reads the underlying pin's level.
+type InputFn func() (level bool)