readsb.proto

// Part of readsb, a Mode-S/ADSB/TIS message decoder.
//
// readsb.proto: Protocol buffer scheme for aicraft data exchange,
//               receiver details and statistics.
//
// Copyright (c) 2020 Michael Wolf <michael@mictronics.de>
//
// This file is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// any later version.
//
// This file is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <http://www.gnu.org/licenses/>.

syntax = "proto3";

/**
 * Readsb single tracked aircraft meta data.
 */
message AircraftMeta {
	uint32 addr = 1; // The 24-bit ICAO identifier of the aircraft, as 6 hex digits. The identifier may start with '~', this means that the address is a non-ICAO address (e.g. from TIS-B).
	string flight = 2; // Callsign, the flight name or aircraft registration as 8 chars.
	uint32 squawk = 3; // Mode A code (Squawk), encoded as 4 octal digits.
	uint32 category	= 4; // Emitter category to identify particular aircraft or vehicle classes (values A0 - D7).
	int32 alt_baro = 5; // The aircraft barometric altitude in feet.
	int32 mag_heading = 6; // Heading, degrees clockwise from magnetic north.
	uint32 ias = 7; // Indicated air speed in knots.
	double lat = 8; // Aircraft position latitude in decimal degrees.
	double lon = 9; // Aircraft position longitude in decimal degrees.
	uint64 messages = 10;  // Total number of Mode S messages received from this aircraft.
	uint64 seen = 11; // When a message was last received from this aircraft. (in milliseconds!!!)
	float rssi = 12; // Recent average RSSI (signal power), in dbFS; this will always be negative.
    uint32 distance = 13; // Distance to site in meter.

	reserved 14;

    enum AirGround {
        AG_INVALID = 0;
        AG_GROUND = 1;
        AG_AIRBORNE = 2;
        AG_UNCERTAIN = 3;
    }
    AirGround air_ground = 15;

	int32 alt_geom = 20; // Geometric (GNSS / INS) altitude in feet referenced to the WGS84 ellipsoid.
	int32 baro_rate = 21; // Rate of change of barometric altitude, feet/minute.
	int32 geom_rate = 22; // Rate of change of geometric (GNSS / INS) altitude. feet/minute
	uint32 gs = 23; // Ground speed in knots.
	uint32 tas = 24; // True air speed in knots.
	float mach = 25; // Mach number.
	int32 true_heading = 26; // Heading, degrees clockwise from true north.
    int32 track = 27; // True track over ground in degrees (0-359).
	float track_rate = 28; // Rate of change of track, degrees/second.
	float roll = 29; // Roll, degrees, negative is left roll.
	
	float nav_qnh = 30; // Navigation Accuracy for Velocity.
	int32 nav_altitude_mcp =31; // Selected altitude from the Mode Control Panel / Flight Control Unit (MCP/FCU) or equivalent equipment.
	int32 nav_altitude_fms = 32; // Selected altitude from the Flight Management System (FMS).
	int32 nav_heading = 33; // Selected heading (True or Magnetic is not defined in DO-260B, mostly Magnetic as that is the de facto standard).

	uint32 nic = 34; // Navigation Integrity Category.
	uint32 rc = 35; // Radius of Containment, meters; a measure of position integrity derived from NIC & supplementary bits.

	int32 version = 36; // ADS-B Version Number 0, 1, 2 (3-7 are reserved)
	uint32 nic_baro = 37; // Navigation Integrity Category for Barometric Altitude
	uint32 nac_p = 38; // Navigation Accuracy for Position
	uint32 nac_v = 39; // Navigation Accuracy for Velocity
	uint32 sil = 40; // Source Integity Level
	
	uint32 seen_pos = 41; // How long ago (in seconds before "now") the position was last updated.
	bool alert = 42; // Flight status alert bit.
	bool spi = 43; // Flight status special position identification bit.
	uint32 gva = 44; // Geometric Vertical Accuracy
    uint32 sda = 45; // System Design Assurance
    double declination = 46; // Geomagnetic declination depending on position
    uint32 wind_speed = 47; // Calculated wind speed
    uint32 wind_direction = 48; // Calculated wind direction
	
	// Type of underlying message, one of:
	enum AddrType {
		ADDR_ADSB_ICAO = 0; // Mode S or ADS-B, ICAO address, transponder sourced.
		ADDR_ADSB_ICAO_NT = 1; // ADS-B, ICAO address, non-transponder.
		ADDR_ADSR_ICAO = 2; // ADS-R, ICAO address.
		ADDR_TISB_ICAO = 3; // TIS-B, ICAO address.
		ADDR_ADSB_OTHER = 4; // ADS-B, other address format.
		ADDR_ADSR_OTHER = 5; // ADS-R, other address format.
		ADDR_TISB_TRACKFILE = 6; // TIS-B, Mode A code + track file number.
		ADDR_TISB_OTHER = 7; // TIS-B, other address format.
		ADDR_MODE_A = 8; // Mode A.
		ADDR_UNKNOWN = 9; // Unknown address format.
	}
	AddrType addr_type = 100;

	// ADS-B emergency/priority status, a superset of the 7x00 squawks
	enum Emergency
	{
		EMERGENCY_NONE = 0;
		EMERGENCY_GENERAL = 1;
		EMERGENCY_LIFEGUARD = 2;
		EMERGENCY_MINFUEL = 3;
		EMERGENCY_NORDO = 4;
		EMERGENCY_UNLAWFUL = 5;
		EMERGENCY_DOWNED = 6;
		EMERGENCY_RESERVED = 7;
	}
	Emergency emergency = 101;
	
	// Interpretation of SIL: unknown, perhour, persample.
	enum SilType {
		SIL_INVALID = 0;
		SIL_UNKNOWN = 1;
		SIL_PER_SAMPLE = 2;
		SIL_PER_HOUR = 3;
	}
	SilType sil_type = 102;
   
  	// Set of engaged automation modes.
	message NavModes {
		bool autopilot = 1;
		bool vnav = 2;
		bool althold = 3;
		bool approach = 4;
		bool lnav = 5;
		bool tcas = 6;
	}
	NavModes nav_modes = 150;
    
	// List of valid source fields for each parameter.
	message ValidSource {
        uint32 callsign = 100;
        uint32 altitude = 101;
        uint32 alt_geom = 102;
        uint32 gs = 103;
        uint32 ias = 104;
        uint32 tas = 105;
        uint32 mach = 106;
        uint32 track = 107;
        uint32 track_rate = 108;
        uint32 roll = 109;
        uint32 mag_heading = 110;
        uint32 true_heading = 111;
        uint32 baro_rate = 112;
        uint32 geom_rate = 113;
        uint32 squawk = 114;
        uint32 emergency = 115;
        uint32 nav_qnh = 116;
        uint32 nav_altitude_mcp = 117;
        uint32 nav_altitude_fms = 118;
        uint32 nav_heading = 119;
        uint32 nav_modes = 120;
        uint32 lat = 121;
        uint32 lon = 122;
        uint32 nic = 123;
        uint32 rc = 124;
        uint32 nic_baro = 125;
        uint32 nac_p = 126;
        uint32 nac_v = 127;
        uint32 sil = 128;
        uint32 sil_type = 129;
        uint32 gva = 130; 
        uint32 sda = 131;
        uint32 wind = 132;
	}
	ValidSource valid_source = 151;
}

message AircraftHistory {
	uint32 addr = 1; // The 24-bit ICAO identifier of the aircraft, as 6 hex digits.
	int32 alt_baro = 5; // The aircraft barometric altitude in feet.
	double lat = 8; // Aircraft position latitude in decimal degrees.
	double lon = 9; // Aircraft position longitude in decimal degrees.
}

/**
 * Collection of tracked aircrafts.
 */
message AircraftsUpdate {
	uint64 now = 1; // The time this file was generated, in seconds since Unix epoch.
	uint64 messages = 2; // The total number of Mode S messages processed since readsb started.
	reserved 3 to 13; // Reserved for future use.
    repeated AircraftHistory history = 14; // Aircraft position history collection.
	repeated AircraftMeta aircraft = 15; // The aircraft collection.
}

/**
 * Readsb receiver details.
 */
message Receiver {
    string version = 1; // Readsb version
    float refresh = 2; // Data refresh period.
    double latitude = 3; // Receiver location latitude.
    double longitude = 4; // Receiver location longitude.
    uint32 altitude = 5; // Receiver altitude.
    uint32 antenna_serial = 6; // Antenna serial number.
    uint32 antenna_flags = 7; // Antenna status flags.
    uint32 antenna_gps_sats = 8; // Antenna GPS satellites used in fix.
    uint32 antenna_gps_hdop = 9; // Antenna GPS HDOP*10, thus 12 is HDOP 1.2.
    uint32 antenna_reserved = 14; // Antenna internal use.
    uint32 history = 15; // Aircraft history size.
}

/**
 * Single statistcs entry.
 */
message StatisticEntry {
    uint64 start = 1; // the start time (in seconds-since-1-Jan-1970) of this statistics collection period.
    uint64 stop = 2; // the end time (in seconds-since-1-Jan-1970) of this statistics collection period.
    uint64 messages = 3; // total number of messages accepted by readsb from any source
    uint32 max_distance_in_metres = 4;
    uint32 max_distance_in_nautical_miles = 5;
    uint64 altitude_suppressed = 6;
    uint64 tracks_new = 7; // total tracks (aircrafts) created. Each track represents a unique aircraft and persists for up to 5 minutes.
    uint64 tracks_single_message = 8; // tracks consisting of only a single message. These are usually due to message decoding errors that produce a bad aircraft address.
    uint64 tracks_with_position = 9;
    uint64 tracks_mlat_position = 10;
    uint64 tracks_tisb_position = 11;
    // statistics about CPU use
    uint64 cpu_demod = 20; // milliseconds spent doing demodulation and decoding in response to data from a SDR dongle
    uint64 cpu_reader = 21; // milliseconds spent reading sample data over USB from a SDR dongle
    uint64 cpu_background = 22; // milliseconds spent doing network I/O, processing received network messages, and periodic tasks.
    // statistics about Compact Position Report message decoding.
    uint64 cpr_surface = 40; // total number of surface CPR messages received
    uint64 cpr_airborne = 41; // total number of airborne CPR messages received
    uint64 cpr_global_ok = 42; // global positions successfuly derived
    uint64 cpr_global_bad = 43; // global positions that were rejected because they were inconsistent
    uint64 cpr_global_range = 44; // global positions that were rejected because they exceeded the receiver max range
    uint64 cpr_global_speed = 45; // global positions that were rejected because they failed the inter-position speed check
    uint64 cpr_global_skipped = 46; // global position attempts skipped because we did not have the right data (e.g. even/odd messages crossed a zone boundary)
    uint64 cpr_local_ok = 47; // local (relative) positions successfully found
    uint64 cpr_local_aircraft_relative = 48; // local positions found relative to a previous aircraft position
    uint64 cpr_local_receiver_relative = 49; // local positions found relative to the receiver position
    uint64 cpr_local_skipped = 50; // local (relative) positions not used because we did not have the right data
    uint64 cpr_local_range = 51; // local positions not used because they exceeded the receiver max range or fell into the ambiguous part of the receiver range
    uint64 cpr_local_speed = 52; // local positions not used because they failed the inter-position speed check
    uint64 cpr_filtered = 53; // number of CPR messages ignored because they matched one of the heuristics for faulty transponder output     
    // statistics about messages received from remote clients. Only present in --net or --net-only mode.
    uint64 remote_modeac = 70; // number of Mode A / C messages received.
    uint64 remote_modes = 71; // number of Mode S messages received.
    uint64 remote_bad = 72; // number of Mode S messages that had bad CRC or were otherwise invalid.
    uint64 remote_unknown_icao = 73; // number of Mode S messages which looked like they might be valid but we didn't recognize the ICAO address and it was one of the message types where we can't be sure it's valid in this case.
    uint64 remote_accepted = 74; // number of valid Mode S messages accepted with N-bit errors corrected.
    // statistics about messages received from a local SDR dongle. Not present in --net-only mode.
    uint64 local_samples_processed = 90; // number of sample blocks processed
    uint64 local_samples_dropped = 91; // number of sample blocks dropped before processing. A nonzero value means CPU overload.
    uint64 local_modeac = 92; // number of Mode A / C messages decoded
    uint64 local_modes = 93; // number of Mode S preambles received. This is *not* the number of valid messages!
    uint64 local_bad = 94; // number of Mode S preambles that didn't result in a valid message
    uint64 local_unknown_icao = 95; // number of Mode S preambles which looked like they might be valid but we didn't recognize the ICAO address and it was one of the message types where we can't be sure it's valid in this case.
    uint64 local_strong_signals = 96; // number of messages received that had a signal power above -3dBFS.
    float local_signal = 97; // mean signal power of successfully received messages, in dbFS; always negative.
    float local_noise = 98; // calculated receiver noise floor level.
    float local_peak_signal = 99; // peak signal power of a successfully received message, in dbFS; always negative.
    uint64 local_accepted = 100; // the number of valid Mode S messages accepted with N-bit errors corrected.
}

/**
 * Readsb receiver statistics.
 */
message Statistics {
    StatisticEntry latest = 1; // covers the time between the end of the "last1min" period and the current time.
    StatisticEntry last_1min = 2; // covers a recent 15-minute period. As above, this may be up to 1 minute out of date.
    StatisticEntry last_5min = 3; // covers a recent 5-minute period. As above, this may be up to 1 minute out of date.
    StatisticEntry last_15min = 4; // covers a recent 1-minute period. This may be up to 1 minute out of date (i.e. "end" may be up to 1 minute old).
    StatisticEntry total = 5; // covers the entire period from when readsb was started up to the current time
    map<uint32, uint32> polar_range = 6; // maximum range per bearing, 0 to 359 degree, default resolution 5 degree.
}