AssistNow service integration guide

Fetching A-GNSS data

To retrieve the A-GNSS data the device firmware shall use a REST API providing in input:

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

• the authentication code (Chipcode) retrieved during the device registration procedure.

• the data to be requested, according to the selected option (Live or Predictive Orbits) in the 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.

Here below 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 constellation for which the A-GNSS data are needed

• data is the list of A-GNSS data requested to the service (for example, almanac, ephemeris, etc..)

All supported parameters are listed in the table at the end of this guide and in the REST API specification.

You are allowed to get the data according to:

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

• the usage policy reported in the corresponding 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 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

AssistNow service replies with the status code 403 and does not provide in the response payload neither the almanac and orbit prediction data that you would be allowed to get, because of your subscription to Predictive Orbits.

Note: although the number of A-GNSS messages received should be fixed (according to the specification reported in the User Guide) in some situations that the number might be different, for multiple reasons.

We recommend to develop the firmware considering these possible situations, and  feeding anyway into the GNSS receiver all the messages received.

Predictive Orbits data

Using the orbit prediction of the SV, the GNSS receiver achieves a fast Time-to-First-Fix in nearly all cases thus reducing the battery drain compared to a case where no A-GNSS data is available. To improve position accuracy, Live Orbit should be considered. 

Predictive Orbits are very useful whenever you need to minimize the access to the internet network 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

• 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 provides in response 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 details how to design the device firmware in order to get the A-GNSS data from the service and inject data in the GNSS receiver.

The following example shows a request of Almanac data and 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 in 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 roughly the same time when  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 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]

If data are stored in the Host, the device Firmware is expected to send at GNSS startup only the messages for the relevant days, filtering out useless data. Although the GNSS receiver autonomously discard not relevant data this approach allows to minimize the feeding time and thus to further reduce the energy drain. 

Live Orbits data

These set of orbital data allow to further reduce 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 be always returned in the response as the first message of the message chain

• Ephemeris, by specifying  the ulorb_l1 in the data attribute

• 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 below 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 service specification. Considering the above query, the service replies with:

• ephemeris data for GPS and Galileo constellation

• health satellite status for GPS constellation, since this data set is not available for Galileo

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

The supported data are listed in a table in the next 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.

The *** shall be replaced by the supported constellation (GPS,GLO,BDS,GAL,QZSS)

Note: the message UBX-MGA-INIT_TIME_UTC , when relevant, is always delivered as the first message of the service response and it shall be always feed 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 summarize all the HTTP status code to be handled by the device firmware when retrieving the A-GNSS data. If any of those condition happens, an error event is reported in the Thingstream platform with the information of the AssistNow Thing impacted. You can access to this event in two ways:

• by looking in the Event tab of the Device profile (Location Services >ZTP > Device Profile)  used for the Device registration (to be verified)

• by searching the Thing  in the Thing List (Location Services > Thing List) and verifying the Events tab in the Thing. Remind that the Thing name corresponds to the payload of the  UBX-SEC-UNIQID message (BDBFABCDEF12 in the example below)

"UBX-SEC-UNIQID": "B56227030A0002000000BDBFABCDEF12A03D" 

Next reading

• Service specifications

• Service API specification

Other readings

• AssistNow User guide
• AssistNow testing with u-center 2
• Developing Host Software