Latest Version: 1.0.0
This is the agent library used to retrieve data from the u-blox AssistNow web service. Data supplied by AssistNow is used by a u-blox GNSS receiver to substantially reduce Time To First Fix, even under poor signal conditions. For more information about the AssistNow service, please see this user guide on the u-blox website.
Details of the device-side library code can be found here.
Note The AssistNow service enforces overuse restrictions. Since many imp agents share a single server (ie. a single source of HTTPS requests) it may be necessary to contact u-blox to ensure requests are not blocked.
You can view the library’s source code on GitHub. Click here to see information on other versions of this library.
To include this library in your project, add
#require "UBloxAssistNow.agent.lib.nut:1.0.0"
at the top of your agent code.
The methods requestOnline() and requestOffline() include a callback parameter. Any function passed into this parameter will be triggered when the response from AssistNow is received. The callback has two parameters: error and response. If no error was encountered, error will be null, otherwise it will be an error message string. The response from the server will be passed into response.
To use this service you must register with u-blox and receive an authorization token.
| Parameter | Type | Required? | Description |
|---|---|---|---|
| token | String | Yes | The authorization token supplied by u-blox (see link above) |
If the device is online, use this method to get data from AssistNow to improve your device's Time To First Fix. The data provided includes time-aid information, Earth orientation parameters, and satellite almanacs, ephemerides and health information. Server-side data is updated every 30-60 minutes.
| Parameter | Type | Required? | Description |
|---|---|---|---|
| reqParams | Table | Yes | Table of request parameters. Can be an empty table (see below) |
| reqCallback | Function | Yes | Function that will be triggered when the response from AssistNow is received (see ‘Request Callbacks’ for details) |
| Key Name | Type | Possible Values | Default | Description |
|---|---|---|---|---|
| datatype | Array of strings | "eph", "alm", "aux", "pos" |
None | The data types required. Time data is always returned for each request, even if this parameter is not supplied |
| format | String | "mga", "aid" |
"mga" |
Specifies the format of the data returned:"mga" = UBXMGA-* (M8 module and up)"aid" = UBX-AID-* (U7 module or earlier) |
| gnss | Array of strings | "gps", "qzss", "glo", "bds", "gal" |
"gps" |
GNSS for which data should be returned |
| lat | String or float | -90 to 90 | None | Approximate user latitude in WGS 84 in units of degrees and fractional degrees |
| lon | String or float | -180 to 180 | None | Approximate user longitude in WGS 84 in units of degrees and fractional degrees |
| alt | String or float | -1000 to 50000 | 0 | Approximate user altitude above WGS 84 ellipsoid in units of meters |
| pacc | String or float | 0 to 6000000 | None | Approximate accuracy of the submitted position in meters |
| tacc | String or float | 0 to 3600 | None | The timing accuracy in seconds |
| latency | String or float | 0 to 3600 | None | Typical latency in seconds between the time the server receives the request and the time the assistance data arrives at the GNSS receiver |
| filteronpos | None | None | None | If this key is present in table, the ephemeris data returned will only contain information for the satellites which are likely to be visible from the approximate position provided (see the lat, lon, alt and pacc parameters). If an approximate position is not provided, no filtering will be performed |
| filteronsv | Array of strings | None | An array of u-blox gnssId:svId pairs. The ephemeris data returned will only contain data for the listed satellites |
Note To maintain accuracy, we recommended you use strings rather than float values for the lat, lon, alt, pacc, tacc and latency parameters. Floats will be converted to strings using format("%f", floatVal).
Nothing.
If the device is likely to have connection issues, use this when the device is online to download data from the AssistNow Offline Service, specifying the time period (one to five weeks) and the type(s) of GNSS to use so your device can estimate the positions of the satellites when no live data is available. The data returned will need to be stored in the device’s Flash and transferred to the u-blox receiver for use. Using these estimates does not provide as accurate a position fix as if current ephemeris data is used, but it allows much faster Time To First Fix (TTFF) in nearly all cases.
The data obtained from AssistNow is organized by date, normally a day at a time. Consequently the more weeks for which coverage is requested, the larger the amount of data your application will need to manage and store. Similarly, each different GNSS requires its own data. In extreme cases, the service may provide several hundred kilobytes of data. This volume of data can be reduced by requesting a lower resolution, but this has a small negative impact on both position accuracy and TTFF. Server-side data is updated daily or twice daily.
| Parameter | Type | Required? | Description |
|---|---|---|---|
| reqParams | Table | Yes | Table of request parameters. Must contain a gnss, all other values are optional (see below) |
| reqCallback | Function | Yes | Function that will be triggered when the response from AssistNow is received (see ‘Request Callbacks’ for details) |
| Key Name | Type | Possible Values | Default | Description |
|---|---|---|---|---|
| gnss | Array of strings | "gps", "glo" |
None | The GNSS for which data should be returned. The table must include this key |
| format | String | "mga", "aid" |
"mga" |
Specifies the format of the data returned:"mga" = UBXMGA-* (M8 module and up)"aid" = UBX-AID-* (U7 module or earlier) |
| period | Integer | 1, 2, 3, 4, 5 | 4 | The number of weeks into the future for which data can be downloaded. Data can be requested up to five weeks in advance |
| resolution | Integer | 1, 2, 3 | 1 | The resolution of the data: 1 = Every day 2 = Every other day 3 = Every third day |
| days | Integer | 1, 2, 3, 5, 7, 10, 14 | 14 | The GNSS for which data should be returned. Supported on U7 module or earlier |
| almanac | Array of strings | "gps", "glo", "bds", "gal", "qzss" |
None | Added before MGA data is uploaded. Supported on MGA only |
Nothing.
This method takes the response from requestOffline() and returns a table of UBX-MGA-ANO assist messages organized by date.
| Parameter | Type | Required? | Description |
|---|---|---|---|
| offlineResp | HTTP response | Yes | The response parameter returned from requestOffline() |
| dateFormatter | Function | No | A function that takes the year, month and day bytes from a UBX-MGA-ANO message payload and formats them into a date string |
| logErrors | Bool | No | Whether errors encountered when parsing offline response data should be logged. Default: false |
Table — keys are date strings created via the dateFormatter, and values are a concatenated string of all messages for that date. If the response doesn’t have a 200 status code, or if no UBX-MGA-ANO messages are found, the table will be empty.
This method takes the year, month and day bytes from the AssistNow payload and returns a date string formatted YYYYMMDD. This is the formatter used by getOfflineMsgByDate() if one is not specified.
| Parameter | Type | Required? | Description |
|---|---|---|---|
| year | Integer | Yes | Year from the AssistNow message |
| month | Integer | Yes | Month from the AssistNow message |
| day | Integer | Yes | Day from the AssistNow message |
String — a date formatted as YYYYMMDD.
By default there are no HTTP request headers set, and the imp API’s defaults will be used. Use this method to customize HTTP request headers if needed.
| Parameter | Type | Required | Description |
|---|---|---|---|
| headers | Table | Yes | Table of HTTP headers |
Nothing.
The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.
| Version | Source Code | Notes |
|---|---|---|
| 1.0.0 | GitHub | Initial release |
This library is licensed under the MIT License.