Docs / Developer / Configuration Protocol

Configuration Protocol

Exact PID keys, ranges, validation, ownership, persistence, and acknowledgement behavior in v1.

ESPFlight Docs · v1 • Validated v1 documentation path

# PID configuration message

Firmware v1.0.0 accepts partial PID updates through the WebSocket. A packet is treated as PID configuration when type or cmd is pid , or when it contains a supported PID key.

{"type":"pid","request_id":17,"kp_roll":1.20,"ki_roll":0.03,"kd_roll":8.0,"kp_yaw":2.0}

request_id is echoed in the response. Legacy requests may use zero, but new clients should send a positive identifier for deterministic correlation.

# Supported keys and ranges

Swipe horizontally to see all columns.

Group	Keys	Valid range
P	`kp_roll` , `kp_pitch` , `kp_yaw` , `kp_alt`	`0…50`
I	`ki_roll` , `ki_pitch` , `ki_yaw` , `ki_alt`	`0…10`
D	`kd_roll` , `kd_pitch` , `kd_yaw` , `kd_alt`	`0…500`

If a Roll key changes while the corresponding Pitch key is omitted, the v1 firmware mirrors that new Roll value to Pitch. Explicit Pitch keys override that convenience behavior.

# Validation, ownership, and persistence

PID changes are accepted only when the controller is fully disarmed.

If a control owner exists, only that WebSocket client may change PID values.

Every supplied value must be a finite JSON number inside the firmware bounds; otherwise the whole request is rejected before live gains change.

Accepted gains are committed to EEPROM before success is reported.

If EEPROM persistence fails, runtime gains are rolled back to the previous set.

# PID acknowledgement

{"type":"pid_ack","request_id":17,"ok":true,"message":"pid_saved_and_applied"}

Treat ok as authoritative. The stable short message code explains rejection or persistence failure and should be surfaced for diagnostics instead of silently assuming success.