Wait conditions and reasons

wait_until and a step’s until share one closed set of conditions. They are evaluated on the session’s pump thread after every MAVLink message, against the latest message of each type, never as arbitrary code.

Conditions

Condition	Needs value	Reads	op applies
altitude	number, m	height_m: from SITL’s true position, above the pad since arm, otherwise GLOBAL_POSITION_INT.relative_alt above home	yes
airspeed	number, m/s	VFR_HUD.airspeed	yes
waypoint	number	MISSION_CURRENT.seq, the current mission item	yes
sim_time	number, s	the autopilot clock, SYSTEM_TIME.time_boot_ms, as in snapshot.t_sim_s	yes
time	number, s	sim seconds since the wait was registered	no, always at least value
mode	mode name	the flight mode the autopilot’s heartbeat reports, case-insensitive	no, equality
text	text	any STATUSTEXT containing value that arrived after since_seq	no, substring
armed	none	the armed flag in the autopilot’s heartbeat	no
disarmed	none	the same flag, cleared	no
landed	none	EXTENDED_SYS_STATE.landed_state on the ground; before that message arrives, disarmed and within 0.3 m of the pad	no

op is >= (the default), <= or ==. A condition whose message has not arrived yet is never met: an airspeed wait before the first VFR_HUD waits.

time counts from this call and sim_time from boot. For anything scheduled, read snapshot.t_sim_s and wait on sim_time with an absolute target, or pass relative: true. In wait_until, a relative sim_time counts from the tick the previous wait or step on this session settled, and fails if none has. In a step it counts from the tick the step started, which is the tick the previous step settled.

since_seq matters for text. A wait counts texts whose seq is after it, so passing the seq of the last snapshot you saw catches a text that arrived between that snapshot and this call. Without it, only texts after the call count.

Reactions

then_rc, then_mode and then_speedup are applied by the pump thread in the tick the condition is met, before the reply leaves. They do nothing on timeout. If the condition already holds when the call arrives, the reaction is applied at once and the wait returns met with waited_sim_s: 0.

Reasons

Reason	wait_until	Step	Meaning
met	yes	yes	the condition held
timeout	yes	yes	timeout_s sim seconds passed first. A step with on_timeout: "stop" fails the program; with continue the next step starts
cap	yes	no	the call’s wall-clock limit, wait_cap_s, came first. The wait is not over: call again with since_seq set to snapshot.seq
died	yes	yes	SITL exited, PANICked, lost the link, or its clock stopped for stall_s. snapshot.error says which
closed	yes	no	the session was closed (by close_sitl, kill_instance or the idle reaper) during the wait
aborted	no	yes	abort_steps or close_sitl ended the program, or an internal error named in the program’s error

timeout_s is in sim seconds and wait_cap_s in wall seconds, so which comes first depends on the speedup. At speedup 10, a timeout_s of 60 is six wall seconds and the cap never matters. At an idle speed of 0.05, the cap comes first almost always.

Which snapshot you got

snapshot_at: "settle" means the snapshot was taken in the tick the wait settled inside the server (met, timeout, died), a measurement at that moment. "return" means it was taken as the call returned, after a cap or when the condition was already true.

WaitResult

Field	Type	Meaning
satisfied	bool
reason	str	met; timeout (timeout_s of sim time passed); died (SITL died, see snapshot.error); cap (the call's wall-clock limit came first: call again with since_seq=snapshot.seq to keep waiting); closed (the session was closed during the wait)
waited_sim_s	float
waited_wall_s	float
snapshot_at	str	settle: taken in the tick the wait settled; return: taken as the call returned (cap, or already true)
snapshot	Snapshot