Skip to content

Onboard Programs

inksong edited this page Nov 9, 2026 · 3 revisions

Onboard Programs

A quadcopter hovering above a state machine made of voxels

A language model decides in hundreds of milliseconds to tens of seconds; a quadcopter needs its sticks corrected fifty times a second. An onboard program puts the fast loop on the aircraft's stick path. It is restricted Python that runs at 50 Hz in an isolated program host on this computer. It reads only what the aircraft can sense and outputs the four sticks and the trigger.

Layer Rate Implemented by
Reflexes: attitude stabilisation, motor mixing 250 Hz and above The flight controller (real) or the simulated autopilot
Behaviour: onboard programs 50 Hz Programs written by people or agents
Decisions: agents Seconds to minutes Copilot and external agents: write, test, tune, duel

A complete program

PARAMS = {"target_alt": 1.0, "hover": 0.5, "kp": 0.3, "kd": 0.15}   # tunable while running

def init(ctx):
    ctx.state = "climb"

def step(obs, ctx):
    p = ctx.params
    if not obs.armed or obs.alt is None:
        ctx.state = "idle"
        return Sticks(throttle=0.0)
    error = p["target_alt"] - obs.alt
    ctx.state = "hold" if abs(error) < 0.1 else "climb"
    return Sticks(throttle=clamp(p["hover"] + p["kp"] * error - p["kd"] * obs.vz, 0.0, 1.0))
  • Sticks(roll, pitch, yaw, throttle, fire): roll, pitch and yaw in [−1, 1], throttle in [0, 1].
  • ctx: mem, params (follows live tuning), state (shown on the stage label), log(), t, rng.
  • Library without import: clamp, wrap180, lerp, deadband, lowpass, PID, StateMachine, Timer.
  • Language: a subset of Python 3 checked against an AST allow-list; math is the only import; no classes, files, network or dunder access; 64 KB of source.

What a program sees

Attitude and body rates, body acceleration, barometric height and climb rate, position and velocity only where a source exists, battery, motor output, arena hit points and ammunition, contacts (other aircraft within 30 m with bearing, elevation, relative velocity and closing speed), collision (the last contact within 1 s), the arena bounds and, in copilot mode, the person's sticks. Airframe defects are not in the observation; they show only in flight. The full table is in the programs guide.

Built-in examples

id Behaviour
hover_trim Hover with an integrator that learns the hover throttle
liftoff Take-off by throttle search
takeoff_hover_land Take off to target_alt, hover hold_s seconds, land at descent m/s and disarm; every throttle value is a parameter to tune while it flies, and with learn on it finds the hover throttle itself
patrol Timed-turn patrol without a position source
hunter_easy, hunter_medium, hunter_hard Arena hunters: search, approach, fire, evade, dodge a head-on run
rammer Climb, search, pursue with proportional navigation while weaving across the line of sight, ram, recover; never fires
figure8_evader Figure eight around the arena centre on a position source with a weaving height; dodges sideways and changes height when an aircraft of another team closes in; never fires

Examples are read only; Duplicate makes an editable copy.

Deploying and safety

  • Arm and start on the Lab's Run tab (on by default) arms the aircraft in STABILIZE once the program is in place, so it flies at once; a real aircraft asks for the word ARM. Stopping the program on the ground disarms it again. Without it the program waits until the aircraft is armed: a program only outputs sticks and never arms by itself.
  • While it flies, the Params tab tunes it live, and saving and deploying a new revision takes over in the air without landing.
  • ctx.disarm() disarms after the landing; Relay refuses it in the air.
  • A deployed program flies as PROGRAM · <name> · <state> on the stage and in the fleet.
  • Possession pauses it at once; releasing does not resume it. Emergency stop, link loss and a crash stop it. The 0.8 s stick timeout applies.
  • Each frame has a 2 ms soft budget; a frame that misses 15 ms outputs safe sticks; 25 faults or 3 missed frames in a row end the program as faulted. A host past 512 MB is ended.
  • A real aircraft accepts programs only after Allow programs on this aircraft (confirm word PROGRAM) and passed preflight; its fire output is ignored.
  • Programs come only from this computer. The LAN carries flight state, never code.

From Python

with RelayClient() as relay:
    relay.open_session("my-agent")
    pid = relay.program_create("My hover", copy_of="hover_trim")["program"]["id"]
    assert relay.program_validate(pid)["ok"]
    print(relay.program_test(pid)["passed"])                  # unit tests
    print(relay.challenge_submit("hover", pid)["result"])     # headless, hidden seeds
    relay.claim("sim-1"); relay.mode("sim-1", "STABILIZE"); relay.arm("sim-1")
    relay.program_deploy("sim-1", pid, airframe={"preset": "rough", "seed": 7})
    relay.program_params("sim-1", ki=0.2)                     # tune while it flies

Next: Lab, Challenges and Duels.

Clone this wiki locally