API documentation

This module provides a pythonic way to process ADS-B messages. It can work with any software that provides BaseStation-like output, for example dump1090.

To get started quickly, install the module and take a look at the example section.

TCP Connection

class py1090.Connection(host='localhost', port=30003)[source]

Bases: _io.TextIOWrapper

File like object which can be used to read BaseStation messages from a TCP server.

The connection can be used as contextmanager (with-block) and as iterator:

with Connection() as connection:
        for line in connection:
                print(line)
Parameters:
  • host (str) – IP or hostname
  • port (int) – Port number
has_data()[source]

Checks if the socket currently has data available for reading (using select.select()).

Returns:True if there is data available for reading, False otherwise.
Return type:bool
readmessage()[source]

Reads a single line from the connection, parses it via Message.from_string() and returns it.

Returns:next unread message from socket
Return type:Message

BaseStation Message

class py1090.Message[source]

Bases: object

Abstract representation of the information contained in a BaseStation line.

The fields are listed in the order of appearance in the format. A sample line looks like this:

MSG,3,111,11111,3C49CC,111111,2015/05/01,17:06:55.370,2015/05/01,17:06:55.326,,24400,,,50.65931,6.67709,,,,,,0

This message contains the coordinates (50.65931, 6.67709) and altitude of 24400ft of an aircraft with the ADS-B hexident 3C49CC. The third, fourth and sixth fields have been set to ‘111...’ which indicates that the demodulator did not support these fields.

The attributes of this object will be set according to their values or left at None if no information is available.

To create an instance of this object, use Message.from_string(). To serialize back into a BaseStation string, use Message.to_string().

See also

John Woodsides SBS Station Tutorial
Source of most of the information provided about the socket format here.
Variables:
  • message_type (str) –

    The message type: MSG, STA, ID, AIR, SEL or CLK. Usually only messages of type MSG (transmission messages) are of interest. Most softwares (e.g. dump1090) do not even support any other message types.

    ID Type Description
    SEL SELECTION CHANGE MESSAGE Generated when the user changes the selected aircraft in BaseStation.
    ID NEW ID MESSAGE Generated when an aircraft being tracked sets or changes its callsign.
    AIR NEW AIRCRAFT MESSAGE Generated when the SBS picks up a signal for an aircraft that it isn’t currently tracking.
    STA STATUS CHANGE MESSAGE Generated when an aircraft’s status changes according to the timeout values in the Data Settings menu.
    CLK CLICK MESSAGE Generated when the user doubleclicks (or presses return) on an aircraft (i.e. to bring up the aircraft details window).
    MSG TRANSMISSION MESSAGE Generated by the aircraft. There are eight different MSG types.
  • transmission_type (int) –

    Message subtype 1-8. Only used for transmission messages (MSG):

    Value Spec Description
    1 DF17 BDS 0,8 ES Identification and Category
    2 DF17 BDS 0,6 ES Surface Position Message (Triggered by nose gear squat switch.)
    3 DF17 BDS 0,5 ES Airborne Position Message
    4 DF17 BDS 0,9 ES Airborne Velocity Message
    5 DF4, DF20 Surveillance Alt Message (Triggered by ground radar. Not CRC secured.)
    6 DF5, DF21 Surveillance ID Message (Triggered by ground radar. Not CRC secured.)
    7 DF16 Air To Air Message (Triggered from TCAS)
    8 DF11 All Call Reply (Broadcast but also triggered by ground radar)

    Transmission messages of type 5 and 6 will only be output if the aircraft has previously sent a MSG 1, 2, 3, 4 or 8 signal.

    Abbr.: DF = Downlink Format, BDS = Binary Data Store, TCAS = Traffic Alert and Collision Avoidance System

  • session_id (int) – Database Session record number.
  • aircraft_id (int) – Database Aircraft record number.
  • hexident (str) – Aircraft Mode S hexadecimal code, given in upper case.
  • flight_id (str) – Database Flight record number, given in upper case.
  • generation_time (datetime.datetime) – Generation time of the message.
  • record_time (datetime.datetime) – Recording time of the message.
  • callsign (str) – An eight digit flight ID - can be flight number or registration (or even nothing).
  • altitude (int) – Mode C altitude. Height relative to 1013.2mb (Flight Level). Not height above MSL (mean sea level).
  • ground_speed (float) – Speed over ground (not indicated airspeed) in knots (use helpers.knots_to_kmh or helpers.knots_to_mps to convert).
  • track (float) – Track of aircraft (not heading), in degrees. Derived from the velocity E/W and velocity N/S.
  • latitude (float) – Latitude in degrees, North and East positive. Airborne valid for 4 decimal places (about 5.1m), on ground valid for 5 places (about 1.25m). Since not all positions can be encoded, some information has to be added by the client. This is not implemented in py1090 yet.
  • longitude (float) – Longitude in degrees, South and West negative. For accuracy information see latitude.
  • vertical_rate (int) – Vertical velocity in ft/s, 64ft/s resolution.
  • squawk (str) – Assigned Mode A squawk code.
  • squawk_alert (bool) – Flag to indicate squawk has changed.
  • emergency (bool) – Flag to indicate emergency code has been set.
  • spi (bool) – Special Purpose identification. Flag to indicate transponder ident has been activated.
  • on_ground (bool) – Flag to indicate ground squat switch is active.
to_string()[source]

Serializes the message into the BaseStation format.

Return type:str
classmethod from_string(string)[source]

Creates a new message from a BaseStation format line.

Parameters:string (str) – String to parse.
Return type:Message
static iter_messages(iterator)[source]

Iterates an through an iterator and yields one message per line

for message in Message.iter_messages(file):
        print(message)
Parameters:iterator (iterable) –

Collection of flights

class py1090.FlightCollection[source]

Bases: object

A collection of FlightCollectionEntry‘s, stored by hexident.

It does not provide groundbreaking new features, but it’s a helper that stores flights for easy querying. An instance can be queried (collection['xxxxx']) and iterated through.

add(message)[source]

Adds a message to this collection.

Parameters:message (Message) – message to add
add_list(iterable)[source]

Adds multiple messages to the collection.

Parameters:iterable (iterable) – List, file-like object or Connection which contains all lines to be added. Calls Message.from_string() on each item if it is not a Message already.
flights()[source]

All stored flights.

Returns:List of py1090.collection.FlightCollectionEntry
Return type:list
class py1090.collection.FlightCollectionEntry[source]

Bases: object

Entry of a FlightCollection. Allows for easy querying flight data, since one single message does not contain all the data information about a flight.

See also

Message
For details about the accuracy of the positional information provided by this class.
append(message)[source]

Adds a message that should belong to this collection.

Will raise an exception if the message hexident does not match the one of the flight. Only adds message of type ‘MSG’ (transmission messages).

Parameters:message (Message) – the message to append
last_altitude

Finds the last known altitude of the flight (by iterating backwards through collected messages).

Returns:the altitude in feet, None otherwise.
Return type:float
last_position

Finds the last known position of the flight (by iterating backwards through collected messages).

Returns:a tuple of float if the position was ever recorded, (None, None) otherwise.
Return type:tuple
path

Reconstructs the flight path. Yields it as an iterator.

Yields:tuple – (lat, lon, alt) describing the latitude, longitude and altitude of a message