Skip to main content

Configure protocols and settings

What this example shows​

Writing the receiver's settings from a script: 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 Examples/ADSBReceiver-configureProtocolsAndSettings.py from the pinned module, without the file's header comment. The script body is exactly as shipped. The UART1 wiring on IO17 and IO18 and the reset on IO21 are the board's own wiring.

from machine import UART
from ADSBReceiver import (
ADSBReceiver,
DECODED_PROTOCOL_CSV,
INC_MODE_IMMEDIATE_ON_POSITION_UPDATE,
STATS_PROTOCOL_CSV,
BAUDRATE_115200,
)

uart = UART(1, baudrate=115200, rx=17, tx=18, rxbuf=4096)
adsb = ADSBReceiver(uart, reset_pin=21)


# Small helper to print whether a setting write succeeded.
def printResult(what, ok):
print("{} -> {}".format(what, "AT+OK" if ok else "FAILED"))


# Settings can only be written while in CONFIGURATION state.
if not adsb.enterConfiguration():
print("Failed to enter CONFIGURATION state.")
else:
# --- ADS-B decoded output protocol ---
printResult("ADSB_RX_PROTOCOL_DECODED=CSV", adsb.setAdsbRxProtocolDecoded(DECODED_PROTOCOL_CSV))

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

# Per-aircraft ADS-B statistics (frames/s, PPS calibration), see the statistics example.
printResult("ADSB_STATISTICS=CSV", adsb.setAdsbStatisticsProtocol(STATS_PROTOCOL_CSV))

# --- SYSTEM settings ---
printResult("SYSTEM_LOG=0", adsb.setSystemLog(False))
printResult("SYSTEM_STATISTICS=CSV", adsb.setSystemStatisticsProtocol(STATS_PROTOCOL_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_115200))

print("Returning to RUN state...")
adsb.exitConfiguration(115200)

Save it to a file on your computer, then run it on the board with mpremote run <file.py>, putting your file's name in place of <file.py>. It needs the module installed as shown on the MicroPython Library page.

Expected result​

When the receiver accepts every write, the script prints:

ShellMicroPython
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 script prints Failed to enter CONFIGURATION state. and stops. The script runs once and exits.

Functions used​

ADSBReceiver(uart, reset_pin=None)returns ADSBReceiver

Creates the receiver object on a UART you have already opened. If you give a reset pin, the module makes it a high-impedance input, so the pin is only driven during hardwareReset().

ReturnsA receiver object ready for the other functions.

Parameters

TypeNameDescription
machine.UARTuartAn open UART connected to the receiver. Size its receive buffer when you create it, as the example does with rxbuf=4096: dense traffic can overflow the default buffer and corrupt lines.
int or Nonereset_pinGPIO wired to the receiver's RESET pin. Optional, default None, which disables hardwareReset(). This board uses 21.
enterConfiguration()returns bool

Moves the receiver from RUN to CONFIGURATION state. It sends AT+CONFIG=1, switches the UART to 115200 (the receiver's fixed CONFIGURATION baud rate) 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(protocol)returns bool

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

ReturnsTrue on success, False otherwise.

Parameters

TypeNameDescription
intprotocolOne of DECODED_PROTOCOL_NONE (0), DECODED_PROTOCOL_CSV (1) or DECODED_PROTOCOL_MAVLINK (2).
setAdsbRxProtocolInc(mode)returns bool

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

ReturnsTrue on success, False otherwise.

Parameters

TypeNameDescription
intmodeOne of INC_MODE_ALWAYS_ONCE_PER_SECOND (0), INC_MODE_ONCE_PER_SECOND_IF_UPDATED (1) or INC_MODE_IMMEDIATE_ON_POSITION_UPDATE (2).
setAdsbStatisticsProtocol(protocol)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 module sends CSV or None.

ReturnsTrue on success, False otherwise.

Parameters

TypeNameDescription
intprotocolSTATS_PROTOCOL_NONE (0) or STATS_PROTOCOL_CSV (1).
setSystemLog(enable)returns bool

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

ReturnsTrue on success, False otherwise.

Parameters

TypeNameDescription
boolenableTrue to enable the log, False to disable it.
setSystemStatisticsProtocol(protocol)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 on success, False otherwise.

Parameters

TypeNameDescription
intprotocolSTATS_PROTOCOL_NONE (0) or STATS_PROTOCOL_CSV (1).
setBaudrate(baudrate)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 rate.

ReturnsTrue on success, False otherwise.

Parameters

TypeNameDescription
intbaudrateOne of BAUDRATE_115200 (0), BAUDRATE_921600 (1), BAUDRATE_3000000 (2) or BAUDRATE_57600 (3). These are setting values, not baud rates.
exitConfiguration(run_baud=115200)returns bool

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

ReturnsTrue if the receiver reports being in RUN state, False otherwise.

Parameters

TypeNameDescription
intrun_baudThe baud rate the receiver's BAUDRATE setting is stored as, for example 115200. Optional, default 115200. It is a real baud rate here, unlike setBaudrate().

Putting it together​

Every write sits between enterConfiguration() and exitConfiguration(). The setting functions take the module's constants, so you never write the raw setting text yourself.

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