HERE Tracking Developer's Guide Version 1.0 - HERE Technologies
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
HERE Tracking Developer's Guide Version 1.0
Legal Notices
© 2019 HERE Global B.V. and its Affiliate(s). All rights reserved.
This material, including documentation and any related computer programs, is protected by copyright controlled by
HERE. All rights are reserved. Copying, including reproducing, storing, adapting or translating, any or all of this
material requires the prior written consent of HERE. This material also contains confidential information, which may
not be disclosed to others without the prior written consent of HERE.
Trademark Acknowledgements
HERE is trademark or registered trademark of HERE Global B.V. Other product and company names mentioned
herein may be trademarks or trade names of their respective owners.
Disclaimer
This content is provided "as-is" and without warranties of any kind, either express or implied, including, but not
limited to, the implied warranties of merchantability, fitness for a particular purpose, satisfactory quality and non-
infringement. HERE does not warrant that the content is error free and HERE does not warrant or make any
representations regarding the quality, correctness, accuracy, or reliability of the content. You should therefore
verify any information contained in the content before acting on it.
To the furthest extent permitted by law, under no circumstances, including without limitation the negligence of
HERE, shall HERE be liable for any damages, including, without limitation, direct, special, indirect, punitive,
consequential, exemplary and/ or incidental damages that result from the use or application of this content, even
if HERE or an authorized representative has been advised of the possibility of such damages.
1Document Information
Product
Name: HERE Tracking
Version: Version 1.0
Document
Name: HERE Tracking - Developer's Guide
ID: ca942c18-ccd4-46f3-bab0-1f02b11615cc
Status: FINAL
Date: 2019-04-26T13:13:10.869Z
2Table of Contents
Introduction
Concepts
Devices
Device Licenses
Device Authentication
Telemetry
Ingestion
Positioning
Shadows
Traces
Geofences
Transitions
Notifications
Vendors
Getting Started
Creating a device licence
Preparing the device
Claiming ownership of a device
Send data to the cloud
Process data in the cloud
Send data to the device
Tips
Optimize positioning result
Optimize indoor positioning result
3Introduction
Introduction
HERE Tracking is a fast and flexible IoT location platform that makes it quick and easy to add location awareness to
your products.
HERE Tracking exposes a set of REST APIs and client libraries to enable location tracking and geofencing for a
variety of device form-factors including small-footprint (small memory and processing power) devices. HERE
Tracking also includes end-user applications on mobile and web to be used as reference apps to demonstrate the
product capabilities.
For the terms and conditions covering this documentation, see the HERE Documentation License.
Why Use HERE Tracking
HERE Tracking provides resources to address the following high-level use cases:
FEATURE DESCRIPTION
Provides the APIs to connect all your tracker devices and to rapidly deploy your IoT
Connect Devices
solution.
Real-time Location Track your devices indoor and outdoor, see traces on a map, create geofences and
and Data get custom notifications.
Retrieve historical tracking data for analysis with data visualization tools such as
Historical data
charts, graphs, and heatmaps.
Features
HERE Tracking builds upon a set of objects and backend capabilities that facilitate working with IoT devices in an
open and flexible manner. Here's a summary of the main features:
Devices
Add devices to the cloud and configure in detail how they report their geolocation and enviromental data.
Positioning
Use WiFi, Cell and Bluetooth LE to determine position on devices without GPS or in areas where GPS is unavailable.
Shadows
Manage the configuration for your devices and access their reported geolocation and enviromental data.
Traces
Access current and historical data that a device collected.
Geofences
4Introduction
Create circular and polygonal geofences on the map that trigger notifications when a device enters or exits a
geofence.
Notifications
Receive notifications via webhook when devices enter or leave geofences.
5Devices
Devices
Devices record position, sensor readings, WiFi, Bluetooth or network cell measurements and send them to HERE
Tracking.
Devices authenticate to HERE Tracking using an OAuth 1.0 header generated from their unique deviceId and
deviceSecret .
Data sent by a device to HERE Tracking is not stored until the device is added to a user account. When a user adds a
device, the device is assigned a unique trackingId and the user gets secure access to the data generated by that
device via the trackingId .
A device can later be removed from the user account if it is sold or decommissioned. In this case, the trackingId is
dissociated from the device and the device can be added to another user account and assigned a new trackingId .
The original data will still be accessible to the original user but not the new data.
6Device Licenses
Device License
A deviceId and deviceSecret pair. Every device needs this in order to authenticate against HERE Tracking.
7Device Authentication
Authenticating a device
Every device must provide a valid access token when it sends telemetry to HERE Tracking. Tokens must be obtained
from HERE Tracking. A device must be added to a user account before it will be sent a valid access token.
HERE Tracking requires that you sign your requests for tokens. The signature method uses the OAuth 1.0 standard.
For more information on this standard, see the OAuth Core 1.0 specification.
IMPORTANT You must create a new signature for each token request to HERE Tracking. Signatures can only be
used once.
The process for generating a signed request is described in the API documentation.
8Telemetry
Telemetry
This is the data sent by the device to HERE Tracking. The data must be accompanied by a valid access token to both
authenticate and authorize data storage.
Telemetry can contain GPS position, WiFi, Bluetooth or cell measurements along with a payload of sensor
measurements and a timestamp specifying the time at which these measurements were taken.
Telemetry recorded in the past can be uploaded to enable recording of offline sensor readings and positions. If
historical telemetry is uploaded, it is compared against associated geofences and transitions are recorded but
notifications are not generated as they may be significantly out-of-date.
9Ingestion
Ingestion
A device can send its telemetry – GPS position, sensor readings, WiFi or Bluetooth scans – to HERE Tracking once it
has been provisioned with a license. If the device has not yet been added to a user account, the data will not be
stored.
IMPORTANT Devices should use this endpoint to send data to HERE Tracking and not any other endpoint.
10Positioning
Positioning
To have a position associated with a device, the request body must contain either a position or a scan object. If
both are provided, the scan is resolved to a position using the HERE Positioning API. The more accurate of the two
positions (provided and resolved) is used as the device's position.
For more details, see the HERE Positioning API documentation.
11Shadows
Shadows
Shadows provide an effective way to manage configurations for devices that are only intermittently online.
Shadows are stored in HERE Tracking and contain two states of a device's configuration: The reported state and
the desired state.
The reported state contains the telemetry that was sent by the device when it was last online.
The desired state contains the settings that will be sent to the device when it next comes online.
IMPORTANT Devices should not communicate directly with this service but should instead send telemetry to
the ingestion endpoint only.
Ideally, applications should only write to the desired configuration state and only read from reported
configuration state.
Example
A connected heater reports that the temperature of the room in which it is installed is 25°C. This value is stored in
the device's reported state.
Reported state
{
"reported": {
"payload": {
"temperature": 25.2
}
}
}
The facility management system wants the room temperature lowered and sets the desired value:
Reported state
{
"desired": {
"payload": {
"temperature": 21
}
}
}
The next time the device comes online, it will receive this desired state.
The device will then change the temperature of the room and update its shadow again
Reported state
{
"reported": {
"payload": {
"temperature": 21
12Shadows
}
}
}
13Traces
Traces
A device's trace is a record of its reported state through time. Every time telemetry is ingested, it is recorded along
with the timestamp provided with the telemetry. You can query traces based on date ranges.
14Geofences
Geofences
A geofence is a geographic boundary that you can define and associate with your devices. HERE Tracking can then
notify you when a device transitions into or out of a geofence.
Geofences can be circular or polygonal. Circular fences are defined by a centre geo-coordinate and a radius while
polygonal fences are defined as a set of geo-coordinates.
Once created, a geofence can be associated with a device. This association means that every time a location update
is received from the device, it will be compared to the area of geofence. If the device has transitioned from outside
the geofence to inside or vice versa, a transition event is recorded and HERE Tracking will generate a
notification .
15Transitions
Transitions
A transition event is created every time a device enters or exits an associated geofence. These events are stored in
the transition log.
This log also includes details of events where a device 'almost' crossed a geofence boundary. Device positions
determined through GPS, WiFi or other methods have a range of uncertainty about them. This uncertainty is
typically represented as a radius around the recorded point showing the accuracy of the position.
These are times when the accuracy radius reported around a device interesects with the geofence boundary but
where it is not possible to confirm what side of the geofence boundary the device is on. This returns those events
as well as total transitions.
Types of transitions
There are three types of transition event:
1. Transition to inside
The device and its accuracy radius are now completely enclosed in the geofence
2. Transition to outside
The device and its accuracy radius are now completely outside in the geofence
3. Boundary
The accuracy radius intersects with the geofence boundary.
The device is completely outside the geofence
16Transitions
The device position intersects the geofence and is probably outside
The device position intersects the geofence and is probably inside
The device is completely inside the geofence
17Transitions
18Notifications
Notifications
A webhook notification is created every time a device enters or exits an associated geofence.
Webhook
HERE Tracking can send a POST request to a specified URL containing details of the device location, the geofence
and whether it has entered or exited.
19Vendors
Vendor
Device licences can only be created by a vendor. A vendor is a user who has a developer plan (evaluation, free or
paid) with HERE that has been enabled for device licence creation. Plans can be enabled for device licence creation
via https://tracking.here.com or via your HERE support contact.
The vendor has no access to the data generated by the device as that is securely limited to the user account the
device has been added to.
20Creating a device licence
Creating a device licence
To create a new device licence, you must be a vendor. This means you have an appId with a valid evaluation
licence obtained through tracking.here.com. In HERE Tracking, vendors create the devices and the application
software but do not own the data created by the device.
NOTE: For trial purposes, there is nothing wrong with using the same HERE account as vendor and as user but in
standard practice, the vendor would create the device and sell it to the end-user.
Creating a licence
Prerequisites
A HERE account
A valid evaluation plan appId
Log in the vendor
curl -X POST \
https://tracking.api.here.com/users/v2/login \
-H 'Content-Type: application/json' \
-d '{
"email": "{vendorUserEmail}",
"password": "{vendorUserPassword}"
}'
This will return a HERE Account accessToken . In this guide, we will refer to this as the vendorToken .
Request one device licence
You may request one device license using this request
curl -X POST \
https://tracking.api.here.com/registry/v2/{appId}/one-device \
-H 'Authorization: Bearer {vendorToken}' \
-H 'Content-Type: application/json'
Request multiple device licences
Create device license job
curl -X POST \
https://tracking.api.here.com/registry/v2/{appId}/devices \
-H 'Authorization: Bearer {vendorToken}' \
-H 'Content-Type: application/json' \
-d '{
"count": 5
}'
This will return a jobId which can be used to track the progress of the licence creation. For a small number of
devices, this will be almost instantaneous. For evaluation, you can create a maximum of 10 device licences.
21Creating a device licence
Check job progress
curl -X GET \
'https://tracking.api.here.com/registry/v2/{jobId}/status' \
-H 'Authorization: Bearer {vendorToken}' \
-H 'Content-Type: application/json'
Retrieve licence
curl -X GET \
'https://tracking.api.here.com/registry/v2/{jobId}/results' \
-H 'Authorization: Bearer {vendorToken}' \
-H 'Content-Type: application/json'
22Preparing the device
Preparing the device
Prerequisites
At least one Device Licence – a deviceId and deviceSecret
By this point, you have a licence to send data to HERE Tracking. Now we need to set up a device to actually send the
data.
You have several options now depending on what kind of device you want to use.
NOTE: Even once a device has a licence installed, its data will not be saved in HERE Tracking until the device is
claimed by an end-user (see Claiming ownership of a device).
Android app
As a fast way for evaluating HERE Tracking, download the HERE Tracker android app from the Google Play Store.
This acts like a 'Virtual Tracker' and sends its data to HERE Tracking. The app can be configured to position itself
with WiFi, BLE, Cell, GPS or any combination of technologies.
Download
Launch
Enter licence
NOTE: This is a way to do rapid prototyping and evaluation. It is not intended as a way for clients to produce real
products.
Use HERE Tracking device firmware C library
HERE Tracking provides a C library and sample application via GitHub.
Follow the instructions in the project to install and use the sample application.
Use HERE Tracking ingestion APIs
You may build your own tracker firmware that collects telemetry data and then you use HERE Tracking ingestion
APIs to upload your ingestion data to HERE Tracking cloud.
23Claiming ownership of a device
Claiming ownership of a device
For the rest of this guide, we will deal with the end user and not the vendor. The user controls the device and can
access data created by the device.
In order to do that, the first step is to claim the device. This allows the device data to be saved in HERE Tracking.
Add a device to a user account
Prerequisites:
Valid deviceId and deviceSecret that have not yet been added to a user account
Valid user account
Log the user in
curl -X POST \
https://tracking.api.here.com/users/v2/login \
-H 'Content-Type: application/json' \
-d '{
"email": "{userEmail}",
"password": "{userPassword}"
}'
This will return an accessToken . In this guide, we will refer to this as the userToken .
Add the device to the user account
curl -X PUT \
https://tracking.api.here.com/registry/v2/devices/{deviceId} \
-H 'Authorization: Bearer {userToken}' \
-H 'Content-Type: application/json'
This will return a trackingId . This is the unique identifier associated with the data in HERE Tracking.
NOTE: This is different from the deviceId used in the licence. The deviceId is permanently associated with the
hardware, the trackingId is associated with the data. If the device is later sold or transferred, the deviceId
remains the same but the trackingId changes.
Verify the device is in the user's list of devices
curl -X GET \
https://tracking.api.here.com/users/v2/devices \
-H 'Authorization: Bearer {userToken}'
24Send data to the cloud
Send data to the cloud
Your user account now has access to the data reported by the device. The next step is for the device to report data.
If you are using one of the sample HERE Tracker applications (Android, C), you may already be seeing data in HERE
Tracking. The following examples show what those applications are doing and allow you to do it manually yourself.
Send data to HERE Tracking
Prerequisites
Valid deviceId and deviceSecret for a device that has been added to a user account
Log in device
Follow the documentation for details on how to generate a signed OAuth 1.0 request.
curl -X POST \
https://tracking.api.here.com/v2/token
-H 'Authorization: Bearer {signedRequest}'
You will receive an accessToken for the device. In this guide, we will refer to this as the trackingToken . If you
receive an error "412 Precondition Failed", it means the device has not been claimed by an end-user yet. See the
previous section for details on how to claim a device.
Send data
curl -X POST \
https://tracking.api.here.com/v2/ \
-H 'Authorization: Bearer {deviceToken}' \
-H 'Content-Type: application/json' \
-d '[{
"timestamp": 1529320151007,
"position": {
"lat": 52.5,
"lng": 13.4,
"alt": 1,
"accuracy": 10
}
}]'
You will receive the device's updated shadow.
25Process data in the cloud
Process data in the cloud
Create a geofence
Geofences can be circular (specified by a centre point and a radius) or polygonal (an array of coordinates).
curl -X POST \
'https://tracking.api.here.com/geofences/v2' \
-H 'authorization: Bearer {userToken}' \
-H 'content-type: application/json' \
-d '{
"type": "circle",
"definition": {
"center": {
"latitude": 52.5308398,
"longitude": 13.38490035
},
"radius": 100
}
}'
This will create a circular geofence and return the unique ID. At this point, the geofence isn't associated with any
device but it will be visible on the web dashboard.
You can also get a list of the IDs of geofences you previously created.
curl -X GET \
'https://tracking.api.here.com/geofences/v2/' \
-H 'authorization: Bearer {userToken}' \
-H 'content-type: application/json'
Associate geofence and device
Now that we have a device sending its location and a geofence around an area, we can associate one to the other.
This will cause a notification to be sent whenever this device transitions from outside-the-fence to inside-the-fence
or vice versa.
curl -X PUT \
https://tracking.api.here.com/geofence-associations/v2/{geofenceId}/{trackingId} \
-H 'authorization: Bearer {userToken}' \
-H 'content-type: application/json'
Send telemetry outside the fence then inside the fence
curl -X POST \
https://tracking.api.here.com/v2/ \
-H 'authorization: Bearer {deviceToken}' \
-H 'content-type: application/json' \
-d '[{
"timestamp": 1529436288264
"position": {
"alt": 107,
"accuracy": 1,
"lng": 0,
"lat": 60,
"altaccuracy": 1
}
26Process data in the cloud
}]'
curl -X POST \
https://tracking.api.here.com/v2/ \
-H 'authorization: Bearer {deviceToken}' \
-H 'content-type: application/json' \
-d '[{
"timestamp": 1529436303311
"position": {
"alt": 107,
"accuracy": 1,
"lng": 13.3848191,
"lat": 52.5308059,
"altaccuracy": 1
}
}]'
You can confirm the location of the updates using the web dashboard.
See a transition was recorded
All geofence transitions and near-transitions are recorded in the transition history.
curl -X GET \
https://tracking.api.here.com/transitions/v2/devices/{trackingId} \
-H 'authorization: Bearer {userToken}' \
-H 'content-type: application/json'
A near-transition is one where the accuracy radius of the position update provided overlaps with the geofence
boundary. In this case, it is not possible to say conclusively whether the device is on one side of the fence or the
other. These events don't generate webhook notifications but will be recorded and available through the API.
27Send data to the device
Send data to the device
You manage the device's configuration via its online Device Shadow. This is the online representation of the device
which contains its last known reported state and the configuration to be sent to the device.
When devices send data to the cloud, the response returned is a JSON object containing the values that differ
between the desired stateVersion and reported stateVersion of device shadow.
For example, if the device was already configured at stateVersion 0 which contains the following:
{
"payload": {
"led": "green",
"text": "online",
"threshold": 28
},
"system": {
"stateVersion": 0
}
}
and the new desired state configured by user is as follows:
{
"payload": {
"led": "blue",
"text": "active",
"threshold": 28
},
"system": {
"stateVersion": 1
}
}
and the device reported the following reported state:
{
"position": {},
"payload": {
"temperature": 25
},
"system": {
"stateVersion": 0
}
}
The response returned by the cloud will be:
{
"payload": {
"led": "blue",
"text": "active"
},
"system": {
"stateVersion": 1
}
}
28Send data to the device
The device can then set its internal state to match the desired state. It should also use the new stateVersion to
report all the upcoming states until it receives a newer version in the response.
NOTE: If the device doesn't send a stateVersion as below:
{
"position": {},
"payload": {
"temperature": 25
}
}
It will receive the entire desired state set by user and the latest stateVersion .
{
"payload": {
"led": "blue",
"text": "active",
"threshold": 28
},
"system": {
"stateVersion": 1
}
}
Set desired configuration
To set configuration on a device and save the values to the Device Shadow, Use HERE Tracking web application or
HERE Tracking shadows endpoint. Whenever you set new device configurations, the stateVersion of the device
shadow in HERE Tracking cloud is incremented. The next time the device synchronises with the cloud, it will receive
the configuration along with the new stateVersion .
curl -X POST \
https://tracking.api.here.com/shadows/v2/{deviceId} \
-H 'authorization: Bearer {userToken}' \
-H 'content-type: application/json' \
-d '{
"desired": {
"payload": {
"led": "red"
}
}
}'
29Optimize positioning result
Tips for Positioning Data Accuracy
Use the following tips to get the most accurate positioning response.
To ensure the best possible positioning result, provide high-quality measurements.
The result quality depends on the measurement freshness and correctness.
Your APIs for listing available WLANs may include some old or cached WLANs that are no longer relevant. If
such stale WLANs are included in a positioning request, the resulting location estimate may be inaccurate,
incorrect, or simply not available.
Filter out any old WLANs from the measurements and do not send them in your requests.
During cell handovers (from one cell to another) and during cell technology handovers (between 2G/3G/4G),
the cell parameters returned by external APIs may be temporarily incoherent. For example, the cell identifier
may be measured from the new cell, but the LAC code may still be the one for the old cell. Beware of such
corrupt measurements, as they may result in incorrect location estimates. They may also even prevent the
service from being able to determine a position.
You can compare several subsequent measurements to better detect such anomalies or recheck the parameter
values a few seconds after a cell change is detected.
During an ongoing call or data transfer, the cell identifier reported by your APIs may be stale. The values may
identify the cell in which the call started, instead of the current cell, when the device has moved during the
call.
In such cases, the location estimate can be incorrect. You can detect these situations on the client side by
checking the Radio Resource Control State.
Include cell measurements in a WLAN-based positioning requests to get better positioning results.
30Optimize indoor positioning result
Tips for Indoor Positioning Data Accuracy
Use the following tips to get the most accurate indoor positioning response.
WiFi
The objective of WiFi scanning is to capture all the WiFi APs (Access Point) observable by the device.
Limiting the number of WiFi APs in the object sent to server in any way is highly undesirable.
Indoor Positioning specifics
Rx level is mandatory
About timestamps
Including measurement timestamps to the object sent to server is highly recommended.
If measurement timestamps are available in the device, we recommend including up to a 10-second
tail of measurements to the object sent to server.
If measurement timestamps are unavailable in the device, only include the instantaneous
measurements (no tail) to the object sent to server.
Bluetooth
The objective of Bluetooth scanning is to capture all the Eddystone/iBeacon Bluetooth beacons observable by
the device.
Limiting the number of beacons in the object sent to server in any way is highly undesirable.
Only include Eddystone and/or iBeacon beacons to the object sent to server.
Always include one of {MAC Address, EddystoneID, iBeaconID}. Prefer MAC Address.
About timestamps
Including measurement timestamps to the object sent to server is highly recommended.
If measurement timestamps are available in the device, we recommend including up to a 10-second tail of
measurements to the object sent to server. In this case, make 500ms scans continuously.
If measurement timestamps are unavailable in the device, only include the instantaneous measurements
(no tail) to the object sent to server. For an instantaneous measurement make a single 3000ms scan.
31You can also read
