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 sketch says both start disabled, which is not what this board reports. The sketch 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 sketch 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 4_Statistics.ino from the pinned library, without the file's header comment. The sketch body is exactly as shipped.

ESP32S3 Dev Module
4_Statistics.ino
#include "ADSB-Receiver-SOLDERED.h"

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

// Called once per second with the module's own CPU load and uptime.
void onSystemStats(const SystemStats &s)
{
Serial.print("[SYSTEM] CPU load=");
Serial.print(s.cpuLoad);
Serial.print("% uptime=");
Serial.print(s.uptime);
Serial.print("s crcValid=");
Serial.println(s.crcValid ? "yes" : "no");
}

// Called once per second with the ADS-B receiver frame counts and PPS calibration.
void onAdsbStats(const AdsbStats &s)
{
Serial.print("[ADS-B] Mode-S fps=");
Serial.print(s.fpss);
Serial.print(" Mode-A/C fps=");
Serial.print(s.fpsac);
Serial.print(" PPS calib=");
Serial.print(s.calib);
Serial.print(" crcValid=");
Serial.println(s.crcValid ? "yes" : "no");
}

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

// 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(StatsProtocol::CSV);
adsb.setAdsbStatisticsProtocol(StatsProtocol::CSV);
adsb.exitConfiguration(115200);
}
else
{
Serial.println("Failed to enter CONFIGURATION state.");
}
}

void loop()
{
adsb.poll();
}

Expected result​

Open Tools → Serial Monitor, set the baud rate to 115200 and reset the board. Once a second the sketch 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.

Serial MonitorAutoscrollShow timestampNewline115200 baud
Message (Enter to send message to the board)
[SYSTEM] CPU load=21.30% uptime=1s crcValid=yes
[ADS-B] Mode-S fps=23 Mode-A/C fps=0 PPS calib=0.00 crcValid=yes
[SYSTEM] CPU load=18.70% uptime=2s crcValid=yes
[ADS-B] Mode-S fps=19 Mode-A/C fps=0 PPS calib=0.00 crcValid=yes
[SYSTEM] CPU load=19.40% uptime=3s crcValid=yes
[ADS-B] Mode-S fps=27 Mode-A/C fps=0 PPS calib=0.00 crcValid=yes
[SYSTEM] CPU load=22.10% uptime=4s crcValid=yes
[ADS-B] Mode-S fps=31 Mode-A/C fps=0 PPS calib=0.00 crcValid=yes
[SYSTEM] CPU load=18.20% uptime=5s crcValid=yes
[ADS-B] Mode-S fps=22 Mode-A/C fps=0 PPS calib=0.00 crcValid=yes
[SYSTEM] CPU load=20.60% uptime=6s crcValid=yes
[ADS-B] Mode-S fps=26 Mode-A/C fps=0 PPS calib=0.00 crcValid=yes
[SYSTEM] CPU load=19.10% uptime=7s crcValid=yes
[ADS-B] Mode-S fps=24 Mode-A/C fps=0 PPS calib=0.00 crcValid=yes

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

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

ReturnsNothing.

Parameters

TypeNameDescription
void (*)(const SystemStats &s)cbThe function to call. 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(AdsbStatsCallback cb)returns void

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

ReturnsNothing.

Parameters

TypeNameDescription
void (*)(const AdsbStats &s)cbThe function to call. 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 a 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 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.

setSystemStatisticsProtocol(StatsProtocol p)returns bool

Turns the system statistics message on or off (the SYSTEM_STATISTICS setting). The receiver's datasheet for firmware v2.89.28 gives it as off by default.

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

Parameters

TypeNameDescription
StatsProtocolpStatsProtocol::NONE or StatsProtocol::CSV.
setAdsbStatisticsProtocol(StatsProtocol p)returns bool

Turns the ADS-B statistics message on or off (the ADSB_STATISTICS setting). The receiver's datasheet gives CSV as its default, and the receiver on this board reports CSV; the library's comment says it starts disabled.

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

Parameters

TypeNameDescription
StatsProtocolpStatsProtocol::NONE or StatsProtocol::CSV.
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.
poll()returns void

Reads every byte that has arrived, parses the complete lines and fires the registered callbacks. It does not block, so call it on every pass of loop().

ReturnsNothing.

Putting it together​

Register the 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.