Skip to main content

Configure protocols and settings

What this example shows​

Writing the receiver's settings from a sketch: the decoded output protocol (CSV or MAVLink), how often aircraft reports are sent, the two statistics protocols, the receiver's own system log and its RUN-state baud rate. Each write prints whether the receiver accepted it.

The example code​

This is 3_ConfigureProtocolsAndSettings.ino from the pinned library, without the file's header comment. The sketch body is exactly as shipped. It selects CSV output, so change one value at a time to see what each setting does.

ESP32S3 Dev Module
3_ConfigureProtocolsAndSettings.ino
#include "ADSB-Receiver-SOLDERED.h"

// Create an instance of the ADS-B object
ADSBReceiver adsb;

// Small helper to print whether a setting write succeeded.
void printResult(const char *what, bool ok)
{
Serial.print(what);
Serial.println(ok ? " -> AT+OK" : " -> FAILED");
}

void setup()
{
Serial.begin(115200);
adsb.begin(115200);

// Settings can only be written while in CONFIGURATION state.
if (!adsb.enterConfiguration())
{
Serial.println("Failed to enter CONFIGURATION state.");
return;
}

// --- ADS-B decoded output protocol ---
printResult("ADSB_RX_PROTOCOL_DECODED=CSV", adsb.setAdsbRxProtocolDecoded(DecodedProtocol::CSV));

// Reporting cadence for decoded aircraft: update ASAP after any position update.
printResult("ADSB_RX_PROTOCOL_INC=IMMEDIATE_ON_POSITION_UPDATE",
adsb.setAdsbRxProtocolInc(IncMode::IMMEDIATE_ON_POSITION_UPDATE));

// Per-aircraft ADS-B statistics (frames/s, PPS calibration), see example 4.
printResult("ADSB_STATISTICS=CSV", adsb.setAdsbStatisticsProtocol(StatsProtocol::CSV));

// --- SYSTEM settings ---
printResult("SYSTEM_LOG=0", adsb.setSystemLog(false));
printResult("SYSTEM_STATISTICS=CSV", adsb.setSystemStatisticsProtocol(StatsProtocol::CSV));

// Changing BAUDRATE takes effect on the *next* RUN state entry: exitConfiguration()
// below must be told the new value so the local UART follows the module.
printResult("BAUDRATE=BPS_115200", adsb.setBaudrate(Baudrate::BPS_115200));

Serial.println("Returning to RUN state...");
adsb.exitConfiguration(115200);
}

void loop()
{
}

Expected result​

Open Tools → Serial Monitor, set the baud rate to 115200 and reset the board. When the receiver accepts every write, the sketch prints:

Serial MonitorAutoscrollShow timestampNewline115200 baud
Message (Enter to send message to the board)
ADSB_RX_PROTOCOL_DECODED=CSV -> AT+OK
ADSB_RX_PROTOCOL_INC=IMMEDIATE_ON_POSITION_UPDATE -> AT+OK
ADSB_STATISTICS=CSV -> AT+OK
SYSTEM_LOG=0 -> AT+OK
SYSTEM_STATISTICS=CSV -> AT+OK
BAUDRATE=BPS_115200 -> AT+OK
Returning to RUN state...

A write the receiver rejects prints FAILED in place of AT+OK. If the receiver does not enter CONFIGURATION state, the sketch prints Failed to enter CONFIGURATION state. and stops. The sketch runs once and loop() stays empty.

Functions used​

ADSBReceiver()returns None

Creates the receiver object. With no arguments it uses the library's board defaults: hardware UART 1, IO17 for the receiver's TX line, IO18 for its RX line and IO21 for its RESET line, which is how this board is wired.

ReturnsConstructor; no return value.

Parameters

TypeNameDescription
uint8_tuartNumESP32 hardware UART to use. Optional, default 1. Avoid 0, which is usually the USB console.
int8_trxPinESP32 GPIO wired to the module's TX pin. Optional, default 17.
int8_ttxPinESP32 GPIO wired to the module's RX pin. Optional, default 18.
int8_tresetPinESP32 GPIO wired to the module's RESET pin. Optional, default 21. Pass -1 if it is not connected.
begin(uint32_t initialBaud, size_t rxBufferSize)returns void

Opens the UART link to the receiver. Call it once in setup().

ReturnsNothing.

Parameters

TypeNameDescription
uint32_tinitialBaudBaud rate to start at. Optional, default 115200. Use 115200 unless the module's BAUDRATE setting was changed earlier.
size_trxBufferSizeSize of the UART receive buffer in bytes. Optional, default 4096.
enterConfiguration()returns bool

Moves the receiver from RUN to CONFIGURATION state. It sends AT+CONFIG=1, switches the local UART to 115200 and confirms the new state with AT+CONFIG?. Settings can only be written in this state.

Returnstrue if the receiver reports being in CONFIGURATION state, false otherwise.

setAdsbRxProtocolDecoded(DecodedProtocol p)returns bool

Chooses the format of the decoded aircraft data the receiver sends. The receiver takes this setting as a name, so the library sends CSV, Mavlink or None.

Returnstrue if the receiver answered AT+OK, false otherwise.

Parameters

TypeNameDescription
DecodedProtocolpDecodedProtocol::NONE, DecodedProtocol::CSV or DecodedProtocol::MAVLINK.
setAdsbRxProtocolInc(IncMode m)returns bool

Chooses how often aircraft reports are sent (the ADSB_RX_PROTOCOL_INC setting).

Returnstrue if the receiver answered AT+OK, false otherwise.

Parameters

TypeNameDescription
IncModemIncMode::ALWAYS_ONCE_PER_SECOND (0), IncMode::ONCE_PER_SECOND_IF_UPDATED (1) or IncMode::IMMEDIATE_ON_POSITION_UPDATE (2).
setAdsbStatisticsProtocol(StatsProtocol p)returns bool

Turns the per-aircraft ADS-B statistics message on or off (the ADSB_STATISTICS setting). The receiver takes this setting as a name, so the library sends CSV or None.

Returnstrue if the receiver answered AT+OK, false otherwise.

Parameters

TypeNameDescription
StatsProtocolpStatsProtocol::NONE or StatsProtocol::CSV.
setSystemLog(bool enable)returns bool

Turns the receiver's own system log on or off (the SYSTEM_LOG setting, written as 1 or 0).

Returnstrue if the receiver answered AT+OK, false otherwise.

Parameters

TypeNameDescription
boolenabletrue to enable the log, false to disable it.
setSystemStatisticsProtocol(StatsProtocol p)returns bool

Turns the system statistics message (the receiver's CPU load and uptime) on or off (the SYSTEM_STATISTICS setting, written as a number).

Returnstrue if the receiver answered AT+OK, false otherwise.

Parameters

TypeNameDescription
StatsProtocolpStatsProtocol::NONE (0) or StatsProtocol::CSV (1).
setBaudrate(Baudrate b)returns bool

Sets the receiver's baud rate for RUN state (the BAUDRATE setting). It takes effect the next time the receiver enters RUN state, so tell exitConfiguration() the same value.

Returnstrue if the receiver answered AT+OK, false otherwise.

Parameters

TypeNameDescription
BaudratebBaudrate::BPS_115200 (0), Baudrate::BPS_921600 (1), Baudrate::BPS_3000000 (2) or Baudrate::BPS_57600 (3).
exitConfiguration(uint32_t runBaud)returns bool

Moves the receiver from CONFIGURATION back to RUN state. It sends AT+CONFIG=0, switches the local UART to runBaud and confirms the new state with AT+CONFIG?.

Returnstrue if the receiver reports being in RUN state, false otherwise.

Parameters

TypeNameDescription
uint32_trunBaudBaud rate for RUN state. Optional, default 115200. It must match the receiver's stored BAUDRATE setting.

Putting it together​

Every write sits between enterConfiguration() and exitConfiguration(). The typed functions take the library's enumerations, so you never write the raw setting text yourself. The example only changes the values it names, and BPS_115200 is the factory-default RUN baud rate used everywhere else in this documentation.

If you write a different baud rate, pass the same rate to exitConfiguration(), and to begin() in every sketch that talks to the receiver afterwards. A mismatch leaves your sketch and the receiver at different speeds, and no aircraft data arrives.