> For the complete documentation index, see [llms.txt](https://dronebridge.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dronebridge.gitbook.io/docs/dronebridge-for-esp32-drone-light-show-edition/developers-dlse-api-definition/settings.md).
# Settings
Read and write device configuration
## Get all device settings
> Returns all internally stored configuration parameters together with their data-type metadata. The exact set of keys mirrors the firmware's settings.csv table that is used to flash the firmware with pre-applied settings.
```json
{"openapi":"3.0.3","info":{"title":"DroneBridge ESP32 REST API","version":"1.0.0"},"tags":[{"name":"Settings","description":"Read and write device configuration"}],"servers":[{"url":"http://192.168.2.1","description":"Default ESP32 AP address"}],"paths":{"/api/settings":{"get":{"tags":["Settings"],"summary":"Get all device settings","description":"Returns all internally stored configuration parameters together with their data-type metadata. The exact set of keys mirrors the firmware's settings.csv table that is used to flash the firmware with pre-applied settings.\n","operationId":"getSettings","responses":{"200":{"description":"Settings retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsResponse"}}}}}}}},"components":{"schemas":{"SettingsResponse":{"description":"Response to `GET /api/settings`.\n","allOf":[{"$ref":"#/components/schemas/SettingsParams"},{"type":"object","description":"Per-parameter data-type metadata keys (one per parameter, suffix `_type`).","additionalProperties":{"type":"string"}}]},"SettingsParams":{"type":"object","description":"All configurable firmware parameters. Boolean parameters are represented as `0`/`1` (UINT8 min/max false/true). GPIO parameters accept any valid ESP32 GPIO number (0 – maximum supported GPIO by the chip).\n","properties":{"esp32_mode":{"type":"integer","description":"Radio/operating mode of the ESP32. Must not be changed at runtime; only takes effect after reboot. 1 = Wi-Fi AP, 802.11b, 2 = Wi-Fi client, 802.11b,\n","enum":[1,2],"default":1},"ssid":{"type":"string","description":"Wi-Fi SSID to connect to in client (STA) mode.","minLength":1,"maxLength":32,"default":"DroneBridge for ESP32"},"ssid_ap":{"type":"string","description":"SSID broadcast by the ESP32 in Wi-Fi AP mode.","minLength":1,"maxLength":32,"default":"DroneBridge for ESP32"},"wifi_pass":{"type":"string","description":"Password for Wi-Fi connections and ESP-NOW encryption.","minLength":7,"maxLength":64,"default":"dronebridge"},"wifi_pass_ap":{"type":"string","description":"Password for the Wi-Fi access point in AP mode.","minLength":7,"maxLength":64,"default":"dronebridge"},"ap_ip":{"type":"string","format":"ipv4","description":"IPv4 address assigned to the ESP32 when operating in Wi-Fi AP mode.","minLength":8,"maxLength":16,"default":"192.168.2.1"},"ip_sta":{"type":"string","format":"ipv4","description":"Static IPv4 address used in Wi-Fi client (STA) mode. Leave empty to use DHCP. If set, ip_sta_gw and ip_sta_netmsk must also be provided.\n","minLength":0,"maxLength":16,"default":""},"ip_sta_gw":{"type":"string","format":"ipv4","description":"Gateway IP address used when a static IP (ip_sta) is configured in STA mode.\n","minLength":0,"maxLength":16,"default":""},"ip_sta_netmsk":{"type":"string","description":"Subnet mask used when a static IP (ip_sta) is configured in STA mode.","minLength":0,"maxLength":16,"default":""},"udp_client_ip":{"type":"string","format":"ipv4","description":"IPv4 address of the first/persisted UDP client target. Only this entry is saved to NVM; additional clients can be registered at runtime via POST /api/settings/clients/udp. Leave empty if no persistent UDP client is needed.\n","minLength":0,"maxLength":16,"default":""},"wifi_hostname":{"type":"string","description":"mDNS/DHCP hostname of the ESP32, used in both AP and STA mode. Defaults to the lwIP CONFIG_LWIP_LOCAL_HOSTNAME compile-time value.\n","minLength":1,"maxLength":32,"default":"dronebridge"},"wifi_chan":{"type":"integer","description":"Wi-Fi channel used in AP and ESP-NOW mode.","minimum":1,"maximum":165,"default":6},"wifi_en_gn":{"type":"integer","description":"Allow 802.11b/g/n(/ax) mode. `0` = 802.11b only (best range); `1` = b/g/n/ax where supported.\n","enum":[0,1],"default":0},"wifi_dis_udpdet":{"type":"integer","description":"Disable automatic UDP client detection. When `1`, only manually registered UDP clients receive serial traffic; senders of incoming UDP packets are no longer auto-added.\n","enum":[0,1],"default":0},"udp_local_port":{"type":"integer","description":"Local UDP port the ESP32 listens on for incoming GCS messages.","minimum":1,"maximum":65535,"default":14555},"wifi_brcst_nudp":{"type":"integer","description":"Broadcast serial data to the broadcast address when no known UDP client exists, enabling auto-detection by GCS tools like Skybrush.\n","enum":[0,1],"default":1},"wifi_brcst_port":{"type":"integer","description":"UDP port used for broadcast transmissions when no known UDP client is registered (linked to `wifi_brcst_nudp`).\n","minimum":1,"maximum":65535,"default":14550},"radio_ant_selec":{"type":"integer","description":"Antenna selection. Maps to `DB_ANTENNA_SELECTION_*` constants: `0` = internal, `1` = external, `2` = auto diversity (not supported for now). Diversity requires a hardware RF switch (e.g. SeeedStudio ESP32-C6).\n","minimum":0,"maximum":2,"default":0},"radio_ant_sw":{"type":"integer","description":"GPIO number connected to the external antenna switch signal. Set to `0` to disable.\n","minimum":0,"default":0},"radio_ant_en":{"type":"integer","description":"GPIO used to enable the external antenna switch circuit. Set to `0` if not needed.\n","minimum":0,"default":0},"baud":{"type":"integer","description":"UART baud rate. Stick to the options available in the web ui to prevent issues.","minimum":1200,"maximum":5000000,"default":115200},"gpio_tx":{"type":"integer","description":"GPIO number of the UART TX pin.","minimum":0},"gpio_rx":{"type":"integer","description":"GPIO number of the UART RX pin.","minimum":0},"gpio_rts":{"type":"integer","description":"GPIO number of the UART RTS pin. Set to the same value as `gpio_cts` to disable hardware flow control.\n","minimum":0},"gpio_cts":{"type":"integer","description":"GPIO number of the UART CTS pin. Set to the same value as `gpio_rts` to disable hardware flow control.\n","minimum":0},"rts_thresh":{"type":"integer","description":"UART RTS threshold. Controls when the RTS line is asserted. Leave at the default unless you have a specific reason to change it.\n","minimum":1,"maximum":127,"default":127},"proto":{"type":"integer","description":"Serial telemetry protocol / parser. Maps to `DB_SERIAL_PROTOCOL_*` constants: `0` = MAVLink (parsed, only complete frames forwarded); `4` = Transparent (raw pass-through).\n","enum":[0,4],"default":0},"trans_pack_size":{"type":"integer","description":"Maximum payload size (bytes) per over-the-air packet in transparent or MAVLink mode. Stick to the options in the web UI to prevent issues\n","minimum":16,"maximum":1056,"default":576},"serial_timeout":{"type":"integer","description":"Serial read timeout in milliseconds. After this period without new bytes the accumulated data is sent over the air even if `trans_pack_size` has not been reached.\n","minimum":1,"maximum":65535,"default":50},"udp_client_port":{"type":"integer","description":"Remote port of the persisted UDP client / GCS endpoint. `0` means no client is persisted.\n","minimum":0,"maximum":65535,"default":0},"rep_rssi_dbm":{"type":"integer","description":"RSSI reporting unit in MAVLink RADIO_STATUS messages. `1` = dBm (QGroundControl); `0` = 0-100 percentage (Mission Planner).\n","enum":[0,1],"default":1},"show_det_flash":{"type":"integer","description":"Enable detection of the flight controller entering firmware-flash mode so the ESP32 can react accordingly.\n","enum":[0,1],"default":1},"show_ap_fail_to":{"type":"integer","description":"Timeout in milliseconds for the ESP32 to connect to the configured access point in STA mode. If the timeout expires a failsafe AP is started using the AP-mode settings.\n","minimum":0,"default":90000},"show_pm_en_hb":{"type":"integer","description":"Emit a fake MAVLink heartbeat on behalf of the flight controller while it is powered down, so the GCS does not lose the connection.\n","enum":[0,1],"default":1},"show_pm_en":{"type":"integer","description":"Enable the ESP32 power-management subsystem for the flight controller. Must be supported by the hardware.\n","enum":[0,1],"default":0},"show_pm_gpio":{"type":"integer","description":"GPIO number connected to the flight-controller power control pin.","minimum":0},"show_pm_logic":{"type":"integer","description":"Logic level of the power control GPIO. Maps to `DB_PM_LOGIC_*`: `0` = active-low; `1` = active-high.\n","enum":[0,1]},"show_pm_pulse_l":{"type":"integer","description":"Duration in milliseconds of the pulse on the power control GPIO when it emulates a toggle button. Set to `0` for level-triggered (latching) power control.\n","minimum":0,"maximum":65535,"default":0},"show_pm_qu_gpio":{"type":"integer","description":"GPIO used to sense whether the flight controller is currently powered. Set to `0` to disable power-state sensing.\n","minimum":0,"default":0},"show_pm_en_emcy":{"type":"integer","description":"Allow the power-off command to execute even while the drone is armed or in an unknown state. Intended for emergency power-off (e.g. Skybrush kill button).\n","enum":[0,1],"default":0},"show_en_syid_ip":{"type":"integer","description":"Derive the MAVLink system ID from the last octet of the configured static IPv4 address instead of `show_man_sysid`. The system ID is also overwritten the first time a MAVLink packet with a system ID is received from the flight controller.\n","enum":[0,1],"default":1},"show_man_sysid":{"type":"integer","description":"Manually assigned MAVLink system ID used until the flight controller's system ID is learned or `show_en_syid_ip` takes over.\n","minimum":0,"maximum":255,"default":1},"adc_v_en":{"type":"integer","description":"Enable battery voltage monitoring via the ESP32 ADC.","enum":[0,1],"default":0},"adc_v_gpio":{"type":"integer","description":"GPIO number connected to the battery voltage sense circuit.","minimum":0,"default":0},"adc_v_multi":{"type":"integer","description":"Voltage ADC multiplier / scaling factor used to convert the raw ADC reading to actual battery voltage.\n","minimum":1,"maximum":65535,"default":110},"adc_a_en":{"type":"integer","description":"Enable battery current monitoring via the ESP32 ADC.","enum":[0,1],"default":0},"adc_a_gpio":{"type":"integer","description":"GPIO number connected to the battery current sense circuit.","minimum":0,"default":0},"adc_a_multi":{"type":"integer","description":"Current ADC multiplier in mA/V used to convert the raw ADC reading to actual current draw.\n","minimum":1,"default":36364}}}}}}
```
## Update device settings
> Accepts a JSON object whose keys are parameter names. Only the keys that are present are updated; all others keep their current values. \*\*The device will reboot automatically after persisting the new settings.\*\* Returns an error if the drone is currently armed.
```json
{"openapi":"3.0.3","info":{"title":"DroneBridge ESP32 REST API","version":"1.0.0"},"tags":[{"name":"Settings","description":"Read and write device configuration"}],"servers":[{"url":"http://192.168.2.1","description":"Default ESP32 AP address"}],"paths":{"/api/settings":{"post":{"tags":["Settings"],"summary":"Update device settings","description":"Accepts a JSON object whose keys are parameter names. Only the keys that are present are updated; all others keep their current values. **The device will reboot automatically after persisting the new settings.** Returns an error if the drone is currently armed.\n","operationId":"postSettings","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsRequest"}}}},"responses":{"200":{"description":"Settings accepted; device will reboot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}},"400":{"description":"Request body too large (≥ 10 240 bytes)","content":{"text/plain":{"schema":{"type":"string"}}}},"422":{"description":"Drone is armed – settings cannot be changed while armed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}},"500":{"description":"Internal server error while receiving data","content":{"text/plain":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"SettingsRequest":{"description":"Body for `POST /api/settings`. Send only the keys you want to change; all others keep their current values. Key names must exactly match the `db_name` field of the firmware parameter table.\n","allOf":[{"$ref":"#/components/schemas/SettingsParams"}]},"SettingsParams":{"type":"object","description":"All configurable firmware parameters. Boolean parameters are represented as `0`/`1` (UINT8 min/max false/true). GPIO parameters accept any valid ESP32 GPIO number (0 – maximum supported GPIO by the chip).\n","properties":{"esp32_mode":{"type":"integer","description":"Radio/operating mode of the ESP32. Must not be changed at runtime; only takes effect after reboot. 1 = Wi-Fi AP, 802.11b, 2 = Wi-Fi client, 802.11b,\n","enum":[1,2],"default":1},"ssid":{"type":"string","description":"Wi-Fi SSID to connect to in client (STA) mode.","minLength":1,"maxLength":32,"default":"DroneBridge for ESP32"},"ssid_ap":{"type":"string","description":"SSID broadcast by the ESP32 in Wi-Fi AP mode.","minLength":1,"maxLength":32,"default":"DroneBridge for ESP32"},"wifi_pass":{"type":"string","description":"Password for Wi-Fi connections and ESP-NOW encryption.","minLength":7,"maxLength":64,"default":"dronebridge"},"wifi_pass_ap":{"type":"string","description":"Password for the Wi-Fi access point in AP mode.","minLength":7,"maxLength":64,"default":"dronebridge"},"ap_ip":{"type":"string","format":"ipv4","description":"IPv4 address assigned to the ESP32 when operating in Wi-Fi AP mode.","minLength":8,"maxLength":16,"default":"192.168.2.1"},"ip_sta":{"type":"string","format":"ipv4","description":"Static IPv4 address used in Wi-Fi client (STA) mode. Leave empty to use DHCP. If set, ip_sta_gw and ip_sta_netmsk must also be provided.\n","minLength":0,"maxLength":16,"default":""},"ip_sta_gw":{"type":"string","format":"ipv4","description":"Gateway IP address used when a static IP (ip_sta) is configured in STA mode.\n","minLength":0,"maxLength":16,"default":""},"ip_sta_netmsk":{"type":"string","description":"Subnet mask used when a static IP (ip_sta) is configured in STA mode.","minLength":0,"maxLength":16,"default":""},"udp_client_ip":{"type":"string","format":"ipv4","description":"IPv4 address of the first/persisted UDP client target. Only this entry is saved to NVM; additional clients can be registered at runtime via POST /api/settings/clients/udp. Leave empty if no persistent UDP client is needed.\n","minLength":0,"maxLength":16,"default":""},"wifi_hostname":{"type":"string","description":"mDNS/DHCP hostname of the ESP32, used in both AP and STA mode. Defaults to the lwIP CONFIG_LWIP_LOCAL_HOSTNAME compile-time value.\n","minLength":1,"maxLength":32,"default":"dronebridge"},"wifi_chan":{"type":"integer","description":"Wi-Fi channel used in AP and ESP-NOW mode.","minimum":1,"maximum":165,"default":6},"wifi_en_gn":{"type":"integer","description":"Allow 802.11b/g/n(/ax) mode. `0` = 802.11b only (best range); `1` = b/g/n/ax where supported.\n","enum":[0,1],"default":0},"wifi_dis_udpdet":{"type":"integer","description":"Disable automatic UDP client detection. When `1`, only manually registered UDP clients receive serial traffic; senders of incoming UDP packets are no longer auto-added.\n","enum":[0,1],"default":0},"udp_local_port":{"type":"integer","description":"Local UDP port the ESP32 listens on for incoming GCS messages.","minimum":1,"maximum":65535,"default":14555},"wifi_brcst_nudp":{"type":"integer","description":"Broadcast serial data to the broadcast address when no known UDP client exists, enabling auto-detection by GCS tools like Skybrush.\n","enum":[0,1],"default":1},"wifi_brcst_port":{"type":"integer","description":"UDP port used for broadcast transmissions when no known UDP client is registered (linked to `wifi_brcst_nudp`).\n","minimum":1,"maximum":65535,"default":14550},"radio_ant_selec":{"type":"integer","description":"Antenna selection. Maps to `DB_ANTENNA_SELECTION_*` constants: `0` = internal, `1` = external, `2` = auto diversity (not supported for now). Diversity requires a hardware RF switch (e.g. SeeedStudio ESP32-C6).\n","minimum":0,"maximum":2,"default":0},"radio_ant_sw":{"type":"integer","description":"GPIO number connected to the external antenna switch signal. Set to `0` to disable.\n","minimum":0,"default":0},"radio_ant_en":{"type":"integer","description":"GPIO used to enable the external antenna switch circuit. Set to `0` if not needed.\n","minimum":0,"default":0},"baud":{"type":"integer","description":"UART baud rate. Stick to the options available in the web ui to prevent issues.","minimum":1200,"maximum":5000000,"default":115200},"gpio_tx":{"type":"integer","description":"GPIO number of the UART TX pin.","minimum":0},"gpio_rx":{"type":"integer","description":"GPIO number of the UART RX pin.","minimum":0},"gpio_rts":{"type":"integer","description":"GPIO number of the UART RTS pin. Set to the same value as `gpio_cts` to disable hardware flow control.\n","minimum":0},"gpio_cts":{"type":"integer","description":"GPIO number of the UART CTS pin. Set to the same value as `gpio_rts` to disable hardware flow control.\n","minimum":0},"rts_thresh":{"type":"integer","description":"UART RTS threshold. Controls when the RTS line is asserted. Leave at the default unless you have a specific reason to change it.\n","minimum":1,"maximum":127,"default":127},"proto":{"type":"integer","description":"Serial telemetry protocol / parser. Maps to `DB_SERIAL_PROTOCOL_*` constants: `0` = MAVLink (parsed, only complete frames forwarded); `4` = Transparent (raw pass-through).\n","enum":[0,4],"default":0},"trans_pack_size":{"type":"integer","description":"Maximum payload size (bytes) per over-the-air packet in transparent or MAVLink mode. Stick to the options in the web UI to prevent issues\n","minimum":16,"maximum":1056,"default":576},"serial_timeout":{"type":"integer","description":"Serial read timeout in milliseconds. After this period without new bytes the accumulated data is sent over the air even if `trans_pack_size` has not been reached.\n","minimum":1,"maximum":65535,"default":50},"udp_client_port":{"type":"integer","description":"Remote port of the persisted UDP client / GCS endpoint. `0` means no client is persisted.\n","minimum":0,"maximum":65535,"default":0},"rep_rssi_dbm":{"type":"integer","description":"RSSI reporting unit in MAVLink RADIO_STATUS messages. `1` = dBm (QGroundControl); `0` = 0-100 percentage (Mission Planner).\n","enum":[0,1],"default":1},"show_det_flash":{"type":"integer","description":"Enable detection of the flight controller entering firmware-flash mode so the ESP32 can react accordingly.\n","enum":[0,1],"default":1},"show_ap_fail_to":{"type":"integer","description":"Timeout in milliseconds for the ESP32 to connect to the configured access point in STA mode. If the timeout expires a failsafe AP is started using the AP-mode settings.\n","minimum":0,"default":90000},"show_pm_en_hb":{"type":"integer","description":"Emit a fake MAVLink heartbeat on behalf of the flight controller while it is powered down, so the GCS does not lose the connection.\n","enum":[0,1],"default":1},"show_pm_en":{"type":"integer","description":"Enable the ESP32 power-management subsystem for the flight controller. Must be supported by the hardware.\n","enum":[0,1],"default":0},"show_pm_gpio":{"type":"integer","description":"GPIO number connected to the flight-controller power control pin.","minimum":0},"show_pm_logic":{"type":"integer","description":"Logic level of the power control GPIO. Maps to `DB_PM_LOGIC_*`: `0` = active-low; `1` = active-high.\n","enum":[0,1]},"show_pm_pulse_l":{"type":"integer","description":"Duration in milliseconds of the pulse on the power control GPIO when it emulates a toggle button. Set to `0` for level-triggered (latching) power control.\n","minimum":0,"maximum":65535,"default":0},"show_pm_qu_gpio":{"type":"integer","description":"GPIO used to sense whether the flight controller is currently powered. Set to `0` to disable power-state sensing.\n","minimum":0,"default":0},"show_pm_en_emcy":{"type":"integer","description":"Allow the power-off command to execute even while the drone is armed or in an unknown state. Intended for emergency power-off (e.g. Skybrush kill button).\n","enum":[0,1],"default":0},"show_en_syid_ip":{"type":"integer","description":"Derive the MAVLink system ID from the last octet of the configured static IPv4 address instead of `show_man_sysid`. The system ID is also overwritten the first time a MAVLink packet with a system ID is received from the flight controller.\n","enum":[0,1],"default":1},"show_man_sysid":{"type":"integer","description":"Manually assigned MAVLink system ID used until the flight controller's system ID is learned or `show_en_syid_ip` takes over.\n","minimum":0,"maximum":255,"default":1},"adc_v_en":{"type":"integer","description":"Enable battery voltage monitoring via the ESP32 ADC.","enum":[0,1],"default":0},"adc_v_gpio":{"type":"integer","description":"GPIO number connected to the battery voltage sense circuit.","minimum":0,"default":0},"adc_v_multi":{"type":"integer","description":"Voltage ADC multiplier / scaling factor used to convert the raw ADC reading to actual battery voltage.\n","minimum":1,"maximum":65535,"default":110},"adc_a_en":{"type":"integer","description":"Enable battery current monitoring via the ESP32 ADC.","enum":[0,1],"default":0},"adc_a_gpio":{"type":"integer","description":"GPIO number connected to the battery current sense circuit.","minimum":0,"default":0},"adc_a_multi":{"type":"integer","description":"Current ADC multiplier in mA/V used to convert the raw ADC reading to actual current draw.\n","minimum":1,"default":36364}}},"StatusResponse":{"type":"object","description":"Generic status/message response used by several endpoints","properties":{"status":{"type":"string","enum":["success","failed"]},"msg":{"type":"string"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://dronebridge.gitbook.io/docs/dronebridge-for-esp32-drone-light-show-edition/developers-dlse-api-definition/settings.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.