system.yaml

# 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.system
description: Standardized system messages from Swift Navigation devices.
stable: True
public: True
include:
  - types.yaml
definitions:

 - MSG_STARTUP:
    id: 0xFF00
    short_desc: System start-up message
    desc: >
        The system start-up message is sent once on system
        start-up. It notifies the host or other attached devices that
        the system has started and is now ready to respond to commands
        or configuration requests.
    fields:
        - cause:
            type: u8
            desc: Cause of startup
            fields:
              - 0-7:
                  desc: Cause of startup
                  values:
                    - 0: Power on
                    - 1: Software reset
                    - 2: Watchdog reset
        - startup_type:
            type: u8
            desc: Startup type
            fields:
              - 0-7:
                  values:
                    - 0: Cold start
                    - 1: Warm start
                    - 2: Hot start

        - reserved:
            type: u16
            desc: Reserved

 - MSG_DGNSS_STATUS:
    id: 0xFF02
    short_desc: Status of received corrections
    desc: >
        This message provides information about the receipt of Differential
        corrections.  It is expected to be sent with each receipt of a complete
        corrections packet.
    fields:
        - flags:
            type: u8
            desc: Status flags
            fields:
              - 4-7:
                  desc: Reserved
              - 0-3:
                  desc: Differential type
                  values:
                      - 0: Invalid
                      - 1: Code Difference
                      - 2: RTK
        - latency:
            type: u16
            units: deci-seconds
            desc: Latency of observation receipt
        - num_signals:
            type: u8
            desc: Number of signals from base station
        - source:
            type: string
            encoding: unterminated
            desc: Corrections source string


 - MSG_HEARTBEAT:
    id: 0xFFFF
    short_desc: System heartbeat message
    desc: >
        The heartbeat message is sent periodically to inform the host
        or other attached devices that the system is running. It is
        used to monitor system malfunctions. It also contains status
        flags that indicate to the host the status of the system and
        whether it is operating correctly. Currently, the expected
        heartbeat interval is 1 sec.


        The system error flag is used to indicate that an error has
        occurred in the system. To determine the source of the error,
        the remaining error flags should be inspected.
    fields:
        - flags:
            type: u32
            desc: Status flags
            fields:
              - 31:
                  desc: External antenna present
                  values:
                      - 0: No external antenna detected
                      - 1: External antenna is present
              - 30:
                  desc: External antenna short
                  values:
                      - 0: No short detected
                      - 1: Short detected
              - 24-29:
                  desc: Reserved
              - 16-23:
                  desc: SBP major protocol version number
              - 8-15:
                  desc: SBP minor protocol version number
              - 3-7:
                  desc: Reserved
              - 2:
                  desc: SwiftNAP Error
                  values:
                      - 0: System Healthy
                      - 1: An error has occurred in the SwiftNAP
              - 1:
                  desc: IO Error
                  values:
                      - 0: System Healthy
                      - 1: An IO error has occurred
              - 0:
                  desc: System Error Flag
                  values:
                      - 0: System Healthy
                      - 1: An error has occurred

 - SubSystemReport:
    short_desc: Subsystem Status report
    embedded_type: true
    desc: >
      Report the general and specific state of a subsystem.  If the generic
      state is reported as initializing, the specific state should be ignored.
    fields:
        - component:
            type: u16
            desc: Identity of reporting subsystem
            fields:
              - 0-15:
                  desc: Subsystem
                  values:
                      - 0: Primary GNSS Antenna
                      - 1: Measurement Engine
                      - 2: Corrections Client
                      - 3: Differential GNSS Engine
                      - 4: CAN
                      - 5: Wheel Odometry
                      - 6: Sensor Fusion Engine
        - generic:
            type: u8
            desc: Generic form status report
            fields:
              - 0-7:
                  desc: Generic
                  values:
                      - 0: OK/Nominal
                      - 1: Initializing
                      - 2: Unknown
                      - 3: Degraded
                      - 4: Unusable
        - specific:
            type: u8
            desc: Subsystem specific status code

 - MSG_STATUS_REPORT:
    id: 0xFFFE
    short_desc: Status report message
    desc: >
        The status report is sent periodically to inform the host
        or other attached devices that the system is running. It is
        used to monitor system malfunctions. It contains status
        reports that indicate to the host the status of each subsystem and
        whether it is operating correctly.


        Interpretation of the subsystem specific status code is product
        dependent, but if the generic status code is initializing, it should
        be ignored.  Refer to product documentation for details.
    fields:
        - reporting_system:
            type: u16
            desc: Identity of reporting system
            fields:
              - 0-15:
                 desc: System
                 values:
                     - 0: Starling
                     - 1: Precision GNSS Module (PGM)
        - sbp_version:
            type: u16
            desc: SBP protocol version
            fields:
              - 8-15:
                  desc: SBP major protocol version number
              - 0-7:
                  desc: SBP minor protocol version number
        - sequence:
            type: u32
            desc: Increments on each status report sent
        - uptime:
            type: u32
            desc: Number of seconds since system start-up
        - status:
            type: array
            fill: SubSystemReport
            desc: Reported status of individual subsystems

 - StatusJournalItem:
    short_desc: Subsystem Status report
    embedded_type: true
    desc: >
      Reports the uptime and the state of a subsystem via generic and specific
      status codes.  If the generic state is reported as initializing, the
      specific state should be ignored.
    fields:
        - uptime:
            type: u32
            desc: Milliseconds since system startup
        - report:
            type: SubSystemReport

 - MSG_STATUS_JOURNAL:
    id: 0xFFFD
    short_desc: Status report journal
    desc: >
        The status journal message contains past status reports (see
        MSG_STATUS_REPORT) and functions as a error/event storage for telemetry
        purposes.
    fields:
        - reporting_system:
            type: u16
            desc: Identity of reporting system
            fields:
              - 0-15:
                 desc: System
                 values:
                     - 0: Starling
                     - 1: Precision GNSS Module (PGM)
        - sbp_version:
            type: u16
            desc: SBP protocol version
            fields:
              - 8-15:
                  desc: SBP major protocol version number
              - 0-7:
                  desc: SBP minor protocol version number
        - total_status_reports:
            type: u32
            desc: Total number of status reports sent since system startup
        - sequence_descriptor:
            type: u8
            desc: >
              Index and number of messages in this sequence. First nibble is
              the size of the sequence (n), second nibble is the zero-indexed
              counter (ith packet of n)
        - journal:
            type: array
            fill: StatusJournalItem
            desc: Status journal

 - MSG_INS_STATUS:
    id: 0xFF03
    short_desc: Inertial Navigation System status message
    desc: >
        The INS status message describes the state of the operation
        and initialization of the inertial navigation system.
    fields:
        - flags:
            type: u32
            desc: Status flags
            fields:
              - 29-31:
                  desc: INS Type
                  values:
                      - 0: Smoothpose Loosely Coupled
                      - 1: Starling
              - 14-28:
                  desc: Reserved
              - 11-13:
                  desc: Motion State
                  values:
                      - 0: Unknown or Init
                      - 1: Arbitrary Motion
                      - 2: Straight Motion
                      - 3: Stationary
              - 10:
                  desc: Odometry Synch
                  values:
                      - 0: Odometry timestamp nominal
                      - 1: Odometry timestamp out of bounds
              - 8-9:
                  desc: Odometry status
                  values:
                      - 0: No Odometry
                      - 1: Odometry received within last second
                      - 2: Odometry not received within last second
              - 4-7:
                  desc: INS Error
                  values:
                      - 0: Reserved
                      - 1: IMU Data Error
                      - 2: INS License Error
                      - 3: IMU Calibration Data Error
              - 3:
                  desc: GNSS Fix
                  values:
                      - 0: No GNSS fix available
                      - 1: GNSS fix
              - 0-2:
                  desc: Mode
                  values:
                      - 0: Awaiting initialization
                      - 1: Dynamically aligning
                      - 2: Ready
                      - 3: GNSS Outage exceeds max duration
                      - 4: FastStart seeding
                      - 5: FastStart validating
                      - 6: Validating unsafe fast start seed
 - MSG_CSAC_TELEMETRY:
    id: 0xFF04
    short_desc: Experimental telemetry message
    public: false
    desc: >
        The CSAC telemetry message has an implementation defined telemetry string
        from a device. It is not produced or available on general Swift Products.
        It is intended to be a low rate message for status purposes.
    fields:
        - id:
            type: u8
            desc: Index representing the type of telemetry in use.  It is implementation defined.
        - telemetry:
            type: string
            encoding: unterminated
            desc: Comma separated list of values as defined by the index

 - MSG_CSAC_TELEMETRY_LABELS:
    id: 0xFF05
    short_desc: Experimental telemetry message labels
    public: false
    desc: >
        The CSAC telemetry message provides labels for each member of the string
        produced by MSG_CSAC_TELEMETRY. It should be provided by a device at a lower
        rate than the MSG_CSAC_TELEMETRY.
    fields:
        - id:
            type: u8
            desc: Index representing the type of telemetry in use.  It is implementation defined.
        - telemetry_labels:
            type: string
            encoding: unterminated
            desc: Comma separated list of telemetry field values

 - MSG_INS_UPDATES:
    id: 0xFF06
    short_desc: Inertial Navigation System update status message
    desc: >
        The INS update status message contains information about executed and rejected INS updates.
        This message is expected to be extended in the future as new types of measurements are being added.
    fields:
        - tow:
            type: u32
            units: ms
            desc: GPS Time of Week
        - gnsspos:
            type: u8
            desc: GNSS position update status flags
            fields:
              - 4-7:
                  desc: Number of attempted GNSS position updates since last message.
              - 0-3:
                  desc: Number of rejected GNSS position updates since last message.
        - gnssvel:
            type: u8
            desc: GNSS velocity update status flags
            fields:
              - 4-7:
                  desc: Number of attempted GNSS velocity updates since last message.
              - 0-3:
                  desc: Number of rejected GNSS velocity updates since last message.
        - wheelticks:
            type: u8
            desc: Wheelticks update status flags
            fields:
              - 4-7:
                  desc: Number of attempted wheeltick updates since last message.
              - 0-3:
                  desc: Number of rejected wheeltick updates since last message.
        - speed:
            type: u8
            desc: Wheelticks update status flags
            fields:
              - 4-7:
                  desc: Number of attempted speed updates since last message.
              - 0-3:
                  desc: Number of rejected speed updates since last message.
        - nhc:
            type: u8
            desc: NHC update status flags
            fields:
              - 4-7:
                  desc: Number of attempted NHC updates since last message.
              - 0-3:
                  desc: Number of rejected NHC updates since last message.
        - zerovel:
            type: u8
            desc: Zero velocity update status flags
            fields:
              - 4-7:
                  desc: Number of attempted zero velocity updates since last message.
              - 0-3:
                  desc: Number of rejected zero velocity updates since last message.

 - MSG_GNSS_TIME_OFFSET:
    id: 0xFF07
    short_desc: Offset of the local time with respect to GNSS time
    desc: >
        The GNSS time offset message contains the information that is needed to translate messages
        tagged with a local timestamp (e.g. IMU or wheeltick messages) to GNSS time for the sender
        producing this message.
    fields:
        - weeks:
            type: s16
            units: weeks
            desc: Weeks portion of the time offset
        - milliseconds:
            type: s32
            units: ms
            desc: Milliseconds portion of the time offset
        - microseconds:
            type: s16
            units: microseconds
            desc: Microseconds portion of the time offset
        - flags:
            type: u8
            desc: Status flags
            fields:
              - 1-7:
                  desc: Reserved, set to zero
              - 0:
                  desc: Weeks behavior
                  values:
                    - 0: Not affected on local timestamp rollover
                    - 1: Incremented on local timestamp rollover

 - MSG_PPS_TIME:
    id: 0xFF08
    short_desc: Local time at detection of PPS pulse
    desc: >
      The PPS time message contains the value of the sender's local time in
      microseconds at the moment a pulse is detected on the PPS input. This
      is to be used for synchronisation of sensor data sampled with a local
      timestamp (e.g. IMU or wheeltick messages) where GNSS time is unknown
      to the sender.


      The local time used to timestamp the PPS pulse must be generated by the
      same clock which is used to timestamp the IMU/wheel sensor data and
      should follow the same roll-over rules (i.e. it should roll over to zero
      after 604800 seconds). A separate MSG_PPS_TIME message should be sent
      for each source of sensor data which uses local timestamping.  The sender
      ID for each of these MSG_PPS_TIME messages should match the sender ID of
      the respective sensor data.
    fields:
        - time:
            type: u64
            units: microseconds
            desc: Local time in microseconds
        - flags:
            type: u8
            desc: Status flags
            fields:
              - 2-7:
                    desc: Reserved, set to zero
              - 0-1:
                  desc: Time uncertainty
                  values:
                    - 0: Unknown
                    - 1: +/- 10 milliseconds
                    - 2: +/- 10 microseconds
                    - 3: < 1 microseconds

 - MSG_SENSOR_AID_EVENT:
    id: 0xFF09 # 65289
    short_desc: Sensor state and update status data
    desc: >
      This diagnostic message contains state and update status information for
      all sensors that are being used by the fusion engine. This message will
      be generated asynchronously to the solution messages and will be emitted
      anytime a sensor update is being processed.
    fields:
        - time:
            type: u32
            units: milliseconds
            desc: Update timestamp in milliseconds.
        - sensor_type:
            type: u8
            desc: Sensor type
            fields:
                - 0-7:
                    desc: Type identifier
                    values:
                        - 0: GNSS position
                        - 1: GNSS average velocity
                        - 2: GNSS instantaneous velocity
                        - 3: Wheel ticks
                        - 4: Wheel speed
                        - 5: IMU
                        - 6: Time differences of carrier phase
        - sensor_id:
            type: u16
            desc: Sensor identifier
        - sensor_state:
            type: u8
            desc: Reserved for future use
        - n_available_meas:
            type: u8
            desc: Number of available measurements in this epoch
        - n_attempted_meas:
            type: u8
            desc: Number of attempted measurements in this epoch
        - n_accepted_meas:
            type: u8
            desc: Number of accepted measurements in this epoch
        - flags:
            type: u32
            desc: Reserved for future use

 - MSG_GROUP_META:
     id: 0xFF0A  # 65290
     short_desc: Solution Group Metadata
     public: true
     desc: >
       This leading message lists the time metadata of the Solution Group.
       It also lists the atomic contents (i.e. types of messages included) of the Solution Group.
     fields:
       - group_id:
           type: u8
           desc: Id of the Msgs Group, 0 is Unknown, 1 is Bestpos, 2 is Gnss
       - flags:
           type: u8
           desc: Status flags (reserved)
           fields:
             - 2-7:
                 desc: Reserved
             - 0-1:
                 desc: Solution Group type
                 values:
                   - 0: None (invalid)
                   - 1: GNSS only
                   - 2: GNSS+INS (Fuzed)
                   - 3: Reserved
       - n_group_msgs:
           type: u8
           desc: Size of list group_msgs
       - group_msgs:
           type: array
           fill: u16
           size_fn: n_group_msgs
           desc: >
             An in-order list of message types included in the Solution Group,
             including GROUP_META itself