SmartSense data API

SmartSense provides a set of endpoints for gathering asset and sensor data programmatically. SmartSense organizes devices, sensors, and their readings into logical units referred to as assets. Let’s go over some definitions below.

Definitions

• Asset – An asset is a logical abstraction of something that is being monitored. A common example is a fridge or a freezer.
   
• Sensor Reading – A sensor reading is a figure or amount of data that is based on input from a sensor, such as information related to temperature or humidity.
   
• Sensor Point – A sensor point is a logical abstraction for what is being monitored. A fridge asset, for example, could have a temperature and a humidity sensor point.
  
  Sensor points cannot be moved between assets and can only have one sensor associated with it at a time.
   
• Sensor – A sensor is a device that measures physical occurrences such as the current temperature or humidity. At SmartSense, a sensor gets attached to a sensor point to link its data to an asset.
  
  A sensor is also attached to a singular device, never more than one.
  
  Example: A store has a fridge and an asset in SmartSense. The temperature and humidity in the fridge must be monitored, so the asset has two sensor points, one for temperature and one for humidity.
  
  Inside the fridge is a device with a temperature and humidity sensor attached. At SmartSense, these sensors get linked with the asset's sensor points. If the Device in the fridge gets replaced with a new device and sensors, the new sensors would be associated with the same sensor points on the asset in SmartSense.
  
  Querying the readings for the fridge's sensor points would show the readings from the first set of sensors for the times when they were attached to the sensor points, and the new sensors after being attached.
   
• Device – Devices communicate data from the sensors to the SmartSense cloud, and a sensor must be connected to a device to properly measure a reading.

Data Specific Types

The SmartSense Data API defines the following types:

Dates

Parameters of type date should be sent to (and are sent from) the service as a combined date and time in ISO 8601 format. Time zone information must be included or the results of the API call are not defined.

 

Note: All dates returned by the service are in UTC.

readingDate

readingDate specifies the point in time a reading was captured by a sensor or device, e.g., a temperature sensor recorded a temperature of 32.45°F on Friday, January 15th at 3:17 pm, UTC.

 

processedDate

processedDate specifies the point in time when a reading was processed by SmartSense.

Example: An external temperature sensor, attached to a device, records a temperature of 32.45°F on Friday, January 15th at 3:17 pm, UTC. Due to an interruption in cellular service, the device is unable to send the reading to SmartSense for five minutes. Thus, the reading would have a readingDate of 3:17 pm, but a processedDate of 3:22 pm.

Applications using this API to capture all readings processed by SmartSense should use the processedAfterDate filter to request new readings since the last request (see Synchronizing Readings).

 

lastActivityDate

lastActivityDate specifies the time a device or sensor last contacted SmartSense. If the device has never contacted SmartSense this field will be null.
 

Numbers
 

DeviceId

The deviceId field is a 20-digit number that is converted to a string and transmitted. It is converted to a string to ease interoperability.

 

Power Reading Values

A device reading type of Power indicates the status of a device's power source. Values range from 0 to 10 for battery-only devices (e.g., Z-Point Wireless Sensor). For AC-powered devices with battery backup, the values range from 16 to 26 when the device is plugged in and 0 to 10 when not plugged in. A value of 16 indicates AC power only while a value higher than 16 would indicate AC power plus some battery backup.

 

Signal Strength Reading Values

A device reading type of Signal Strength is a normalized status of a device's wireless signal. Values range from 1-10.

 

IncidentSeverity

IncidentSeverity describes how severe an Incident or alarm is. An Incident's severity is always equal to the highest severity of any alarm associated with the Incident. An alarm's severity is always equal to the severity configured on the configured alarm that created it. This type has 5 values:

1: Lowest

2: Low

3: Medium

4: High

5: Highest

 

IncidentStatus

IncidentStatus describes the status of an incident. These values can be updated by the system as new readings come in that resolve or retrigger alarms or by users interacting with incidents in the UI. This type has 4 values:

0: New

1: Active

2: On Hold

99: Closed

The New status means the system has created the incident, but no user action has been taken. Active indicates a user has been assigned to the incident. On Hold is functionally the same as Active, with the addition that a user has selected to put the incident on hold in the UI. Closed means the incident is resolved and will no longer be used by the system; this means that new reading violations will result in new incidents being created.

 

AlarmStatus

AlarmStatus describes the status of an alarm. An incident can have many alarms so their status is tracked separately per alarm. This type has 4 values:

0: Closed

1: Open

2: Acknowledged

3: Resolved

The Closed status means the system will no longer take any actions with the alarm. New reading violations will result in new alarms. The Open status means the alarm is active. The current reading is out of range and the alarm is available for user action. Acknowledged is the same as Open, with the addition of indicating that a user acknowledged the alarm in the UI. A Resolved alarm means the readings have come back in range.

 

ViolationOperator

ViolationOperator describes the relational operator used to compare an incoming reading against an alarm threshold. All incidents and alarms are created by the system by comparing readings gathered by sensors to configured alarm thresholds. These thresholds consist of a value and comparison operator, which are also tracked in the alarm instance. This type has 3 values:

-1: Less Than

0: Equal To

1: Greater Than

 

ThresholdType

ThresholdType describes the type of readings that an alarm is set up or triggered. Each incident will only track alarms for one type of reading. As an example, consider an asset with both temperature and humidity sensors that has two configured alarms: one for temperature and one for humidity. If both sensors go out of range for their respective configured alarm, two incidents (one per reading type) will be created. The type of reading that each incident is responsible for is tracked with this ThresholdType enumeration. The possible values for this type are:

1: Temperature

2: Missed Report

3: Humidity

4: Power

5: Wind Speed

6: Soil Moisture

7: Flood

8: Voltage

9: Pressure

10: Pressure Pascal

11: Leaf Wetness

12: Rainfall

13: Percent CO2

14: Percent O2

15: OLPHC Pressure

16: Dry Contact

17: CentiPascal Pressure

18: Power Low Battery

20: Starwatch Pressure

21: Starwatch Level

23: Pressure KiloPascal

24: Current MilliAmp

25: Current Amp

26: Charge

27: Level

28: Capacitance PicoFarad

99: Validation

Enums

Enums are variable types that have a limited set of values, and fields that are enums are returned as strings in JSON. The string value will be limited to the possible enum values as defined for the type. All enum types have the possibility of being null.

 

ReadingType

Specifies the type of reading.

Values:

• "Temperature"
• "Humidity"
• "Power"
• "Signal Strength"

Unit

Specifies the unit of a reading.

Values:

• "F"
• "C"
• "%"

DeviceType

Specifies the type of device.

Values:

• "Node"
• "Repeater"
• "Gateway"

SensorType

Specifies the type of sensor.

Values:

• "Temperature"
• "Humidity"

List of IDs

Results Paging

Results paging is a method of separating multiple search results into individual pages to make the information more comprehensive, to not overwhelm the service, and to mitigate time-out issues. Paging also helps limit responses so that the entire data set isn't pulled with each request. Many of the endpoints that return a list of data are subject to paging.

Paged responses include the following paging information:

If there is an additional page, a link to the next page is specified in the HTTP response header called next. This header may include default values for non-required GET parameters that were not specified in the original request, so this header is preferred over manually creating the URI for your next page to guarantee correct results.

The default pageSize can be overridden by setting a pageSize query parameter:

Synchronizing Readings

Clients wishing to have their own copy of sensor or device readings can use the processedAfterDate query parameter to stay up to date with SmartSense. Whenever the last "page" of results is returned from a query containing a processedAfterDate value, a header (nextProcessedAfterDate) is included in the response specifying the processedAfterDate value to use on the next query.

Example: Client Alice wants all sensor readings since March 1st, 2021 (UTC), as well as any readings that arrive after that point. Alice will poll SmartSense every 15 minutes using the processedAfterDate query parameter. 

To begin, Alice makes the following request: 

GET /v1/data/asset/4146/sensorpoint/55689?processedAfterDate="2021-03-01T00:00:00.00Z" 

The response from the server may contain several "pages" of data. Each "page" (except the last) will have a header in the response with a link to the next "page." The final "page" will contain a nextProcessedAfterDate header with a datetime value. Alice saves this value as X. 

After retrieving all "pages," Alice now has a copy of all sensor readings from the account up to and including the datetime X.

 

After 15 minutes have passed, Alice queries SmartSense for readings and uses a new value for processedAfterDate: specifically, nextProcessedAfterDate value X from the last "page" of the previous request. SmartSense will respond with any new readings that have arrived since Alice’s last query. 

Alice repeats this process every 15 minutes to stay up to date with SmartSense.

Interactive API Documentation

For detailed endpoint documentation and the ability to test API calls directly, visit our Swagger documentation:

Swagger UI 

The Swagger interface provides:

• Complete endpoint specifications 
• Request and response schemas 
• Interactive API testing
• Real-time examples