Repository navigation
Onboard Programs
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 |
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;
mathis the only import; no classes, files, network or dunder access; 64 KB of source.
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.
| 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.
- 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; itsfireoutput is ignored. - Programs come only from this computer. The LAN carries flight state, never code.
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 fliesNext: Lab, Challenges and Duels.
Get started
Simulation
- Simulator and Physics
- Collisions and Rings
- Firmware Twins and HITL
- PX4 and ArduPilot SITL
- Simulators Compared
Arena
Programs and agents
Tools
Help