Microcontroller boards

Boards

AEL 1.0.0 builds for the microcontroller boards Raspberry Pi Pico (RP2040), STM32 NUCLEO-G071RB and ESP32-C3. One more microcontroller board, to be announced.

AEL 1.0.0 also builds for the ESP32 family of microcontrollers (ESP32-C3, ESP32-C6, ESP32-H2, ESP32-S3, ESP32 and ESP32-S2) and for coin-cell-class microcontroller boards.

Each board is a target of its own. Its board support, which ael target install sets up, gives its target name and names its profile. Supported targets lists every target.

Profiles and runtime sizes

Runtimes come in sizes for each class of device, from servers down to coin-cell-class microcontrollers, and a program that does not fit its device's class is refused when you build it. A board's support names its profile, and the profile decides what the runtime on the board contains:

• Edge. An optional heap, storage, networking and TLS are available on small networked boards. Each is off until you switch it on, with its memory cost shown in the memory report, and code that needs an option you have not switched on fails when you build.
• Nano. No heap and no operating system. Every agent, mailbox, timer and buffer has a capacity fixed when you build, and a full mailbox or collection returns an explicit result instead of growing.
• Coin-cell-class and other small boards. Their runtimes are smaller than Nano's, with no heap and no operating system. On small boards, agents take turns on a cooperative scheduler, with timers and mailboxes, each with a capacity fixed when you build. On the smallest boards, a program is one main loop and the interrupts it binds, with no scheduler.

A program that needs more than its board's profile offers fails when you build, with a diagnostic that points at your source, before anything is flashed.

What your program can use

Hardware access covers GPIO, clocks, UART, interrupts and defined panic behaviour:

• Pins (GPIO). A pin belongs to one part of your program at a time.
• Clocks and timers. A clock that only moves forward, and timers that stay correct when the hardware counter wraps around.
• Serial ports (UART). Input and output over the board's serial connection.
• Interrupts. An interrupt wakes the agent that waits for it, and the work done inside the interrupt stays small and bounded.
• Panics. A panic stops the program in a defined way: the board's outputs go to the safe state its board support defines, and the fault is reported where the board can report it.

Concurrency on microcontrollers is safe, with bounded mailboxes, timers, cooperative scheduling, supervision and restarts. See Concurrency.

Robotics components

Optional device packages, written in AEL, drive common robotics components: motor drivers, servos, inertial sensors, encoders and range sensors.

• Your board's pins and buses. A device package uses the pins, buses and timers of your board, and holds each one the way the rest of your program does: one part of your program at a time.
• Added like any package. You add a device package to your project like any other package.

Robotics describes the robotics packages and how safety stays deterministic.

Honest limits

• Cooperative scheduling. On Nano boards, agents take turns on one processor core. A handler runs until it waits, so a long computation delays the others; scheduling alone does not guarantee a deadline.
• Bounded recursion. Recursion whose depth cannot be bounded is refused on the smallest boards. See Limits.
• No models on the board. Models do not run on a microcontroller. Prompt-driven agents reach a model through AEL Gateway, described below, on boards of the Nano and Edge profiles; coin-cell-class and other small boards run no prompt-driven agent.
• No subagents. An agent spawns subagents at run time: short-lived agents that each do one task. A board creates no agent at run time, so the check refuses spawn on every board. See Where subagents run.
• No network edges. The same edge runs in one process, between processes or over the network, as your deployment places it. On a board it stays inside the program, because boards carry no network transport for edges.
• No isolation. You mark an agent, node or subagent as isolated: it always runs in a sandbox in its own process. Isolation needs the isolation facilities of Linux and runs only on the Linux target the documentation names for it: on microcontroller boards, an isolated component is refused, never run without isolation. See Supported targets.
• Per-board peripherals. Each board's support lists the capabilities it provides. Using one the board does not have fails when you build, before anything is flashed.

Building firmware and memory reports

ael build builds a firmware image for a board:

ael target install stm32g071-nucleo
ael build --target stm32g071-nucleo -o build/sensors --release --memory-report

Firmware images come with RAM, flash and stack reports:

• The report breaks memory down by what you declared: agents, mailboxes, timers and buffers, as well as the runtime's own share.
• Each figure says whether it is exact, a safe upper bound or measured on a device. Anything that cannot be known is shown as unknown, never as zero.
• You can make a build fail when a required figure is unknown or the program does not fit the budget you set, with a reserve kept free.

Building never flashes a device.

Flashing and monitoring

You flash and monitor supported boards from the command line, using each board's standard flashing tools:

ael devices
ael flash --target stm32g071-nucleo --device <device> --artifact build/sensors
ael monitor --device <device>

• ael flash writes exactly the firmware image you name to the one device you select, after checking that the device is the board the image was built for and that the image is intact. Flashing never happens by itself.
• A device takes one operation at a time, and an interrupted flash leaves a clear state and a way to recover.
• Boards need their makers' flashing tools installed; ael doctor reports any that are missing. "Nothing else to install" holds only for desktop and server programs written in AEL alone.

Flashing a board and Monitoring a device describe the commands in full.

Prompt-driven agents through AEL Gateway

Prompt-driven agents run on small devices through AEL Gateway, and each device keeps its safe local behaviour when offline.

• On the board, each prompt-driven agent is a small stub: it sends typed input to the gateway and waits for a compact typed result. Deterministic work on the device keeps running as usual.
• On the gateway, AEL Gateway is a program on a desktop or server target near your devices, such as a Linux single-board computer, and keeps the system prompts, model bindings, credentials and conversation history. None of them is stored on the board.
• Fixed size. Messages between a board and its gateway have a fixed maximum size, so they always fit the board's memory.
• Checked on the board. Every result passes your own typed checks on the board, such as ranges, freshness and the device's current state, before it can reach hardware. A prompt, a gateway or a model's answer can never grant a new hardware permission.
• Offline. When the gateway or the model is unreachable, too slow or answers with something invalid, the device does what you declared: return a typed error, keep a last safe bounded action, or go to a safe state.

Updating a prompt on the gateway and updating firmware are coordinated through one plan; see Deployment and rollback.

Related

• Supported targets: every target and profile.
• Building a program: the build options.
• Listing devices: finding the device to flash.
• Logging and monitoring: logs on boards and watching a device.
• Robotics: robot agents, from device packages to safety.