/* * 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; /** * The interface is required for the HAL to communicate certain information * like status and location info back to the platform, the platform implements * the interfaces and passes a handle to the HAL. */ interface IGnssCallback { /** Flags for the gnssSetCapabilities callback. */ @export(name="", value_prefix="GPS_CAPABILITY_") enum Capabilities : uint32_t { /** * GNSS HAL schedules fixes for RECURRENCE_PERIODIC mode. * If this is not set, then the framework will use 1000ms for * minInterval and will call start() and stop() to schedule the GNSS. */ SCHEDULING = 1 << 0, /** GNSS supports MS-Based AGNSS mode */ MSB = 1 << 1, /** GNSS supports MS-Assisted AGNSS mode */ MSA = 1 << 2, /** GNSS supports single-shot fixes */ SINGLE_SHOT = 1 << 3, /** GNSS supports on demand time injection */ ON_DEMAND_TIME = 1 << 4, /** GNSS supports Geofencing */ GEOFENCING = 1 << 5, /** GNSS supports Measurements for at least GPS. */ MEASUREMENTS = 1 << 6, /** GNSS supports Navigation Messages */ NAV_MESSAGES = 1 << 7 }; /** GNSS status event values. */ @export(name="", value_prefix="GPS_STATUS_") enum GnssStatusValue : uint8_t { /** GNSS status unknown. */ NONE = 0, /** GNSS has begun navigating. */ SESSION_BEGIN = 1, /** GNSS has stopped navigating. */ SESSION_END = 2, /** GNSS has powered on but is not navigating. */ ENGINE_ON = 3, /** GNSS is powered off. */ ENGINE_OFF = 4 }; /** * Flags that indicate information about the satellite */ @export(name="", value_prefix="GNSS_SV_FLAGS_") enum GnssSvFlags : uint8_t { NONE = 0, HAS_EPHEMERIS_DATA = 1 << 0, HAS_ALMANAC_DATA = 1 << 1, USED_IN_FIX = 1 << 2, HAS_CARRIER_FREQUENCY = 1 << 3 }; struct GnssSvInfo { /** * Pseudo-random or satellite ID number for the satellite, a.k.a. Space Vehicle (SV), or * FCN/OSN number for Glonass. The distinction is made by looking at constellation field. * Values must be in the range of: * * - GNSS: 1-32 * - SBAS: 120-151, 183-192 * - GLONASS: 1-24, the orbital slot number (OSN), if known. Or, if not: * 93-106, the frequency channel number (FCN) (-7 to +6) offset by * + 100 * i.e. report an FCN of -7 as 93, FCN of 0 as 100, and FCN of +6 * as 106. * - QZSS: 193-200 * - Galileo: 1-36 * - Beidou: 1-37 */ int16_t svid; /** * Defines the constellation of the given SV. */ GnssConstellationType constellation; /** * Carrier-to-noise density in dB-Hz, typically in the range [0, 63]. * It contains the measured C/N0 value for the signal at the antenna port. * * This is a mandatory value. */ float cN0Dbhz; /** Elevation of SV in degrees. */ float elevationDegrees; /** Azimuth of SV in degrees. */ float azimuthDegrees; /** * Carrier frequency of the signal tracked, for example it can be the * GPS central frequency for L1 = 1575.45 MHz, or L2 = 1227.60 MHz, L5 = * 1176.45 MHz, varying GLO channels, etc. If the field is zero, it is * the primary common use central frequency, e.g. L1 = 1575.45 MHz for * GPS. * * For an L1, L5 receiver tracking a satellite on L1 and L5 at the same * time, two GnssSvInfo structs must be reported for this same * satellite, in one of the structs, all the values related * to L1 must be filled, and in the other all of the values related to * L5 must be filled. * * If the data is available, svFlag must contain HAS_CARRIER_FREQUENCY. */ float carrierFrequencyHz; /** * Contains additional data about the given SV. */ bitfield<GnssSvFlags> svFlag; }; /** * Represents SV status. */ struct GnssSvStatus { /** * Number of GNSS SVs currently visible, refers to the SVs stored in sv_list */ uint32_t numSvs; /** * Pointer to an array of SVs information for all GNSS constellations, * except GNSS, which is reported using svList */ GnssSvInfo[GnssMax:SVS_COUNT] gnssSvList; }; /** * Called when a GNSS location is available. * * @param location Location information from HAL. */ gnssLocationCb(GnssLocation location); /** * Called to communicate the status of the GNSS engine. * * @param status Status information from HAL. */ gnssStatusCb(GnssStatusValue status); /** * @param svInfo SV status information from HAL. */ gnssSvStatusCb(GnssSvStatus svInfo); /** * Called when NMEA data is available. * Callback for reporting NMEA sentences. * * @param timestamp Marks the instance of reporting. * @param nmea Follows standard NMEA 0183. Each sentence begins with a '$' * and ends with a carriage return/line feed sequence and can be no longer * than 80 characters of visible text (plus the line terminators). The data * is contained within this single line with data items separated by commas. * The data itself is just ascii text and may extend over multiple sentences * in certain specialized instances but is normally fully contained in one * variable length sentence. The data may vary in the amount of precision * contained in the message. For example time might be indicated to decimal * parts of a second or location may be shown with 3 or even 4 digits after * the decimal point. Programs that read the data must only use the commas * to determine the field boundaries and not depend on column positions. * There is a provision for a checksum at the end of each sentence which may * or may not be checked by the unit that reads the data. The checksum field * consists of a '*' and two hex digits representing an 8 bit exclusive OR * of all characters between, but not including, the '$' and '*'. */ gnssNmeaCb(GnssUtcTime timestamp, string nmea); /** * Callback to inform framework of the GNSS engine's capabilities. * * @param capabilities Capability parameter is a bit field of * the Capabilities enum. */ gnssSetCapabilitesCb(bitfield<Capabilities> capabilities); /** * Callback utility for acquiring the GNSS wakelock. This can be used to prevent * the CPU from suspending while handling GNSS events. */ gnssAcquireWakelockCb(); /** Callback utility for releasing the GNSS wakelock. */ gnssReleaseWakelockCb(); /** Callback for requesting NTP time */ gnssRequestTimeCb(); /** * Provides information about how new the underlying GPS/GNSS hardware and * software is. * * This information will be available for Android Test Applications. If a GNSS * HAL does not provide this information, it will be considered "2015 or * earlier". * * If a GNSS HAL does provide this information, then newer years will need to * meet newer CTS standards. E.g. if the date are 2016 or above, then N+ level * GnssMeasurement support will be verified. */ struct GnssSystemInfo{ /** * year in which the last update was made to the underlying hardware/firmware * used to capture GNSS signals, e.g. 2016 */ uint16_t yearOfHw; }; /** * Callback to inform framework of the engine's hardware version information. * * @param info GnssSystemInfo about the GPS/GNSS hardware. */ gnssSetSystemInfoCb(GnssSystemInfo info); };