Management and Data Reporting for Electronic Temperature Sensors - Developer Guide

 

Contents

Management and Data Reporting for Electronic Temperature Sensors - Developer Guide

Overview

Audience

Workflow

Getting Started

API Authentication

Enroll Devices

List the Sensors

Associate a Sensor with a Task

Sorting, Filtering, and Pagination

How To:

Perform a Sample Task

Display full event record for a Task ID

Overview

The Management for Electronic Temperature Sensor APIs provide the ability to configure Sensors for use. This includes Enrolling Sensors, creating Tasks, Configuring Sensors, adding Sensors to Tasks, associating Assets IDs with tasks and stopping Tasks.

The Data Reporting for Electronic Temperature Sensor APIs are designed to provide data for after Task reports.  Every Sensor reading and monitored Event that occurred the use of the Sensor assigned Tasks are recorded and stored for 7 years. These APIs allow you to view that history. Useful for reconciliation and final disposition determinations. This set of APIs are designed to provide data that can be used to create post-Task reports. 

The log request is a raw request to the long-term data storage system.  Every temperature reading captured by the Sensor is listed as a separate event.  This means that every Sensor can have many  thousands of Events associated with it. The system also captures other major events in the use of the Sensor.  The APIs provide means of filtering and paginating this data. 

Audience

This guide is for developers of applications that integrate data from the Zebra Sensor.

Workflow

The table below describes the steps needed to achieve a simple use case for using Zebra Temperature Sensors.

Step	API	Comments
Enroll the Sensor	POST /devices/sensor-enrollments	Use the serial number on the Sensor.
Create a Task	POST /environmental/tasks	Configure the temperature recording thresholds and start method. Repeat for each Task.
Associate the Sensor with the Task	POST /environmental/tasks/{taskId)/sensors	Use the Task ID returned when the Task was created.  Repeat for each sensor.
Verify sensors associated with a tenant	GET /devices/environmental-sensors	Optional filters are available.
Stop the Task	POST /environmental/tasks/{taskId}/stop	Stop recording temperatures.
Retrieve data for the Task	GET /environmental/tasks/{taskId}	Use the Task ID returned when the Task was created.
Retrieve data for all Tasks	GET /environmental/tasks	Optional filters are available.
Retrieve alarms for the Task	GET /environmental/tasks/{taskId}/alarms	Use the Task ID returned when the Task was created.
Display the Event record for the Task	GET /data/environmental/tasks/{taskId}/log	Data may not be immediately available.

Getting Started

API Authentication

Access to all Zebra APIs need to be authenticated. There are several methods available for Authentication with Zebra APIs.   Once you have been granted access to the Electronic Temperature Sensor APIs, you will find a client key on [JJ1] your App page of the Zebra Developer Portal. It is very important that you keep this key safe and secure from your code, repositories, or others.  Do not give or share your full key with anyone.

Simple Key

Most of the APIs can be authenticated by just providing the client key in the headers under the ‘apikey’ parameter. This is ONLY recommended for initial testing and Proof of Concept work.  This is the most insecure method and should never be used outside of the developer’s control[JJ2] .

1. Copy the ‘Consumer Key’ by clicking the  button.
2. To verify, Go to the Api page that you want to work with and,
3. Click the Authorize button

 

4. Paste the client key into the box labeled the ApiKeyAuth text box and click ‘Authorize’.

Note:  This key is sometimes referred to by several names: App key, API key, consumer key, or client key.  They all refer to the same thing. We will refer to it as a client key in this document.

OAuth – Client Credentials – not available for early access

An OAuth bearer token can be created by providing the client key and client secret.  You will find a client key and secret on the App page of the Zebra Developer Portal.  All Zebra Bearer tokens last for one hour but can be refreshed using the previous token.  Client Credentials grant type should only be used from a client app’s server, never directly from a client app directly as this may provide open access to client keys.

Generate token: https://developer.zebra.com/apis/oauth-client-credentials#/Client%20Credentials%20Grant%20Type/Generate%20Access%20Token%20Client%20Credentials [JJ2] [JJ3] 

To verify, call the API above and get a token.  If the token returns with ‘abc123’, then the value you provide to the Authorization

OAuth – Authorization Code – not available for early access

The primary method for creating a Bearer token specific to customers, is the Authorization Code grant type.  This is the standard 3-legged OAuth used in many web applications.  It is considered one of the most secure methods of getting a token.  All Zebra Bearer tokens last for one hour but can be refreshed using the previous token. 

Authorization code grant type is a multi-step process.  First you redirect to the IDP login and provide a redirect URI.  After the customer logs in, the IDP will send the authorization code to the client app URI.  Authorization codes last for 10 seconds.  The client app calls the token API with the code to get a bearer token.

Generate Token: https://developer.zebra.com/apis/oauth-authorization-code-0

Enroll Devices

Pre-Requisites

1. A ZB200 bridge
2. Access to an ethernet port and ethernet cable
3. One or more ZS300 temperature Sensors
4. An apikey

Procedure

1. Navigate to the Zebra Developer portal

https://developer.zebra.com

2. Login to the portal.
3. Navigate to the Management for Electronic Temperature Sensors API page.
4. Click the green Authorize button and enter your apikey.
5. Click Close.
6. Expand the POST /devices/sensor-enrollments method.
7. Click the Try it out button.
8. Enter the serial number of the ZS300 temperature sensor in the JSON body (replacing the word string).

See the image for the location of the serial number.

9. Click the Execute button.

A successful response displays with the HTTP Status Code 200.

The response body is an empty JSON body.

The device is scheduled to be enrolled.

10. Hold down the button on the front of the sensor until the amber LED blinks.

After about 1 or 2 minutes the device is enrolled.

Post-Requisites:

Proceed with Listing the Sensors.

List the Sensors

Pre-Requisites

1. At least one Sensor has been Enrolled.

Procedure

1. Navigate to the Management for Electronic Temperature Sensors API page.
2. Click the green Authorize button and enter your apikey.
3. Click Close.
4. Expand the GET /devices/environmental-sensors method.
5. Click the Try it out out button.
6. Enter 0 in the page parameter.
7. Enter 1 in the size parameter.

If you have more than one Sensor enrolled, enter a larger size parameter.

8. Enter the serial number of the Sensor in the text filter parameter.

9. Click Execute.

If successful, a response body with an HTTP Status Code of 200 is returned.

A JSON body is included in the response which contains details of the currently enrolled Sensor.

1. {
2.   "sensors": [
3.     {
4.       "id": "83f87911-2184-4f26-91c5-83f87911c1b4",
5.       "mac_address": "01757E1A0001",
6.       "serial_number": "ABC123456789",
7.       "model": "ZS300-10001-0001",
8.       "manufacturer": "Zebra Technologies",
9.       "hardware_revision": "2",
10.       "firmware_revision": "D01.0.0.712",
11.       "battery_level": 99,
12.       "name": "ZS300_DLJ222902256",
13.       "status": "SENSOR_STATUS_STOPPED",
14.       "alarm_count": 0,
15.       "first_seen": "2022-11-04T19:42:27.168719Z",
16.       "certificate_url": "https://storage.googleapis.com/spg-zpc-p-envirovue-certs/certificates/Z…",
17.       "most_recent": {
18.         "task_id": "abe2c7d0-a8f8-4017-8958-abe2c7d0204f",
19.         "sensor_task_id": "202ac1cf-3b29-463d-964b-202ac1cf2092",
20.         "sensor_task_status": "SENSOR_TASK_STATUS_COMPLETED"
21.       },
22.       "requested": {},
23.       "certificate_type": "CERTIFICATE_TYPE_CONFORMANCE"
24.     }
25.   ],
26.   "page_response": {
27.     "total_elements": "1",
28.     "size": 1,
29.     "total_pages": 1
30.   }
31. }

Post-Requisites

1. Save the ID of the Sensor for the next step.

Associate a Sensor with a Task

Pre-Requisite

1. The ID of an enrolled Sensor is available

Procedure

1. Navigate to the Management for Electronic Temperature Sensors API page.
2. Click the green Authorize button and enter your apikey.
3. Click Close.
4. Expand the POST /environmental/tasks method.
5. Click the Try it out button.
6. Enter the sample JSON in the Request Object box.

1. {
2.     "task_from_details": {
3.         "task_details": {
4.             "name": "My Task 1",
5.             "interval_seconds": 15,
6.             "loop_reads": true,
7.             "start_immediately": {},
8.             "sensor_type": "SENSOR_TYPE_TEMPERATURE",
9.             "alarm_low_temp": 15,
10.             "alarm_high_temp": 30,
11.             "low_duration_seconds": 30,
12.             "high_duration_seconds": 30
13.         }
14.     }
15. }

7. Click Execute.

A successful response with an HTTP Status Code of 200 is returned.

The task ID is returned in the response body.

7. {
8.   "id": "abe2c7d0-a8f8-4017-8958-abe2c7d0204f"
9. }
10. Expand the POST /environmental/tasks/{taskId}/sensors method.
11. Click the Try it out button.
12. Enter the task ID just returned in the taskId path parameter field.
13. Enter the sensor ID that was returned from Listing the Sensors in the sensor ID array in the Request Object box.
14. Click Execute.

A response is returned with an HTTP Status code of 200.

A JSON object with the sensor_id and sensor_task_id association is returned as shown below.

1. {
2.   "associated_sensors": [
3.     {
4.       "sensor_id": "83f87911-2184-4f26-91c5-83f87911c1b4",
5.       "sensor_task_id": "abe2c7d0-a8f8-4017-8958-abe2c7d0204f"
6.     }
7.   ]
8. }

Sorting, Filtering, and Pagination

Pagination for the Data Reporting for Electronic Temperature Sensors

The Sense-Events services use token-based pagination due to the potentially very large number of results.    The default page size is 100.  The way this works is you request the first page of content and optionally request a size (number of sense events) to return.  Responses will also include a token for the next page.  Use this token in the next request, optionally with a size, to get the next set of event data.

How To:

Perform a Sample Task

Pre-Requisites

1. One or more Sensors have been Enrolled.
2. A Task has been created.
3. One or more Sensors have associated with a Task.

Procedure

1. Repeat the List the Sensors procedure.
2. Note the status field of the Sensor is SENSOR_STATUS_STOPPED.
3. Press the button on the Sensor and hold for ten seconds until the LED blinks orange.

After the sensor LED blinks green, the Task has started.

Note: If theSsensor LED does not blink green, move the Sensor is closer to the bridge.

If you repeat the List the Sensors procedure again, the status changes to SENSOR_STATUS_ACTIVE.

4. Allow the Task to run for at least several minutes.
5. Move the Sensor around to different temperature conditions.
6. After several minutes, stop the Task by expanding the POST /environmental/tasks/{taskId}/stop
7. Click the Try it out button.
8. Enter the taskId in the path parameter.

9. Click Execute.

A response is returned with an HTTP Status Code of 200.

The task is scheduled to stop.

When all sensors associated with the task are within range of the bridge, then the task is stopped.

1. {
2.   "task": {
3.     "id": "abe2c7d0-a8f8-4017-8958-abe2c7d0204f",
4.     "sensor_count": "1",
5.     "status": "TASK_STATUS_STOP_PENDING",
6.     "sensor_task_status_overview": {
7.       "stop_pending": "1"
8.     },
9.     "started": "2022-11-04T20:22:33.303659Z",
10.     "taskDetails": {
11.       "name": "Ryan Task 1",
12.       "created": "2022-11-04T20:10:06.083344Z",
13.       "updated": "2022-11-04T20:30:10.762285Z",
14.       "interval_minutes": 0,
15.       "interval_seconds": 15,
16.       "loop_reads": true,
17.       "start_immediately": {},
18.       "sensor_type": "SENSOR_TYPE_TEMPERATURE",
19.       "alarm_low_temp": 15,
20.       "alarm_high_temp": 30,
21.       "low_duration_seconds": 30,
22.       "high_duration_seconds": 30
23.     },
24.     "alarm_count": "0"
25.   }
26. }

10. Repeat List the Sensors  procedure to verify that:
    
    1. The status field has returned to the SENSOR_STATUS_STOPPED status.
    2. The sensor task status is SENSOR_TASK_STATUS_COMPLETED.

Display full event record for a Task ID

This use case is to enable developers to create detailed reports based on the full set of data from a task.  The API for this is the Data Reporting for Electronic Temperature Sensors.  You first need to get an authorization token using one of the authorization methods above.   

Using the Developer Portal Interactive Documentation

2. Get your client key from the App page See Authentication- Simple Key
3. Go to the Documentation page on the Developer Portal. https://developer.zebra.com/apis/analytics-and-reporting-temperature
4. Click the Authorize button.

5. Paste the client key into the box labeled the ApiKeyAuth text box and click ‘Authorize’.

6. Select the /tasks/{taskId}/sense-events endpoint to drop down the documentation.
7. Click ‘Try it out’
8. Enter a Task ID
9. Click ‘Execute’

10. Verify the data response is similar to the response below.
    1. {
    2.   [
    3.     "type": "beacon",
    4.     "event": {
    5.       "id": "6359fcb8-96a0-461c-90b1-07dbb002c063",
    6.       "timestamp": 1633359112806,
    7.       "deviceId": "bridge-id_or_phone-id",
    8.       "data": {
    9.         "format": "beacon",
    10.         "id": "sensormac",
    11.         "value": "-2.06",
    12.         "rssi": -51
    13.       },
    14.       "analytics": {
    15.         "recordedTimestamp": 1633359112806,
    16.         "resourceId": "bridge-id_or_phone-id",
    17.         "tenant": "my_tenant",
    18.         "timestamp": 1633359112806,
    19.         "meta": "{\"taskId\":\"067e2b5e-0f70-4010-8245-28361008cca4\"}"
    20.       },
    21.       "decode": {
    22.         "temperature": {
    23.           "alert": true,
    24.           "deviation": 0.3,
    25.           "format": "celsius",
    26.           "taskId": "task id",
    27.           "sample": -2.06
    28.         }
    29.       }
    30.     }
        
        1.   ]
    31. }

Using an API test tool

1. Now go to your favorite API test tool.  The example below is using Postman, but  other tools can be used as well.
2. Download the Yaml file from the Developer Portal

3. Import the Yaml file as a test suite

4. Modify the taskID to be a valid task you created. Unclick the startTime and endTime.

5. Go to the Headers tab and enter the Key ‘apikey’ and Value ‘your api key from step 1'.
6. Click Send
7. Verify the Response is the same as the response you received in step 9.
8. Modify the startTime and endTime dates as desired to filter the results within a time range.

 

Application Integration

9. In Postman, click the Code menu and select the language for your application.

10. You can now copy and paste this into your application code for complete integration.