Settings

Read and write device configuration

Get all device settings

get

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.

Responses

200

Settings retrieved successfully

application/json

Response to GET /api/settings.

and

get

/api/settings

HTTPcURLJavaScriptPython

GET /api/settings HTTP/1.1
Host: 192.168.2.1
Accept: */*

200

Settings retrieved successfully

{
  "esp32_mode": 1,
  "ssid": "MyNetwork",
  "ssid_ap": "DroneBridge for ESP32",
  "wifi_pass": "dronebridge",
  "wifi_pass_ap": "dronebridge",
  "ap_ip": "192.168.2.1",
  "ip_sta": "192.168.1.50",
  "ip_sta_gw": "192.168.1.1",
  "ip_sta_netmsk": "255.255.255.0",
  "udp_client_ip": "192.168.2.255",
  "wifi_hostname": "dronebridge",
  "wifi_chan": "number",
  "wifi_en_gn": 0,
  "wifi_dis_udpdet": 0,
  "udp_local_port": 14555,
  "wifi_brcst_nudp": 1,
  "wifi_brcst_port": 14550,
  "radio_ant_selec": 0,
  "radio_ant_sw": 0,
  "radio_ant_en": 0,
  "baud": "number",
  "gpio_tx": 17,
  "gpio_rx": 16,
  "gpio_rts": 1,
  "gpio_cts": 1,
  "rts_thresh": 127,
  "proto": "number",
  "trans_pack_size": 576,
  "serial_timeout": 50,
  "udp_client_port": 0,
  "rep_rssi_dbm": 1,
  "show_det_flash": 1,
  "show_ap_fail_to": 90000,
  "show_pm_en_hb": 1,
  "show_pm_en": 0,
  "show_pm_gpio": 1,
  "show_pm_logic": 0,
  "show_pm_pulse_l": 0,
  "show_pm_qu_gpio": 0,
  "show_pm_en_emcy": 0,
  "show_en_syid_ip": 1,
  "show_man_sysid": 1,
  "adc_v_en": 0,
  "adc_v_gpio": 0,
  "adc_v_multi": 110,
  "adc_a_en": 0,
  "adc_a_gpio": 0,
  "adc_a_multi": 36364
}

Update device settings

post

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.

Body

application/json

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

esp32_modeinteger · enumOptional

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,

Default: 1Example: 1Possible values:

ssidstring · min: 1 · max: 32Optional

Wi-Fi SSID to connect to in client (STA) mode.

Default: DroneBridge for ESP32Example: MyNetwork

ssid_apstring · min: 1 · max: 32Optional

SSID broadcast by the ESP32 in Wi-Fi AP mode.

Default: DroneBridge for ESP32Example: DroneBridge for ESP32

wifi_passstring · min: 7 · max: 64Optional

Password for Wi-Fi connections and ESP-NOW encryption.

Default: dronebridgeExample: dronebridge

wifi_pass_apstring · min: 7 · max: 64Optional

Password for the Wi-Fi access point in AP mode.

Default: dronebridgeExample: dronebridge

ap_ipstring · ipv4 · min: 8 · max: 16Optional

IPv4 address assigned to the ESP32 when operating in Wi-Fi AP mode.

Default: 192.168.2.1Example: 192.168.2.1

ip_stastring · ipv4 · max: 16Optional

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.

Default: ""Example: 192.168.1.50

ip_sta_gwstring · ipv4 · max: 16Optional

Gateway IP address used when a static IP (ip_sta) is configured in STA mode.

Default: ""Example: 192.168.1.1

ip_sta_netmskstring · max: 16Optional

Subnet mask used when a static IP (ip_sta) is configured in STA mode.

Default: ""Example: 255.255.255.0

udp_client_ipstring · ipv4 · max: 16Optional

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.

Default: ""Example: 192.168.2.255

wifi_hostnamestring · min: 1 · max: 32Optional

mDNS/DHCP hostname of the ESP32, used in both AP and STA mode. Defaults to the lwIP CONFIG_LWIP_LOCAL_HOSTNAME compile-time value.

Default: dronebridgeExample: dronebridge

wifi_chaninteger · min: 1 · max: 165Optional

Wi-Fi channel used in AP and ESP-NOW mode.

Default: 6Example: 6

wifi_en_gninteger · enumOptional

Allow 802.11b/g/n(/ax) mode. 0 = 802.11b only (best range); 1 = b/g/n/ax where supported.

Default: 0Possible values:

wifi_dis_udpdetinteger · enumOptional

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.

Default: 0Possible values:

udp_local_portinteger · min: 1 · max: 65535Optional

Local UDP port the ESP32 listens on for incoming GCS messages.

Default: 14555Example: 14555

wifi_brcst_nudpinteger · enumOptional

Broadcast serial data to the broadcast address when no known UDP client exists, enabling auto-detection by GCS tools like Skybrush.

Default: 1Possible values:

wifi_brcst_portinteger · min: 1 · max: 65535Optional

UDP port used for broadcast transmissions when no known UDP client is registered (linked to wifi_brcst_nudp).

Default: 14550Example: 14550

radio_ant_selecinteger · max: 2Optional

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

Default: 0

radio_ant_swintegerOptional

GPIO number connected to the external antenna switch signal. Set to 0 to disable.

Default: 0

radio_ant_enintegerOptional

GPIO used to enable the external antenna switch circuit. Set to 0 if not needed.

Default: 0

baudinteger · min: 1200 · max: 5000000Optional

UART baud rate. Stick to the options available in the web ui to prevent issues.

Default: 115200Example: 115200

gpio_txintegerOptional

GPIO number of the UART TX pin.

Example: 17

gpio_rxintegerOptional

GPIO number of the UART RX pin.

Example: 16

gpio_rtsintegerOptional

GPIO number of the UART RTS pin. Set to the same value as gpio_cts to disable hardware flow control.

gpio_ctsintegerOptional

GPIO number of the UART CTS pin. Set to the same value as gpio_rts to disable hardware flow control.

rts_threshinteger · min: 1 · max: 127Optional

UART RTS threshold. Controls when the RTS line is asserted. Leave at the default unless you have a specific reason to change it.

Default: 127

protointeger · enumOptional

Serial telemetry protocol / parser. Maps to DB_SERIAL_PROTOCOL_* constants: 0 = MAVLink (parsed, only complete frames forwarded); 4 = Transparent (raw pass-through).

Default: 0Possible values:

trans_pack_sizeinteger · min: 16 · max: 1056Optional

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

Default: 576

serial_timeoutinteger · min: 1 · max: 65535Optional

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.

Default: 50

udp_client_portinteger · max: 65535Optional

Remote port of the persisted UDP client / GCS endpoint. 0 means no client is persisted.

Default: 0

rep_rssi_dbminteger · enumOptional

RSSI reporting unit in MAVLink RADIO_STATUS messages. 1 = dBm (QGroundControl); 0 = 0-100 percentage (Mission Planner).

Default: 1Possible values:

show_det_flashinteger · enumOptional

Enable detection of the flight controller entering firmware-flash mode so the ESP32 can react accordingly.

Default: 1Possible values:

show_ap_fail_tointegerOptional

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.

Default: 90000Example: 90000

show_pm_en_hbinteger · enumOptional

Emit a fake MAVLink heartbeat on behalf of the flight controller while it is powered down, so the GCS does not lose the connection.

Default: 1Possible values:

show_pm_eninteger · enumOptional

Enable the ESP32 power-management subsystem for the flight controller. Must be supported by the hardware.

Default: 0Possible values:

show_pm_gpiointegerOptional

GPIO number connected to the flight-controller power control pin.

show_pm_logicinteger · enumOptional

Logic level of the power control GPIO. Maps to DB_PM_LOGIC_*: 0 = active-low; 1 = active-high.

Possible values:

show_pm_pulse_linteger · max: 65535Optional

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.

Default: 0

show_pm_qu_gpiointegerOptional

GPIO used to sense whether the flight controller is currently powered. Set to 0 to disable power-state sensing.

Default: 0

show_pm_en_emcyinteger · enumOptional

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

Default: 0Possible values:

show_en_syid_ipinteger · enumOptional

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.

Default: 1Possible values:

show_man_sysidinteger · max: 255Optional

Manually assigned MAVLink system ID used until the flight controller's system ID is learned or show_en_syid_ip takes over.

Default: 1

adc_v_eninteger · enumOptional

Enable battery voltage monitoring via the ESP32 ADC.

Default: 0Possible values:

adc_v_gpiointegerOptional

GPIO number connected to the battery voltage sense circuit.

Default: 0

adc_v_multiinteger · min: 1 · max: 65535Optional

Voltage ADC multiplier / scaling factor used to convert the raw ADC reading to actual battery voltage.

Default: 110

adc_a_eninteger · enumOptional

Enable battery current monitoring via the ESP32 ADC.

Default: 0Possible values:

adc_a_gpiointegerOptional

GPIO number connected to the battery current sense circuit.

Default: 0

adc_a_multiinteger · min: 1Optional

Current ADC multiplier in mA/V used to convert the raw ADC reading to actual current draw.

Default: 36364Example: 36364

Responses

200

Settings accepted; device will reboot

application/json

Generic status/message response used by several endpoints

statusstring · enumOptionalExample: successPossible values:

msgstringOptionalExample: Settings changed! Rebooting ...

400

Request body too large (≥ 10 240 bytes)

text/plain

422

Drone is armed – settings cannot be changed while armed

application/json

500

Internal server error while receiving data

text/plain

post

/api/settings

HTTPcURLJavaScriptPython

POST /api/settings HTTP/1.1
Host: 192.168.2.1
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "wifi_ssid": "MyDrone",
  "wifi_pass": "secret123"
}

{
  "status": "success",
  "msg": "Settings changed! Rebooting ..."
}