ST / GPS_Provider

An extension of original API for working with GPS devices.

Dependents:   A_TeseoLocationNEW A_TeseoLocation TeseoLocation

GPS_Provider Library

A controller-neutral API for working with GPS devices.

Overview

This library is an extension of the original API published on os.mbed.com

Besides the basic geo-location functionality, this extended API includes the following features:

  • Geofencing
  • Odometer
  • Datalogging

Getting started

This GPS API is meant to be used for building projects on os.mbed.com

A good starting point is this page:

TeseoLocation

GPSProvider/GPSProvider.h@0:0a9c622571d7, 2018-11-09 (annotated)

Committer:
apalmieri
Date:
Fri Nov 09 17:09:12 2018 +0000
Revision:
0:0a9c622571d7
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
apalmieri 0:0a9c622571d7 1 /* mbed Microcontroller Library
apalmieri 0:0a9c622571d7 2 * Copyright (c) 2006-2014 ARM Limited
apalmieri 0:0a9c622571d7 3 *
apalmieri 0:0a9c622571d7 4 * Licensed under the Apache License, Version 2.0 (the "License");
apalmieri 0:0a9c622571d7 5 * you may not use this file except in compliance with the License.
apalmieri 0:0a9c622571d7 6 * You may obtain a copy of the License at
apalmieri 0:0a9c622571d7 7 *
apalmieri 0:0a9c622571d7 8 * http://www.apache.org/licenses/LICENSE-2.0
apalmieri 0:0a9c622571d7 9 *
apalmieri 0:0a9c622571d7 10 * Unless required by applicable law or agreed to in writing, software
apalmieri 0:0a9c622571d7 11 * distributed under the License is distributed on an "AS IS" BASIS,
apalmieri 0:0a9c622571d7 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
apalmieri 0:0a9c622571d7 13 * See the License for the specific language governing permissions and
apalmieri 0:0a9c622571d7 14 * limitations under the License.
apalmieri 0:0a9c622571d7 15 */
apalmieri 0:0a9c622571d7 16
apalmieri 0:0a9c622571d7 17 #ifndef __GPS_PROVIDER_H__
apalmieri 0:0a9c622571d7 18 #define __GPS_PROVIDER_H__
apalmieri 0:0a9c622571d7 19
apalmieri 0:0a9c622571d7 20 // [ST-GNSS] - Geofencing API
apalmieri 0:0a9c622571d7 21 class GPSGeofence; /* forward declaration */
apalmieri 0:0a9c622571d7 22 // [ST-GNSS] - Datalogging API
apalmieri 0:0a9c622571d7 23 class GPSDatalog; /* forward declaration */
apalmieri 0:0a9c622571d7 24
apalmieri 0:0a9c622571d7 25 class GPSProviderImplBase; /* forward declaration */
apalmieri 0:0a9c622571d7 26 extern GPSProviderImplBase *createGPSProviderInstance(void);
apalmieri 0:0a9c622571d7 27
apalmieri 0:0a9c622571d7 28
apalmieri 0:0a9c622571d7 29 //
apalmieri 0:0a9c622571d7 30 // Here's a snippet showing how this API can be used. The handler gets invoked
apalmieri 0:0a9c622571d7 31 // from thread context--i.e. from the main application.
apalmieri 0:0a9c622571d7 32 //
apalmieri 0:0a9c622571d7 33 // void handleGPSData(const LocationUpdateParams_t *newLocation) {
apalmieri 0:0a9c622571d7 34 // ...
apalmieri 0:0a9c622571d7 35 // }
apalmieri 0:0a9c622571d7 36 //
apalmieri 0:0a9c622571d7 37 // GPSProvider gps;
apalmieri 0:0a9c622571d7 38 //
apalmieri 0:0a9c622571d7 39 // gps.setPowerMode(LOW_POWER);
apalmieri 0:0a9c622571d7 40 // gps.onLocationUpdate(handleGPSData);
apalmieri 0:0a9c622571d7 41 //
apalmieri 0:0a9c622571d7 42 // gps.reset();
apalmieri 0:0a9c622571d7 43 // gps.start();
apalmieri 0:0a9c622571d7 44 //
apalmieri 0:0a9c622571d7 45 // while (true) {
apalmieri 0:0a9c622571d7 46 // /* purely optional */
apalmieri 0:0a9c622571d7 47 // static bool printedDeviceInfo = false;
apalmieri 0:0a9c622571d7 48 // if (!printedDeviceInfo && gps.haveDeviceInfo()) {
apalmieri 0:0a9c622571d7 49 // printf("%s", gps.getDeviceInfo());
apalmieri 0:0a9c622571d7 50 // printedDeviceInfo = true;
apalmieri 0:0a9c622571d7 51 // }
apalmieri 0:0a9c622571d7 52 //
apalmieri 0:0a9c622571d7 53 // /* Main message processing activity; location callbacks are called
apalmieri 0:0a9c622571d7 54 // * as a result of message processing. */
apalmieri 0:0a9c622571d7 55 // gps.process();
apalmieri 0:0a9c622571d7 56 // /* sleep(); */
apalmieri 0:0a9c622571d7 57 //
apalmieri 0:0a9c622571d7 58 // if (/* at some point in the future */) {
apalmieri 0:0a9c622571d7 59 // break;
apalmieri 0:0a9c622571d7 60 // }
apalmieri 0:0a9c622571d7 61 // }
apalmieri 0:0a9c622571d7 62 // gps.stop();
apalmieri 0:0a9c622571d7 63 //
apalmieri 0:0a9c622571d7 64
apalmieri 0:0a9c622571d7 65 class GPSProvider {
apalmieri 0:0a9c622571d7 66
apalmieri 0:0a9c622571d7 67 public:
apalmieri 0:0a9c622571d7 68 /** Power mode selection */
apalmieri 0:0a9c622571d7 69 enum PowerMode_t {
apalmieri 0:0a9c622571d7 70 POWER_FULL, /**< full-power mode typically results in high-accuracy location data updated at 1Hz. */
apalmieri 0:0a9c622571d7 71 POWER_LOW, /**< low-power mode involves longer periods of hibernation in between location updates. */
apalmieri 0:0a9c622571d7 72 };
apalmieri 0:0a9c622571d7 73
apalmieri 0:0a9c622571d7 74 /**
apalmieri 0:0a9c622571d7 75 * GPS time starts from UTC 01/06/1980(MM/DD/YYYY) and includes 2 fields:
apalmieri 0:0a9c622571d7 76 * week and tow. For a given GPS time, week is the passed week number since
apalmieri 0:0a9c622571d7 77 * the GPS start time, and tow(time of week) is the passed seconds since the
apalmieri 0:0a9c622571d7 78 * last Sunday. For example, a given UTC time [10/30/3014
apalmieri 0:0a9c622571d7 79 * 01:10:00](MM/DD/YYYY HH:MM:SS) can be converted into GPS time [1816,
apalmieri 0:0a9c622571d7 80 * 4200](week, seconds).
apalmieri 0:0a9c622571d7 81 *
apalmieri 0:0a9c622571d7 82 * GPS time can be used as a quite accurate time once position is fixed.
apalmieri 0:0a9c622571d7 83 */
apalmieri 0:0a9c622571d7 84 struct GPSTime_t {
apalmieri 0:0a9c622571d7 85 uint16_t gps_week;
apalmieri 0:0a9c622571d7 86 uint32_t tow; /* time of week (in millisecond) */
apalmieri 0:0a9c622571d7 87 };
apalmieri 0:0a9c622571d7 88
apalmieri 0:0a9c622571d7 89 typedef double LocationType_t;
apalmieri 0:0a9c622571d7 90 typedef float Altitude_t;
apalmieri 0:0a9c622571d7 91 struct LocationUpdateParams_t {
apalmieri 0:0a9c622571d7 92 uint32_t version; /* Layout-version for the following structure;
apalmieri 0:0a9c622571d7 93 * this is to accommodate changes over time. */
apalmieri 0:0a9c622571d7 94 bool valid; /* Does this update contain a valid location. */
apalmieri 0:0a9c622571d7 95 LocationType_t lat;
apalmieri 0:0a9c622571d7 96 LocationType_t lon;
apalmieri 0:0a9c622571d7 97 Altitude_t altitude;
apalmieri 0:0a9c622571d7 98
apalmieri 0:0a9c622571d7 99 unsigned numGPSSVs; /* num GPS Satellites */
apalmieri 0:0a9c622571d7 100 unsigned numGLOSVs; /* num GLONASS Satellites */
apalmieri 0:0a9c622571d7 101
apalmieri 0:0a9c622571d7 102 GPSTime_t gpsTime; /* gps time */
apalmieri 0:0a9c622571d7 103 uint64_t utcTime; /* UTC time in millisecond */
apalmieri 0:0a9c622571d7 104 };
apalmieri 0:0a9c622571d7 105
apalmieri 0:0a9c622571d7 106 /** [ST-GNSS] - Geofencing API */
apalmieri 0:0a9c622571d7 107 struct Timestamp_t {
apalmieri 0:0a9c622571d7 108 int hh; /**< Hours */
apalmieri 0:0a9c622571d7 109 int mm; /**< Minutes */
apalmieri 0:0a9c622571d7 110 int ss; /**< Seconds */
apalmieri 0:0a9c622571d7 111 int year; /**< Year */
apalmieri 0:0a9c622571d7 112 int month; /**< Month */
apalmieri 0:0a9c622571d7 113 int day; /**< Day */
apalmieri 0:0a9c622571d7 114 };
apalmieri 0:0a9c622571d7 115
apalmieri 0:0a9c622571d7 116 struct GeofenceStatusParams_t {
apalmieri 0:0a9c622571d7 117 Timestamp_t timestamp;
apalmieri 0:0a9c622571d7 118 int *currentStatus;
apalmieri 0:0a9c622571d7 119 int numGeofences;
apalmieri 0:0a9c622571d7 120 int idAlarm;
apalmieri 0:0a9c622571d7 121 };
apalmieri 0:0a9c622571d7 122
apalmieri 0:0a9c622571d7 123 /** [ST-GNSS] - Datalogging API */
apalmieri 0:0a9c622571d7 124 struct LogStatusParams_t {
apalmieri 0:0a9c622571d7 125 Timestamp_t firstEntryTimestamp;
apalmieri 0:0a9c622571d7 126 Timestamp_t lastEntryTimestamp;
apalmieri 0:0a9c622571d7 127 unsigned usedEntries;
apalmieri 0:0a9c622571d7 128 uint8_t bufferStatus;
apalmieri 0:0a9c622571d7 129 unsigned remainingFreeEntries;
apalmieri 0:0a9c622571d7 130 };
apalmieri 0:0a9c622571d7 131
apalmieri 0:0a9c622571d7 132 /** [ST-GNSS] - Datalogging API */
apalmieri 0:0a9c622571d7 133 struct LogQueryParams_t {
apalmieri 0:0a9c622571d7 134 Timestamp_t startTimestamp;
apalmieri 0:0a9c622571d7 135 unsigned entries;
apalmieri 0:0a9c622571d7 136 };
apalmieri 0:0a9c622571d7 137
apalmieri 0:0a9c622571d7 138 /** [ST-GNSS] - Datalogging API */
apalmieri 0:0a9c622571d7 139 struct LogQueryRespParams_t {
apalmieri 0:0a9c622571d7 140 uint8_t statusBitmap;
apalmieri 0:0a9c622571d7 141 uint8_t logMask;
apalmieri 0:0a9c622571d7 142 Timestamp_t timestamp;
apalmieri 0:0a9c622571d7 143 uint8_t fix;
apalmieri 0:0a9c622571d7 144 unsigned quality;
apalmieri 0:0a9c622571d7 145 uint8_t geo;
apalmieri 0:0a9c622571d7 146 LocationType_t lat;
apalmieri 0:0a9c622571d7 147 LocationType_t lon;
apalmieri 0:0a9c622571d7 148 Altitude_t altitude;
apalmieri 0:0a9c622571d7 149 double speed;
apalmieri 0:0a9c622571d7 150 double odo;
apalmieri 0:0a9c622571d7 151 };
apalmieri 0:0a9c622571d7 152
apalmieri 0:0a9c622571d7 153 // [ST-GNSS] - Odometer API
apalmieri 0:0a9c622571d7 154 struct OdoParams_t {
apalmieri 0:0a9c622571d7 155 Timestamp_t timestamp;
apalmieri 0:0a9c622571d7 156 unsigned odoA;
apalmieri 0:0a9c622571d7 157 unsigned odoB;
apalmieri 0:0a9c622571d7 158 unsigned odoPon;
apalmieri 0:0a9c622571d7 159 };
apalmieri 0:0a9c622571d7 160
apalmieri 0:0a9c622571d7 161 public:
apalmieri 0:0a9c622571d7 162 /**
apalmieri 0:0a9c622571d7 163 * Set the operating mode for power. Typically this allows the user to
apalmieri 0:0a9c622571d7 164 * choose between various low-power modes. Entering low-power modes often
apalmieri 0:0a9c622571d7 165 * results in a trade-off between accuracy and power consumption.
apalmieri 0:0a9c622571d7 166 *
apalmieri 0:0a9c622571d7 167 * The new mode takes effect upon calling start().
apalmieri 0:0a9c622571d7 168 *
apalmieri 0:0a9c622571d7 169 * @param power The new power mode.
apalmieri 0:0a9c622571d7 170 * @return true if the update was successful.
apalmieri 0:0a9c622571d7 171 */
apalmieri 0:0a9c622571d7 172 bool setPowerMode(PowerMode_t power);
apalmieri 0:0a9c622571d7 173
apalmieri 0:0a9c622571d7 174 /**
apalmieri 0:0a9c622571d7 175 * HW reset to get location chip into hibernation mode, but in readiness for
apalmieri 0:0a9c622571d7 176 * starting operation. The GPS controller emerges from hibernation when
apalmieri 0:0a9c622571d7 177 * start() is called.
apalmieri 0:0a9c622571d7 178 *
apalmieri 0:0a9c622571d7 179 * The typical initialization sequence is:
apalmieri 0:0a9c622571d7 180 * reset();
apalmieri 0:0a9c622571d7 181 * start(); // and thereafter receive location-update callbacks.
apalmieri 0:0a9c622571d7 182 */
apalmieri 0:0a9c622571d7 183 void reset(void);
apalmieri 0:0a9c622571d7 184
apalmieri 0:0a9c622571d7 185 /**
apalmieri 0:0a9c622571d7 186 * Start the GPS operation, taking into account the operation mode set
apalmieri 0:0a9c622571d7 187 * previously. Following this call, the user may expect to receive location
apalmieri 0:0a9c622571d7 188 * notifications in interrupt context if a handler has previously been set.
apalmieri 0:0a9c622571d7 189 *
apalmieri 0:0a9c622571d7 190 * @note: calling start repeatedly doesn't hurt.
apalmieri 0:0a9c622571d7 191 */
apalmieri 0:0a9c622571d7 192 void start(void);
apalmieri 0:0a9c622571d7 193
apalmieri 0:0a9c622571d7 194 /**
apalmieri 0:0a9c622571d7 195 * Stop active operation of the GPS; and put it to hibernation.
apalmieri 0:0a9c622571d7 196 *
apalmieri 0:0a9c622571d7 197 * @note: You don't need to call reset() afterwards to enter hibernation.
apalmieri 0:0a9c622571d7 198 * @note: Calling stop() repeatedly doesn't hurt.
apalmieri 0:0a9c622571d7 199 */
apalmieri 0:0a9c622571d7 200 void stop(void);
apalmieri 0:0a9c622571d7 201
apalmieri 0:0a9c622571d7 202 /**
apalmieri 0:0a9c622571d7 203 * Process location data from chip and update location and satellite
apalmieri 0:0a9c622571d7 204 * information. This API is supposed to be called repeatedly from the
apalmieri 0:0a9c622571d7 205 * application in thread mode to process incoming messages as they are
apalmieri 0:0a9c622571d7 206 * received from the GPS controller. Arriving data is first appended to
apalmieri 0:0a9c622571d7 207 * something like a circular buffer by interrupts, and then parsed as
apalmieri 0:0a9c622571d7 208 * messages in thread mode.
apalmieri 0:0a9c622571d7 209 *
apalmieri 0:0a9c622571d7 210 * The application typically enters a loop calling process() after
apalmieri 0:0a9c622571d7 211 * initializing the GPS controller with start(). process() returns
apalmieri 0:0a9c622571d7 212 * immediately if there is no work to be done, but it must get invoked
apalmieri 0:0a9c622571d7 213 * frequently in order to keep pace with arriving data.
apalmieri 0:0a9c622571d7 214 *
apalmieri 0:0a9c622571d7 215 * Mbed's sleep() may be usefully thrown into the application's process()
apalmieri 0:0a9c622571d7 216 * loop to save power--sleep() has the effect of putting the processor to
apalmieri 0:0a9c622571d7 217 * sleep while waiting for an event (such as an interrupt). As always, some
apalmieri 0:0a9c622571d7 218 * care must be taken in employing sleep(), because there is a small
apalmieri 0:0a9c622571d7 219 * synchronization window where an interrupt may arrive and pend data which
apalmieri 0:0a9c622571d7 220 * doesn't get processed (as illustrated below).
apalmieri 0:0a9c622571d7 221 *
apalmieri 0:0a9c622571d7 222 * while (true) {
apalmieri 0:0a9c622571d7 223 * process();
apalmieri 0:0a9c622571d7 224 * <-- interrupt arrives now and appends new data
apalmieri 0:0a9c622571d7 225 * sleep(); // but then we go to sleep without processing it.
apalmieri 0:0a9c622571d7 226 * }
apalmieri 0:0a9c622571d7 227 *
apalmieri 0:0a9c622571d7 228 * There is a way around it: if sleep() boils down to the use of ARM's WFE
apalmieri 0:0a9c622571d7 229 * instruction (as opposed to WFI), then its safe from the above-mentioned
apalmieri 0:0a9c622571d7 230 * synchronization window.
apalmieri 0:0a9c622571d7 231 */
apalmieri 0:0a9c622571d7 232 void process(void);
apalmieri 0:0a9c622571d7 233
apalmieri 0:0a9c622571d7 234 /**
apalmieri 0:0a9c622571d7 235 * @return true if the initialization process has received enough
apalmieri 0:0a9c622571d7 236 * information to determine the hardware's version/device-info.
apalmieri 0:0a9c622571d7 237 */
apalmieri 0:0a9c622571d7 238 bool haveDeviceInfo(void) const;
apalmieri 0:0a9c622571d7 239
apalmieri 0:0a9c622571d7 240 /**
apalmieri 0:0a9c622571d7 241 * Fetch the device information string. This is expected to contain the
apalmieri 0:0a9c622571d7 242 * version number or any other device identifier.
apalmieri 0:0a9c622571d7 243 */
apalmieri 0:0a9c622571d7 244 const char *getDeviceInfo(void) const;
apalmieri 0:0a9c622571d7 245
apalmieri 0:0a9c622571d7 246 /**
apalmieri 0:0a9c622571d7 247 * This is a wildcard API for sending controller specific commands. Use of
apalmieri 0:0a9c622571d7 248 * this API will make programs non-portable, but then there may arise a
apalmieri 0:0a9c622571d7 249 * genuine need to access special functionality.
apalmieri 0:0a9c622571d7 250 *
apalmieri 0:0a9c622571d7 251 * @param command A controller specific command.
apalmieri 0:0a9c622571d7 252 * @param arg Argument to the command; interpreted according to the command.
apalmieri 0:0a9c622571d7 253 * @return any return from the command.
apalmieri 0:0a9c622571d7 254 */
apalmieri 0:0a9c622571d7 255 uint32_t ioctl(uint32_t command, void *arg);
apalmieri 0:0a9c622571d7 256
apalmieri 0:0a9c622571d7 257 /** [ST-GNSS ] - Enable verbose NMEA stream */
apalmieri 0:0a9c622571d7 258 void setVerboseMode(int level);
apalmieri 0:0a9c622571d7 259
apalmieri 0:0a9c622571d7 260 /**
apalmieri 0:0a9c622571d7 261 * [ST-GNSS] - Odometer API
apalmieri 0:0a9c622571d7 262 * Enable the Geofencing subsystem.
apalmieri 0:0a9c622571d7 263 *
apalmieri 0:0a9c622571d7 264 * The Geofencing subsystem is enabled.
apalmieri 0:0a9c622571d7 265 *
apalmieri 0:0a9c622571d7 266 * @return GPS_ERROR_NONE on success /
apalmieri 0:0a9c622571d7 267 * A callback (if set) will be invoked upon a message is received
apalmieri 0:0a9c622571d7 268 * from the GPS device.
apalmieri 0:0a9c622571d7 269 */
apalmieri 0:0a9c622571d7 270 gps_provider_error_t enableGeofence(void);
apalmieri 0:0a9c622571d7 271
apalmieri 0:0a9c622571d7 272 /**
apalmieri 0:0a9c622571d7 273 * [ST-GNSS] - Geofencing API
apalmieri 0:0a9c622571d7 274 * Configure the Geofence subsystem.
apalmieri 0:0a9c622571d7 275 *
apalmieri 0:0a9c622571d7 276 * @param geofences A pointer to an array of geofences to be included within this provider.
apalmieri 0:0a9c622571d7 277 * @return GPS_ERROR_NONE on success /
apalmieri 0:0a9c622571d7 278 * A callback (if set) will be invoked upon a message is received
apalmieri 0:0a9c622571d7 279 * from the GPS device.
apalmieri 0:0a9c622571d7 280 */
apalmieri 0:0a9c622571d7 281 gps_provider_error_t configGeofences(GPSGeofence *geofences[], unsigned geofenceCount);
apalmieri 0:0a9c622571d7 282
apalmieri 0:0a9c622571d7 283 /**
apalmieri 0:0a9c622571d7 284 * [ST-GNSS] - Geofencing API
apalmieri 0:0a9c622571d7 285 * Request a message to know the internal Geofence subsystem status.
apalmieri 0:0a9c622571d7 286 *
apalmieri 0:0a9c622571d7 287 * @return GPS_ERROR_NONE on success /
apalmieri 0:0a9c622571d7 288 * A callback (if set) will be invoked upon a message is received
apalmieri 0:0a9c622571d7 289 * from the GPS device.
apalmieri 0:0a9c622571d7 290 */
apalmieri 0:0a9c622571d7 291 gps_provider_error_t geofenceReq(void);
apalmieri 0:0a9c622571d7 292
apalmieri 0:0a9c622571d7 293 /**
apalmieri 0:0a9c622571d7 294 * [ST-GNSS] - Datalogging API
apalmieri 0:0a9c622571d7 295 * Enable the Datalogging subsystem.
apalmieri 0:0a9c622571d7 296 *
apalmieri 0:0a9c622571d7 297 * The Datalogging subsystem is enabled.
apalmieri 0:0a9c622571d7 298 *
apalmieri 0:0a9c622571d7 299 * @return GPS_ERROR_NONE on success /
apalmieri 0:0a9c622571d7 300 * A callback (if set) will be invoked upon a message is received
apalmieri 0:0a9c622571d7 301 * from the GPS device.
apalmieri 0:0a9c622571d7 302 */
apalmieri 0:0a9c622571d7 303 gps_provider_error_t enableDatalog(void);
apalmieri 0:0a9c622571d7 304
apalmieri 0:0a9c622571d7 305 /**
apalmieri 0:0a9c622571d7 306 * [ST-GNSS] - Datalogging API
apalmieri 0:0a9c622571d7 307 * Create and enable a new data log.
apalmieri 0:0a9c622571d7 308 *
apalmieri 0:0a9c622571d7 309 * @param datalog A pointer to data log.
apalmieri 0:0a9c622571d7 310 * @return GPS_ERROR_NONE on success /
apalmieri 0:0a9c622571d7 311 * A callback (if set) will be invoked upon a message is received
apalmieri 0:0a9c622571d7 312 * from the GPS device.
apalmieri 0:0a9c622571d7 313 */
apalmieri 0:0a9c622571d7 314 gps_provider_error_t configDatalog(GPSDatalog *datalog);
apalmieri 0:0a9c622571d7 315
apalmieri 0:0a9c622571d7 316 /**
apalmieri 0:0a9c622571d7 317 * [ST-GNSS] - Datalogging API
apalmieri 0:0a9c622571d7 318 * Start or restart the current data log.
apalmieri 0:0a9c622571d7 319 *
apalmieri 0:0a9c622571d7 320 * @return GPS_ERROR_NONE on success /
apalmieri 0:0a9c622571d7 321 * A callback (if set) will be invoked upon a message is received
apalmieri 0:0a9c622571d7 322 * from the GPS device.
apalmieri 0:0a9c622571d7 323 */
apalmieri 0:0a9c622571d7 324 gps_provider_error_t startDatalog(void);
apalmieri 0:0a9c622571d7 325
apalmieri 0:0a9c622571d7 326 /**
apalmieri 0:0a9c622571d7 327 * [ST-GNSS] - Datalogging API
apalmieri 0:0a9c622571d7 328 * Stop or restart the current data log.
apalmieri 0:0a9c622571d7 329 *
apalmieri 0:0a9c622571d7 330 * @return GPS_ERROR_NONE on success /
apalmieri 0:0a9c622571d7 331 * A callback (if set) will be invoked upon a message is received
apalmieri 0:0a9c622571d7 332 * from the GPS device.
apalmieri 0:0a9c622571d7 333 */
apalmieri 0:0a9c622571d7 334 gps_provider_error_t stopDatalog(void);
apalmieri 0:0a9c622571d7 335
apalmieri 0:0a9c622571d7 336 /**
apalmieri 0:0a9c622571d7 337 * [ST-GNSS] - Datalogging API
apalmieri 0:0a9c622571d7 338 * Erase the current data logging.
apalmieri 0:0a9c622571d7 339 *
apalmieri 0:0a9c622571d7 340 * @return GPS_ERROR_NONE on success /
apalmieri 0:0a9c622571d7 341 * A callback (if set) will be invoked upon a message is received
apalmieri 0:0a9c622571d7 342 * from the GPS device.
apalmieri 0:0a9c622571d7 343 */
apalmieri 0:0a9c622571d7 344 gps_provider_error_t eraseDatalog(void);
apalmieri 0:0a9c622571d7 345
apalmieri 0:0a9c622571d7 346 /**
apalmieri 0:0a9c622571d7 347 * [ST-GNSS] - Datalogging API
apalmieri 0:0a9c622571d7 348 * Raised from the host to get information about the datalog subsystem.
apalmieri 0:0a9c622571d7 349 *
apalmieri 0:0a9c622571d7 350 * @return GPS_ERROR_NONE on success / GPS_ERROR_LOG_REQ_STATUS on failure.
apalmieri 0:0a9c622571d7 351 */
apalmieri 0:0a9c622571d7 352 gps_provider_error_t logReqStatus(void);
apalmieri 0:0a9c622571d7 353
apalmieri 0:0a9c622571d7 354 /**
apalmieri 0:0a9c622571d7 355 * [ST-GNSS] - Datalogging API
apalmieri 0:0a9c622571d7 356 * Trigger a query request to the GNSS receiver.
apalmieri 0:0a9c622571d7 357 *
apalmieri 0:0a9c622571d7 358 * @param logReqQuery The log query request.
apalmieri 0:0a9c622571d7 359 * @return GPS_ERROR_NONE on success / GPS_ERROR_LOG_REQ_QUERY on failure.
apalmieri 0:0a9c622571d7 360 */
apalmieri 0:0a9c622571d7 361 gps_provider_error_t logReqQuery(LogQueryParams_t &logReqQuery);
apalmieri 0:0a9c622571d7 362
apalmieri 0:0a9c622571d7 363 /**
apalmieri 0:0a9c622571d7 364 * [ST-GNSS] - Odometer API
apalmieri 0:0a9c622571d7 365 * Enable the Odometer subsystem.
apalmieri 0:0a9c622571d7 366 *
apalmieri 0:0a9c622571d7 367 * The Odometer subsystem is enabled.
apalmieri 0:0a9c622571d7 368 *
apalmieri 0:0a9c622571d7 369 * @return GPS_ERROR_NONE on success /
apalmieri 0:0a9c622571d7 370 * A callback (if set) will be invoked upon a message is received
apalmieri 0:0a9c622571d7 371 * from the GPS device.
apalmieri 0:0a9c622571d7 372 */
apalmieri 0:0a9c622571d7 373 gps_provider_error_t enableOdo(void);
apalmieri 0:0a9c622571d7 374
apalmieri 0:0a9c622571d7 375 /**
apalmieri 0:0a9c622571d7 376 * [ST-GNSS] - Odometer API
apalmieri 0:0a9c622571d7 377 * Reset the Odometer subsystem.
apalmieri 0:0a9c622571d7 378 *
apalmieri 0:0a9c622571d7 379 * The Odometer subsystem starts evaluating the ground distance
apalmieri 0:0a9c622571d7 380 * from the current resolved position.
apalmieri 0:0a9c622571d7 381 *
apalmieri 0:0a9c622571d7 382 * @param alarmDistance The distance from the current resolved position
apalmieri 0:0a9c622571d7 383 * triggering an alarm
apalmieri 0:0a9c622571d7 384 * @return GPS_ERROR_NONE on success /
apalmieri 0:0a9c622571d7 385 * A callback (if set) will be invoked upon a message is received
apalmieri 0:0a9c622571d7 386 * from the GPS device.
apalmieri 0:0a9c622571d7 387 */
apalmieri 0:0a9c622571d7 388 gps_provider_error_t startOdo(unsigned alarmDistance);
apalmieri 0:0a9c622571d7 389
apalmieri 0:0a9c622571d7 390 /**
apalmieri 0:0a9c622571d7 391 * [ST-GNSS] - Odometer API
apalmieri 0:0a9c622571d7 392 * Stop the Odometer subsystem.
apalmieri 0:0a9c622571d7 393 *
apalmieri 0:0a9c622571d7 394 * @return GPS_ERROR_NONE on success /
apalmieri 0:0a9c622571d7 395 * A callback (if set) will be invoked upon a message is received
apalmieri 0:0a9c622571d7 396 * from the GPS device.
apalmieri 0:0a9c622571d7 397 */
apalmieri 0:0a9c622571d7 398 gps_provider_error_t stopOdo(void);
apalmieri 0:0a9c622571d7 399
apalmieri 0:0a9c622571d7 400 /**
apalmieri 0:0a9c622571d7 401 * [ST-GNSS] - Odometer API
apalmieri 0:0a9c622571d7 402 * Reset the Odometer subsystem.
apalmieri 0:0a9c622571d7 403 *
apalmieri 0:0a9c622571d7 404 * @return GPS_ERROR_NONE on success /
apalmieri 0:0a9c622571d7 405 * A callback (if set) will be invoked upon a message is received
apalmieri 0:0a9c622571d7 406 * from the GPS device.
apalmieri 0:0a9c622571d7 407 */
apalmieri 0:0a9c622571d7 408 gps_provider_error_t resetOdo(void);
apalmieri 0:0a9c622571d7 409
apalmieri 0:0a9c622571d7 410 /**
apalmieri 0:0a9c622571d7 411 * @return true if we've obtained at least one valid location since last
apalmieri 0:0a9c622571d7 412 * calling start().
apalmieri 0:0a9c622571d7 413 *
apalmieri 0:0a9c622571d7 414 * @Note: This is cleared after reset().
apalmieri 0:0a9c622571d7 415 */
apalmieri 0:0a9c622571d7 416 bool locationAvailable(void) const;
apalmieri 0:0a9c622571d7 417
apalmieri 0:0a9c622571d7 418 /**
apalmieri 0:0a9c622571d7 419 * @return the last valid location if there is any; else NULL.
apalmieri 0:0a9c622571d7 420 */
apalmieri 0:0a9c622571d7 421 const LocationUpdateParams_t *getLastLocation(void) const;
apalmieri 0:0a9c622571d7 422
apalmieri 0:0a9c622571d7 423 /**
apalmieri 0:0a9c622571d7 424 * Type declaration for a callback to be invoked from interrupt context upon
apalmieri 0:0a9c622571d7 425 * receiving new location data.
apalmieri 0:0a9c622571d7 426 *
apalmieri 0:0a9c622571d7 427 * @Note: Please note that the handler gets invoked from interrupt context.
apalmieri 0:0a9c622571d7 428 * Users *should not* do any long running or blocking operations in the
apalmieri 0:0a9c622571d7 429 * handler.
apalmieri 0:0a9c622571d7 430 */
apalmieri 0:0a9c622571d7 431 typedef void (* LocationUpdateCallback_t)(const LocationUpdateParams_t *params);
apalmieri 0:0a9c622571d7 432
apalmieri 0:0a9c622571d7 433 /**
apalmieri 0:0a9c622571d7 434 * Setup the locationUpdate callback.
apalmieri 0:0a9c622571d7 435 *
apalmieri 0:0a9c622571d7 436 * @Note: Please note that the handler gets invoked from interrupt context.
apalmieri 0:0a9c622571d7 437 * Users *should not* do any long running or blocking operations in the
apalmieri 0:0a9c622571d7 438 * handler.
apalmieri 0:0a9c622571d7 439 */
apalmieri 0:0a9c622571d7 440 void onLocationUpdate(LocationUpdateCallback_t callback);
apalmieri 0:0a9c622571d7 441
apalmieri 0:0a9c622571d7 442 /**
apalmieri 0:0a9c622571d7 443 * In low-power operation, the GPS controller may be expected to hibernate
apalmieri 0:0a9c622571d7 444 * for extended periods and location updates may be infrequent. It should
apalmieri 0:0a9c622571d7 445 * then be possible for an application to demand location data when needed.
apalmieri 0:0a9c622571d7 446 *
apalmieri 0:0a9c622571d7 447 * This calls results in a locationCallback if there is a useful location to
apalmieri 0:0a9c622571d7 448 * report.
apalmieri 0:0a9c622571d7 449 */
apalmieri 0:0a9c622571d7 450 void lpmGetImmediateLocation(void);
apalmieri 0:0a9c622571d7 451
apalmieri 0:0a9c622571d7 452 /**
apalmieri 0:0a9c622571d7 453 * [ST-GNSS] - Geofencing API
apalmieri 0:0a9c622571d7 454 */
apalmieri 0:0a9c622571d7 455 bool isGeofencingSupported(void);
apalmieri 0:0a9c622571d7 456
apalmieri 0:0a9c622571d7 457 /**
apalmieri 0:0a9c622571d7 458 * [ST-GNSS] - Geofencing API
apalmieri 0:0a9c622571d7 459 *
apalmieri 0:0a9c622571d7 460 * Type declaration for a callback to be invoked upon
apalmieri 0:0a9c622571d7 461 * receiving new geofence cfg message.
apalmieri 0:0a9c622571d7 462 */
apalmieri 0:0a9c622571d7 463 typedef void (* GeofenceCfgMessageCallback_t)(int ret_code);
apalmieri 0:0a9c622571d7 464 /**
apalmieri 0:0a9c622571d7 465 * [ST-GNSS] - Geofencing API
apalmieri 0:0a9c622571d7 466 *
apalmieri 0:0a9c622571d7 467 * Setup the geofenceCfg callback.
apalmieri 0:0a9c622571d7 468 */
apalmieri 0:0a9c622571d7 469 void onGeofenceCfgMessage(GeofenceCfgMessageCallback_t callback);
apalmieri 0:0a9c622571d7 470 /**
apalmieri 0:0a9c622571d7 471 * [ST-GNSS] - Geofencing API
apalmieri 0:0a9c622571d7 472 *
apalmieri 0:0a9c622571d7 473 * Type declaration for a callback to be invoked upon
apalmieri 0:0a9c622571d7 474 * receiving new geofence status message.
apalmieri 0:0a9c622571d7 475 */
apalmieri 0:0a9c622571d7 476 typedef void (* GeofenceStatusMessageCallback_t)(const GeofenceStatusParams_t *params, int ret_code);
apalmieri 0:0a9c622571d7 477 /**
apalmieri 0:0a9c622571d7 478 * [ST-GNSS] - Geofencing API
apalmieri 0:0a9c622571d7 479 *
apalmieri 0:0a9c622571d7 480 * Setup the geofenceStatus callback.
apalmieri 0:0a9c622571d7 481 */
apalmieri 0:0a9c622571d7 482 void onGeofenceStatusMessage(GeofenceStatusMessageCallback_t callback);
apalmieri 0:0a9c622571d7 483
apalmieri 0:0a9c622571d7 484 /**
apalmieri 0:0a9c622571d7 485 * [ST-GNSS] - Datalogging API
apalmieri 0:0a9c622571d7 486 */
apalmieri 0:0a9c622571d7 487 bool isDataloggingSupported(void);
apalmieri 0:0a9c622571d7 488
apalmieri 0:0a9c622571d7 489 /**
apalmieri 0:0a9c622571d7 490 * [ST-GNSS] - Datalogging API
apalmieri 0:0a9c622571d7 491 *
apalmieri 0:0a9c622571d7 492 * Type declaration for a callback to be invoked upon
apalmieri 0:0a9c622571d7 493 * receiving new log status message.
apalmieri 0:0a9c622571d7 494 *
apalmieri 0:0a9c622571d7 495 * Report the internal data log subsystem state.
apalmieri 0:0a9c622571d7 496 */
apalmieri 0:0a9c622571d7 497 typedef void (* LogStatusCallback_t)(const LogStatusParams_t *params);
apalmieri 0:0a9c622571d7 498
apalmieri 0:0a9c622571d7 499 /**
apalmieri 0:0a9c622571d7 500 * [ST-GNSS] - Datalogging API
apalmieri 0:0a9c622571d7 501 *
apalmieri 0:0a9c622571d7 502 * Setup the log status callback.
apalmieri 0:0a9c622571d7 503 */
apalmieri 0:0a9c622571d7 504 void onLogStatus(LogStatusCallback_t callback);
apalmieri 0:0a9c622571d7 505
apalmieri 0:0a9c622571d7 506 /**
apalmieri 0:0a9c622571d7 507 * [ST-GNSS] - Datalogging API
apalmieri 0:0a9c622571d7 508 *
apalmieri 0:0a9c622571d7 509 * Type declaration for a callback to be invoked upon
apalmieri 0:0a9c622571d7 510 * receiving new log query message compliant to the query raised by the host.
apalmieri 0:0a9c622571d7 511 */
apalmieri 0:0a9c622571d7 512 typedef void (* LogQueryCallback_t)(const LogQueryRespParams_t *params);
apalmieri 0:0a9c622571d7 513
apalmieri 0:0a9c622571d7 514 /**
apalmieri 0:0a9c622571d7 515 * [ST-GNSS] - Datalogging API
apalmieri 0:0a9c622571d7 516 *
apalmieri 0:0a9c622571d7 517 * Setup the log query callback.
apalmieri 0:0a9c622571d7 518 */
apalmieri 0:0a9c622571d7 519 void onLogQuery(LogQueryCallback_t callback);
apalmieri 0:0a9c622571d7 520
apalmieri 0:0a9c622571d7 521 /**
apalmieri 0:0a9c622571d7 522 * [ST-GNSS] - Odometer API
apalmieri 0:0a9c622571d7 523 */
apalmieri 0:0a9c622571d7 524 bool isOdometerSupported(void);
apalmieri 0:0a9c622571d7 525
apalmieri 0:0a9c622571d7 526 /**
apalmieri 0:0a9c622571d7 527 * [ST-GNSS] - Odometer API
apalmieri 0:0a9c622571d7 528 *
apalmieri 0:0a9c622571d7 529 * Type declaration for a callback to be invoked upon
apalmieri 0:0a9c622571d7 530 * receiving new odometer subsystem megssage.
apalmieri 0:0a9c622571d7 531 */
apalmieri 0:0a9c622571d7 532 typedef void (* OdoCallback_t)(const OdoParams_t *params);
apalmieri 0:0a9c622571d7 533
apalmieri 0:0a9c622571d7 534 /**
apalmieri 0:0a9c622571d7 535 * [ST-GNSS] - Datalogging API
apalmieri 0:0a9c622571d7 536 *
apalmieri 0:0a9c622571d7 537 * Setup the odometer callback.
apalmieri 0:0a9c622571d7 538 */
apalmieri 0:0a9c622571d7 539 void onOdo(OdoCallback_t callback);
apalmieri 0:0a9c622571d7 540
apalmieri 0:0a9c622571d7 541 public:
apalmieri 0:0a9c622571d7 542 /**
apalmieri 0:0a9c622571d7 543 * Default constructor.
apalmieri 0:0a9c622571d7 544 */
apalmieri 0:0a9c622571d7 545 GPSProvider() : impl(createGPSProviderInstance()) {
apalmieri 0:0a9c622571d7 546 /* empty */
apalmieri 0:0a9c622571d7 547 }
apalmieri 0:0a9c622571d7 548
apalmieri 0:0a9c622571d7 549 virtual ~GPSProvider() {
apalmieri 0:0a9c622571d7 550 stop();
apalmieri 0:0a9c622571d7 551 }
apalmieri 0:0a9c622571d7 552
apalmieri 0:0a9c622571d7 553 private:
apalmieri 0:0a9c622571d7 554 /**
apalmieri 0:0a9c622571d7 555 * We use 'composition' to combine a driver-implementation object to the
apalmieri 0:0a9c622571d7 556 * GPSProvider interface. The implementation object will come to life
apalmieri 0:0a9c622571d7 557 * through the createGPSProviderInstance(), which must be defined by the
apalmieri 0:0a9c622571d7 558 * driver library. The mechanics of the implementation are to be hidden
apalmieri 0:0a9c622571d7 559 * behind the abstract interface provided by GPSProvider.
apalmieri 0:0a9c622571d7 560 */
apalmieri 0:0a9c622571d7 561 GPSProviderImplBase *const impl;
apalmieri 0:0a9c622571d7 562
apalmieri 0:0a9c622571d7 563 /* disallow copy constructor and assignment operators */
apalmieri 0:0a9c622571d7 564 private:
apalmieri 0:0a9c622571d7 565 GPSProvider(const GPSProvider&);
apalmieri 0:0a9c622571d7 566 GPSProvider & operator= (const GPSProvider&);
apalmieri 0:0a9c622571d7 567 };
apalmieri 0:0a9c622571d7 568
apalmieri 0:0a9c622571d7 569 #endif /*__GPS_PROVIDER_H__*/