> 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.<br>

```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.<br>

```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"}}}}}}
```