2.1.1.1.1. adsb.sbs package

2.1.1.1.1.1. Submodules

2.1.1.1.1.2. adsb.sbs.aircraft module

This module implements an aircraft class to store details of aircraft that are active during a session.

class adsb.sbs.aircraft.Aircraft(hex_ident: str, history_size: int = 50, history_interval: int = 5) → None

Bases: object

The Aircraft class stores details for a specific aircraft observed during a session.

distance

Return the distance in km between a location and this aircraft.

path() → List[Tuple[[datetime.datetime, float, float], float]]

Return the travel path of this aircraft

position

Return the aircraft position as (lat, lon) tuple

update_altitude(alt: float, timestamp: datetime.datetime)

Update the altitude of the aircraft

update_details(details: dict)

Associate aircraft details, such as model, type, operator, etc, with this aircraft.

update_ident(callsign: str, timestamp: datetime.datetime)

Update the identity of the aircraft

update_motion(ground_speed: float, track: float, vertical_rate: float, timestamp: datetime.datetime)

Update the motion attributes of the aircraft

update_position(alt: float, lat: float, lon: float, timestamp: datetime.datetime)

Update the position attributes of the aircraft

2.1.1.1.1.3. adsb.sbs.archive module

This module implements a SBS message archive writing and reading capability. It can be used to save messages to file so that they can be replayed or analysed at a later time.

An archive is simply a recording of the message lines that were received from the server. Each message line item is prefixed with a timestamp and terminated with a new line. By associating a timestamp with the message in the log file the messages can then be replayed at different rates.

class adsb.sbs.archive.RotatingArchiveFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None)

Bases: object

Base class for handlers that record to disk files and rotate log files at a certain point.

Handler for logging to a set of files, which switches from one file to the next when the current file reaches a certain size.

Shamelessly duplicated from the Python standard library logging module with deep class hierarchy condensed and stripped of logger record specifics.

close()

Closes the stream.

doRollover()

Do a rollover, as described in __init__().

emit(record: str)

Emit a record to the log file, catering for rollover as described in doRollover().

In this case the record is a SBS format message line. It does not require any extra formatting. This method overrides the default logging behaviour so that SBS messsages can be written to file directly.

A timestamp, in UTC, is added to facilitate replaying a session log at a rate faster than real time while keeping the relative spacing between the messages.

flush()

Flushes the stream.

rotate(source, dest)

When rotating, rotate the current log.

The default implementation calls the ‘rotator’ attribute of the handler, if it’s callable, passing the source and dest arguments to it. If the attribute isn’t callable (the default is None), the source is simply renamed to the destination.

Parameters:

• source – The source filename. This is normally the base filename, e.g. ‘test.log’
• dest – The destination filename. This is normally what the source is rotated to, e.g. ‘test.log.1’.

rotation_filename(default_name)

Modify the filename of a log file when rotating.

This is provided so that a custom filename can be provided.

The default implementation calls the ‘namer’ attribute of the handler, if it’s callable, passing the default name to it. If the attribute isn’t callable (the default is None), the name is returned unchanged.

Parameters:default_name – The default name for the log file.

shouldRollover(record)

Determine if rollover should occur.

Basically, see if the supplied record would cause the file to exceed the size limit we have.

terminator = '\r\n'

adsb.sbs.archive.read_archive(archive_file)

This generator yields lines from a session archive log file. Each line is returned as a 2-tuple containing a UTC timestamp and the SBS format message bytes.

Parameters:archive_file – An archive file

2.1.1.1.1.4. adsb.sbs.client module

class adsb.sbs.client.Client(host: str = 'localhost', port: int = 30003, on_raw_msg_callback: Callable[bytes, NoneType] = None, on_msg_callback: Callable[adsb.sbs.message.SBSMessage, NoneType] = None, record: bool = False, record_file: str = None, loop: asyncio.events.AbstractEventLoop = None)

Bases: object

A SBS message client.

A Client connects to a SBS server to obtain ADSB messages in the SBS format. A Client can record messages to a file if configured to do so.

Users of the Client would typically provide a callback function to receive either raw message string or SBSMessage objects.

connect(host: str, port=30003) → None

Connect to a SBS interface.

Parameters:

• host – The SBS server host to connect to.
• port – The SBS server port to connect to.

disconnect() → None

Disconnect from a SBS interface

start() → None

Start the client

start_recording(record_file: str = None, maxBytes: int = 8388608, backupCount: int = 3) → None

Start recording messages to a log file

stop() → None

Stop the client

stop_recording() → None

Stop recording messages to file

2.1.1.1.1.5. adsb.sbs.json_utils module

The JSON encoding and decoding functions are modelled after the json package which use loads to parse a message from a string and dumps to encode a message to a string.

class adsb.sbs.json_utils.DateTimeAwareDecoder

Bases: json.decoder.JSONDecoder

Extend JSON decoder to support decoding datetime and timedelta objects

dict_to_object(d)

class adsb.sbs.json_utils.DateTimeAwareEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: json.encoder.JSONEncoder

Extend JSON encoder to support encoding datetime and timedelta objects

default(obj)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

adsb.sbs.json_utils.dumps(m: adsb.sbs.message.SBSMessage, indent: int = None, sort_keys: bool = False) → str

Serialize a SBSMessage object into a JSON format string

adsb.sbs.json_utils.loads(line: Union[bytes, str]) → adsb.sbs.message.SBSMessage

Deserialize a JSON format string into a SBSMessage

2.1.1.1.1.6. adsb.sbs.message module

This module implements classes and functions to assist with parsing a SBS format message line into a SBSMessage object and back again.

class adsb.sbs.message.Fields

Bases: enum.Enum

SBS protocol message fields.

Fields a declared in the order they appear in a message.

aircraft_id = 3

alert = 18

altitude = 11

callsign = 10

emergency = 19

flight_id = 5

generated_date = 6

generated_time = 7

ground_speed = 12

hex_ident = 4

is_on_ground = 21

lat = 14

logged_date = 8

logged_time = 9

lon = 15

message_type = 0

session_id = 2

spi = 20

squawk = 17

track = 13

transmission_type = 1

vertical_rate = 16

class adsb.sbs.message.MessageType

Bases: object

This class defines the different SBS message types.

Transmission messages contain information sent by aircraft. All others are produced by the application supplying the SBS feed.

Click = 'CLK'

New_Aircraft = 'AIR'

New_Id = 'ID'

Selection_Change = 'SEL'

Status_Aircraft = 'STA'

Transmission = 'MSG'

class adsb.sbs.message.SBSMessage(message_type, transmission_type, session_id, aircraft_id, hex_ident, flight_id, generated_date, generated_time, logged_date, logged_time, callsign, altitude, ground_speed, track, lat, lon, vertical_rate, squawk, alert, emergency, spi, is_on_ground)

Bases: tuple

aircraft_id

Alias for field number 3

alert

Alias for field number 18

altitude

Alias for field number 11

callsign

Alias for field number 10

emergency

Alias for field number 19

flight_id

Alias for field number 5

generated_date

Alias for field number 6

generated_time

Alias for field number 7

ground_speed

Alias for field number 12

hex_ident

Alias for field number 4

is_on_ground

Alias for field number 21

lat

Alias for field number 14

logged_date

Alias for field number 8

logged_time

Alias for field number 9

lon

Alias for field number 15

message_type

Alias for field number 0

session_id

Alias for field number 2

spi

Alias for field number 20

squawk

Alias for field number 17

track

Alias for field number 13

transmission_type

Alias for field number 1

vertical_rate

Alias for field number 16

class adsb.sbs.message.TransmissionType

Bases: enum.Enum

Only ES_SURFACE_POS and ES_AIRBORNE_POS transmissions have position (latitude and longitude) information.

ES = Entended Squitter DF = Downlink Format BDS = B-Definition Subfield

AIR_TO_AIR = 7

ALL_CALL_REPLY = 8

ES_AIRBORNE_POS = 3

ES_AIRBORNE_VEL = 4

ES_IDENT_AND_CATEGORY = 1

ES_SURFACE_POS = 2

SURVEILLANCE_ALT = 5

SURVEILLANCE_ID = 6

adsb.sbs.message.fromString(line: Union[bytes, str]) → adsb.sbs.message.SBSMessage

Parse a SBS format message string into a SBSMessage object.

Parameters:line – A bytes or string object representing a SBS format message.

adsb.sbs.message.toString(m: adsb.sbs.message.SBSMessage) → bytes

Convert a SBS message object to s SBS format string

2.1.1.1.1.7. adsb.sbs.protocol module

This module implements a protocol for receiving messages in the SBS format.

class adsb.sbs.protocol.SBSProtocol(on_msg_callback: Callable[str, NoneType] = None, loop: asyncio.events.AbstractEventLoop = None)

Bases: asyncio.protocols.Protocol

A simple line based protocol to extract SBS messages from a stream.

close() → None

Close the connection

connection_lost(reason: str) → None

React to an existing connection being lost

connection_made(transport: asyncio.transports.BaseTransport) → None

React to a new connection being made

data_received(data: bytes) → None

Process a raw data stream. Accumulate message chunks until a complete message can be extracted from the buffer. Messages are delimited by the characters rn.

Sources such as mutability/dump1090 also send a heartbeat message, containing only rn, if there is no ADSB activity. These need to be handled gracefully.

Each SBS message has the trailing rn delimiter discarded and is converted to a string before being passed to the message handler.

class adsb.sbs.protocol.SBSServerProtocol(server: SBSServer)

Bases: asyncio.protocols.Protocol

A SBSProtocol instance specifically for use in a SBS server.

The main use for this class is in unit tests.

close() → None

Close the connection

connection_lost(reason: str) → None

Called when the connection is lost or closed.

The argument is an exception object or None (the latter meaning a regular EOF is received or the connection was aborted or closed).

connection_made(transport: asyncio.transports.BaseTransport) → None

Called when a connection is made.

The argument is the transport representing the pipe connection. To receive data, wait for data_received() calls. When the connection is closed, connection_lost() is called.

data_received(data: bytes) → None

The server does not expect to receive data from clients. It is effectively a one-way publisher socket.

send_message(data: bytes, add_delimiter: bool = False) → None

Send message to client.

Parameters:

• bytes – A SBS format message string encoded into bytes to send to clients.
• add_delimiter – A boolean flag that determines if a message delimiter should be added to the message bytes. By default this is False.

2.1.1.1.1.8. adsb.sbs.server module

class adsb.sbs.server.Server(host: str = 'localhost', port: int = 30003, backlog=100, loop: asyncio.events.AbstractEventLoop = None) → None

Bases: object

deregister_protocol(peer: Tuple[str, int]) → None

De-register a protocol instance from the server.

This peer will no longer receive messages.

Parameters:peer – Tuple of (host:str, port:int).

register_protocol(peer: Tuple[str, int], prot: SBSServerProtocol) → None

Register a protocol instance with the server.

Parameters:

• peer – Tuple of (host:str, port:int).
• prot – a SBSServerProtocol instance.

send_message(msg: bytes, peer: Tuple[str, int] = None) → None

Send a message.

Parameters:

• msg – A bytes object representing the SBS format message to send to peers. The message is assumed to include the end of message delimiter.
• peer – A specific peer to send the message to. Peer is a Tuple of (host:str, port:int). If not specified then the message is broadcast to all peers.

start() → None

Start the server

stop() → None

Stop the server

2.1.1.1.1.9. adsb.sbs.session module

A session maintains information about the currently visible aircraft.

class adsb.sbs.session.Session(record: bool = False, record_file: str = None, cache_enabled: bool = True, cache_file: str = 'session_cache.pickle', session_threshold_minutes: int = 2, check_interval: float = 5.0, origin: Tuple[float, float] = None, loop: asyncio.events.AbstractEventLoop = None)

Bases: object

A session maintains information about aircraft received from a SBS Client.

A session is connected to a SBS source to receive a stream of messages or can operate in a replay mode where it is fed messages from a session log archive.

close()

Stop the session

connect(host, port=30003)

Connect the session to a SBS interface

discard_lost_aircraft(aircraft_dict)

Remove aircraft that were last seen beyond the expiry threshold. The expiry threshold is a configurable session attribute.

Parameters:aircraft_dict – A dict of aircraft participating in this session.

disconnect()

Disconnect the session from a SBS interface

load_aircraft_cache()

Initialise the aircraft cache using the cache file.

manage_session()

Perform periodic session management actions.

on_sbs_message(msg_str: str)

Process a SBS message line string.

This method is typically called by a SBS client. However, it may also be called when replaying a session file.

start_recording(record_file: str = None, maxBytes: int = 8388608, backupCount: int = 3)

Start recording session messages to log file.

stop_recording()

Stop recording session messages to file.

2.1.1.1.1.10. Module contents