2.3. Sensors¶
A sensor represents a physical or virtual sensor or actuator. It contains a data stream made up of fields.
A sensor has the following attributes:
Name | Value Description |
---|---|
id | the numeric id of the sensor. This may be used in the API in place of the sensor name. |
name ** |
|
description ** | a description of the sensor for text searches. |
longName ** | longer display name of the sensor. |
url | DEPRECATED |
latitude |
|
longitude |
|
lastUpdate |
|
visibility | PUBLIC: The sensor is publicly visible
PRIVATE: The sensor is only visible to the owner. In any case posting data to the sensor is restricted to the sensor’s owner.
|
owner | the owner of the sensor |
fields | the expected data fields, their type (number or string), units and if available, last update time and value. (For more info: Sensor Fields ) |
tags | the list of tags for the sensor (For more info: Tags) |
data | sensor data (not shown yet) |
** Required when creating a new sensor.
2.3.1. Querying Sensors¶
A list of matching sensors may also be queried by the system.
The current query parameters are as follows:
Name | Value Description |
---|---|
scope | all - all sensors the current user has access to
subscribed - the sensors the user has subscribed to
| contributed - the sensors the user has contributed to the system.
|
metadata |
|
tags | list of comma separated tags |
orgs | list of comma separated organization names |
private | DEPRECATED, use visibility instead. (true - private sensors only; false - public only`). |
visibility | filter by the visibility of the sensors, either of public, or private |
text | text to search for in the name, long name and description |
active | when true it returns sensors that have been updated in the last 15 minutes; when false it returns sensors that have not been updated in the last 15 minutes. |
offset | offset into list of sensors for paging |
limit | limit to show for paging. The maximum number of sensors to display is 1000. |
location |
|
Note
If active is ommited the query will not evaluate if a sensor has, or has not, been updated in the last 15 minutes.
To query for sensors, add query parameters after the sensors URL as follows:
URL | http://wotkit.sensetecnic.com/api/v1/sensors?{query} |
Privacy | Public or Private |
Format | json |
Method | GET |
Returns | 200 OK if successful. A JSON object in the response body containing a list of sensor descriptions matching the query. |
example
curl --user {id}:{password} "http://wotkit.sensetecnic.com/api/v1/sensors?tags=canada"
Output:
[
{
"id": 71,
"name": "api-data-test",
"longName": "api-data-test",
"description": "api-data-test",
"tags": [
"canada",
"data",
"winnipeg"
],
"latitude": 0,
"longitude": 0,
"visibility": "PUBLIC",
"owner": "sensetecnic",
"lastUpdate": "2013-03-09T03:12:35.438Z",
"created": "2013-07-01T23:17:37.000Z",
"subscriberNames": [],
"fields": [
{
"name": "lat",
"longName": "latitude",
"type": "NUMBER",
"index": 0,
"required": false,
"value": 0
},
{
"name": "lng",
"longName": "longitude",
"type": "NUMBER",
"index": 1,
"required": false,
"value": 0
},
{
"name": "value",
"longName": "Data",
"type": "NUMBER",
"index": 2,
"required": true,
"value": 5,
"lastUpdate": "2013-03-09T03:12:35.438Z"
},
{
"name": "message",
"longName": "Message",
"type": "STRING",
"index": 3,
"required": false,
"value": "hello",
"lastUpdate": "2013-03-09T03:12:35.438Z"
}
],
"publisher": "sensetecnic",
"thingType": "SENSOR"
}
]
2.3.2. Viewing a Single Sensor¶
To view a single sensor, query the sensor by sensor name or id as follows:
URL | http://wotkit.sensetecnic.com/api/v1/sensors/{sensorname} |
Privacy | Public or Private |
Format | json |
Method | GET |
Returns | 200 OK if successful. A JSON object in the response body describing a sensor. |
example
curl --user {id}:{password} "http://wotkit.sensetecnic.com/api/v1/sensors/sensetecnic.mule1"
Output:
{
"id": 1,
"name": "mule1",
"longName": "Yellow Taxi 2",
"description": "A big yellow taxi that travels from Vincent's house to UBC and then back.",
"tags": [
"gps",
"taxi"
],
"imageUrl": "",
"latitude": 51.06038631669101,
"longitude": -114.087524414062,
"visibility": "PUBLIC",
"owner": "sensetecnic",
"lastUpdate": "2014-06-19T22:45:36.556Z",
"created": "2013-07-01T23:17:37.000Z",
"subscriberNames": [
"mike",
"fred",
"nhong",
"smith",
"roseyr",
"mitsuba",
"rymndhng",
"lchyuen",
"test",
"lesula"
],
"metadata": {},
"fields": [
{
"name": "lat",
"longName": "latitude",
"type": "NUMBER",
"index": 0,
"units": "degrees",
"required": false,
"value": 49.22288,
"lastUpdate": "2014-04-28T16:20:23.891Z"
},
{
"name": "lng",
"longName": "longitude",
"type": "NUMBER",
"index": 1,
"units": "degrees",
"required": false,
"value": -123.16246,
"lastUpdate": "2014-04-28T16:20:23.891Z"
},
{
"name": "value",
"longName": "Speed",
"type": "NUMBER",
"index": 2,
"units": "km/h",
"required": true,
"value": 10,
"lastUpdate": "2014-06-19T22:45:36.281Z"
},
{
"name": "message",
"longName": "Message",
"type": "STRING",
"index": 3,
"required": false
}
],
"publisher": "sensetecnic",
"thingType": "SENSOR"
}
2.3.3. Creating/Registering a Sensor¶
The sensor resource is a JSON object. To register a sensor, you POST a sensor resource to the url /sensors
.
To create a sensor the API end-point is:
URL | http://wotkit.sensetecnic.com/api/v1/sensors |
Privacy | Private |
Format | json |
Method | POST |
Returns | 201 Created if successful; 400 Bad Request if sensor is invalid; 409 Conflict if sensor with the same name already exists. |
The JSON object has the following fields:
Field Name | Information | |
---|---|---|
(REQUIRED) | name | The unique name for the sensor field. It is required when creating/updating/deleting a field and cannot be changed. The sensor name must be at least 4 characters long, contain only lowercase letters, numbers, dashes and underscores, and can start with a lowercase letter or an underscore only. |
(REQUIRED) | longName | The display name for the field. It is required when creating/updating/deleting a field and can be changed. |
(OPTIONAL) | latitude | The GPS latitude position of the sensor, it will default to 0 if not provided. |
(OPTIONAL) | longitude | The GPS longitude position of the sensor, it will default to 0 if not provided. |
(OPTIONAL) | visibility | It will default to “PRIVATE” if not provided (even when updating a sensor). |
(OPTIONAL) | tags | A list of tags for the sensor (For more info: Tags) |
(OPTIONAL) | fields | A fields object in the format {"name":"test-field","type":"STRING"} (For more info: Sensor Fields) |
example
curl --user {id}:{password} --request POST --header "Content-Type: application/json" --data-binary @test-sensor.txt 'http://wotkit.sensetecnic.com/api/v1/sensors'
For this example, the file test-sensor.txt contains the following.
{
"visibility":"PUBLIC",
"name":"taxi-cab",
"longName":"taxi-cab"
"description":"A big yellow taxi.",
"longName":"Big Yellow Taxi",
"latitude":51.060386316691,
"longitude":-114.087524414062
}
2.3.4. Creating/Registering multiple Sensors¶
To register multiple sensors, you PUT a list of sensor resources to the url /sensors
.
- The sensor resources is a JSON list of objects as described in Creating/Registering a Sensor.
- Limited to 100 new sensors per call. (subject to change)
URL | http://wotkit.sensetecnic.com/api/v1/sensors |
Privacy | Private |
Format | json |
Method | PUT |
Returns | 201 Created if successful; 400 Bad Request if sensor is invalid; 409 Conflict if sensor with the same name already exists ; 201 Created and a JSON object in the response body describing a dictionary where the keys are the sensor names and the values are true/false depending on whether creating the sensor succeeded. |
2.3.5. Updating a Sensor¶
Updating a sensor is the same as registering a new sensor other than PUT is used and the sensor name or id is included in the URL.
Note that all top level fields supplied will be updated.
- You may update any fields except “id”, “name” and “owner”.
- Only fields that are present in the JSON object will be updated.
- If “tags” list or “fields” list are included, they will replace the existing lists.
- If “visibility” is hardened (that is, the access to the sensor becomes more restrictive) then all currently subscribed users are automatically unsubscribed, regardless of whether they can access the sensor after the change.
To update a sensor owned by the current user:
URL | http://wotkit.sensetecnic.com/api/v1/sensors/{sensorname} |
Privacy | Private |
Format | json |
Method | PUT |
Returns | 204 No Content if successful. |
For instance, to update a sensor description and add tags:
example
curl --user {id}:{password} --request PUT --header "Content-Type: application/json" --data-binary @update-sensor.txt 'http://wotkit.sensetecnic.com/api/v1/sensors/taxi-cab'
The file update-sensor.txt would contain the following:
{
"visibility":"PUBLIC",
"name":"taxi-cab",
"description":"A big yellow taxi. Updated description",
"longName":"Big Yellow Taxi",
"latitude":51.060386316691,
"longitude":-114.087524414062,
"tags": ["big", "yellow", "taxi"]
}
2.3.6. Deleting a Sensor¶
Deleting a sensor is done by deleting the sensor resource through a DELETE request.
To delete a sensor owned by the current user:
URL | http://wotkit.sensetecnic.com/api/v1/sensors/{sensorname} |
Privacy | Private |
Format | not applicable |
Method | DELETE |
Returns | 204 No Content if successful. |
example
curl --user {id}:{password} --request DELETE 'http://wotkit.sensetecnic.com/api/v1/sensors/test-sensor'