Getting Started

Getting Started

Hyper Precise Location Coverage Maps

https://thingspace.verizon.com/resources/support/coverage-map/

Unselect LTE and LTE-M layers to show RTK and DGNSS coverage.

Hyper Precise Location coverage is updated frequently as deployment expands

Access and Tokens

In order for getting the Hyper Precise Location Service, the device (client) has to get authenticated with the OAuth 2.0 server and obtain a bearer token and URL for the Hyper Precise Location Server. For mutual authentication, the device and OAuth server use Mutual Transport Layer Security (MTLS). The device and OAuth server confirm to RCF 6749.

Device vendors can obtain signed X.509 certificates from any of the known Certificate Authorities (CA), such as DigiCert, Commodo, GoDaddy, etc.

Client Authentication using Mutual Transport Layer Security (MTLS)

Clients can be authenticated using MTLS. A new scope will be defined for each client that wants to get authenticated via this path. 

The information for client authentication using MTLS for the Hyper Precise Location service:

Value

Description

URL

https://auth.thingspace.verizon.com/oauth2/token

Method

POST

URL Parameters

None.

Request Example

curl -X 'POST' -d 'grant_type=client_credentials&scope=ts.bullseye&client_id={IMEI}' -H 'Content-Type: application/x-www-form-urlencoded'  'https://auth.thingspace.verizon.com/oauth2/token' --cert {CLIENT_CERT} --key {CLIENT_KEY}

Response Code and Content

Response Code: 200 OK

Content:

{
    “access_token”: “{token}",
    “expires_in”: 86400,
    “scope”: “ts.bullseye”,
    “server_address”: “http://random.bullseye.server.url.com:1234”,
    “token_type”: “bearer”
}

Response Parameters

If an Access Token request is successful and authorized, the Auth service will return an access token and an optional refresh token as described in RFC 6749 Section 5.1. The response will be a JSON object with the following properties:

Parameter

Description

access_token
required

The Access Token created by Auth Service. This is required to make User Services API calls.  

token_type
required

Specifies the type of token. bearer is currently the only valid value.

expires_in

Specifies the lifetime, in seconds, of the Access Token.

scope
required

Specifies the scope requested by the client.

server_address

Specifies the address of the server for further communication using the Access Token

For more information on the code and token response_type, see RFC 6749 Section 4.1 and Section 4.2

Setting a Reply Path

Once all devices are activated, a GET /caster request needs to be sent with current location data to be corrected.

curl -v -H 'Authorization: Bearer {bearer token}' -H 'Ntrip-Version: Ntrip/2.0' -H 'Ntrip-GGA: {GPGGA data}' http://caas.hyperlocation.io:2100/CASTER --output -
*   Trying 34.215.0.140...
* TCP_NODELAY set
* Connected to caas.hyperlocation.io (34.215.0.140) port 2100 (#0)
> GET /CASTER HTTP/1.1
> Host: caas.hyperlocation.io:2100
> User-Agent: curl/7.64.1
> Accept: */*
> Authorization: Bearer {bearer token}
> Ntrip-Version: Ntrip/2.0
> Ntrip-GGA: {GPGGA data}

Successful request:

< HTTP/1.1 200 OK
< Connection: keep-alive
< Content-Type: gnss/data
< no chunk, no close, no size. Assume close to signal end

Failed request:

< HTTP/1.1 401 Unauthorized
< Connection: close
< WWW-Authenticate: Basic realm="Secure Area"
< Date: Mon, 19 Apr 2021 19:26:36 GMT
< Content-Length: 41
<
* Closing connection 0

Getting GPGGA Data

This is the device's current location (GPS) information needing correction and it conforms to the NMEA 0183 standard.

The GPGGA data is generated by the software being used and examples of output and more information can be found in the Wikipedia page about NMEA 0183.

The GPGGA data is a string of 16 comma seperated values (with a line feed or carriage return at the end as the 17th character) or a "Sentence". An example looks like this:

$GNGGA,150322.00,3256.78980,N,09649.10378,W,1,12,0.93,209.0,M,-25.2,M,,,*7E    

Position

Structure

Description

Format

Example

1

$GNGGA

Log header. 

 n/a

$GNGGA

2

utc

UTC time status of position (hours/minutes/seconds/ decimal seconds)

hhmmss.ss

150322.00

3

lat

Latitude (decimal degrees: DDmm.mm)

numeric

3256.78980

4

lat dir

Latitude direction (N = North, S = South)

Single alpha character

N

5

lon

Longitude (decimal degrees: DDDmm.mm)

numeric

09649.10378

6

lon dir

Longitude direction (E = East, W = West)

Single alpha character

W

7

quality

GPS Quality Indicator. See the "Quality Indicator" table below

numeric

1

8

# sats

Number of satellites in use. May be different to the number in view

numeric

12

9

hdop

Horizontal dilution of precision

numeric

0.93

10

alt

Antenna altitude above/below mean sea level

numeric

209.0

11

a-units

Units of antenna altitude (M = meters)

Single alpha character

M

12

undulation

Undulation - the relationship between the geoid and the WGS84 ellipsoid

numeric

-25.2

13

u-units

Units of undulation (M = meters)

Single alpha character

M

14

age

Age of correction data (in seconds)

The maximum age reported here is limited to 99 seconds.

numeric

(empty when no differential data is present)

15

stn ID

Differential base station ID

numeric

(empty when no differential data is present)

16

*xx

Check sum

*hh

*7E

17

[CR][LF]

Sentence terminator (Carriage Return or Line Feed)

 n/a

[CR][LF]

Quality Indicator

Indicator

Description

0

Fix not available or invalid

1

Single point

2

Pseudorange differential

4

RTK fixed ambiguity solution

5

RTK floating ambiguity solution

6

Dead reckoning mode

7

Manual input mode (fixed position)

8

Simulator mode

9

Wide Area Augmentation System (WAAS) This is the United Sates standard of the regional Satellite-based Augmentation Systems (SBAS)