Machine API

There should be a clearly documented API for peripherals in TinyGo. Here is an initial attempt.

For reference:

• The MicroPython hardware API

Pins

type Pin struct {
    // depends on the platform
}

type PinMode ... // type depends on the platform

const (
    // values depend on the platform
    PIN_OUTPUT PinMode = ...
    PIN_INPUT  PinMode = ...
)

// Pin configuration. More fields may be added in the future, but the zero
// value must do the expected thing - e.g. pull configuration must default to
// 'no pull'.
type PinConfig struct {
    Mode PinMode
}

// Initialize PWM on platforms that need such a thing.
func InitPWM()

// Configures pin mode and possibly other settings.
func (p Pin) Configure(config PinConfig)

// Sets the pin to high or low when configured as output.
func (p Pin) Set(high bool)

// Gets the current value of the pin. Pin must be configured as input pin.
func (p Pin) Get() bool

// Enables PWM with the given duty cycle. Pin must be configured as output pin.
func (p Pin) SetPWM(dutycycle uint16)

// Sets the frequency for this PWM. This may be a no-op on some platforms.
func (p Pin) SetPWMFrequency(...)

// Reads a number from the ADC. Pin must be configured as input pin.
func (p Pin) ReadADC() uint16

PWM uses a 16-bits number for the duty cycle where 0 means 0% and 0xffff means 100% (so that for example 0xc000 means 75% on). This is a 16 bits number so that the most precision can be reached on all platforms and PWM peripherals that implement less bits can simply ignore the lower bits (for example, use dutycycle / 256 for an 8-bits PWM).

ADC uses a 16-bits number for the same reason, and is also 0 for the lowest possible output and 0xffff for the highest possible output. This means that an ADC that is not 16 bits must scale the output to fit 16 bits (for example, a 12 bits PWM must multiply the output by 16).

Open issues:

• How should a pin object be obtained?
• How should PWM be stopped?
• This assumes that PWM, ADC etc. all use the same system for configuring as input or output. Is this true on all platforms?