1/*
2 * Copyright (C) 2016 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.hardware.gnss@1.0;
18
19/** Represents a GNSS navigation message (or a fragment of it). */
20interface IGnssNavigationMessageCallback {
21    /**
22     * Enumeration of available values to indicate the GNSS Navigation message
23     * types.
24     *
25     * For convenience, first byte is the GnssConstellationType on which that signal
26     * is typically transmitted.
27     */
28    @export(name="", value_prefix="GNSS_NAVIGATION_MESSAGE_TYPE_")
29    enum GnssNavigationMessageType : int16_t {
30        UNKNOWN    = 0,
31        /** GPS L1 C/A message contained in the structure.  */
32        GPS_L1CA       = 0x0101,
33        /** GPS L2-CNAV message contained in the structure. */
34        GPS_L2CNAV     = 0x0102,
35        /** GPS L5-CNAV message contained in the structure. */
36        GPS_L5CNAV     = 0x0103,
37        /** GPS CNAV-2 message contained in the structure. */
38        GPS_CNAV2      = 0x0104,
39        /** Glonass L1 CA message contained in the structure. */
40        GLO_L1CA        = 0x0301,
41        /** Beidou D1 message contained in the structure. */
42        BDS_D1          = 0x0501,
43        /** Beidou D2 message contained in the structure. */
44        BDS_D2          = 0x0502,
45        /** Galileo I/NAV message contained in the structure. */
46        GAL_I           = 0x0601,
47        /** Galileo F/NAV message contained in the structure. */
48        GAL_F           = 0x0602
49    };
50
51    /**
52     * Status of Navigation Message
53     * When a message is received properly without any parity error in its
54     * navigation words, the status must be set to PARITY_PASSED.
55     * If a message is received with words that failed a parity check, but the GNSS
56     * receiver has corrected those words, the status must be set to PARITY_REBUILT.
57     * Do not send any navigation message that contains words with parity errors
58     * that cannot be corrected.
59     */
60    @export(name="navigation_message_status", value_prefix="NAV_MESSAGE_STATUS_")
61    enum NavigationMessageStatus : uint16_t {
62        PARITY_PASSED  = (1 << 0),
63        PARITY_REBUILT = (1 << 1),
64        UNKNOWN  = 0
65    };
66
67    struct GnssNavigationMessage {
68        /**
69         * Satellite vehicle ID number, as defined in GnssSvInfo::svid
70         * This is a mandatory value.
71         */
72        int16_t svid;
73
74        /**
75         * The type of message contained in the structure.
76         * This is a mandatory value.
77         */
78        GnssNavigationMessageType type;
79
80        /**
81         * The status of the received navigation message.
82         * No need to send any navigation message that contains words with parity
83         * errors that cannot be corrected.
84         */
85        bitfield<NavigationMessageStatus> status;
86
87        /**
88         * Message identifier. It provides an index so the complete Navigation
89         * Message can be assembled.
90         *
91         * - For GNSS L1 C/A subframe 4 and 5, this value corresponds to the 'frame
92         *   id' of the navigation message, in the range of 1-25 (Subframe 1, 2, 3
93         *   does not contain a 'frame id' and this value can be set to -1.)
94         *
95         * - For Glonass L1 C/A, this refers to the frame ID, in the range of 1-5.
96         *
97         * - For BeiDou D1, this refers to the frame number in the range of 1-24
98         *
99         * - For Beidou D2, this refers to the frame number, in the range of 1-120
100         *
101         * - For Galileo F/NAV nominal frame structure, this refers to the subframe
102         *   number, in the range of 1-12
103         *
104         * - For Galileo I/NAV nominal frame structure, this refers to the subframe
105         *   number in the range of 1-24
106         */
107        int16_t messageId;
108
109        /**
110         * Sub-message identifier. If required by the message 'type', this value
111         * contains a sub-index within the current message (or frame) that is being
112         * transmitted.
113         *
114         * - For GNSS L1 C/A, BeiDou D1 & BeiDou D2, the submessage id corresponds to
115         *   the subframe number of the navigation message, in the range of 1-5.
116         *
117         * - For Glonass L1 C/A, this refers to the String number, in the range from
118         *   1-15
119         *
120         * - For Galileo F/NAV, this refers to the page type in the range 1-6
121         *
122         * - For Galileo I/NAV, this refers to the word type in the range 1-10+
123         */
124        int16_t submessageId;
125
126        /**
127         * The data of the reported GNSS message. The bytes (or words) are specified
128         * using big endian format (MSB first).
129         *
130         * - For GNSS L1 C/A, Beidou D1 & Beidou D2, each subframe contains 10 30-bit
131         *   words. Each word (30 bits) must fit into the last 30 bits in a
132         *   4-byte word (skip B31 and B32), with MSB first, for a total of 40
133         *   bytes, covering a time period of 6, 6, and 0.6 seconds, respectively.
134         *   The standard followed is 1995 SPS Signal specification.
135         *
136         * - For Glonass L1 C/A, each string contains 85 data bits, including the
137         *   checksum.  These bits must fit into 11 bytes, with MSB first (skip
138         *   B86-B88), covering a time period of 2 seconds.
139         *   The standard followed is Glonass Interface Control Document Edition 5.1.
140         *
141         * - For Galileo F/NAV, each word consists of 238-bit (sync & tail symbols
142         *   excluded). Each word must fit into 30-bytes, with MSB first (skip
143         *   B239, B240), covering a time period of 10 seconds. The standard
144         *   followed is European GNSS(Galileo) Signal in Space Interface
145         *   Control Document Issue 1.2.
146         *
147         * - For Galileo I/NAV, each page contains 2 page parts, even and odd, with
148         *   a total of 2x114 = 228 bits, (sync & tail excluded) that must fit
149         *   into 29 bytes, with MSB first (skip B229-B232). The standard followed
150         *   is same as above.
151         *
152         * The data reported here must be the raw data as demodulated by the GNSS
153         * receiver, not data received from an external source (i.e. not from a server
154         * download.)
155         */
156        vec<uint8_t> data;
157    };
158
159    /**
160     * The callback to report an available fragment of a GNSS navigation messages
161     * from the HAL.
162     *
163     * @param message - The GNSS navigation submessage/subframe representation.
164     */
165     gnssNavigationMessageCb(GnssNavigationMessage message);
166};
167