# Copyright (C) 2015-2021 Swift Navigation Inc.
# Contact: https://support.swiftnav.com
#
# This source is subject to the license found in the file 'LICENSE' which must
# be distributed together with this source. All other rights reserved.
#
# THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
# EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED
# WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.

package: swiftnav.sbp.solution_meta
description: Standardized Metadata messages for Fuzed Solution from Swift Navigation devices.
stable: True
public: True
include:
  - types.yaml
definitions:

 # the actual union-like type of the elements going into the array sol_in in MSG_SOLN_META
 - SolutionInputType:
     short_desc: Flags for a given solution input type
     desc: >
       Metadata describing which sensors were involved in the solution.
       The structure is fixed no matter what the actual sensor type is.
       The sensor_type field tells you which sensor we are talking about. It also tells you
       whether the sensor data was actually used or not.
       The flags field, always a u8, contains the sensor-specific data.
       The content of flags, for each sensor type, is described in the relevant structures in this section.
     type: u16
     fields:
       - sensor_type:
           type: u8
           desc: The type of sensor
           fields:
             - 5-7:
                 desc: Reserved
             - 3-4:
                 desc: Sensor Usage
                 values:
                   - 0: Unknown
                   - 1: Received and used
                   - 2: Received but not used
             - 0-2:
                 desc: Sensor Type
                 values:
                   - 0: Invalid
                   - 1: GNSS Position (see GNSSInputType)
                   - 2: GNSS Velocity Displacement (see GNSSInputType)
                   - 3: GNSS Velocity Doppler (see GNSSInputType)
                   - 4: Odometry Ticks (see OdoInputType)
                   - 5: Odometry Speed (see OdoInputType)
                   - 6: IMU Sensor (see IMUInputType)
                   - 7: Reserved
       - flags:
           type: u8
           units: (XX)InputType
           desc: Refer to each InputType description

 - MSG_SOLN_META_DEP_A:
     id: 0xFF0F
     short_desc: Deprecated
     desc: Deprecated.
     public: false
     replaced_by:
       - MSG_SOLN_META
     fields:
       - pdop:
           type: u16
           units: 0.01
           desc: Position Dilution of Precision as per last available DOPS from PVT engine (0xFFFF indicates invalid)
       - hdop:
           type: u16
           units: 0.01
           desc: Horizontal Dilution of Precision as per last available DOPS from PVT engine (0xFFFF indicates invalid)
       - vdop:
           type: u16
           units: 0.01
           desc: Vertical Dilution of Precision as per last available DOPS from PVT engine (0xFFFF indicates invalid)
       - n_sats:
           type: u8
           desc: Number of satellites as per last available solution from PVT engine
       - age_corrections:
           type: u16
           units: deciseconds
           desc: Age of corrections as per last available AGE_CORRECTIONS from PVT engine (0xFFFF indicates invalid)
       - alignment_status:
           type: u8
           desc: State of alignment and the status and receipt of the alignment inputs
           fields:
             - 3-7:
                 desc: Reserved
             - 0-2:
                 desc: Alignment status
                 values:
                   - 0: Unknown reason or already aligned
                   - 1: Seed values loaded and Alignment in progress
                   - 2: No seed values and Alignment in progress
                   - 3: Seed values loaded but no GNSS measurements
                   - 4: No seed values nor GNSS measurements
                   - 5: Reserved
                   - 6: Reserved
                   - 7: Reserved
       - last_used_gnss_pos_tow:
           type: u32
           units: ms
           desc: Tow of last-used GNSS position measurement
       - last_used_gnss_vel_tow:
           type: u32
           units: ms
           desc: Tow of last-used GNSS velocity measurement
       - sol_in:
           type: array
           fill: SolutionInputType
           desc: Array of Metadata describing the sensors potentially involved in the solution.
             Each element in the array represents a single sensor type and consists of flags containing (meta)data
             pertaining to that specific single sensor. Refer to each (XX)InputType descriptor in the present doc.

 - MSG_SOLN_META:
     id: 0xFF0E
     short_desc: Solution Sensors Metadata
     public: true
     desc: >
       This message contains all metadata about the sensors received and/or used in computing the sensorfusion solution.
       It focuses primarily, but not only, on GNSS metadata.
       Regarding the age of the last received valid GNSS solution, the highest two bits are time status, indicating
       whether age gnss can or can not be used to retrieve time of measurement (noted TOM, also known as time of validity)
       If it can, subtract 'age gnss' from 'tow' in navigation messages to get TOM. Can be used before alignment is
       complete in the Fusion Engine, when output solution is the last received valid GNSS solution and its tow is not a TOM.
     fields:
       - tow:
           type: u32
           units: ms
           desc: GPS time of week rounded to the nearest millisecond
       - pdop:
           type: u16
           units: 0.01
           desc: Position Dilution of Precision as per last available DOPS from PVT engine (0xFFFF indicates invalid)
       - hdop:
           type: u16
           units: 0.01
           desc: Horizontal Dilution of Precision as per last available DOPS from PVT engine (0xFFFF indicates invalid)
       - vdop:
           type: u16
           units: 0.01
           desc: Vertical Dilution of Precision as per last available DOPS from PVT engine (0xFFFF indicates invalid)
       - age_corrections:
           type: u16
           units: deciseconds
           desc: Age of corrections as per last available AGE_CORRECTIONS from PVT engine (0xFFFF indicates invalid)
       - age_gnss:
           type: u32
           units: ms
           desc: Age and Time Status of the last received valid GNSS solution.
           fields:
             - 30-31:
                 desc: Time status
                 values:
                     - 0: Age can not be used to retrieve TOM
                     - 1: Age can be used to retrieve TOM
                     - 2: Reserved
                     - 3: Reserved
             - 0-29:
                 desc: Age of the last received valid GNSS solution
       - sol_in:
           type: array
           fill: SolutionInputType
           desc: Array of Metadata describing the sensors potentially involved in the solution.
             Each element in the array represents a single sensor type and consists of flags containing (meta)data
             pertaining to that specific single sensor. Refer to each (XX)InputType descriptor in the present doc.

 #############################################
 # One structure definition per sensor class
 # Feel free to add more sensor Classes.
 # They must all consist of only a u8 flags field.
 # This type are never used nor instantiated per se.
 # These definitions are for reference and documentation purposes.
 #############################################
 # for GNSS sensors
 - GNSSInputType:
     short_desc: Instruments the physical type of GNSS sensor input to the fuzed solution
     public: true
     embedded_type: true
     desc: >
       Metadata around the GNSS sensors involved in the fuzed solution.
       Accessible through sol_in[N].flags in a MSG_SOLN_META.
     fields:
       - flags:
           type: u8
           desc: flags that store all relevant info specific to this sensor type.
           fields:
             - 2-7:
                 desc: Reserved
             - 0-1:
                 desc: Type of GNSS measurement
                 values:
                   - 0: GNSS Position
                   - 1: GNSS Velocity Doppler
                   - 2: GNSS Velocity Displacement

 # for IMU sensors
 - IMUInputType:
     short_desc: >
       Provides detail about the IMU sensor, its timestamping mode,
       and its quality for input to the fuzed solution
     public: true
     embedded_type: true
     desc: >
       Metadata around the IMU sensors involved in the fuzed solution.
       Accessible through sol_in[N].flags in a MSG_SOLN_META.
     fields:
       - flags:
           type: u8
           desc: Instrument time, grade, and architecture for a sensor.
           fields:
             - 6-7:
                 desc: Reserved
             - 4-5:
                 desc: Time status
                 values:
                   - 0: Reference epoch is start of current GPS week
                   - 1: Reference epoch is time of system startup
                   - 2: Reference epoch is unknown
                   - 3: Reference epoch is last PPS
             - 2-3:
                 desc: IMU Grade
                 values:
                   - 0: Consumer Grade
                   - 1: Tactical grade
                   - 2: Intermediate Grade
                   - 3: Superior (Marine / Aviation) Grade
             - 0-1:
                 desc: IMU architecture
                 values:
                   - 0: 6-axis MEMS
                   - 1: Other type

 # for Odometry sensors
 - OdoInputType:
     short_desc: >
       Provides detail about the Odometry sensor, its timestamping mode,
       and its quality for input to the fuzed solution
     public: true
     embedded_type: true
     desc: >
       Metadata around the Odometry sensors involved in the fuzed solution.
       Accessible through sol_in[N].flags in a MSG_SOLN_META.
     fields:
       - flags:
           type: u8
           desc: Instrument ODO rate, grade, and quality.
           fields:
             - 6-7:
                 desc: Reserved
             - 4-5:
                 desc: Rate
                 values:
                   - 0: Fixed incoming rate
                   - 1: Triggered by minimum distance or speed
                   - 2: Reserved
                   - 3: Reserved
             - 2-3:
                 desc: Odometer grade
                 values:
                   - 0: Low Grade (e.g. quantized CAN)
                   - 1: Medium Grade
                   - 2: Superior Grade
                   - 3: Reserved
             - 0-1:
                 desc: Odometer class
                 values:
                   - 0: Single or averaged ticks
                   - 1: Single or averaged speed
                   - 2: Multi-dimensional ticks
                   - 3: Multi-dimensional speed