Docs / Developer / Telemetry Protocol

Telemetry Protocol

Exact v1 telemetry envelope, update rate, field semantics, and client rules.

ESPFlight Docs · v1 • Validated v1 documentation path

# Update schedule

Firmware v1.0.0 emits the main telemetry envelope every 200 ms (5 Hz) while disarmed and every 1000 ms (1 Hz) while armed. Flight-state and failsafe transitions trigger an immediate update instead of waiting for the next periodic interval.

# Main telemetry envelope

{
  "type":"main",
  "armed":false,
  "mac":"AA:BB:CC:DD:EE:FF",
  "boot_session_id":123,
  "flight_session_id":7,
  "flightTime":{"type":"flightTime","seconds":18},
  "altitude":{"available":true,"ready":true,"healthy":true,"mm":498,"target_mm":500,"pid":2.4,"assist_active":true,"mode":"hold"},
  "failsafe":{"active":false,"reason":0,"link_loss":false,"low_battery":false,"landing":false,"battery_lockout":false},
  "system":{"type":"system","rssi":-51,"bat":3.31,"firmware_version":"1.0.0","protocol_version":2}
}

A loopTime object is included when valid timing samples are available, with curr , avg , and hz .

# Field semantics

Swipe horizontally to see all columns.

Field	Meaning
`armed`	Controller-reported ARM state; use this as authoritative UI state.
`boot_session_id`	Changes across controller boots/restarts.
`flight_session_id`	Identifies the current powered-flight timing session.
`flightTime.seconds`	Current or most recently completed powered-flight time, not total ARMED duration.
`altitude.*`	Optional VL53L0X/assist availability, freshness, height, target, PID contribution, and mode.
`failsafe.reason`	Reason bit mask; convenience Booleans expose link loss and low battery.
`system.rssi`	Current Wi-Fi RSSI in dBm.
`system.bat`	Firmware battery/supply-voltage proxy used by the v1 platform.
`system.firmware_version`	Exact firmware release identity.
`system.protocol_version`	Protocol compatibility identity.

# Client rules

Do not infer ARM or failsafe state from a local button animation.

Tolerate the optional loopTime object and future additive fields.

Check firmware and protocol versions before enabling incompatible controls.

Keep safety-critical transitions synchronized with firmware ACKs and telemetry.