The Point One Navigation Polaris API provides secure and efficient GNSS corrections and supporting data.
System Overview
The Polaris API provides a secure way for a group of devices to use a single API key to request and use Access Tokens to access the Point One GNSS corrections streams. It can be used in place of NTRIP, but still maintains industry standard RTCMv3 messages for correction data.
Open source C, C++ and Python clients are available on Github:
https://github.com/pointoneNav/polaris
Message Flow
Device Server Type
Access Token (http)
| Access Token Request [API Key]-----> | JSON
| <--------[Access Token] | JSON
|
GNSS Corrections Streams (TCP/IP)
| Authorization [Access Token]---> | System Message
| Position (ECEF or LLA) -----> | System Message
| |
| <--- Corrections | RTCM3 Message
| <--- Corrections | RTCM3 Message
| <--- Corrections | RTCM3 Message
| Position (ECEF or LLA)-----> | System Message
| |
| <--- Corrections | RTCM3 Message
| <--- Corrections | RTCM3 Message
| <--- Corrections | RTCM3 Message
Access Token Request
The device submits the API key to receive an [Access Token] which is used to authorize the GNSS streams.
The [Access Token] request endpoint is:
https://api.pointonenav.com/api/v1/auth/token
-
Method: POST
-
Auth required: NO
-
Data constraints
{
"grant_type": "authorization_code",
"token_type": "bearer",
"authorization_code": "[API Key]",
"unique_id": "[Unique Id]"
}
-
Data example
{
"grant_type": "authorization_code",
"token_type": "bearer",
"authorization_code": "a94fd3abd3a84o494273h28923dh38",
"unique_id": "fd3c9b488fbb43459dd920ca11251c2b"
}
Success Response
- Code : 200 OK
- Content example
{
"token_type": "bearer",
"access_token": "3c92c819ebc44def884ab3f931a22024",
"expires_in": "604800",
"issued_at": "1515449959"
}
Note: The expiration time indicates the time at which the token can no longer be used for new connections and a new access request must be sent. Once connected using a valid token, a client will continue to receive data even if the token expires.
Error Response
- Code: 403 FORBIDDEN
- Condition: If API_KEY is invalid.
GNSS Streams
The GNSS stream endpoints and corresponding messages support RTCM3 streams over TCP/IP using an access token for authentication.
The available GNSS stream endpoints are:
polaris.pointonenav.com:8090 (TLS Encrypted)
polaris.pointonenav.com:8088 (plaintext, not recommended for production designs)
System Messages
System messages are framed with a header and footer to aid in processing. The header includes two start bytes, followed by a message class, message ID, and payload length (in bytes). The footer contains a 16b checksum, described below.
Packets look as follows:
0xB5 0x62 <CLASS:1> <ID:1> <LEN_DATA:2> <---DATA---> <CHK:2>
Note: All values in the following messages, including the payload length (LEN_DATA) and checksum (CHK), are little endian.
Checksum is calculated over everything except the first two bytes. The algorithm is:
CK_A, CK_B = 0, 0
for i in range(len(packet)):
CK_A = CK_A + packet[i]
CK_B = CK_B + CK_A
# Ensure unsigned byte range
CK_A = CK_A & 0xFF
CK_B = CK_B & 0xFF
# Compute 16b checksum
CHK = (CK_B << 8) | CK_A
Authorization via Access Token
Class: 0xE0 Id: 0x01
Authorization is accomplished by sending the System Message for Authentication:
The payload is the [Access Token] received from the API server encoded as a series of characters: For example, for the access token 3c92c819ebc44def884ab3f931a22024 we have:
b5 62 e0 01 20 00 33 63 39 32 63 38 31 39 65 62 63 34 34 64 65 66 38 38 34 61 62 33 66 39 33 31 61 32 32 30 32 34 c0 b9
(This token in this example is shorter for clarity, an actual token would be much longer like below)
eyJhbGciOiJBMTI4S1ciLCJ6aXAiOiJERUYiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0.N-URpWR7VRV44W2uDgbNBb-RaQ4yrgo9jw2Kf_8jOcKp5dCLN1WoLQ.bAljVEcUUpIGpgjEeF441w.orPAve6fhzZoYtSYF7JGAZ0ZHgRuOhFQtVSF7HgIbw4Fn4fgBCQPdvdRJQ5-yvX6NKiuffv1MzTx5lMaB0pXEMf39S9XWh70Ybz8d1OCe5Y.p5FyEcMI2GKIsneHLJmMYw
If the token is invalid or expired, the socket will be closed immediately.
Position ECEF
Class: 0xE0 Id: 0x03
Sending this message causes the backend to reevaluate its assignment of the device’s current correction source. It’s up to the client when to send this, but a common strategy is to remember the last point at which it is sent and only send it again after moving > 1km.
B5 62 E0 03 0C 00 <ECEFX in cm:4> <ECEFY in cm:4> <ECEFZ in cm:4> <CHK:2>
Note: ECEF coordinates are sent as signed 32 bit integers in CENTIMETERS.
Position LLA (WGS84)
Class: 0xE0 Id: 0x04
Sending this message causes the backend to reevaluate its assignment of the device’s current correction source. It’s up to the client when to send this, but a common strategy is to remember the last point at which it is sent and only send it again after moving > 1km.
B5 62 E0 04 0C 00 <LATITUDE:4> <LONGITUDE:4> <ALTITUDE:4> <CHK:2>
Note: latitude and longitude coordinates are sent as signed 32 bit integers in DECIMAL DEGREES scaled by 1x10^7. Altitude is sent in MILLIMETERS.
RTCM3 Messages
Once the device is authenticated and an initial position message is sent the system will output RTCM3 messages. It is recommended to resend the device position at a regular interval of once a minute. 1 Hz is the highest recommended rate for high dynamic applications.
Note: RTCM Messages are NOT encapsulated in the system message format.
The system currently outputs RTCM3 messages L1/L2/L5 on GPS, GLONASS, GALILEO AND BEIDOU. The details of those specs are in the RTCM3.1 ICD