gnss/1.0/IGnssNavigationMessageCallback.hal

/*
 * Copyright (C) 2016 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.hardware.gnss@1.0;

/** Represents a GNSS navigation message (or a fragment of it). */
interface IGnssNavigationMessageCallback {
    /*
     * Enumeration of available values to indicate the GNSS Navigation message
     * types.
     *
     * For convenience, first byte is the GnssConstellationType on which that signal
     * is typically transmitted.
     */
    enum GnssNavigationMessageType : int16_t {
        UNKNOWN    = 0,
        /** GNSS L1 C/A message contained in the structure.  */
        GNSS_L1CA       = 0x0101,
        /** GNSS L2-CNAV message contained in the structure. */
        GNSS_L2CNAV     = 0x0102,
        /** GNSS L5-CNAV message contained in the structure. */
        GNSS_L5CNAV     = 0x0103,
        /** GNSS CNAV-2 message contained in the structure. */
        GNSS_CNAV2      = 0x0104,
        /** Glonass L1 CA message contained in the structure. */
        GLO_L1CA        = 0x0301,
        /** Beidou D1 message contained in the structure. */
        BDS_D1          = 0x0501,
        /** Beidou D2 message contained in the structure. */
        BDS_D2          = 0x0502,
        /** Galileo I/NAV message contained in the structure. */
        GAL_I           = 0x0601,
        /** Galileo F/NAV message contained in the structure. */
        GAL_F           = 0x0602
    };

    /*
     * Status of Navigation Message
     * When a message is received properly without any parity error in its
     * navigation words, the status must be set to PARITY_PASSED. But if a message is
     * received with words that failed parity check, but GNSS is able to correct
     * those words, the status must be set to PARITY_REBUILT.
     * No need to send any navigation message that contains words with parity error
     * and cannot be corrected.
     */
    enum NavigationMessageStatus : uint16_t {
        PARITY_PASSED  = (1 << 0),
        PARITY_REBUILT = (1 << 1),
        UNKNOWN  = 0
    };

    struct GnssNavigationMessage {
        /*
         * Satellite vehicle ID number, as defined in GnssSvInfo::svid
         * This is a mandatory value.
         */
        int16_t svid;

        /*
         * The type of message contained in the structure.
         * This is a mandatory value.
         */
        GnssNavigationMessageType type;

        /*
         * The status of the received navigation message.
         * No need to send any navigation message that contains words with parity
         * error and cannot be corrected.
         */
        bitfield<NavigationMessageStatus> status;

        /*
         * Message identifier. It provides an index so the complete Navigation
         * Message can be assembled.
         *
         * - For GNSS L1 C/A subframe 4 and 5, this value corresponds to the 'frame
         *   id' of the navigation message, in the range of 1-25 (Subframe 1, 2, 3
         *   does not contain a 'frame id' and this value can be set to -1.)
         *
         * - For Glonass L1 C/A, this refers to the frame ID, in the range of 1-5.
         *
         * - For BeiDou D1, this refers to the frame number in the range of 1-24
         *
         * - For Beidou D2, this refers to the frame number, in the range of 1-120
         *
         * - For Galileo F/NAV nominal frame structure, this refers to the subframe
         *   number, in the range of 1-12
         *
         * - For Galileo I/NAV nominal frame structure, this refers to the subframe
         *   number in the range of 1-24
         */
        int16_t messageId;

        /*
         * Sub-message identifier. If required by the message 'type', this value
         * contains a sub-index within the current message (or frame) that is being
         * transmitted.
         *
         * - For GNSS L1 C/A, BeiDou D1 & BeiDou D2, the submessage id corresponds to
         *   the subframe number of the navigation message, in the range of 1-5.
         *
         * - For Glonass L1 C/A, this refers to the String number, in the range from
         *   1-15
         *
         * - For Galileo F/NAV, this refers to the page type in the range 1-6
         *
         * - For Galileo I/NAV, this refers to the word type in the range 1-10+
         */
        int16_t submessageId;

        /*
         * The data of the reported GNSS message. The bytes (or words) are specified
         * using big endian format (MSB first). The data is stored and decoded
         * in a server for research purposes.
         *
         * - For GNSS L1 C/A, Beidou D1 & Beidou D2, each subframe contains 10 30-bit
         *   words. Each word (30 bits) must fit into the last 30 bits in a
         *   4-byte word (skip B31 and B32), with MSB first, for a total of 40
         *   bytes, covering a time period of 6, 6, and 0.6 seconds, respectively.
         *   The standard followed is 1995 SPS Signal specification.
         *
         * - For Glonass L1 C/A, each string contains 85 data bits, including the
         *   checksum.  These bits must fit into 11 bytes, with MSB first (skip
         *   B86-B88), covering a time period of 2 seconds.
         *   The standard followed is Glonass Interface Control Document Edition 5.1.
         *
         * - For Galileo F/NAV, each word consists of 238-bit (sync & tail symbols
         *   excluded). Each word must fit into 30-bytes, with MSB first (skip
         *   B239, B240), covering a time period of 10 seconds. The standard
         *   followed is European GNSS(Galileo) Signal in Space Interface
         *   Control Document Issue 1.2.
         *
         * - For Galileo I/NAV, each page contains 2 page parts, even and odd, with
         *   a total of 2x114 = 228 bits, (sync & tail excluded) that must fit
         *   into 29 bytes, with MSB first (skip B229-B232). The standard followed
         *   is same as above.
         *
         * TODO(b/32022567): Describe this relationship with data to the VTS
         * via custom annotations and plug in a VTS test to verify that the data
         * correctly follows the standard.
         *
         */
        vec<uint8_t> data;
    };

    /*
     * The callback to report an available fragment of a GNSS navigation messages
     * from the HAL.
     *
     * @param message - The GNSS navigation submessage/subframe representation.
     */
     gnssNavigationMessageCb(GnssNavigationMessage message);
};