Skip to main content

Statistics

What this example shows​

Reading the receiver's two health messages: the system statistics (CPU load and uptime) and the ADS-B statistics (frames received per second and the calibration measured against the pulse-per-second signal). The receiver on this board runs firmware 2.89.28.0, the version its datasheet is written for, and reports the system statistics as off (AT+SYSTEM_STATISTICS=0) and the ADS-B statistics as CSV (AT+ADSB_STATISTICS=CSV), as the datasheet gives them. The comment in the script says both start disabled, which is not what this board reports. The script turns both on, so it works either way.

Two of the ADS-B figures need context on this board. The receiver fitted here is the basic SC1 version, which decodes ADS-B only: Mode-A/C decoding belongs to the SC1-EXT version. The receiver's statistics message always has a Mode-A/C frames-per-second field, so the script prints one, but the SC1 version does not decode Mode-A/C: do not read that figure as Mode-A/C traffic. The calibration value is the receiver's real microcontroller frequency measured against the pulse-per-second signal of a GNSS module, and the board has no GNSS module, so the value needs an external PPS source to mean anything.

The example code​

This is Examples/ADSBReceiver-statistics.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, STATS_PROTOCOL_CSV

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


# Called once per second with the module's own CPU load and uptime.
def onSystemStats(s):
print(
"[SYSTEM] CPU load={}% uptime={}s crcValid={}".format(
s.cpuLoad, s.uptime, "yes" if s.crcValid else "no"
)
)


# Called once per second with the ADS-B receiver frame counts and PPS calibration.
def onAdsbStats(s):
print(
"[ADS-B] Mode-S fps={} Mode-A/C fps={} PPS calib={} crcValid={}".format(
s.fpss, s.fpsac, s.calib, "yes" if s.crcValid else "no"
)
)


# Register the callbacks that will receive the stats messages.
adsb.onSystemStats(onSystemStats)
adsb.onAdsbStats(onAdsbStats)

# Both statistics protocols default to disabled, so turn them on here.
if adsb.enterConfiguration():
adsb.setSystemStatisticsProtocol(STATS_PROTOCOL_CSV)
adsb.setAdsbStatisticsProtocol(STATS_PROTOCOL_CSV)
adsb.exitConfiguration(115200)
else:
print("Failed to enter CONFIGURATION state.")

while True:
adsb.poll()

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​

Once a second the script prints one [SYSTEM] line and one [ADS-B] line. A [SYSTEM] line shows the receiver's CPU load in percent, its uptime in seconds and whether the message's checksum was valid. An [ADS-B] line shows the Mode-S frames received per second and the checksum result, next to the Mode-A/C and PPS calibration fields described above. If the receiver does not enter CONFIGURATION state, the script prints Failed to enter CONFIGURATION state. and then keeps polling.

ShellMicroPython
[SYSTEM] CPU load=20.8% uptime=1s crcValid=yes
[ADS-B] Mode-S fps=25 Mode-A/C fps=0 PPS calib=0.0 crcValid=yes
[SYSTEM] CPU load=19.6% uptime=2s crcValid=yes
[ADS-B] Mode-S fps=21 Mode-A/C fps=0 PPS calib=0.0 crcValid=yes
[SYSTEM] CPU load=18.4% uptime=3s crcValid=yes
[ADS-B] Mode-S fps=18 Mode-A/C fps=0 PPS calib=0.0 crcValid=yes
[SYSTEM] CPU load=21.7% uptime=4s crcValid=yes
[ADS-B] Mode-S fps=29 Mode-A/C fps=0 PPS calib=0.0 crcValid=yes
[SYSTEM] CPU load=20.2% uptime=5s crcValid=yes
[ADS-B] Mode-S fps=26 Mode-A/C fps=0 PPS calib=0.0 crcValid=yes
[SYSTEM] CPU load=18.9% uptime=6s crcValid=yes
[ADS-B] Mode-S fps=23 Mode-A/C fps=0 PPS calib=0.0 crcValid=yes
[SYSTEM] CPU load=19.7% uptime=7s crcValid=yes
[ADS-B] Mode-S fps=20 Mode-A/C fps=0 PPS calib=0.0 crcValid=yes

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.
onSystemStats(cb)returns None

Registers the function that is called for every system statistics message (the receiver's #S: line).

ReturnsNothing.

Parameters

TypeNameDescription
function or NonecbThe function to call, given a SystemStats object. s.cpuLoad is the CPU load in percent, s.uptime is the uptime (the example prints it in seconds) and s.crcValid tells you whether the checksum matched.
onAdsbStats(cb)returns None

Registers the function that is called for every ADS-B statistics message (the receiver's #AS: line).

ReturnsNothing.

Parameters

TypeNameDescription
function or NonecbThe function to call, given an AdsbStats object. s.fpss is the number of Mode-S frames received per second, s.fpsac the Mode-A/C frames per second (the SC1 version on this board does not decode Mode-A/C), s.calib the real microcontroller frequency measured against the GNSS pulse-per-second signal (the board has no GNSS module), and s.crcValid whether the checksum matched.
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.

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). The receiver's datasheet for firmware v2.89.28 gives it as off by default.

ReturnsTrue on success, False otherwise.

Parameters

TypeNameDescription
intprotocolSTATS_PROTOCOL_NONE (0) or STATS_PROTOCOL_CSV (1).
setAdsbStatisticsProtocol(protocol)returns bool

Turns the 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. The receiver's datasheet gives CSV as its default, and the receiver on this board reports CSV; the module's comment says it starts disabled.

ReturnsTrue on success, False otherwise.

Parameters

TypeNameDescription
intprotocolSTATS_PROTOCOL_NONE (0) or STATS_PROTOCOL_CSV (1).
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.
poll()returns None

Reads every byte that has arrived, parses the complete lines and calls the registered functions. It does not block, so call it on every pass of your loop.

ReturnsNothing.

Putting it together​

Register the two callbacks, switch both statistics messages on while the receiver is in CONFIGURATION state, return to RUN state and keep calling poll(). Each message then reaches its callback, about once a second according to the example's own comments.