diff --git a/mesh.proto b/mesh.proto index ae7b65b..bc1b104 100644 --- a/mesh.proto +++ b/mesh.proto @@ -56,7 +56,7 @@ message Position { */ /* - * In meters above MSL + * In meters above MSL (but see issue #359) */ int32 altitude = 3; @@ -73,6 +73,157 @@ message Position { * seconds since 1970 */ fixed32 time = 9; + + /* + * Precision positioning elements - optional and usually not included + * ------------------------------------------------------------------ + */ + + /* + * How the location was acquired: manual, onboard GPS, external (EUD) GPS + */ + enum LocSource { + LOCSRC_UNSPECIFIED = 0; + LOCSRC_MANUAL_ENTRY = 1; + LOCSRC_GPS_INTERNAL = 2; + LOCSRC_GPS_EXTERNAL = 3; + /* + * More location sources can be added here when available: + * GSM, radio beacons (BLE etc), location fingerprinting etc + */ + } + + LocSource location_source = 10; + + /* + * How the altitude was acquired: manual, GPS int/ext, etc + * Default: same as location_source if present + */ + enum AltSource { + ALTSRC_UNSPECIFIED = 0; + ALTSRC_MANUAL_ENTRY = 1; + ALTSRC_GPS_INTERNAL = 2; + ALTSRC_GPS_EXTERNAL = 3; + ALTSRC_BAROMETRIC = 4; + } + + AltSource altitude_source = 11; + + /* + * Positional timestamp (actual timestamp of GPS solution) in integer epoch seconds + */ + fixed32 pos_timestamp = 12; + + /* + * Pos. timestamp milliseconds adjustment (rarely available or required) + */ + int32 pos_time_millis = 13; + + /* + * HAE altitude in meters - can be used instead of MSL altitude + */ + sint32 altitude_hae = 14; + + /* + * Geoidal separation in meters + */ + sint32 alt_geoid_sep = 15; + + /* + * Horizontal, Vertical and Position Dilution of Precision, in 1/100 units + * - PDOP is sufficient for most cases + * - for higher precision scenarios, HDOP and VDOP can be used instead, + * in which case PDOP becomes redundant (PDOP=sqrt(HDOP^2 + VDOP^2)) + */ + uint32 PDOP = 16; + uint32 HDOP = 17; + uint32 VDOP = 18; + + /* + * GPS accuracy (a hardware specific constant) in mm + * multiplied with DOP to calculate positional accuracy + * Default: "'bout three meters-ish" :) + */ + uint32 gps_accuracy = 19; + + /* + * Ground speed in m/s and True North TRACK in 1/100 degrees + * + * Clarification of terms: + * - "track" is the direction of motion (measured in horizontal plane) + * - "heading" is where the fuselage points (measured in horizontal plane) + * - "yaw" indicates a relative rotation about the vertical axis + */ + uint32 ground_speed = 20; + uint32 ground_track = 21; + + /* + * GPS fix quality (from NMEA GxGGA statement or similar) + */ + uint32 fix_quality = 22; + + /* + * GPS fix type 2D/3D (from NMEA GxGSA statement) + */ + uint32 fix_type = 23; + + /* + * GPS "Satellites in View" number + */ + uint32 sats_in_view = 24; + + /* + * Sensor ID - in case multiple positioning sensors are being used + */ + uint32 sensor_id = 25; + + /* + * Values relevant mainly to airborne users + */ + + /* + * Orientation angles of aircraft: + * - heading: True North direction in which the fuselage is pointing + * - roll: angle between trans axis and trans-long plane (positive = right wing low) + * - pitch: angle between horizontal axis and horizontal plane (positive = nose up) + * All values in 1/100 degrees + */ + uint32 heading = 30; + sint32 roll = 31; + sint32 pitch = 32; + + /* + * True air speed in meters/second + */ + uint32 air_speed = 33; + + /* + * Distance to ground (measured directly, i.e by a range sensor) + * in cm (1/100 of meters) + */ + uint32 ground_distance_cm = 34; + + /* + * End of values relevant to airborne users + */ + + /* + * Estimated/expected time (in seconds) until next update: + * - if we update at fixed intervals of X seconds, use X + * - if we update at dynamic intervals (based on relative movement etc), + * but "AT LEAST every Y seconds", use Y + */ + uint32 pos_next_update = 40; + + /* + * A sequence number, incremented with each Position message to help + * detect lost updates if needed + */ + uint32 pos_seq_number = 41; + + /* + * END precision positioning elements + */ } /* diff --git a/radioconfig.proto b/radioconfig.proto index ffc45fa..7be2507 100644 --- a/radioconfig.proto +++ b/radioconfig.proto @@ -177,6 +177,46 @@ enum LocationSharing { LocDisabled = 2; } +/* + * Bit field of boolean configuration options, indicating which optional + * fields to include when assembling POSITION messages + * Longitude and latitude are always included (also time if GPS-synced) + * + * NOTE: the more fields are included, the larger the message will be - + * leading to longer airtime and a higher risk of packet loss + */ +enum PositionFlags { + /* Required for compilation */ + POS_UNDEFINED = 0x0000; + + /* Include an altitude value (if available) */ + POS_ALTITUDE = 0x0001; + + /* Altitude value is MSL */ + POS_ALT_MSL = 0x0002; + + /* Include geoidal separation */ + POS_GEO_SEP = 0x0004; + + /* Include the DOP value ; PDOP used by default, see below */ + POS_DOP = 0x0008; + + /* If POS_DOP set, send separate HDOP / VDOP values instead of PDOP */ + POS_HVDOP = 0x0010; + + /* Include battery level */ + POS_BATTERY = 0x0020; + + /* Include number of "satellites in view" */ + POS_SATINVIEW = 0x0040; + + /* Include a sequence number incremented per packet */ + POS_SEQ_NOS = 0x0080; + + /* Include positional timestamp (from GPS solution) */ + POS_TIMESTAMP = 0x0100; +} + /* * The entire set of user settable/readable settings for our radio device. * Includes both the current channel settings and any preferences the user has @@ -485,6 +525,11 @@ message RadioConfig { */ uint32 environmental_measurement_plugin_sensor_pin = 147; + /* + * Bit field of boolean configuration options for POSITION messages + * (bitwise OR of PositionFlags) + */ + uint32 position_flags = 150; }