You can read full device state including its meta data, methods, properties and alerts. You can also shape the response object by providing parameters shown below.
If you are writing using a device key you can substitute {ref} with _this_
.
Api Key Authorization
Required Fields | Values |
---|---|
Context type | Device or App |
Scopes | device:read-data |
State Object
Device state is a compact representation of device metadata, and the most recent device values. It is mainly consists of 4 sections:
- State Header: mainly device metadata plus some additional fields
- List of property instances: property metadata and the most recent instant value
- List of method instances: method metadata and method statistics
- List of alert instances: alert metadata and alert statistics
Most recent property values, method and alert statistics only show up after the first use. Users can customize state view using query parameters (see below) to include or exclude sections.
State header
Below we list attributes specific to device state header.
Attribute | Description |
---|---|
initiatedAt | Device backend start date and time in ISO 8601 format. This is mostly used for debugging purposes. In general, a device backend begins to exist with the first incoming or outgoing data, but cluster manager can kill or start device backends as it sees fit. |
ingestion | Device ingestion rate. It consists of 2 fields: rateLimit defines the maximum number of feeds per minute, and maxNrOfDpPerFeed defines the maximum number of data points allowed per feed. ingestion cannot be changed by the user; it is automatically set by device's account plan. See your account plan details for device ingestion rates. |
Properties
It consists of 4 subsections: ref
, meta
, value
and stats
. ref
shows the property references, meta
show the details of the property, value
is the most recent value written into the property and stats
shows the write statistics of this property.
At minimum, it has only ref
and meta
subsection. value
and stats
subsections show up only after the first write operation.
meta
subsection contains the property instance meta data, value
subsection contains the most recent value of the property instance in form of data value object, stats
subsection contains property statistics where count
shows how many times this property is set since its owner object is created.
Below we show a fully populated value
and stats
subsections of a numeric property instance. Non numeric properties contain only count
field in their stats
subsections.
"ref": {
"id": "_prp_944478333222595585",
"qname": "mysensor$temp"
},
"meta": {
"id": "_prp_944478333222595585",
"accountId": "_acc_944477132420380208",
"ownerId": "_dpf_944477240279924130",
"name": "Temp",
"friendlyName": "Temperature",
"qualifiedName": "mysensor$temp",
"description": "Indoor temperature readings",
"type": "number",
"access": "protected",
"publish": "changed",
"retention": {
"type": "mostrecent",
"condition": {
"when": "always"
}
},
"locked": false,
"dateCreated": "2017-06-27T03:07:42.324Z",
"dateModified": "2017-06-27T03:07:42.324Z"
},
"value": {
"mostRecent": 23,
"time": "2017-07-21T00:27:59.123Z",
"annotations": {
"customer-id": "8CS238429929348923"
},
"location": {
"zone": "Portland Factory",
"geo": {
"lat": 41.0296287,
"lon": 28.6232202,
"alt": 0
}
},
"tags": [
"grp:floor1"
]
},
"stats": {
"count": 3,
"min": 23,
"max": 23,
"sum": 69
}
Methods
Method consists of 5 sections. ref
, meta
, lastExecution
, stats
and disabled
. lastExecution
shows a brief about the last execution. time
shows execution time in milliseconds. stats
section shows how many times this method is executed, minimum and maximum execution times in milliseconds.
"ref": {
"id": "_mtd_944552945643610010",
"qname": "mysensor$gettemperature"
},
"meta": {
"id": "_mtd_944552945643610010",
"accountId": "_acc_944477132420380208",
"ownerId": "_dpf_944478335659071432",
"name": "getTemperature",
"friendlyName": "getTemperature",
"inherited": false,
"qualifiedName": "mysendor$gettemperature",
"access": "public",
"inputTTL": "5 seconds",
"inputId": "_prp_944478333222595585",
"methodImpl": {
"funcBody": "if (value > 35.0) { return \"hot\" } else { return \"warm\"; }",
"script": "javascript"
},
"locked": false,
"dateCreated": "2017-07-27T05:38:05.593Z",
"dateModified": "2017-07-27T05:41:48.56Z"
},
"lastExecution": {
"status": "Success",
"at": "2017-07-27T05:49:33.603Z",
"time": 1
},
"stats": {
"count": 1,
"min": 1,
"max": 1,
"sum": 1,
"failures": 0
},
"disabled": false