Boards and AEL Gateway — AEL documentation

With AEL, the Agent Engineering Language, one language reaches from servers down to microcontrollers, and a feature a target cannot support fails at compile time, not on the device. This tutorial builds firmware for a board, reads its memory report, flashes a device and recovers from an interrupted flash, then gives the board a prompt-driven agent through AEL Gateway.

Supported targets lists the boards and their profiles; this tutorial writes <board> where you put one of them.

Step 1: set up the board's target

ael target install <board>
ael doctor

The AEL 1.0.0 build for Linux, macOS or Windows comes with target management and a health check, and desktop and server programs need nothing else installed. Boards are the exception: flashing uses each board maker's standard flashing tools, which you install yourself, and ael doctor tells you when they are missing.

Step 2: write within the board's limits

The smallest profile needs no heap and no operating system. Every agent, mailbox, timer and buffer has a capacity fixed when you build, and a full collection returns an explicit result instead of growing:

enum Reading {
    Normal(u16),
    High(u16),
    Missing,
}

fn classify(samples: [u16; 4], limit: u16) -> Reading {
    let mut highest: u16 = 0;
    let mut i: u32 = 0;
    while i < 4 {
        if samples[i] > highest {
            highest = samples[i];
        }
        i = i + 1;
    }
    if highest == 0 {
        return Reading::Missing;
    }
    if highest > limit {
        return Reading::High(highest);
    }
    return Reading::Normal(highest);
}

The function uses a fixed array and no heap, so it fits the smallest boards. Code that needs an option the board does not offer fails when you build, before anything is flashed.

Step 3: build and read the memory report

ael build --target <board> -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, and 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 the build fail when a required figure is unknown or the firmware does not fit the budget you set.

Building never flashes a device.

Step 4: flash the device

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

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

ael flash checks that the device is connected, that it is the board you named and that the firmware image was built for it and is intact, and refuses to write otherwise. It takes the device for itself until the flash has finished or failed.

Step 5: recover from an interrupted flash

If the device is unplugged or the flash stops part-way, ael flash says so, reports what state the device was left in and tells you how to recover it, such as putting the board back into its bootloader and flashing again. An interrupted flash is never reported as a success. Run the same ael flash command again once the device is back.

Step 6: add a prompt-driven agent through AEL Gateway

Prompt-driven agents run on small devices through a gateway, and each device keeps its safe local behaviour when offline. AEL Gateway runs on a desktop or server target near your devices:

On the board	On AEL Gateway
A small stub for each prompt-driven agent, which sends typed input and waits for a compact typed result.	The system prompts, model bindings, credentials and conversation history. None of them is stored on the board.
Your typed checks on every result (ranges, freshness and the device's current state) before it can reach hardware.	The model calls, within the budget and limits you set.
The behaviour you declared for when the gateway is unreachable: a typed error, a last safe bounded action or a safe state.	Messages to the board of a fixed maximum size, so they always fit its memory.

A prompt, a gateway or a model's answer can never grant the board a new hardware permission.

Step 7: deploy a new prompt to the gateway

A prompt change that keeps the same typed inputs, outputs, tools and permissions updates the gateway and flashes no firmware:

ael deploy plan
ael deploy apply --plan <plan>

A device never starts using a new prompt or tool contract before its gateway serves it. A change to the typed inputs, outputs or tools a device uses needs new firmware, flashed in a coordinated update of the device and its gateway, and rolling back returns both to the previous compatible version. Deployment and rollback has the full table.

Honest limits

Models do not run on a microcontroller: a prompt-driven agent on a board always reaches its model through AEL Gateway.
On the smallest boards, agents take turns on one processor core, and scheduling alone does not guarantee a deadline.
Each board's support lists the peripherals it provides; one the board does not have fails when you build.
This page states no memory figure: the memory report gives the figures for your firmware on your board.