Critical Asset Sensor Quick Start

Verizon Critical Asset Sensor Quick Start Guide

{{toc}}

Overview

The Verizon Critical Asset Sensor contains a variety of sensors that make it a great solution for many use cases. The suite of environmental sensors includes:

  • GPS location
  • temperature
  • pressure
  • humidity
  • light
  • 3-axis accelerometer to detect shock and vibration
  • gyroscope (tilt)

This page contains instructions on how to set the device reporting frequency and configure streaming.

Set reporting frequency and GPS mode

The default configuration of the Critical Asset Sensor is to read and report all sensors every hour. You can change this to occur more frequently or less often, depending on your needs. Less frequent reporting provides greater battery life and uses less data.

Read/Reporting Frequency “frequency” value
15 minutes High
1 hour Medium
4 hours Low
24 hours Ultra Low

The GPS receiver in the Critical Asset Sensor is enabled by default. If you don’t need to track the device’s location, you can disable the GPS receiver to provide greater battery life.

GPS Receiver “location_mode” value
Enabled. Location is sent with other sensor data. gps
Disabled disable

Use POST /devices/configurations/actions/set to change the reporting frequency and GPS mode. Note that the values are case sensitive.

curl -X POST https://core.thingspace.verizon.com/api/v1/devices/configuration/actions/set \
  -H 'Authorization: Bearer efa34799723e58b1cf71fceaed941803' \
  -H 'VZ-M2M-Token: 7c5bc6e4-50f9-445d-8d6d-8fa0e108dea1' \
  -H 'Content-Type: application/json' \
  -d '{
  "accountidentifier": {"billingaccountid":"1223334444-00001" },
  "resourceidentifier": {"imei": 864508030084799 },
  "configuration":{"frequency":"High", "location_mode":"gps"}
}'

NOTE: ThingSpace cannot send configuration change requests immediately because Critical Asset Sensors sleep during the “frequency” period and are not reachable until the specified interval elapses. When the frequency period has elapsed, the device wakes up to read sensors and send data to ThingSpace, and ThingSpace is able to send configuration changes to the device. The device then goes back to sleep for the period of time set by the (new) configuration.

Once you send a POST /devices/actions/configuration/set request for a device, you cannot cancel or overwrite it. After the device wakes up and gets the configuration change request, you can send another request, if needed, and that request will be queued for when the device wakes up again.

Set up streaming

You can stream data from ThingSpace to various endpoints, such as to accounts with cloud service providers. This section first describes how to set up generic streaming, and then how to configure ThingSpace to stream to an AWS account.

Stream to a host:port endpoint

Streaming requires a target resource to define the endpoint, and a subscription resource to define what is streamed to the target.

Create a target to define the streaming endpoint

A target resource defines an endpoint that can be used for streaming. After creating a target, use the target ID from the response when you create a subscription to set up a data stream.

Use a POST /targets request to create a target, with these parameters:

  • billingaccountid (required) The ID of the billing account that is making the request, in the format 1234567890-12345.
  • name (optional) Name of the target. Can be used when querying for the target later.
  • description (optional) Descriptive information about the target.
  • addressscheme (required) The transport format. Must be streamrest for streaming to a host:port endpoint.
  • address (required) The endpoint for data streams. The format is usually a host:port value.
Sample request
curl -X POST https://thingspace.verizon.com/api/cc/v1/targets \
  -H 'authorization: Bearer d13c10f356e65b36ad5ea89d86f12247' \
  -H 'vz-m2m-token: 32a61f4b-575a-4204-92d2-9460891fceaf' \
  -H 'content-type: application/json' \
  -d '{
    "accountidentifier":{"billingaccountid": "1223334444-00001"},
    "address":"https://mysite.com:1536/streaming",
    "addressscheme":"streamrest",
    "name":"Stream Target"
}'
Sample response
{
  "address": "https://mysite.com:1536/streaming",
  "addressscheme": "streamrest",
  "createdon": "2019-02-07T04:57:51.322Z",
  "id": "aef1d746-16b1-689b-ee9f-45c34960a427",
  "kind": "ts.target",
  "lastupdated": "2019-02-07T04:57:51.322Z",
  "name": "Stream Target",
  "version": "1.0",
  "versionid": "ebed2772-2a94-11e9-aac7-02420a40130c"
}

You will need the ID of the target when you create a subscription.

Create a subscription

A subscription defines a streaming channel that sends data from devices in the account to an endpoint defined in a target resource. Note the requirements for these values:

  • email is the address to which any error reports will be delivered.
  • streamkind must be ts.event to stream all device data.
  • targetid must be the ID of the target that was created to define the endpoint.
  • name is not required, but can be used when querying for the subscription later.
Sample request
curl -X POST https://thingspace.verizon.com/api/cc/v1/subscriptions \
  -H 'authorization: Bearer d13c10f356e65b36ad5ea89d86f12247' \
  -H 'vz-m2m-token: 32a61f4b-575a-4204-92d2-9460891fceaf' \
  -H 'content-type: application/json' \
  -d '{
    "accountidentifier":{"billingaccountid":"1223334444-00001"},
    "email":"me@mycompany.com",
    "streamkind":"ts.event",
    "targetid":"aef1d746-16b1-689b-ee9f-45c34960a427",
    "name":"subscription1"
}'
Sample response
{
  "configurationfailures": 0,
  "createdon": "2019-01-28T03:18:34.323Z",
  "email": "me@mycompany.com",
  "id": "b8719618-bf7e-6b0a-e40a-5939d00b17a1",
  "kind": "ts.subscription",
  "laststreamingstatus": "",
  "laststreamingtime": "0001-01-01T00:00:00Z",
  "lastupdated": "2019-01-28T03:18:34.323Z",
  "name": "subscription1",
  "networkfailures": 0,
  "streamfailures": 0,
  "streamkind": "ts.event",
  "targetid": "aef1d746-16b1-689b-ee9f-45c34960a427",
  "version": "1.0",
  "versionid": "6525b340-22ab-11e9-ac5d-02420a40130c"
}

Streaming to AWS

Generate an External ID

ThingSpace uses an external ID for increased security when streaming to AWS. You generate the ID in ThingSpace, then use it when configuring an AWS account and a ThingSpace target resource.

Sample request
curl -X POST https://thingspace.verizon.com/api/cc/v1/targets/actions/newextid \
  -H 'authorization: Bearer d13c10f356e65b36ad5ea89d86f12247' \
  -H 'vz-m2m-token: 32a61f4b-575a-4204-92d2-9460891fceaf' \
  -H 'content-type: application/json' \
  -d '{"accountidentifier": {"billingaccountid":"1223334444-00001"}}'
Sample response
{
  "externalid": "XsosZrEEkfPuR3aGOk2iHIr6tXN275ioJF6bezIrQB9EbzpTRep8J7RmV7HQ=="
}

Configure AWS Account

Follow these steps to allow ThingSpace to send device data to your AWS account.

  1. Sign in to AWS.
  2. Browse to IAM (Identity and Access Management).
  3. From the IAM Dashboard, click Roles in the left column.
  4. Click Create role.
  5. Select Another AWS account as the type of trusted identity.
  6. Enter the Verizon Account ID, which is 675479154635.
  7. Check the box to Require external ID and paste in the ID generated in section 6.3.1.
  8. Click Next: Permissions.
  9. Select these permissions:
    • AWSIotDataAccess
    • AWSIoTFullAccess
    • AWSIoTThingsRegistration
  10. Click Next: Tags.
  11. No AWS tags are required. Click Next: Review.
  12. Enter a name for the role (for example, “ThingSpace”). 
  13. Click Create Role.

AWS will display the role summary page. You will need the Role ARN from that page when you create a target in ThingSpace.

Create a target for AWS streaming

A target resource defines an endpoint that can be used for streaming. After creating a target, use the target ID from the response when you create a subscription to set up a data stream.

Note the requirements for these values to stream to AWS:

  • addressscheme must be “streamawsiot”.
  • address is the ARN provided by AWS for the role created in the previous step.
  • region is the AWS region where your application connects to AWS IoT services. See AWS Regions and Endpoints for a table of regions for the AWS IoT Core service. Note that Things and data from one region will not be visible in another region.
  • externalidis the long string generated in section 6.3.1.
  • name (and description) are not required, but resource names can be used to query for resources later.
Sample request
 curl -X PUT \
  https://thingspace.verizon.com/api/v1/targets \
  -H 'authorization: Bearer d13c10f356e65b36ad5ea89d86f12247' \
  -H 'vz-m2m-token: 32a61f4b-575a-4204-92d2-9460891fceaf' \
  -H 'content-type: application/json'
  -d '{
    "accountidentifier":{"billingaccountid": "1223334444-00001"},
    "name":"AWS target",
    "description":"description",
    "addressscheme":"streamawsiot",
    "address":"arn:aws:iam::15625542789:role/ThingSpace",
    "externalid":"XsosZrEEkfPuR3aGOk2iHIr6tXN275ioJF6bezIrQB9EbzpTRep8J7RmV7HQ=="
}'
Sample response
{
    "address": "arn:aws:iam::15625542789:role/ThingSpace",
    "addressscheme": "streamawsiot",
    "createdon": "2019-01-28T02:51:54.941Z",
    "externalid": "XsosZrEEkfPuR3aGOk2iHIr6tXN275ioJF6bezIrQB9EbzpTRep8J7RmV7HQ==",
    "id": "ee113948-8f03-67e0-f42a-8a33cbb6ce34",
    "kind": "ts.target",
    "lastupdated": "2019-01-28T02:51:54.941Z",
    "name": "AWS target",
    "version": "1.0",
    "versionid": "abd77755-22a7-11e9-a2ee-02420a46120b"
}

You will need the highlighted ID of the target when you create a subscription.

Create a subscription

A subscription defines a streaming channel that sends data from devices in the account to an endpoint defined in a target resource. Note the requirements for these values:

  • email is the address to which any error reports will be delivered.
  • streamkind can be ts.event to stream all device data. It can also be ts.event.diagnostics or ts.event.security to only receive events of those specific types.
  • targetid must be the ID of the target that was created to define the endpoint.
  • name is not required, but can be used when querying for the subscription later.
Sample request
curl -X POST https://thingspace.verizon.com/api/cc/v1/subscriptions \
  -H 'authorization: Bearer d13c10f356e65b36ad5ea89d86f12247' \
  -H 'vz-m2m-token: 32a61f4b-575a-4204-92d2-9460891fceaf' \
  -H 'content-type: application/json' \
  -d '{
    "accountidentifier":{"billingaccountid":"1223334444-00001"},
    "email":"me@mycompany.com",
    "streamkind":"ts.event",
    "targetid":"ee113948-8f03-67e0-f42a-8a33cbb6ce34",
    "name":"Account-level subscription"
}'
Sample response
{
  "configurationfailures": 0,
  "createdon": "2019-01-28T03:18:34.323Z",
  "email": "me@mycompany.com",
  "id": "b8719618-bf7e-6b0a-e40a-5939d00b17a1",
  "kind": "ts.subscription",
  "laststreamingstatus": "",
  "laststreamingtime": "0001-01-01T00:00:00Z",
  "lastupdated": "2019-01-28T03:18:34.323Z",
  "name": "Account-level subscription",
  "networkfailures": 0,
  "streamfailures": 0,
  "streamkind": "ts.event",
  "targetid": "ee113948-8f03-67e0-f42a-8a33cbb6ce34",
  "version": "1.0",
  "versionid": "6525b340-22ab-11e9-ac5d-02420a40130c"
}

Viewing Data in AWS

After AWS and ThingSpace are set up as described on this page, ThingSpace registers devices in the account as “things” in your AWS account, and streams data from those devices to the AWS account.

  • Go to the IoT Core page to see a summary of IoT traffic.
  • Click Manage > Things to see things created by ThingSpace (and from other sources). The names of ThingSpace Things are a device identifier (such as the IMEI) prefaced by “ts_“, such as ts_864508030084979.
  • Click a Thing’s name to see more information about that Thing.
  • Click Shadow while viewing a Thing to see the latest data values from the Thing. Critical Asset Sensor values will look similar to this:
{
  "reported": {
    "temperature": "20.7",
    "humidity": "36",
    "light": "0",
    "pressure": "896",
    "battery": "100",
    "acceleration": {
      "x": "0.0133",
      "y": "-1.0394",
      "z": "-0.0328"
    },
    "orientation": {
      "motionInX": "268.0",
      "motionInY": "0.0",
      "motionInZ": "0.0"
    },
    "signalStrength": "-58"
  }
}

Interpreting Sensor Values

See the Critical Asset Sensor Technical Guide for a description of the different sensor readings, including the units of measure and value ranges.