Skip to main content

Read aircraft reports

What this example shows​

Reading the decoded aircraft reports the receiver sends in its default CSV format and printing one line for each update: the aircraft's ICAO address, then the callsign, position, barometric altitude, speed and squawk code when the receiver had them, then whether the aircraft is on the ground and whether the report's checksum was valid.

The example code​

This is 1_ReadAircraftCSV.ino from the pinned library, without the file's header comment. The sketch body is exactly as shipped. The library's default wiring, UART1 on IO17 and IO18 with the reset on IO21, is this board's own wiring, so the constructor needs no arguments.

ESP32S3 Dev Module
1_ReadAircraftCSV.ino
#include "ADSB-Receiver-SOLDERED.h"

// Create an instance of the ADS-B object
// Using a different board? See example 7_CustomBoardWiring.
ADSBReceiver adsb;

// Called once per decoded aircraft update, with whichever fields the module had data for.
void onAircraft(const AdsbAircraft &ac)
{
Serial.print("ICAO ");
Serial.print(ac.icao);

if (ac.callsign.length())
{
Serial.print(" call=");
Serial.print(ac.callsign);
}
if (ac.hasPosition)
{
Serial.print(" lat=");
Serial.print(ac.lat, 5);
Serial.print(" lon=");
Serial.print(ac.lon, 5);
}
if (ac.hasAltBaro)
{
Serial.print(" altBaro=");
Serial.print(ac.altBaro);
Serial.print("ft");
}
if (ac.hasVelH)
{
Serial.print(" vel=");
Serial.print(ac.velH);
Serial.print("kt");
}
if (ac.squawk.length())
{
Serial.print(" squawk=");
Serial.print(ac.squawk);
}
Serial.print(" onGround=");
Serial.print(ac.onGround() ? "yes" : "no");
Serial.print(" crcValid=");
Serial.println(ac.crcValid ? "yes" : "no");
}

void setup()
{
// Start the USB serial monitor.
Serial.begin(115200);

// Open the UART link to the module at its factory-default RUN baud.
adsb.begin(115200);
// Register the function to call whenever a decoded aircraft report arrives.
adsb.onAircraft(onAircraft);

Serial.println("Waiting for ADS-B traffic...");
}

void loop()
{
// Reads incoming bytes and fires the registered callbacks. Must run every loop.
adsb.poll();
}

Install the library as shown on the Arduino Library page, connect the included antenna to the receiver's IPEX connector, and upload the sketch.

Expected result​

Open Tools → Serial Monitor, set the baud rate to 115200 and reset the board. The sketch prints Waiting for ADS-B traffic... once, then one line for every decoded aircraft update. The receiver sends its aircraft message once per second for each aircraft it tracks. Each line starts with ICAO and the address, adds call=, lat= and lon=, altBaro= (feet), vel= (knots) and squawk= when the receiver had them, and ends with onGround= and crcValid=. A field the receiver has no data for yet is left out of the line.

Serial MonitorAutoscrollShow timestampNewline115200 baud
Message (Enter to send message to the board)
Waiting for ADS-B traffic...
ICAO 471F8C call=WZZ3527 lat=45.93120 lon=18.31050 altBaro=37000ft vel=448.00kt squawk=2741 onGround=no crcValid=yes
ICAO 4CA9D2 call=RYR6LF lat=46.22853 lon=17.55442 altBaro=39000ft vel=472.00kt squawk=5162 onGround=no crcValid=yes
ICAO 4BAA67 call=THY1JK lat=45.18264 lon=19.64502 altBaro=38000ft vel=486.00kt squawk=6243 onGround=no crcValid=yes
ICAO 440C2D call=AUA675 lat=45.60175 lon=18.91855 altBaro=36000ft vel=461.00kt squawk=4127 onGround=no crcValid=yes
ICAO 50108A call=CTN472 lat=45.40979 lon=17.43954 altBaro=31275ft vel=412.00kt squawk=2307 onGround=no crcValid=yes
ICAO 4C0215 call=ASL113 lat=45.12000 lon=19.41322 altBaro=28450ft vel=397.00kt squawk=4613 onGround=no crcValid=yes
ICAO 48AE21 altBaro=40000ft squawk=3521 onGround=no crcValid=yes
ICAO 471F8C call=WZZ3527 lat=45.92940 lon=18.31199 altBaro=37000ft vel=449.00kt squawk=2741 onGround=no crcValid=yes
ICAO 4CA9D2 call=RYR6LF lat=46.22718 lon=17.55691 altBaro=39000ft vel=471.00kt squawk=5162 onGround=no crcValid=yes
ICAO 4BAA67 call=THY1JK lat=45.18393 lon=19.64241 altBaro=38000ft vel=485.00kt squawk=6243 onGround=no crcValid=yes
ICAO 440C2D call=AUA675 lat=45.60009 lon=18.92047 altBaro=36000ft vel=462.00kt squawk=4127 onGround=no crcValid=yes
ICAO 50108A call=CTN472 lat=45.40920 lon=17.44213 altBaro=31300ft vel=413.00kt squawk=2307 onGround=no crcValid=yes
ICAO 4C0215 call=ASL113 lat=45.11846 lon=19.41463 altBaro=28425ft vel=396.00kt squawk=4613 onGround=no crcValid=yes
ICAO 48AE21 call=LOT145 altBaro=40000ft vel=488.00kt squawk=3521 onGround=no crcValid=yes

Functions used​

ADSBReceiver(uint8_t uartNum, int8_t rxPin, int8_t txPin, int8_t resetPin)returns None

Creates the receiver object and tells it which UART and pins to use. Every parameter is optional, and the defaults are this board's wiring, so the example passes none.

ReturnsConstructor; no return value.

Parameters

TypeNameDescription
uint8_tuartNumESP32 hardware UART to use. Optional, default 1.
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.
begin(uint32_t initialBaud, size_t rxBufferSize)returns void

Opens the UART link to the receiver. Call it once in setup(). The example uses 115200, the receiver's factory-default baud rate in its RUN state.

ReturnsNothing.

Parameters

TypeNameDescription
uint32_tinitialBaudBaud rate to start at. Optional, default 115200.
size_trxBufferSizeSize of the UART receive buffer in bytes. Optional, default 4096.
onAircraft(AircraftCallback cb)returns void

Registers the function that is called for every decoded aircraft report the receiver sends in CSV format.

ReturnsNothing.

Parameters

TypeNameDescription
void (*)(const AdsbAircraft &ac)cbThe function to call, given an AdsbAircraft. Fields the receiver had no data for stay at their defaults, with the matching has... flag false.

The AdsbAircraft the example reads has these fields:

FieldDescription
icaoThe aircraft's 24-bit ICAO address, as a hex string.
callsignThe callsign, an empty string when unknown.
hasPosition, lat, lonWhether the report carries a position, and the latitude and longitude.
hasAltBaro, altBaroWhether the report carries barometric altitude, and the altitude in feet.
hasVelH, velHWhether the report carries horizontal speed, and the speed in knots.
squawkThe squawk code as a string, empty when unknown.
crcValidTrue when the line's CRC checked out.
onGround()returns bool

Called on the aircraft the callback receives. Tells you whether the report flags the aircraft as being on the ground.

Returnstrue if the aircraft is on the ground.

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​

Create the receiver with no arguments, open the link with begin(), register onAircraft() and call poll() in loop(). The receiver sends CSV by default, so this sketch needs no configuration step: the receiver on this board reports AT+ADSB_RX_PROTOCOL_DECODED=CSV with firmware 2.89.28.0, the version its datasheet is written for. If no aircraft lines appear, select CSV as the Configure protocols and settings example does.