The server exposes 29 tools. This page is generated from the server itself: names, parameters, defaults, descriptions and result types are read from the tool definitions, so they match the code that ships. The descriptions are written for the calling agent, and they are the source of truth for behaviour.
Tools marked read-only change nothing. Destructive ones stop a SITL. A failure the caller can act on (a busy instance, an unknown mode, a refused request) comes back as a tool error whose message says what to do; an arm the autopilot refuses comes back as a normal result with armed: false and the autopilot’s own reason.
Every tool that waits returns within wait_cap_s, about 85 s. A long flight is a loop of bounded waits, each passing since_seq back in.
Session
Step
Wind
Build
Log
Lease
Info
A session is one SITL and the link to it. open_sitl returns the session_id the rest take.
open_sitl
Start a SITL on a leased instance and keep a MAVLink link to it. Returns once home is set, with the session id every other session tool takes. This server's thread then keeps the link alive (GCS heartbeat, RC overrides) between calls. Throttle starts low (RC3 1000). Channel 5 starts at 1800, which is a flight-mode switch position on many parameter sets (FLTMODE_CH 5), so a vehicle may boot in whatever mode that maps to: pass rc={5: <pwm>} to choose, and arm(mode=...) switches before arming either way. The six FLTMODE1 to FLTMODE6 positions are PWM below 1231, 1231 to 1360, 1361 to 1490, 1491 to 1620, 1621 to 1749, and 1750 up; pick a value inside a band (1425 is position 3).
At speedup N, every second you spend between calls passes N sim seconds with the last RC held. idle_speedup=0.05 runs the sim nearly still whenever no call is in flight, which makes your pace irrelevant to the flight. Close it with close_sitl; idle sessions close themselves after session_idle_s.
Returns OpenResult
snapshotread-only
The session's state now: armed, mode, height, attitude, speeds, battery, RC sent, servo outputs, mission item, recent autopilot texts, and seq for wait_until.
Returns Snapshot
get_paramread-only
Read parameters back from the autopilot.
Returns dict[str, float]
set_param
Set parameters and return the values the autopilot reports back.
Returns dict[str, float]
set_mode
Switch flight mode (QLOITER, QHOVER, QLAND, QRTL, AUTO, FBWA, RTL, ...) and confirm it from the autopilot's HEARTBEAT within 5 sim seconds.
Returns Snapshot
arm
Throttle low, switch mode, arm, retrying every 3 sim seconds while pre-arm checks settle. On refusal returns armed false with the autopilot's last PreArm text. Heights are measured from where it armed.
Returns ArmResult
disarm
Force a disarm, in the air too.
Returns Snapshot
set_speedup
Change how fast the session's SITL runs, live. Slow it down to think or to watch a manoeuvre closely, speed it up for cruise legs. wait_until's then_speedup does the same the instant a condition is met.
Returns Snapshot
rc_override
Set the RC override this server sends with every pump.
Returns dict
upload_mission
Upload a mission in metres from home. Home goes in as item 0, so items[i] is mission item i + 1. Retries while ArduPilot ignores mission traffic after boot.
Returns dict
wait_untilread-only
Wait until a condition holds, its timeout of sim time passes, or SITL dies. Always returns a snapshot and a reason: met, timeout, died, cap, or closed if the session was closed meanwhile. One call blocks at most about 85 s of wall time (reason cap): loop with since_seq for longer flights.
At speedup N every second you spend between calls is N sim seconds with the old RC still held, so "wait, then react" overshoots. then_rc, then_mode and then_speedup react in the same tick the condition is met, applied by the server: wait_until altitude >= 5 with then_rc {3: 1500} stops a climb at 5 m. For timing, use sim_time with a target read off snapshot.t_sim_s ("hover until t = 230"), not time, which counts from this call. When the wait settles inside the server (met, timeout, died) the snapshot is taken in that same tick: a measurement at that moment.
Returns WaitResult
close_sitldestructive
Kill the session's SITL, free its instance, and move the kept dataflash logs out to the server's log directory. A session that died is removed the same way; its logs were already handled by its own keep_logs when it died, so keep_logs here applies only to a live session.
Returns CloseResult
list_sessionsread-only
This server's sessions, open or died (a died session stays until close_sitl).
Returns list[SessionInfo]
A step program runs a manoeuvre inside the server, applying each step’s actions in the tick it starts. The step fields are on Step, wind and mission fields.
fly_steps
Fly a sequence of steps inside the server, with no round trip between them. A step applies its actions (rc, mode, speedup, params) in the tick it starts, then waits until its condition holds (the same conditions as wait_until) or timeout_s sim seconds pass; the next step starts in that same tick. A step without until ends as soon as its actions apply.
Every step is checked (mode names, channels, PWM, values, speedup range) before anything runs, and one bad step rejects the program. Arm with the arm tool first; a program cannot arm or upload a mission. One program per session at a time.
Returns within about 85 s: status done, failed or aborted with every step's result (reason, start and end sim time, a snapshot taken in its settling tick), or status running with the steps settled so far and the current index, followed with steps_status. On an idle-paced session a running program keeps the sim at full speed, waited on or not, and idle applies once it ends.
Hover hop, after arm(mode="QLOITER"): [{rc: {3: 2000}, until: "altitude", value: 5}, {rc: {3: 1500}, until: "sim_time", value: 15, relative: true}, {mode: "QLAND", until: "disarmed", timeout_s: 120}].
Returns StepsResult
steps_statusread-only
The session's latest step program: its status, the current step, and the results so far. Follow a program longer than one fly_steps call with this.
Returns StepsResult
abort_steps
Stop the running step program after the current tick. RC stays as last set, so set the throttle (rc_override) or a mode next. A finished program is returned unchanged.
Returns StepsResult
Mean wind and gusts, applied on sim time. The fields are on Step, wind and mission fields.
set_wind
Set the session's wind: a mean speed and direction, an optional updraft, and gusts. Dryden gusts are computed by the server every 0.05 sim s from the current height and airspeed and sent to SITL as SIM_WIND_*, so they evolve through every wait. {speed_mps: 0} stops the wind. A step program's wind action does the same mid-program.
Returns Snapshot
wind_historyread-only
The gusts the session flew: rows of sim time, the gust along the mean wind (u), across it (v) and up (w), and the SIM_WIND_* values SITL was given.
Returns dict
Compile a SITL binary with waf as a background job, and follow it. Which trees may be built, and the Python waf runs under, are in Build a SITL binary.
build_sitl
Build a SITL binary with ArduPilot's waf, as a background job: ./waf configure --board sitl when needed, then ./waf plane (or another vehicle). Waits up to about 85 s and returns the job's state; a longer build keeps going, so follow it with build_status. A first build takes minutes, an incremental one about half a minute. Only trees named in MCARDUPILOT_BUILD_TREES are built, plus the default tree while its git checkout is clean, so a patched tree other runs depend on is never rebuilt by accident. On success the result carries the binary's path and provenance (tree SHA, patch hash, build time).
Container mode (give image and commit) builds explicit inputs instead: a fresh checkout of commit from tree (submodules from the tree's own, offline), patches applied in order, built in the image with no network. The output goes to <data_dir>/builds/<build_id>/ in tree layout with manifest.json; open_sitl's tree argument flies it. build_id is a hash of the inputs, so the same inputs answer from the finished build at once (cached: true).
Returns dict
build_statusread-only
A build's state: queued, staging, configuring, building, verifying, done, failed or cancelled, with waf's step count, and on failure the last log lines.
Returns dict
cancel_builddestructive
Stop a running build (its whole process group). The tree is left as waf left it; the next build carries on from there.
Returns dict
list_buildsread-only
This server's builds, newest last.
Returns list[dict]
A log is named by a session id (its live log, while the session is open), a kept log’s name from list_logs, or a path to a .BIN. Over the HTTP transport, only paths under the server’s data directory are read.
list_logsread-only
Dataflash logs this server keeps (close_sitl moves them here), newest first, and the live log of each open session.
Returns list[dict]
log_summaryread-only
A flight by phase: each span between flight-mode changes (and, in AUTO, mission items) with its duration and averages of airspeed, groundspeed, throttle, lift motors, pitch, peak roll, angle of attack, current and voltage, and peak height; plus the firmware, every autopilot text with its time, and message counts. Times are seconds since boot, as in the log.
Returns dict
log_fieldsread-only
A time series from the log: rows of [t_s, *fields] with each column's unit. An unknown message or column is answered with the ones the log does have.
Returns dict
log_messagesread-only
Whole log messages of the given types in time order, every field included; "more" says the limit cut the list short.
Returns dict
log_compareread-only
Flight B against flight A, for an A/B test (the same flight with a parameter or model file changed). Every number is {a, b, delta, pct}: delta is b - a, pct is delta as a percent of |a|, null when a is 0 or missing.
phases: each flight's log_summary phases are keyed by (mode, armed, mission_item) and matched in order, by longest common subsequence: a phase only one flight has is listed under only_in_a or only_in_b with its index, and every later pair still lines up. matched holds each pair's indexes, times and metrics (duration_s, energy_wh, airspeed, throttle, lift, current, peak height and the rest). totals: whole-log duration, energy in Wh (BAT volts times amps, integrated), peak height and peak current. params: changed {name: {a, b}}, only_in_a and only_in_b {name: value}, and how many are the same; often the whole point of the comparison, so check it first. Values ArduPilot rewrites itself every flight (STAT_*, *_GND_PRESS) are kept apart under bookkeeping. texts: autopilot messages one flight printed and the other did not, ignoring times, the firmware banner and the build hash line; messages that differ only in their numbers ("Reached waypoint #2 dist 91m" against 77m) are grouped under numbers_differ by a template with {n} for each number. same_firmware compares the banners, which carry the build's git hash.
Returns dict
pin_log
Spare a kept log from pruning, or let pruning take it again. Kept logs past log_budget_gb (server_info) are deleted oldest first whenever a close keeps one.
Returns dict
Leases for SITLs you launch yourself, and the view of who holds what.
lease_instance
Reserve a SITL instance for something you launch yourself (a script, sim_vehicle.py -I <n>). The instance's lock is held by this server until release_instance or the server exits, and other sessions and scripts skip it. open_sitl leases its own instance; sessions do not need this.
Returns dict
release_instance
Give back an instance taken with lease_instance. Sessions release theirs at close_sitl.
Returns dict
kill_instancedestructive
Stop whatever SITL runs on an instance. This server's own session there is closed (its logs kept per its keep_logs). A SITL that no lease covers (a stray from a crashed script, autotest.py, make fly) is killed if the process on its ports is a SITL binary. An instance leased by someone else is refused, with the holder named: only its holder may stop it.
Returns dict
list_instancesread-only
Every instance that is leased (by any process, in or out of the pool) or has its ports taken without a lease, with the holder, this server's session on it, and the process on each taken port.
Returns list[InstanceInfo]
server_inforead-only
Server version, the ArduPilot tree and SITL binary (with its build time), the instance pool and who holds each leased instance, and the server's limits.
Returns ServerInfo
The result types the tools above return that have no page of their own. Snapshot is on Snapshot fields, WaitResult on Wait conditions and reasons, and the step results on Step, wind and mission fields.
