Docs

A serial port

A serial port is how a board talks: to a terminal on a desk, to a GPS module, to a modem or to another board.

from board import serial

let port = serial(1, 115200 baud)
port.write("ready\n")
var byte = port.read_byte()
var line = ""
while byte is not none and byte != 10 {
    line = line + char(byte)
    byte = port.read_byte()
}
port.write(f"got {line}\n")

The reasons for each choice are in chapter 46 of decisions.md. The example examples/console.zeno is a small command line over a serial port that drives the LED.

Opening one

serial(n, speed) is the port with that number, at a speed in baud. It gives a Serial. The speed must have its unit:

error: the speed of a serial port is in baud, as in `serial(1, 115200 baud)`, and this is int

A port the board does not have, or a speed of 0 or below, is a ValueError. The simulated board has ports 0 to 3.

Using one

Write Does
port.write("hi\n") sends the bytes of the text, and no line end of its own
port.write_bytes(frame) sends a list[u8] as it is
port.read_byte() the next byte, waiting for it: a u8 or none
port.has_byte() has a byte come that has not been read? It does not wait
port.number which port it is

read_byte gives none only when no more bytes can ever come. On a board that is never. A program that has other work to do asks has_byte() first:

from board import serial, led
from time import sleep

let port = serial(1, 115200 baud)
for turn in range(4) {
    if port.has_byte() {
        let byte = port.read_byte()
        if byte is not none {
            port.write_bytes([byte])
        }
    }
    led.toggle()
    sleep(5 ms)
}

Serial is a type, so a function can take a port, and ports go in lists and fields.

On a computer

Every serial port of the simulated board is the terminal, as a serial monitor is. What is sent is written out as it is, and what is read is what is typed, a byte at a time. The end of what was typed (Ctrl-D, or the end of a file piped in) is the end of the port: read_byte gives none and has_byte is false.

printf 'on\nstatus\n' | zeno run examples/console.zeno

A terminal hands over a line at a time, so on a computer has_byte waits for the next line.

On a board

A compiled program with a serial port calls four more functions of the board layer (board.md), and needs ZENO_SERIALS, the number of ports:

#define ZENO_SERIALS 2
static void zeno_board_serial_open(int port, double baud);
static void zeno_board_serial_write(int port, const uint8_t *bytes, size_t count);
static bool zeno_board_serial_ready(int port);   /* has a byte come? no waiting */
static int zeno_board_serial_read(int port);     /* the next byte, waiting; -1 for no more */

With ST's HAL for an STM32 they could be, for one port (a sketch, not tried on hardware):

extern UART_HandleTypeDef huart2;

static void zeno_board_serial_open(int port, double baud) {
    (void)port;
    huart2.Init.BaudRate = (uint32_t)baud;
    HAL_UART_Init(&huart2);
}
static void zeno_board_serial_write(int port, const uint8_t *bytes, size_t count) {
    (void)port;
    HAL_UART_Transmit(&huart2, (uint8_t *)bytes, (uint16_t)count, HAL_MAX_DELAY);
}
static bool zeno_board_serial_ready(int port) {
    (void)port;
    return __HAL_UART_GET_FLAG(&huart2, UART_FLAG_RXNE);
}
static int zeno_board_serial_read(int port) {
    (void)port;
    uint8_t byte;
    HAL_UART_Receive(&huart2, &byte, 1, HAL_MAX_DELAY);
    return byte;
}

Only a program with a port calls them, so a header written without them still builds every program that has none. The test a_serial_port_on_a_board_of_its_own builds a program over a header whose port is wired back to itself: what is sent comes back to be read.

In a built program

A port is its number, an int64_t. port.write("hi") is one call, zeno_serial_write(1, "hi"), over zeno_board_serial_write. Every engine and every C and LLVM build print the same.

Not yet

read_line, a timeout, reading many bytes at once, 1 / 9600 baud as the time of a bit, parity and stop bits, and a byte arriving by interrupt. See 46.7 in decisions.md.

This page is docs/serial.md in the language repository.