Proposal: PWM abstraction changes to match hardware

[syoder]

Currently, the machine package implements the methods Configure() and Set(). We need additional functionality in order to control the frequency and possibly other PWM settings per device. But because most devices have multiple channels per PWM, we really need a slightly different abstraction that would allow changing PWM settings separately from setting PWM channel outputs. See #855

Functionality we probably need:

• any initialization needed, depending on chip / board
• set frequency (possibly prescaler / bit rate settings?)
• configure an individual channel's output Pin
• set an individual channel's value
• ability to stop the PWM

Option A:

PWM could have the following functions:

• Configure()
• SetFrequency(f int) error
• ConfigureChannel(num int, pin machine.Pin)
• SetChannel(num int, value uint16)
• Stop()

One variation would be to have configure look like this: Configure(pins []machine.Pin) error and not have a ConfigureChannel().

Option B:

Have separate PWM and PWMChannel structs. PWM could have:

• Configure()
• SetFrequency(f int) error
• Channel(num int) (PWMChannel, error)
• Stop()

and PWMChannel could have:

• Configure(pin machine.Pin)
• Set(value uint16)

It would be somewhat painful to rewrite this for all the currently supported machines, but I think we need to do something in order to support servos and other hardware that uses PWMs. I would be happy to work on this if we can reach consensus. Thoughts?

[aykevl]

Thank you for moving this forward!

I've looked a bit into various PWMs and here is what I found:

• The nrf51 series chip does not directly support PWM, but it has some hardware peripherals (TIMER, PPI, GPIOTE) that can be used together to support it. Unfortunately they are shared resources so they can't simply be used without some system for assigning them to appropriate peripherals.
• The nrf52 series chip has the same TIMER/PPI/GPIOTE support but also a dedicated PWM peripheral. You can configure the alignment (edge or center), prescaler, and counter top for the peripheral as a whole. Channels can be assigned to any pin. The PWM literally only supports DMA operation, but it's easy to emulate regular PWM behavior with just a single duty cycle entry that keeps repeating.
• The atsamd21 has TCC peripherals which can be used for PWM purposes. It supports a counter top, prescaler, and a load of other options. Channels can only be assigned to a limited number of pins (like with most SAM D peripherals).
• The esp8266 does not seem to support PWM at all.
• The esp32 has separate peripherals for PWM: one for LEDs and one for motor control. The one for LEDs is more like what you would normally consider a PWM in other chips. It is a bit odd, in that it contains 3 levels: two PWM peripherals (one high-speed and one low-speed), with each 4 timers, and each timer has a pair of channels. This gives a total of 16 channels. Because this is intended for LED control, it also has a fade-in/fade-out feature.

So that's it for the hardware. The architecture usually appears to be of a single counter that counts in various ways (up, down, up and down for "phase correct" or "center-aligned" PWM) at a configurable frequency with some prescaler. A PWM usually has about 4 channels that can then be configured in various ways. Usually you can set a value in a channel, which roughly corresponds to the duty cycle (but the actual duty cycle depends on the counter top and timer-dependent bit width).

If you can, please look into the PWM/timer peripherals of other chip families (stm32, NXP, etc) and include them in this thread to make sure the design caters to as much hardware as possible.

Thinking about this, it might make sense to not design a universal "PWM" peripheral but rather a "timer" peripheral that also supports PWM operations, as that is how it is sometimes called in hardware already. And in a way, it is in fact a timer with extra PWM channels.

[aykevl]

Then there is the other end: the users of this API. This is also very important to summarize before doing a PWM design.

Dimmable LEDs are fairly trivial: LEDs do not require precise control over frequency. The main tradeoff for LEDs is color depth (how many brightness levels it supports) versus PWM frequency (should be as high as possible to avoid flicker).

I've also used the TCC in an atsamd51 for my hardware assisted hub75 driver, to enable the display for a very precise time (basically it needs to be low for a very specific time too short to do with normal GPIO operations). It would be nice to have such support included in this API, but because it deviates significantly from the regular use, I'm not sure whether it cleanly fits.

I don't know much about other hardware, #855 (comment) has a great summary of hardware requirements.

And as always, simple things should be kept simple while complicated things should remain possible.

Here is what a simple usage of an API could look like:

// in the board-specific file e.g. itsybitsy-m4.go

var channel machine.PWMChannel
func init() {
    pwm := machine.PWM0
    pwm.Configure(machine.PWMConfig{}) // default to some sensible frequency for LEDs
    channel = pwm.Channel(0)
}

// in the main.go file

func main() {
    for i := uint32(0); ; i += 0x1000 {
        channel.Set(i)
        time.Sleep(time.Second/2)
    }
}

That's not as simple as I hope it could be.

Some remarks:

• By configuring the PWM in the Configure call, you can do frequency configuration there. There are also many other possible things to configure, such as the top value, center/edge alignment, prescaler, etc. (although I wonder if it would be possible to configure an absolute frequency instead and let the system figure out the proper prescaler, frequency, top value, etc). The might need to be a separate SetFrequency call to support some hardware, anyone have insight into that? (@gwtnz).
• Not shown is a possible pwm.Counter() call, which returns the current counter in the PWM. Most timers/PWMs seem to support this.
• I think it would be sensible to increase the PWM size to 32 bits, as some PWMs have larger than 16 bit counters.

One variation would be to have configure look like this: Configure(pins []machine.Pin) error and not have a ConfigureChannel().

It would be nice to expose extra options, which gets messy quickly when you pass a slice to the Configure call. So in general I'm more in favor of a design like option B, where the PWM (or timer) is separated from the individual channels. This also makes software more composable (as in my example above), as you can pass around individual channels without needing to know how PWMs map to pins or even which channels are on which PWM.

@gwtnz @alankrantas it would be great if you can give some feedback on what specific hardware demands from such a PWM API.

[syoder]

Thinking about this, it might make sense to not design a universal "PWM" peripheral but rather a "timer" peripheral that also supports PWM operations

I believe the nRF52 has both timer and pwm peripherals. Which I guess could both be supported by some common "timer" implementation. But it definitely keeps things confusing! Another option would be a defined interface that both a Timer and PWM adhere to?

And as always, simple things should be kept simple while complicated things should remain possible.

This is the challenge! And it is very hard to do without detailed knowledge of every supported machine - there definitely big gaps in my knowledge.

It would be nice to expose extra options, which gets messy quickly when you pass a slice to the Configure call.

Good point - it probably makes more sense to have a PWMConfig struct with some common set of fields that every machine would define, but individual machines could add additional fields to expose settings unique to them.

[alankrantas]

I probably know much less about hardwares than you all do. It just that buzzers and servos are common in education materials of Arduino, micro:bit and ESP8266 alike. micro:bit's PWM is software-simulated (3 max at a time) and probably so is ESP8266 (MicroPython).

For me, it's totally acceptable that you can only set one frequency across the board at a time (a separate timer you mentioned, is that it?), software PWM or not. That's how micro:bit and ESP8266 behaves. We simply don't mix buzzers and servos. There's not so many occasions to do that anyway.

But it's important that you can change the frequency (in Hz, integer) at any time. I also hope that the API can be as simple as how MicroPython or CircuitPython do it. It's not good for teaching if it gets too complicated.

[aykevl]

micro:bit's PWM is software-simulated (3 max at a time) and probably so is ESP8266 (MicroPython).

The micro:bit (nrf51) doesn't have a dedicated PWM peripheral but it definitely has hardware support. The esp8266 on the other hand doesn't seem to have any hardware support at all so it's hard to get a stable PWM output from it because everything must be done in software.

I totally agree the API should be as simple as possible. But I think limiting to just one frequency would make certain use cases impossible. Also: one PWM instance may only support a limited number of pins so making use of all PWM instances will be necessary.

If you have any concrete API please write it down. It's best to have many ideas to choose from and pick the best parts.

[alankrantas]

Well, it is claimed that micro:bit uses software PWM. Maybe it's a combination of hardware and software (here may have some info). I can't say I really know the answer. But if you tried to output 4th PWM signal in MakeCode the first PWM (on whatever pin) would simply stop.

I don't know what concrete API means; If you means what do I hope it would look like, it's probably like this:

machine.InitPWM()
pwm := machine.PWM{pwmPin}
pwm.Configure(machine.PWMConfig{duty: 32767, freq: 1046})
pwm.Configure(machine.PWMConfig{duty: 32767}) // set to default frequency
pwm.Configure() // set to default frequency, duty = 0?

pwm.Set(32767) // set duty cycle
pwm.SetFreq(1046) // set frequency in Hz (either this pin only or across whole board)
pwm.Deinit() // stop PWM (set duty and freq to 0?)

Also each board may have different available frequency range.

[gwtnz]

As @aykevl and @syoder have mentioned, getting the configs right across different boards / chips is going to be tricky. I'm thinking an interface-based approach (as opposed to a struct-based one) might be the way to go, such that we could define the types Servo and PWM and then have all the low-level details hidden away in their respective machine files, so that individual boards could handle things how they wanted to.

Something like (very similar to the posts above and Arduino etc libs; I'm still pondering how to pass the more specialized data into the generic function calls):

type Servo interface {
        Init(min uint16, max uint16, freq uint32)
        Configure(pin Pin, pulseFreq uint8)
        Set(val uint8)
        Get() uint8
}

type PWM interface {
        Init(min uint32, max uint32, freq uint32)
        Configure(pin Pin)
        Set(val uint32)
        Get() uint32
}

or maybe:

// To set up the timers etc system-wide
type ServoImpl interface {
        Init(min uint16, max uint16, freq uint32)
        Configure(pin Pin, pulseFreq uint8) Servo
}

// To control an individual servo instance associated with a pin
type Servo interface {
        Set(val uint8)
        Get() uint8
}

// To set up the timers etc system-wide
type PWMImpl interface {
        Init(min uint32, max uint32, freq uint32)
        Configure(pin Pin) PWM
}

// To control an individual PWM instance associated with a pin
type PWM interface {
        Set(val uint32)
        Get() uint32
}

IMHO the API would be at the simple level (a la the Arduino library equivalent, easy to get started with), and the implementation would allow for the complex level of managing timer channels, interrupts etc.

This is definitely going to need a bit of thought; looks like the ESP8266 is pretty much out for raw servo control because of that single (known?) timer; it's performance just doesn't look sufficient; even LED work will have to balance frequency with resolution. But something based on the PCA9685 can provide I2C servo control off-chip (though if you have to add another chip, you could just get another microcontroller 😄

On the other hand the stm32 chips are bristling with timers, channels, config options and pins to output them on, and plenty of clock cycles to give the developer choices for frequencies, so almost any conceivable pulse train setup is possible...

It may be that tinygo just plain can't offer features on some of the boards/chips if they can't support it; we probably shouldn't limit the API based on that, but maybe can offer the closest available thing, e.g. no servo control but at least rudimentary PWM on the 8266, similar to the MicroPython lib listed above.

[gwtnz]

periph.io has an interesting example here - there's just a duty cycle and frequency; a servo would be a variation of this with a frequency of 40-50 (Hz), and a duty cycle that ranged between ~2.5% and 12.5% (.5ms-2.5ms, 20ms total for 50Hz freq), though if a servo type was included it would be more intuitive to just have a 0-255 or 0-180 value for the setter but could still call down to the PWM method with an appropriate percentage of the duty cycle:

func (*p Pin) Servo(val uint8) {
   p.PWM(2.5 + val / 25.5, 50)
}

assuming fractions of a percent were available. This would still leave all the quirky timer setup code hidden away nicely.

[alankrantas]

I sometimes use a servo function like this in MicroPython:

def servoWrite(pin, degree):
    actual_degree = int(degree * (122 - 30) / 180 + 30) # convert 0-180 degree to duty cycle (30-122)
    servo = machine.PWM(pin, freq=50, duty=actual_degree)

servo = machine.Pin(5)
servoWrite(servo, 60)

Of course, usually I'll just add a conversion function and directly control the PWM object itself.

This works pretty well for a servo or two, both on ESP8266 and ESP32, and works for several servo variations. Haven't tried more (the power supply is a bigger issue). For more than 3-4 servos it would be indeed sensible to use a PCA9685 board.

Actually, quite a few micro:bit accessories have built-in PCA9685 chips/servo pins and a lithium battery.

[gwtnz]

For LED and servo control, the users would typically vary the duty cycle, and for piezo / buzzer / speaker square-wave sound output, they'd vary the frequency. This does seem like a pretty flexible simple API to use! More complex waveforms and multi-pin or multi-channel things could be left for a future advanced API setup.

[gwtnz]

If I'm reading the ESP8266 MicroPython code correctly, it looks like they're squeezing 1MHz frequency out of the PWM driver / clock, with a 10 bit (1024ish) resolution, and have support for multiple channels, interrupt driven for timing but then software driven for the actual output.
I'm not sure how many devices support this frequency (e.g. low end Arduino?) but if we're looking to standardize on some parameters that we'd match the chips/boards to, this seems pretty reasonable for most cases?

[syoder]

So, based on this discussion so far, I think:

• we do need a SetFrequency() function in addition to allowing frequency in Configure(). Some use-cases will want to dynamically update frequency, while others might only change the duty cycle
• there is a strong desire to keep things simple
• but also a desire to be able to take advantage of what the hardware has to offer (ie, multiple channels, if available)

@aykevl the example that you gave where you said it was not as simple as you had hoped: is that because it required a board specific file in addition to the main.go file? if so, one option would be to have the pwm.Configure() method provision the peripheral if available, otherwise return an error. Where there are multiple, you would be able to spin up multiple PWM objects and Configure() them. The usage would then look like this:

func main() {
    var pwm = machine.PWM{}
    PWM.Configure(machine.PWMConfig{Frequency: 1000})
    var channel = pwm.Channels(0)
    for i := uint32(0); ; i += 0x1000 {
        channel.Set(i)
        time.Sleep(time.Second/2)
    }
}

[aykevl]

@aykevl the example that you gave where you said it was not as simple as you had hoped: is that because it required a board specific file in addition to the main.go file?

No that was intentional. In my own projects I usually put board-specific configuration in a separate file so that I can easily run the same project on multiple boards. What I was referring to was that I didn't like the amount of configuration that was needed.

I've been thinking a bit more about this issue the last few days and I honestly think the timer/channel distinction is inherent to the hardware, so much that hiding it will do more harm than good. While this might seem easy to use:

machine.LED.SetPWM(frequency, dutyCycle)

or this:

machine.PWM{machine.LED}.Set(frequency, dutyCycle)

It hides the fact that frequency is a property of the timer and not of the pin or the chip as a whole. Even though it introduces a bit more complexity, I think it is better to expose it than to hide it and have a leaky abstraction (or dumbed-down abstraction).

I also considered to maybe add some helper functions for this purpose, but I think they will actually make the API more complex simply by making it bigger.

I'm thinking an interface-based approach (as opposed to a struct-based one) might be the way to go, such that we could define the types Servo and PWM and then have all the low-level details hidden away in their respective machine files, so that individual boards could handle things how they wanted to.

I agree we should have a special driver for servos, but I doubt this driver should be in the machine package. The machine package is intended as a low-level HAL to be used by drivers. For example, most I2C and SPI devices aren't driven directly but through a dedicated driver (in the drivers repo). So what I hope is that we can find a low-level abstraction over the various hardware PWMs that is universal enough for a servo driver.

I will investigate the different PWMs further, maybe there is a way to simplify things in a way that does not prevent more advanced use cases.

Regarding the ESP8266: that "PWM" should be supported but I don't think it should influence the API too much. The chip doesn't really have any PWM to speak of (just a timer) and my intention of the machine package is to support hardware peripherals, not software peripherals.

[gwtnz]

Servo definitely feels to me like an abstraction that could live in e.g. the drivers package; it would just require a PWM or even lower level Timer type thing exposed from probably the machine layer. Even PWM could live in drivers as a particular implementation / use case of a Timer.