Query Devices
Query for devices in a number of ways using available filters.
Routes
| Method | URI | Summary |
|---|---|---|
| GET | /v1.0/admin/things | Get list of all devices |
| GET | /v1.0/admin/things/count | Get count of all devices |
| GET | /v1.0/admin/things/{thing_id} | Get one device |
| GET | /v1.0/admin/things/{thing_id}/latest | Get latest readings |
| GET | /v1.0/admin/things/{thing_id}/readings | Get device readings by Thing Id and time frame |
| GET | /v1.0/admin/things/{hardware_id}/status | Get device by hardware Id |
| POST | /v1.0/admin/things | Create a device |
| POST | /v1.0/admin/things/{thing_id}/cmd | Send a command to a device |
| PUT | /v1.0/admin/things/{thing_id} | Update a device |
| DELETE | /v1.0/admin/things/{thing_id} | Delete a device |
info
The parameter {thing_id} is in UUID format, e.g. 6df450e0-91f0-11ed-9d8f-f9c593f1db51 not the hardware id. See how to get thing_id from hardware_id below.
Find all Devices
Query Parameters
| Name | Source | Type | Values |
|---|---|---|---|
| application_id | query | string | |
| limit | query | number | |
| page | query | number | |
| location_id | query | number | |
| status | query | number | 0 Activated 1 Deactivated |
| user_id | query | string | |
| thing_type | query | string | devices or gateways |
| external_id | query | string |
Response Body
| Name | Source | Type | Description |
|---|---|---|---|
| count | body | number | Total number of devices |
| limit | body | number | Number of devices returned per page |
| page | body | number | Current page of results |
| rows | body | array | Array of device objects |
Device Object
| Name | Source | Type | Description |
|---|---|---|---|
| id | Device | number | Internal Id |
| location_id | Device | number | Location Id |
| company_id | Device | number | Company Id |
| parent_id | Device | number | Parent Id |
| cayenne_id | Device | string | Device Id |
| hardware_id | Device | string | EUI or Hardware Id |
| sensor_use_id | Device | number | Sensor Use Id |
| sensor_use | Device | string | Sensor Use String |
| sensor_type | Device | string | Sensor Type |
| thing_name | Device | string | Device Name |
| thing_type | Device | number | Device Template |
| marker_alert | Device | string | Marker Alert |
| properties | Device | string | Properties |
| device_type_id | Device | string | Device Type/Template Id |
| enabled | Device | number | Enabled |
| user_id | Device | string | User Id |
| application_id | Device | string | Application Id |
| status | Device | number | 0 Activated 1 Deactivated |
| created_at | Device | string | Created At |
| updated_at | Device | string | Updated At |
Get single device by Hardware id
Note we are passing hardware_id and status. If status parameter is not include, it will return previous deactivated devices as well.
Here we use the id as thing_id in other requests.
```shell
curl --request GET --url https://api.iotinabox.com/v1.0/admin/things?hardware_id=abcde123456?status=0 \
--header 'authorization: Bearer MyAuthTokenHere' \
--header 'content-type: application/json'
Get devices for an User
Example call to query devices for a user (e.g. one of our two users pulled in the previous example). In this case we'll query against robcan...@yopmail.com, user 99e86f3f-87f4-4d7e-9e87-529e16f27438:
Note how we filter by a specific user_id.
curl --request GET --url https://api.iotinabox.com/v1.0/admin/things?page=0&limit=50&user_id=99e86f3f-87f4-4d7e-9e87-529e16f27438 \
--header 'authorization: Bearer MyAuthTokenHere' \
--header 'content-type: application/json'
Example Response (robcan...@yopmail.com's devices):
{
"count": 2,
"limit": 50,
"page": 0,
"rows": [
{
"sensor_type": null,
"created_at": "2019-05-07T23:04:25.000Z",
"sensor_use": null,
"thing_type": 0,
"thing_name": "Gateway",
"properties": "{\"codec\":\"lorawan.gateway.iotb\"}",
"company_id": 937,
"hardware_id": "eui-00001c497bb44...",
"device_type_id": "36c52526-e689-11e7-80c1-9a214cf093ce",
"application_id": "iot-solutions-canada",
"sensor_use_id": null,
"location_id": 890,
"id": 70006075,
"enabled": 1,
"status": 0,
"user_id": "99e86f3f-87f4-4d7e-9e87-529e16f27438",
"parent_id": null,
"updated_at": "2019-05-07T23:04:25.000Z",
"cayenne_id": "75722a70-711c-11e9-9fd4-e73c33d2d42c"
},
{
"company_id": 937,
"hardware_id": "00137a1000000...",
"device_type_id": "121f6268-e52b-11e7-80c1-9a214cf093ae",
"sensor_type": "Open/Close",
"created_at": "2019-05-07T23:04:45.000Z",
"thing_type": 1,
"sensor_use": "Door",
"thing_name": "OCRPP",
"properties": "{}",
"application_id": "iot-solutions-canada",
"id": 70006076,
"enabled": 1,
"sensor_use_id": null,
"location_id": 890,
"cayenne_id": "815f4c00-711c-11e9-9fd4-e73c33d2d42c",
"updated_at": "2019-05-09T17:00:11.000Z",
"user_id": "99e86f3f-87f4-4d7e-9e87-529e16f27438",
"status": 1,
"parent_id": null
}
]
}
Get Latest Readings
GET - /v1.0/admin/things/{thing_id}/latest
This endpoint will return the latest device sensor readings. In order to properly parse the readings array, you must know the channel mapping for the device. This can be found by querying the /v1.0/things/types/{device_type_id} endpoint.
Example Response
[
{
"ts": 1701362627000,
"type": "value",
"channel": "100",
"name": "Voltage",
"thing_id": "1234567-a248-11ed-a734-c705cd0fd51c",
"event": "uplink",
"v": 4028
},
{
"ts": 1701362627000,
"type": "value",
"channel": "123",
"name": "Temp",
"thing_id": "1234567-a248-11ed-a734-c705cd0fd51c",
"event": "uplink",
"v": 4595
},
... // truncated
Get Device Readings
GET - /v1.0/admin/things/{thing_id}/readings
This endpoint will return device sensor readings by providing a start and end unix timestamp in milliseconds. The readings are returned in descending order by timestamp. In order to properly parse the readings array, you must know the channel mapping for the device. This can be found by querying the /v1.0/things/types/{device_type_id} endpoint. See the example below.
Query Parameters
| Name | Source | Type | Description |
|---|---|---|---|
| start_ts | query | number | Start timestamp in milliseconds |
| end_ts | query | number | End timestamp in milliseconds |
| limit | query | number | (optional) Limit numner of returned readings |
| cursor | query | string | (optional) String value to paginate readings |
Response Body
| Name | Source | Type | Description |
|---|---|---|---|
| count_took | body | number | Time to process query |
| took | body | number | Time to process query |
| transfer | body | number | number of bytes transferred |
| units | body | array | Array of sensor units |
| readings | body | array | Array of readings |
| timestamp | body | string | If present, this value will be set to cursor to get next more readings |
The readings array contains objects with the following properties:
| Name | Source | Type | Description |
|---|---|---|---|
| ts | body | number | Timestamp of reading |
| correlation_id | body | string | Event correlation id of the device reading |
| sensors | body | array | Actual readings are returned in this array { "v": 0, "channel": "10" } |
{
"ts": 1687650221820,
"correlation_id": "24856f3a-404f-4b94-adab-72e8a5fc8db9",
"sensors": [
{
"v": 0,
"channel": "10"
},
{
"v": -64,
"channel": "100"
},
{
"v": 100,
"channel": "5"
}
]
}
Each object will contain an array of sensor values at the set interval. This indicate that at the given timestamp, the sensor values were as follows:
- channel 10: 0
- channel 100: -64
- channel 5: 100
To get a channel mapping for a device, use the /v1.0/things/types/{device_type_id} endpoint.
https://iotinabox-api.mydevices.com/v1.0/things/types/{device_type_id}
The returned payload from this Device Types endpoint will contain a channels array describing the channel mapping for the device. For example:
"channels": [
{
"data": null,
"id": 70,
"name": "battery",
"datatype": "BATTERY",
"data_types_id": 11,
"channel": "5",
"ipso": null,
"order": 1,
"device_type_id": "121f6268-e52b-11e7-80c1-9a214cf093ae"
},
{
"data": null,
"id": 71,
"name": "motion",
"datatype": "INTRUSION",
"data_types_id": 39,
"channel": "10",
"ipso": null,
"order": 1,
"device_type_id": "121f6268-e52b-11e7-80c1-9a214cf093ae"
},
{
"data": null,
"id": 79,
"name": "signal",
"datatype": "RSSI",
"data_types_id": 8,
"channel": "100",
"ipso": null,
"order": 1,
"device_type_id": "121f6268-e52b-11e7-80c1-9a214cf093ae"
}
],
Putting it all together, we can see that the above example reading:
| timestamp | channel | type | value |
|---|---|---|---|
| 1687650221820 | 10 | motion | 0 |
| 1687650221820 | 100 | signal | -65 |
| 1687650221820 | 5 | battery | 100 |
Entire Example Response
{
"count_took": 2,
"took": 70,
"transfer": 986,
"units": [
{
"sensor_id": "47b6a550-cf57-11ed-aaaa-292d59ac7b6c",
"channel": "5",
"from": "p"
},
{
"sensor_id": "47b65730-cf57-11ed-aaaa-292d59ac7b6c",
"channel": "10",
"from": "d"
},
{
"sensor_id": "47b67e40-cf57-11ed-aaaa-292d59ac7b6c",
"channel": "100",
"from": "dbm"
}
],
"readings": [
{
"ts": 1687650221820,
"correlation_id": "24856f3a-404f-4b94-adab-72e8a5fc8db9",
"sensors": [
{
"v": 0,
"channel": "10"
},
{
"v": -64,
"channel": "100"
},
{
"v": 100,
"channel": "5"
}
]
},
{
"ts": 1687643022290,
"correlation_id": "8ea092b2-7320-448f-bce4-3f094ca16605",
"sensors": [
{
"v": 0,
"channel": "10"
},
{
"v": -66,
"channel": "100"
},
{
"v": 100,
"channel": "5"
}
]
}
]
}
Example Requeust
curl --request GET --url https://api.iotinabox.com/v1.0/admin/things/thing_id/readings?start_ts=0&end_ts=0 \
--header 'authorization: Bearer MyAuthTokenHere' \
--header 'content-type: application/json'
Create a Device
Create a Device
curl --request POST --url https://api.iotinabox.com/v1.0/admin/things \
--header 'authorization: Bearer MyAuthTokenHere' \
--header 'content-type: application/json'
--data \
'{
"user_id": "0dfb9c58-5a0b-40eb-9e8c-36c0b1ff883b",
"application_id": "iotinabox",
"company_id": 464,
"location_id": 445,
"device": {
"hardware_id": "a130000000000ff",
"name": "thing_name_5",
"sensor_use": "use5",
"sensor_type": "Ethernet Gateway",
"device_category": "module",
"external_id": "my_external_id_4"
}
}'
Example Response:
{
"id": 1405,
"location_id": 445,
"company_id": 464,
"parent_id": null,
"cayenne_id": "d3fd3d80-6446-11ec-a762-a52e6bb2c8ed",
"hardware_id": "a130000000000ff",
"sensor_use_id": null,
"sensor_use": "use6",
"sensor_type": "Ethernet Gateway",
"thing_name": "thing_name_5",
"thing_type": 1,
"marker_alert": "animate",
"properties": "{\"codec\":\"lorawan.gateway.iotb\",\"deveui\":\"a130000000000ff\",\"network\":\"iotinabox\",\"activation\":\"activated\",\"device_registry_id\":\"4b918ff0-641e-11ec-a762-a52e6bb2c8ed\",\"codec.vol_unit\":\"m3\",\"codec.prox_unit\":\"m\"}",
"device_type_id": "1e563f10-cc0d-11e8-9c69-e9c14d851ba4",
"enabled": 1,
"user_id": "0dfb9c58-5a0b-40eb-9e8c-36c0b1ff883b",
"application_id": "iotinabox",
"status": 0,
"created_at": "2021-12-23T23:19:53.000Z",
"updated_at": "2022-01-03T17:27:41.000Z",
"external_id": "my_external_id_4",
"createdAt": "2021-12-23T23:19:53.000Z",
"updatedAt": "2022-01-03T17:27:41.000Z"
}
Update Device
Update a Device
curl --request PUT --url https://api.iotinabox.com/v1.0/admin/things/d3fd3d80-6446-11ec-a762-a52e6bb2c8ed \
--header 'authorization: Bearer MyAuthTokenHere' \
--header 'content-type: application/json'
--data \
'{
"user_id": "0dfb9c58-5a0b-40eb-9e8c-36c0b1ff883b",
"application_id": "iotinabox",
"sensor_use": "use6",
"name": "thing_name_6",
"external_id": "my_external_id_5",
"company_id": 464,
"location_id": 445
}'
Example Response:
{
"id": 1405,
"location_id": 445,
"company_id": 464,
"parent_id": null,
"cayenne_id": "d3fd3d80-6446-11ec-a762-a52e6bb2c8ed",
"hardware_id": "a130000000000ff",
"sensor_use_id": null,
"sensor_use": "use6",
"sensor_type": "Ethernet Gateway",
"thing_name": "thing_name_6",
"thing_type": 1,
"marker_alert": "animate",
"properties": "{\"codec\":\"lorawan.gateway.iotb\",\"deveui\":\"a130000000000ff\",\"network\":\"iotinabox\",\"activation\":\"activated\",\"device_registry_id\":\"4b918ff0-641e-11ec-a762-a52e6bb2c8ed\",\"codec.vol_unit\":\"m3\",\"codec.prox_unit\":\"m\"}",
"device_type_id": "1e563f10-cc0d-11e8-9c69-e9c14d851ba4",
"enabled": 1,
"user_id": "0dfb9c58-5a0b-40eb-9e8c-36c0b1ff883b",
"application_id": "iotinabox",
"status": 0,
"created_at": "2021-12-23T23:19:53.000Z",
"updated_at": "2022-01-03T17:27:41.000Z",
"external_id": "my_external_id_5",
"createdAt": "2021-12-23T23:19:53.000Z",
"updatedAt": "2022-01-03T17:27:41.000Z"
}
Remove Device
Delete a Device
curl --request DELETE --url https://api.iotinabox.com/v1.0/admin/things/d3fd3d80-6446-11ec-a762-a52e6bb2c8ed \
--header 'authorization: Bearer MyAuthTokenHere' \
--header 'content-type: application/json'
--data \
'{
"user_id": "0dfb9c58-5a0b-40eb-9e8c-36c0b1ff883b"
}'
Example Response:
{
"success": true
}
Get Device by External Id
Get a Device by External Id
curl -- request GET \
-- url https://api.iotinabox.com/v1.0/admin/things?external_id=1234 \
-- header 'Authorization: Bearer YourAuthToken' \
-- header 'Content-Type: application/json'
Send Device Command
Send Device Commands
curl --request POST \
--url http://api.iotinabox.com/v1.0/admin/things/6df450e0-91f0-11ed-9d8f-f9c593f1db51/cmd \
--header 'Authorization: Bearer >>your token here<<' \
--header 'Content-Type: application/json' \
--data '{
"channel": "57",
"value": 1
}'
In the above example the channel must be one of the device capabilities found under device templates. The value depends on the type of capability. Here we have a stop alert downlink and the value must be equal to 1.