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 Examples/ADSBReceiver-readAircraftCSV.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

# Open the UART link to the module at its factory-default RUN baud.
# Board default wiring: IO17 = module TX in, IO18 = module RX out, IO21 = RESET.
# Using a different board? See example ADSBReceiver-customBoardWiring.
uart = UART(1, baudrate=115200, rx=17, tx=18, rxbuf=4096)
adsb = ADSBReceiver(uart, reset_pin=21)


# Called once per decoded aircraft update, with whichever fields the module had data for.
def onAircraft(ac):
line = "ICAO {}".format(ac.icao)
if ac.callsign:
line += " call={}".format(ac.callsign)
if ac.hasPosition:
line += " lat={:.5f} lon={:.5f}".format(ac.lat, ac.lon)
if ac.hasAltBaro:
line += " altBaro={}ft".format(ac.altBaro)
if ac.hasVelH:
line += " vel={}kt".format(ac.velH)
if ac.squawk:
line += " squawk={}".format(ac.squawk)
line += " onGround={}".format("yes" if ac.onGround() else "no")
line += " crcValid={}".format("yes" if ac.crcValid else "no")
print(line)


# Register the function to call whenever a decoded aircraft report arrives.
adsb.onAircraft(onAircraft)

print("Waiting for ADS-B traffic...")

while True:
# Reads incoming bytes and fires the registered callbacks. Must run every loop.
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​

The script 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.

ShellMicroPython
Waiting for ADS-B traffic...
ICAO 471F8C call=WZZ3527 lat=45.82343 lon=18.39996 altBaro=37000ft vel=448.0kt squawk=2741 onGround=no crcValid=yes
ICAO 4CA9D2 call=RYR6LF lat=46.14798 lon=17.70346 altBaro=39000ft vel=472.0kt squawk=5162 onGround=no crcValid=yes
ICAO 4BAA67 call=THY1JK lat=45.26007 lon=19.48813 altBaro=38000ft vel=486.0kt squawk=6243 onGround=no crcValid=yes
ICAO 440C2D call=AUA675 lat=45.50202 lon=19.03399 altBaro=36000ft vel=461.0kt squawk=4127 onGround=no crcValid=yes
ICAO 50108A call=CTN472 lat=45.37443 lon=17.59458 altBaro=32775ft vel=412.0kt squawk=2307 onGround=no crcValid=yes
ICAO 4C0215 call=ASL113 lat=45.02775 lon=19.49813 altBaro=26650ft vel=397.0kt squawk=4613 onGround=no crcValid=yes
ICAO 48AE21 altBaro=40000ft squawk=3521 onGround=no crcValid=yes
ICAO 471F8C call=WZZ3527 lat=45.82163 lon=18.40145 altBaro=37000ft vel=449.0kt squawk=2741 onGround=no crcValid=yes
ICAO 4CA9D2 call=RYR6LF lat=46.14663 lon=17.70594 altBaro=39000ft vel=471.0kt squawk=5162 onGround=no crcValid=yes
ICAO 4BAA67 call=THY1JK lat=45.26136 lon=19.48551 altBaro=38000ft vel=485.0kt squawk=6243 onGround=no crcValid=yes
ICAO 440C2D call=AUA675 lat=45.50036 lon=19.03591 altBaro=36000ft vel=462.0kt squawk=4127 onGround=no crcValid=yes
ICAO 50108A call=CTN472 lat=45.37384 lon=17.59717 altBaro=32800ft vel=413.0kt squawk=2307 onGround=no crcValid=yes
ICAO 4C0215 call=ASL113 lat=45.02621 lon=19.49954 altBaro=26625ft vel=396.0kt squawk=4613 onGround=no crcValid=yes
ICAO 48AE21 call=LOT145 altBaro=40000ft vel=488.0kt squawk=3521 onGround=no crcValid=yes

The addresses and values depend on which aircraft are within the receiver's range. The script loops forever.

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

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

ReturnsNothing.

Parameters

TypeNameDescription
functioncbThe function to call, given an AdsbAircraft object. Fields the receiver had no data for keep their defaults, with the matching has... attribute False.

The AdsbAircraft object the example reads has these attributes:

AttributeDescription
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 report's trailing CRC field matched the line's contents.
onGround()returns bool

Called on the aircraft object 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 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​

Open the UART at 115200 baud, create the receiver on it, register onAircraft() and call poll() in a loop. The receiver sends CSV by default, so this script 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.