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.
[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 ADSBReceiverCreates 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
| Type | Name | Description |
|---|---|---|
machine.UART | uart | An 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 None | reset_pin | GPIO wired to the receiver's RESET pin. Optional, default None, which disables hardwareReset(). This board uses 21. |
onSystemStats(cb)returns NoneRegisters the function that is called for every system statistics message (the receiver's #S: line).
ReturnsNothing.
Parameters
| Type | Name | Description |
|---|---|---|
function or None | cb | The 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 NoneRegisters the function that is called for every ADS-B statistics message (the receiver's #AS: line).
ReturnsNothing.
Parameters
| Type | Name | Description |
|---|---|---|
function or None | cb | The 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 boolMoves 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 boolTurns 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
| Type | Name | Description |
|---|---|---|
int | protocol | STATS_PROTOCOL_NONE (0) or STATS_PROTOCOL_CSV (1). |
setAdsbStatisticsProtocol(protocol)returns boolTurns 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
| Type | Name | Description |
|---|---|---|
int | protocol | STATS_PROTOCOL_NONE (0) or STATS_PROTOCOL_CSV (1). |
exitConfiguration(run_baud=115200)returns boolMoves 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
| Type | Name | Description |
|---|---|---|
int | run_baud | The baud rate the receiver's BAUDRATE setting is stored as, for example 115200. Optional, default 115200. |
poll()returns NoneReads 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.