AssistNow service integration guide

Fetching AssistNow data

To retrieve the AssistNow data, the device firmware must use a REST API that provides the following in the input:

• The hostname of the service interface: assistnow.services.u-blox.com

• The authentication code (Chipcode) that has been retrieved during the device registration procedure.

• The data to be requested, according to the selected option (Live or Predictive Orbits). 

Service Request format rules:

• It should be provided in this format: key=value&key=value&key=value;

• The following rules apply:

  • The order of parameters is not important.

  • Keys and values are case sensitive

  • Keys and values must be separated by an equals character (“=“)

  • (Key/value) pairs must be separated by an ampersand (“&”)

  • If a value contains a list, each item in the list must be separated by a comma (“,”)

  • Numeric values must conform to the regular expression: ^-?[0-9]+(\.[0-9]+)?$. This represents, in order: an optional negative sign, one or more digits, and optionally a decimal point and one or more digits.

Upon reception of the HTTPS GET request, the server responds with the required messages in binary format or an error string in text format. After delivery of all data, the server terminates the connection. All data (with the exception of hostname, which is used to establish the connection) is carried solely within the encrypted connection and is protected from man-in-the-middle attacks in the same way that any HTTPS data is.

Below is an example of a service request:

https://AssistNow.services.u-blox.com/GetAssistNowData.ashx?chipcode=XXXXXXXXX&gnss=gps,glo&data=uporb_1,ualm

where:

• chipcode is the device authentication credential.

• gnss is the list of GNSS constellations for which the AssistNow data are needed.

• data is the list of AssistNow data requested (for example: almanac, ephemeris, etc.).

All supported parameters are listed in the UBX messages section below, and in the REST API specification.

You are allowed to get the data according to:

• The type of subscription (Predictive Orbits or Live Orbits)

• The usage policy explained in the 'Service usage policies' section of the User guide.

Note: if the service query contains a request for a data type that you are not allowed to get, the service replies with the error code 403 (see below) and zero payload. 

• For example, if you have subscribed to the Predictive Orbits service only, and you try to get ephemeris (ulorb_l1) like in the query below

https://AssistNow.services.u-blox.com/GetAssistNowData.ashx?chipcode=XXXXXXXXX&gnss=gps,glo&data=uporb_1,ualm,ulorb_l1

Note: although the number of AssistNow messages received should be fixed (according to the specification reported in the User Guide), in some situations, the number might be different, for multiple reasons. We recommend developing the firmware considering these possible situations, and feeding all the messages received into the GNSS receiver anyway.

Predictive Orbits data

By using satellite orbit predictions, the GNSS receiver can achieve a fast Time-To-First-Fix (TTFF) in most cases, reducing battery consumption compared to operation without AssistNow data. For further improvements in positioning accuracy, AssistNow Live Orbits should be considered.

Predictive Orbits are very useful whenever you need to minimize access to the internet or the device has sporadic internet connectivity (for example, only Wi-Fi connectivity is available, or the asset moves for long periods in regions without network coverage) 

Users of AssistNow Predictive Orbits are expected to select which type of data to get from the service

• Almanac data, by specifying the ualm value in the data attribute in the service request.

• Orbit predictions data, by specifying the uporb_N (N=1,3,7,14) in the data attribute. N refers to the number of prediction days delivered by the service to the GNSS receiver, starting from the day of the query

The service responds with a set of data containing a prediction of each SV orbit in the future. This data must be transferred to a u-blox GNSS receiver, so that it can estimate the positions of the satellites when no better data is available and then calculate a position.

The Host software guide explains in detail how to design the device firmware in order to get the AssistNow data and inject data into the GNSS receiver.

The following example shows a request for Almanac data and a 1-day orbit prediction for GPS and Galileo satellites.

https://AssistNow.services.u-blox.com/GetAssistNowData.ashx?chipcode=XXXXXXXXX&gnss=gps,gal&data=uporb_1,ualm

Let's now dive into each type of data delivered: almanac and orbit prediction

Almanac

Almanac data has a validity period of several weeks; therefore, it can be downloaded from the AssistNow service at approximately the same time the Orbit prediction data is obtained. It can then be stored in the host for uploading on receiver startup, or it can be transferred to the receiver straight away and preserved there (provided suitable non-volatile storage is available).

If Almanac data is requested, the service returns one almanac message for each satellite of the constellation selected (UBX-MGA-XXX-ALM, where XXX = GPS, GLO, BDS, GAL, QZSS)

Orbit predictions

Upon reception of an HTTPS GET request, the service responds with the UBX-MGA-ANO messages in binary format, or an error string in text format. After delivery of all of the data, the server terminates the connection.

The response data is ordered by timestamp and then by GNSS. Hence, the response data appears as follows:

04/09/2013 [GPS SV1, GPS SV2, GPS SV3....GPS SV32]

04/09/2013 [GLO SV1, GLO SV2, GLO SV3....GLO SV24]

05/09/2013 [GPS SV1, GPS SV2, GPS SV3....GPS SV32]

05/09/2013 [GLO SV1, GLO SV2, GLO SV3....GLO SV24]

.

.

.

09/10/2013 [GPS SV1, GPS SV2, GPS SV3....GPS SV32]

09/10/2013 [GLO SV1, GLO SV2, GLO SV3....GLO SV24]

Live Orbits data

This set of orbital data allows for further reducing the Time-To-First-Fix of the GNSS receiver, when compared to Predictive Orbits, and moreover, the position accuracy is improved from the very initial fix. 

The receiver is smart enough to continuously select, for each satellite, the best orbital data available between the Predictive Orbits, the Live Orbits, and the orbital information downloaded directly from satellites. Thanks to this intelligence, Predictive Orbit can be used in conjunction with Live Orbits to address all use cases and always obtain the best compromise between Time to First Fix and position accuracy.

Live Orbits allows the device to get:

• Time information data - you do not need to specify any attribute since the UBX-MGA-INI-TIME_UTC will always be returned in the response as the first message of the message chain.

• Ephemeris, by specifying the ulorb_l1 in the data attribute in the service request.

• Satellite health status, by specifying the usvht in the data attribute.

• Klobuchar Ionospheric assistance, by specifying the ukion in the data attribute.

The following example shows a request for GPS and Galileo satellites for the ephemeris, satellite health status, and ionospheric assistance data

https://AssistNow.services.u-blox.com/GetAssistNowData.ashx?chipcode=XXXXXXXXX&gnss=gps,gal&data=ulorb_l1,usvht,ukion

The service replies with the data available according to the service specification. Considering the above query example, the service replies with:

• Ephemeris data for the GPS and Galileo constellations.

• Health satellite status for the GPS constellation, since this data set is not available for Galileo.

• Klobuchar Ionospheric assistance for the GPS constellation, since this data set is not available for Galileo.

The supported GNSS constellations for each data type are listed in the UBX messages section. 

Minimize response data size

If the filteronpos parameter is provided, the server determines the currently visible satellites considering the device position submitted with the request, and only sends the ephemeris data of those satellites that should be in view at the location of the user. This reduces bandwidth requirements. In this case, the pacc value is taken into account, meaning that the server returns all SVs visible in the given uncertainty region centered in lat and lon  and with radius specified by pacc (in meters)

UBX Messages

The following table summarizes the accepted query parameters and the UBX messages provided in the response corresponding to each data type.

Notes:

• The '***' in the UBX messages column must be replaced by the supported constellation (GPS, GLO, BDS, GAL, QZSS)

• The message UBX-MGA-INIT_TIME_UTC, when relevant, is always delivered as the first message of the service response, and it must always be fed into the receiver as the first message.

• Refer to the API specification to see all the allowed attributes for each query parameter.

Status code handling

The table summarizes all the HTTP status codes to be handled by the device firmware when retrieving the AssistNow data. If any of those conditions happen, an error event is reported in the Thingstream platform with the information of the AssistNow Thing impacted. You can access this event in two ways:

• By looking in the Event tab of the Device profile (Services > ZTP > Device Profiles) used for the Device registration.

• By searching the Thing in the Thing List (Services > Thing List) and verifying the Events tab in the Thing. Note that the Thing name corresponds to the payload of the UBX-SEC-UNIQID message.

  • For example, if the UBX-SEC-UNIQID sent is "B56227030A0002000000XXXXXXXXXXXXA03D": the name of the Thing will be XXXXXXXXXXXX.