Protocol 2

Exact v1 transport, receiver, command, acknowledgement, ownership, and discovery contract.

ESPFlight Docs · v1 • Validated v1 documentation path

# Transport and discovery

Protocol 2 uses UDP only for local discovery and a WebSocket for controller traffic. Firmware v1.0.0 listens for UDP discovery on 4210 and serves its WebSocket on port 81 at path / .

Swipe horizontally to see all columns.

Channel	v1 value	Purpose
UDP	`4210`	Controller discovery broadcast
WebSocket	`ws://<controller-ip>:81/`	Control, configuration, acknowledgements, and telemetry

Discovery advertisement

{"type":"esp","ip":"192.168.1.42","mac":"AA:BB:CC:DD:EE:FF"}

The firmware repeats discovery approximately every 1.5 seconds while discovery is needed. It suppresses the periodic broadcast during a healthy, owned armed control stream.

# Receiver packets

A receiver frame is atomic: all four channels must be present as JSON integers and each value must be between 1000 and 2000 . Partial, mistyped, or out-of-range frames are ignored and do not refresh the control heartbeat.

{"throttle":1000,"roll":1500,"pitch":1500,"yaw":1500}

The first complete valid receiver packet assigns the active WebSocket client as the control owner. Receiver packets from other connected clients are rejected until ownership is released.

# High-level flight commands

ARM, DISARM, Takeoff, and Landing use an explicit command envelope with a mandatory positive request_id .

Request

{"type":"flight_command","cmd":"arm","request_id":42}

Acknowledgement

{"type":"flight_command_ack","cmd":"arm","request_id":42,"ok":true,"message":"..."}

Swipe horizontally to see all columns.

Field	Requirement	Meaning
`type`	`flight_command`	Identifies a high-level request.
`cmd`	`arm` , `disarm` , `takeoff` , or `landing`	Requested state transition.
`request_id`	Positive integer	Correlates the request with its ACK.

Do not treat a button press as the resulting flight state. Use the ACK plus controller telemetry as the authoritative result.

# Connection identity frame

Immediately after a WebSocket client connects, firmware sends the controller MAC identity:

{"type":"mac","mac":"AA:BB:CC:DD:EE:FF"}

# Ownership and security

Trusted-local-network boundary Protocol 2 v1 does not provide encrypted transport or cryptographic client authentication against hostile clients on the same network. Use a private trusted local Wi-Fi network. Single-controller ownership is a safety/state-management mechanism, not a security credential.

If a client changes message shapes or semantics, document and version the compatibility change rather than silently calling it unchanged Protocol 2.