A PWM signal: a pin on for a share of the time
A pin is only ever high or low. Switched on and off fast by a timer of the chip, it dims a lamp, sets the speed of a motor and tells a servo where to turn. That signal is called PWM (pulse-width modulation), and the program only says how much of the time the pin is on.
from board import pwm_pin
let lamp = pwm_pin(9, 1 kHz)
lamp.duty(0.25) # on for a quarter of the time
let servo = pwm_pin(10, 50 Hz)
servo.pulse(1500 us) # on for 1.5 ms of each 20 ms
The reasons for each choice are in chapter 48 of
decisions.md. The example
examples/dimmer.zeno fades a lamp up and
down and sweeps a servo.
What a PWM pin has
| Write | Does |
|---|---|
pwm_pin(9, 1 kHz) |
pin 9, as a pin that makes a signal 1000 times a second: a PwmPin. It is off at first |
lamp.duty(0.25) |
on for that share of the time, a float from 0.0 (off) to 1.0 (on all the time) |
servo.pulse(1500 us) |
on for that long in each period, a time with its unit |
lamp.number |
which pin it is |
The frequency has a unit, and a bare number is refused:
error: the frequency of a PWM pin has a unit, as in `pwm_pin(9, 1 kHz)`, and this is int
A frequency worked out from a period is one too
(units-made.md):
from board import pwm_pin
let period = 20 ms
let servo = pwm_pin(10, 1 / period) # 50 Hz
servo.pulse(2 ms)
duty and pulse are two ways to say one thing. A lamp or a motor is
given a share, and a servo is given a time: 1 ms is one end of its
turn, 1.5 ms the middle and 2 ms the other end, whatever the period.
PwmPin is a type, so a function can ask for one:
from board import pwm_pin
function half(light: PwmPin) {
light.duty(0.5)
}
half(pwm_pin(9, 1 kHz))
It is not a Pin: it has no on and no off. All the time on is
duty(1.0).
What is refused while the program runs
Each is a ValueError:
| The program | The message |
|---|---|
lamp.duty(1.5) |
a duty is from 0.0 to 1.0, and this is 1.5. For a quarter of the time on, write 0.25 |
servo.pulse(30 ms) at 50 Hz |
a pulse lasts from no time to one whole period, which is 0.02 s at this frequency, and this is 0.03 s |
pwm_pin(9, 0 Hz) |
the frequency of a PWM signal must be above 0 Hz |
| a pin no timer reaches | pin 7 of this board cannot make a PWM signal |
A share above 1.0 is never quietly taken as 1.0: a wrong sum should not run a motor at full power.
On a computer
No timer makes the signal on the simulated board. Each change of it is printed, as turning a pin on is:
pin 9 pwm 0.25 at 1000 Hz
pin 10 pwm 0.075 at 50 Hz
Setting the duty a pin already has prints nothing, and so making a pin that has no signal yet, which starts it off, prints nothing. Every pin can make a signal.
On a board
The board header has one function (board.md):
/* Start or change the signal on a pin. False if this pin cannot make one. */
static bool zeno_board_pwm(int pin, double hertz, double duty);
It is called when the pin is made, with a duty of 0, and at each
duty and pulse, with the same frequency and the new share. The
runtime has checked the ranges, so the board sees a frequency above 0
and a duty from 0 to 1. With ST's HAL for an STM32 it could be (a
sketch, not tried on hardware):
static bool zeno_board_pwm(int pin, double hertz, double duty) {
if (pin != 9) return false; /* only the pin TIM3 channel 1 drives */
uint32_t period = (uint32_t)(1000000.0 / hertz); /* the timer counts microseconds */
__HAL_TIM_SET_AUTORELOAD(&htim3, period - 1);
__HAL_TIM_SET_COMPARE(&htim3, TIM_CHANNEL_1, (uint32_t)(duty * period));
HAL_TIM_PWM_Start(&htim3, TIM_CHANNEL_1);
return true;
}
Only a program that makes a PWM pin calls it, so a header without it still builds every program that makes none.
In a built program
A PWM pin is its number, an int64_t. lamp.duty(0.25) is one call,
zeno_pwm_duty(9, 0.25, ...), which checks the range and calls the
board. The runtime keeps the frequency of each pin, eight bytes a pin.
Not yet
Reading back the duty or the frequency, changing the frequency of a
pin that is made, the timer's resolution, complementary outputs for a
motor bridge, and a trial on a real board. See 48.6 in
decisions.md.
This page is docs/pwm.md in the language repository.