The Zeno Book Zeno 0.1 zeno-lang.org

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.

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.

  1. Blink the LED in Morse code: SOS, with dots of 100 ms.

  2. Write a class Relay with a pin and a name, and methods close and open that print what they do.

  3. Change the traffic light so that green lasts twice as long as red, and add a pedestrian lamp on pin 5.

  4. Write a register without unsafe and read the message.