GuidesAPI Reference
Guides
  1. HD GNSS Positioning API Developer Guide

How to set up a client

  1. Connect to the service using MQTTS.
    • Ensure you have a valid username and password.
    • Generate a random MQTT client ID. It must be a valid UUIDv4 to connect. The client ID must be used in the MQTT topic names as indicated by <clientID>.
  2. Make an MQTT subscription to the topic v1/sub/app/<appId>/clients/<clientID>/positions/protobuf to receive ServerResponse messages. The response is also available in JSON format by subscribing to the topic v1/sub/app/<appId>/clients/<clientId>/positions/json, see all topic names in API Overview.
  3. Publish a Configuration message to the MQTT topic v1/pub/app/<appId>/clients/<clientID>/configuration
    • Publishing a configuration is optional. Defaults will be used if the client does not provide a configuration.
    • The response message will contain either Information with status CONFIGURATION_SET or an error.
    • Note: The configuration will expire for idle clients, therefore it is recommended for the client to publish the desired configuration as the first message every time it (re)connects to the service via MQTT or when Information element with status CONFIGURATION_RESET status has been included in the response (if using a non-default configuration).
  4. Get GNSS measurements from a GNSS receiver. This can mean opening a serial port and receiving RTCM3 data from a receiver over USB, or in case Android phones, registering a receiver for the device GNSS measurements with an API call.
    • In case of RTCM3 data it must be parsed into frames (see the RTCM v3 specification). The GNSS receiver should be configured to output RTCM3 messages (either MSM4, MSM5, or MSM7) via the serial port.
  5. Create a Measurements message and publish it to the MQTT topic v1/pub/app/<appId>/clients/<clientID>/measurements. The response will be published in v1/sub/app/<appId>/clients/<clientID>/positions/protobuf and v1/sub/app/<appId>/clients/<clientID>/positions/json. The accuracy of the returned position improves as more measurements are sent.

Multiple sets of measurements can be collected in one Measurements message, so it's possible to buffer them, for example, while waiting for an incremental back-off delay. When multiple sets of measurements have been sent the response will contain multiple results.

However, the server may reject a message that is too large or discard old measurements which defeats the purpose of buffering for longer than several minutes.

📘

Note

A client typically publishes 1 message per second (when it receives new set of GNSS measurements from the receiver) and only exceeds this temporarily for example when also publishing a configuration. The service may rate limit messages from a client that publishes measurements at a higher rate than 1Hz.

It is also possible to use a project HRN in the topic names instead of the username. This makes it possible to enable wildcard subscriptions within a project, see API overview for details.

Protocol

The client must use the MQTTS (MQTT with TLS) protocol to communicate with the service. The MQTT message payload data is encoded in protobuf format unless noted otherwise.

The client should use incremental back-off in case of errors:

  • Incremental back-off for connecting to the MQTT broker in case of disconnection.
  • Incremental back-off for sending new measurements in case of certain error responses (SERVICE_UNAVAILABLE, SERVER_ERROR).

MQTT version

Clients should use MQTT v5.

MQTT QoS

MQTT QoS 0 is recommended for the lowest latency.

MQTT v5 properties

The MQTT v5 Correlation Data property can be used to correlate a server response with a published message.

MQTT topic alias

Clients are recommended to utilize MQTT Topic Aliases to reduce message size.

MQTT session expiry

The client has the option to set the session expiry interval to a non-zero value. This allows the session to be preserved, which can be particularly useful in situations such as a temporary loss of the client's network connectivity.

The server also uses this interval to determine when to clean up the client's positioning session if the client disconnects or becomes idle. Note that this is a desired value and the system can deviate from it.

A recommended value for the session expiry interval is between 0 and 60 seconds. Setting it to a value larger than this does not provide any additional benefits.

If the session expiry interval is not set, it defaults to 0 as per the MQTT v5 specification. This implies that the positioning session may end as soon as the client disconnects from the service.

Updated last month