Cloud-to-cloud connectors

The Tracking API supports making a cloud-to-cloud connection to the SigFox device cloud. The connection is formed by creating a cloud-to-cloud connector which receives reports for devices in a SigFox account from the SigFox cloud, automatically creating virtual devices in the Tracking backend and transforming SigFox device reports into the Tracking API ingestions, thus enabling the SigFox devices to be tracked using the Tracking backend.

Prerequisities

• A valid HERE account user
• A valid Tracking project (along with a Project Admin role)
• SigFox account and devices

Log 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 a HERE Account accessToken.

Creating a SigFox cloud-to-cloud connector

Retrieve available cloud-to-cloud drivers

curl -X GET \
  https://tracking.api.here.com/c2c/v4/drivers \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json'

This will return an array of available cloud-to-cloud drivers. The driver for SigFox cloud has provider sigfox and driverId DRV-bf8642c2-f163-40f9-863c-b2ea85d6378c.

Create a cloud-to-cloud connector

To create a cloud-to-cloud connector, send a POST request to the c2c endpoint. If you are a member of multiple projects, please specify the project ID in the projectId query parameter.

The externalCloudInfo object in the request body must contain the SigFox API access credentials and device type id for the SigFox devices you want to track. Note that these are not your SigFox account login credentials but API access credentials for your SigFox device group.

curl -X POST \
  https://tracking.api.here.com/c2c/v4/connectors?projectId=`projectId` \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{
      "name": "Name for C2C connector",
      "description": "Description for C2C connector",
      "externalCloudInfo": {
        "login": "sigfoxApiAccessLogin",
        "password": "sigfoxApiAccessPassword",
        "deviceType": "sigfoxDeviceTypeId"
      },
      "driverId": "DRV-bf8642c2-f163-40f9-863c-b2ea85d6378c",
      "refreshIntervalS": 600,
      "enabled": true
}'

The created connector will be executed periodically every refreshIntervalS seconds, and this is the interval at which the device reports will be processed.

Retrieve list of cloud-to-cloud connectors

curl -X GET \
  https://tracking.api.here.com/c2c/v4/connectors?projectId=`projectId` \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json'

This will return an array of cloud-to-cloud connectors created for your project. If you are a member of multiple projects, please specify the project ID in the projectId query parameter.

See external device data in the cloud

Retrieve list of external devices

curl -X GET \
  https://tracking.api.here.com/c2c/v4/connectors/{connectorId}/ext-devices \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json'

This will return an array of external devices registered for the connector. The externalDeviceId in the response is the device ID in the external cloud and it is used as the virtual device externalId together with the project's appId when identifying devices in the Tracking API.

Shadows and traces of the external devices can be queried in the same way as for the physical devices.

Retrieve the external device shadow

curl -X GET \
  'https://tracking.api.here.com/shadows/v2/{externalDeviceId}?appId=`appId`' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'content-type: application/json'

This will return the external device's most recent reported and desired shadows.

Retrieve the external device traces

curl -X GET \
  'https://tracking.api.here.com/traces/v2/{externalDeviceId}?appId=`appId`' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'content-type: application/json'

This will return the external device's traces.

Deleting a cloud-to-cloud connector

Deleting a cloud-to-cloud connector will not remove the external devices from the Tracking backend.

curl -X DELETE \
  https://tracking.api.here.com/c2c/v4/connectors/{connectorId} \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json'