27 The Board
Zeno is for programs that run on a board: a microcontroller with pins
that drive LEDs and relays, registers that control its peripherals, and
a clock. This chapter is about the board module, which is
how a program reaches them, and about the simulated board that lets the
same program run on a computer.
27.1 Blink
The program Zeno was made for, written on the first day, before there was a compiler, is this:
from board import led
from time import sleep
while true {
led.toggle()
sleep(500 ms)
}It never ends, as firmware does not. Run on a computer, it prints
led on, led off, led on every
half second, until Ctrl-C stops it. Compiled for a microcontroller, the
same lines blink the LED.
27.2 The simulated board
A computer has no LED on pin 13, so zeno run gives the
program a simulated board. It has 64 pins, all low to begin
with, with the LED on pin 13, where an Arduino Uno has it. It prints a
line each time a pin changes level, which is what a logic
analyser clipped to the pin would show:
from board import led
print(led, led.is_on())
led.on()
led.on()
led.toggle()
print(led.is_on())Pin(13) false
led on
led off
false
The second led.on() printed nothing, because the pin was
already high and did not move.
27.3 Pins
led is the pin the LED is on, and pin(n) is
the pin with that number. A pin can do four things:
| Written | Does |
|---|---|
p.on(),
p.off() |
drive it high or low |
p.toggle() |
give it the other level |
p.is_on() |
is it high? A bool |
p.number |
which pin it is |
Pin is a type, so a function can ask for one, and a pin
can go in a list, a field or a Pin or none:
from board import pin
from time import sleep
function flash(light: Pin, times: int) {
for turn in range(times) {
light.toggle()
sleep(10 ms)
}
}
let lamps = [pin(2), pin(3)]
for lamp in lamps {
flash(lamp, 2)
}pin 2 on
pin 2 off
pin 3 on
pin 3 off
A pin the board does not have is a ValueError:
from board import pin
let relay = pin(99)error: uncaught ValueError: this board has no pin 99. Its pins are 0 to 63
--> main.zeno:2:13
|
2 | let relay = pin(99)
| ^
A pin is not an int: if it were, on(count)
would compile, and so would led + 1. It is not an object
either, because an object lives in memory from the collector, and
blinking an LED should not need one. A pin is a kind of its own to the
checker, and a plain number in the compiled program, so it costs what an
int costs. Units work the same way. (Decision 3.15.)
27.4 The clock
sleep waits for a time with a unit, and
now() reads a clock that only goes forward, in
milliseconds, from a moment such as when the board was switched on (Numbers with Units). Only the
difference of two readings means anything:
from time import sleep, now
let start = now()
sleep(50 ms)
let took = now() - start
print("took at least 50 ms:", took >= 50 ms)took at least 50 ms: true
27.5 Registers
A microcontroller’s peripherals, its timers, serial ports and
converters, are controlled through registers: words of memory
at fixed addresses, given in the data sheet.
register(u32, address) names one, with its size:
from board import register
let control = register(u32, 0x4000_4400)
let data = register(u8, 0x4000_440C)
unsafe {
control.write(u32(control.read() | 1 << 0))
data.write(0x41)
print(control.read(), data.read())
}register 0x40004400 = 0x00000001
register 0x4000440c = 0x41
1 65
A value written must fit the register: control.read()
1| is an int, as every sum of sized numbers is (Sized Numbers and
Bits), so u32(...) puts it back, with a check.
Reading and writing a register must be inside
unsafe { }, because a wrong address or a wrong bit can stop
a chip, and Zeno cannot check either. The block marks the lines a
reviewer should read twice:
from board import register
let data = register(u8, 0x4000_440C)
data.write(0x41)error: writing a register goes inside `unsafe { }`. Zeno cannot check that it is right, so the block marks the lines where a mistake can damage memory
--> main.zeno:3:1
|
3 | data.write(0x41)
| ^
1 error found. Nothing was run.
On the simulated board a register is a word that remembers what was
written, and each write is printed. On a real board it is the real
address. Unsafe Code is about
unsafe and memory by hand.
27.6 A traffic light
This program from the examples folder is a traffic light
on three pins, written as a state machine with an enum. Its times are
short, so the whole run takes a fifth of a second:
examples/signal.zeno
# signal.zeno: a traffic light on three pins, written as a state machine.
#
# zeno run examples/signal.zeno run it on the simulated board
# zeno build --firmware --no-collector examples/signal.zeno
# the build for a microcontroller:
# no setjmp, no garbage collector
#
# On a computer the board is simulated. A line such as `pin 2 on` is what
# a logic analyser clipped to that pin would show. The times are short so
# that the whole run takes a fifth of a second.
from board import pin, led
from time import sleep, now
enum Light {
Red
Green
Amber
}
let red = pin(2)
let amber = pin(3)
let green = pin(4)
# Switch the lamps over: the old one off, then the new one on.
function show(light: Light) {
match light {
case Red {
amber.off()
red.on()
}
case Green {
red.off()
green.on()
}
case Amber {
green.off()
amber.on()
}
}
}
function after(light: Light) -> Light {
match light {
case Red { return Green }
case Green { return Amber }
case Amber { return Red }
}
}
# How long each light stays. The unit is part of the type: a function
# that returned `40` here would not compile.
function hold(light: Light) -> ms {
match light {
case Red { return 40 ms }
case Green { return 30 ms }
case Amber { return 10 ms }
}
}
let start = now()
var light = Red
for step in range(7) {
show(light)
led.toggle() # a heartbeat: the program is alive
sleep(hold(light))
light = after(light)
}
# Seven steps hold for 200 ms in all. `now` only ever goes forward.
print("took at least 200 ms:", now() - start >= 200 ms)pin 2 on
led on
pin 2 off
pin 4 on
led off
pin 4 off
pin 3 on
led on
pin 3 off
pin 2 on
led off
pin 2 off
pin 4 on
led on
pin 4 off
pin 3 on
led off
pin 3 off
pin 2 on
led on
took at least 200 ms: true
27.7 A real board underneath
A compiled program meets the hardware in four C functions, and these, with the number of pins, are everything Zeno knows about a board:
zeno_board_write(pin, level) drive a pin high or low
zeno_board_read(pin) is the pin high?
zeno_board_sleep(seconds) wait
zeno_board_now() a clock that only goes forward, in ms
The simulated board is these four, written for a computer. For a real microcontroller they are written once, over the vendor’s library, in a header, and the C compiler is told where it is. Firmware shows how, with a sketch for an STM32. The Zeno program does not change by a line.
Four functions is the smallest surface a port can have: a board is working the day those four are. The checks, such as a pin that does not exist or a wait below zero, are done once above them, for every board, so the four can be four lines each. (Decision 5.12.)
27.8 What the board does not have yet
In version 0.1 is_on() reads back what the program
wrote: there is no button, and no way to make a pin an input.
Interrupts, timers, PWM, an analogue converter and a serial port are not
in the board module either. Until they are, a program
reaches them through their registers, at the addresses the data sheet
gives. Appendix G lists
these.
from board import led, pin, register. A pin is driven
with on, off and toggle and asked
with is_on; Pin is a type. sleep
and now keep time with units. A register is read and
written inside unsafe. zeno run simulates the
board and prints each change; a compiled program sits on four C
functions that a real board provides.
Blink the LED in Morse code:
SOS, with dots of 100 ms.Write a class
Relaywith a pin and a name, and methodscloseandopenthat print what they do.Change the traffic light so that green lasts twice as long as red, and add a pedestrian lamp on pin 5.
Write a register without
unsafeand read the message.