FORMAT: 1A HOST: http://www.google.com # SensorDefinitionAPI (DRAFT) An API for defining Sensors. We define both data about the physical sensor itself, and MetaData about the information the Sensor delivers **This is a draft document. We welcome feedback, criticisms and suggestions. Currently the best place to do that is on the GitHub Page** *You can view the definition in it's raw form on Github, or beautifully rendered by Apiary:* - http://docs.sensordefinitionapi.apiary.io/ - https://github.com/relayr/SensorDefinitionAPI This API is released under the [Creative Commons Attribution 4.0 International (CC BY 4.0)](http://creativecommons.org/licenses/by/4.0/) # Group General ## Sensor Definitions Collection [/sensordefinitions] The system contains a list of a number of sensor definitions. This endpoint will return a list of the existing sensors, add or delete sensors or modify a sensor within the list. + Model + Body { "_links": { "self": {"href": "http://example.org/sensors"}, "first": { "href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456790" }, "last": { "href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456792" } }, "count" : 4, "_embedded": { "sensors" : [ { "_links": { "self": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456789"}, "hardware": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456789/hardware"}, "firmware": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456789/firmware"}, "communication": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456789/communication"}, "readings": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456789/readings"}, "documentation" : {"href" : "http://example.org/documentation/wunderbar/sensors/temp-humidity"} }, "id" : '550e8400-e29b-41d4-a716-446655456789', "manufacturer" : "relayr", "name": 'Temperature / Humidity Sensor', "productNumber" : "rWB001" },{ "_links": { "self": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456790"}, "hardware": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456790/hardware"}, "firmware": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456790/firmware"}, "communication": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456790/communication"}, "readings": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456790/readings"}, "documentation" : {"href" : "http://example.org/documentation/wunderbar/sensors/sound"} }, "id" : '550e8400-e29b-41d4-a716-446655456790', "manufacturer" : "relayr", "name": 'Sound Level Sensor', "productNumber" : "rWB002" },{ "_links": { "self": { "href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456791"}, "hardware": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456791/hardware"}, "firmware": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456791/firmware"}, "communication": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456791/communication"}, "readings": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456791/readings"}, "documentation" : {"href" : "http://example.org/documentation/wunderbar/sensors/acc-gyro"} }, "id" : '550e8400-e29b-41d4-a716-446655456791', "manufacturer" : "relayr", "name": 'Accelerometer / Gyrosope', "productNumber" : "rWB003" },{ "_links": { "self": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456792"}, "hardware": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456792/hardware"}, "firmware": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456792/firmware"}, "communication": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456792/communication"}, "readings": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456792/readings"}, "documentation" : {"href" : "http://example.org/documentation/wunderbar/sensors/light-color-prox"} }, "id" : '550e8400-e29b-41d4-a716-446655456792', "manufacturer" : "relayr", "name": 'Light / Color / Proximity Sensor', "productNumber" : "rWB003" }] } } ### Retreives a list of sensor definitions - for multiple sensors [GET] + Response 200 (application/hal+json) [Sensor Definitions Collection][] ### Adds a sensor to the list [POST] + Request (application/json) { "manufacturer" : "relayr", "name": 'Light / Color / Proximity Sensor', "productNumber" : "rWB003" } + Response 201 (application/hal+json) + Body { "_links": { "self": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456792"}, "hardware": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456792/hardware"}, "firmware": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456792/firmware"}, "communication": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456792/communication"}, "readings": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456792/readings"} }, "id" : '550e8400-e29b-41d4-a716-446655456792', "manufacturer" : "relayr", "name": 'Light / Color / Proximity Sensor', "productNumber" : "rWB003" } ## Sensor Definition [/sensordefinitions/{sensorID}] + Model + Body { "_links": { "self": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456792"}, "hardware": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456792/hardware"}, "firmware": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456792/firmware"}, "communication": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456792/communication"}, "readings": {"href": "http://example.org/sensors/550e8400-e29b-41d4-a716-446655456792/readings"} }, "id" : '550e8400-e29b-41d4-a716-446655456792', "manufacturer" : "relayr", "name": 'Light / Color / Proximity Sensor', "productNumber" : "rWB003" } ### Returns a list of sensor definitions for a specific sensor [GET] + Response 200 (application/hal+json) [Sensor Definition][] ### Modifies a specific sensor in the list [PATCH] + Parameters + sensorID (required, string, `550e8400-e29b-41d4-a716-446655456789`) ... String `id` of the Sensor + Request (application/json) { "name" : 'Temperature & Humidity Sensor' } + Response 200 (application/hal+json) [Sensor Definition][] ### Removes a sensor from the list [DELETE] + Parameters + sensorID (required, string, `550e8400-e29b-41d4-a716-446655456789`) ... String `id` of the Sensor + Response 204 # Group Hardware Hardware related resource of the **Sensor Definition** ## Hardware Definition [/sensordefinitions/{sensorID}/hardware] + Parameters + sensorID (required, string, `550e8400-e29b-41d4-a716-446655456789`) ... String `id` of the Sensor + Model (application/hal+json) + Headers Link: ;rel="self" + Body { "_links": { "self": { "href": "http://example.org/sensor/550e8400-e29b-41d4-a716-446655456789/description/hardware", "datasheet": "http://example.org/sensor/550e8400-e29b-41d4-a716-446655456789/datasheet.pdf", "parent" : {"href": "http://example.org/sensor/550e8400-e29b-41d4-a716-446655456789"} } }, "date": 1398512005, "voltage-range": {min: 2700, max: 4900, unit: "mV"}, "power": "CR3032 coin-cell", "IOconnectors": { "usb": ["USB-2.0-microB"], "audio": ["3.5mm-stereo-out", "3.5mm-mono-mic"], "ethernet": ["RJ-45"], "1.25mm-pin-header": { "gpio": ["6pin"], "bus": ["I2C", "UART"] } }, "onboard-sensors": ["gyro/accelerometer", "barometer"], "program-debug": {"10-pin-1.25mm": "SWD"}, "wireless": ["BluetoothLE"], "release-notes": "lorem ipsum", "output": {"video": ["HDMI"], "audio":["spdif", "analog"], digital: ["pwm", "gpio"]}, "dimensions": {width:23, height: 15, depth: 45, units: "mm"} } ### Read current Hardware definition [GET] + Response 200 (application/hal+json) [Hardware Definition][] ### Create current Hardware definition [POST] + Request + Body { "date": 1398512005, "voltage": "3.3v", "release-notes": "lorem ipsum" } + Response 201 (application/hal+json) [Hardware Definition][] ### Update current Hardware definition [PATCH] + Request + Body { "power": "CR3032 coin-cell", "release-notes": "lorem ipsum delor" } + Response 200 (application/hal+json) [Hardware Definition][] ### Delete current Hardware definition [DELETE] + Response 204 # Group Firmware Firmware related resource of the **Sensor Definition**. Manufacturers are notoriously slow at releasing firmware updates, often third party suppliers have a better update cycle. The API expects to maintain a history of Firmare updates, that may include stable, latest and nighty builds. A firmware update has the followng structure: **version** *String* is used as a unique identifier for the specific piece of software **date** *Timestamp* identifies the relase date of the firmware **name** *String* if the release has a name **supplier** *String* The name of the firmware update - as mentioned Manufacturer are not the only suppliers of firmware upgrades **release-notes** *String* The relase notes for a release. Currently no Format is specified, however Mardown seems like a good choice ## Firmware [/sensordefinitions/{sensorID}/firmware] + Parameters + sensorID (required, string, `550e8400-e29b-41d4-a716-446655456789`) ... String `id` of the Sensor + Model (application/hal+json) + Headers Link: ;rel="self" + Body { "_links": { "self": { "href": "http://example.org/sensor/550e8400-e29b-41d4-a716-446655456789/description/firmware" }, "download": {"href": "http://example.org/downloads/550e8400-e29b-41d4-a716-446655456789_0.1.zip" }, "history" : {"href": "http://example.org/sensor/550e8400-e29b-41d4-a716-446655456789/description/firmware/history"}, "parent" : {"href": "http://example.org/sensor/550e8400-e29b-41d4-a716-446655456789"} }, "version": "0.2", "date": 1398512005, "name": "RC1", "supplier": "relayr", "release-notes": "lorem ipsum" } ### Read current Firmware release [GET] To get the current recommended version of the firmware use this endpoint. For other relases use the history endpoint + Response 200 (application/hal+json) [Firmware][] ### Set current Firmware release [POST] To update the current firmware, you can post here. If the firmware release is already in the history, you can provide just the version number. If the release has not previously been uploaded, it will be automatically added to the firmware history. + Request + Body { "version": "0.01", "date": 13985412005, "name": "RC1", "supplier": "relayr", "release-notes": "lorem ipsum" } + Response 201 (application/hal+json) [Firmware][] ## Firmware History [/sensordefinitions/{sensorID}/firmware/history/{version}] The Firmware History displays a list of firmware relases for the device. This will include current firmware, as well as Release candidates, Nightlies and legacy releases. + Parameters + sensorID (required, string, `550e8400-e29b-41d4-a716-446655456789`) ... String `id` of the Sensor + Model (application/hal+json) HAL+JSON representation of Gist Collection Resource. The Gist resources in collections are embedded. Note the embedded Gists resource are incomplete representations of the Gist in question. Use the respective Gist link to retrieve its full representation. + Headers Link: ;rel="self" + Body { "_links": { "self": { "href": "/sensor/550e8400-e29b-41d4-a716-446655456789/description/firmware/history" }, "latest": { "href": "/sensor/550e8400-e29b-41d4-a716-446655456789/description/firmware" }, "stable": { "href": "/sensor/550e8400-e29b-41d4-a716-446655456789/description/firmware/history/0.1" }, "nightly": { "href": "/sensor/550e8400-e29b-41d4-a716-446655456789/description/firmware/history/0.1" }, }, "_embedded": { "history": [ { "_links" : { "self": { "href": "/sensor/550e8400-e29b-41d4-a716-446655456789/description/firmware/history/0.1" }, "download": { "href": "http://example.org/downloads/550e8400-e29b-41d4-a716-446655456789_0.1.zip" }, "parent" : {"href": "http://example.org/sensor/550e8400-e29b-41d4-a716-446655456789"} }, "version": "0.1", "date": 1398512005, "name": "RC1", "supplier" : "relayr", "release-notes": "lorem ipsum" } ] }, "total": 1 } ### Read Firmware History [GET] Returns a full list of releases. The Links component contains links to interesting relases. + Response 200 (application/hal+json) [Firmware History][] ### Create a Firmware release to the history [POST] + Request + Body { "version": "0.01", "date": 13985412005, "name": "RC1", "supplier": "relayr", "release-notes": "lorem ipsum" } + Response 201 (application/hal+json) [Firmware][] ### Update a Firmware release [PATCH] + Parameters + sensorID (required, string, `550e8400-e29b-41d4-a716-446655456789`) ... String `id` of the Sensor + version (required, string, `0.1`) ... String `version number` of the Firmware release + Request + Body { "name": "RC1" } + Response 200 (application/hal+json) [Firmware][] ### Delete a Firmware release [DELETE] + Parameters + sensorID (required, string, `550e8400-e29b-41d4-a716-446655456789`) ... String `id` of the Sensor + version (required, string, `0.1`) ... String `version number` of the Firmware release + Response 204 # Group Communcation Communication related resource of the **Sensor Definition** ## Communication Definition [/sensordefinitions/{sensorID}/communications] + Parameters + sensorID (required, string, `550e8400-e29b-41d4-a716-446655456789`) ... String `id` of the Sensor + Model (application/hal+json) + Headers Link: ;rel="self" + Body { "_links": { "self": { "href": "http://example.org/sensor/550e8400-e29b-41d4-a716-446655456789/communication", "parent" : {"href": "http://example.org/sensor/550e8400-e29b-41d4-a716-446655456789"} } }, "protocol" : {"name":"MQTT", "version":"3.1", "transport": "tcp/ip"}, "encryption" : "TLS 1.2", "physical": ["ethernet", "wifi"] } ### Read current Communication definition [GET] + Response 200 (application/hal+json) [Communication Definition][] ### Create current Communication definition [POST] + Request + Body { "protocol" : {"name":"MQTT"}, "encryption" : "TLS 1.2" } + Response 201 (application/hal+json) [Communication Definition][] ### Update current Communication definition [PATCH] + Request + Body { "protocol" : {"name":"MQTT", "verion":"3.1.1"}, "encryption" : "TLS 1.2" } + Response 200 (application/hal+json) [Communication Definition][] ### Delete current Communication definition [DELETE] + Response 204 # Group Readings Sensors can deliver many differnet readings. For example the Wunderbar uses the Meas-Spec HPP828E031 for the Tempertaure / humidity sensor. It is a single chip which can provide both readings. Typically the device sends the readings as a unitary value which must then be parsed. by the recevier of the data. Values sent will typically be a `Number`with no additional Information. This makes it naturally difficult for a developer to interpret. To give meaning to the number we provide metadata about the reading. Within Electrical Engineering the term `meaning`is used to explain waht is being measured, for instance "Temperature or Humidity" Combining this with `units` gives the developer enough information to understand what the value is. To evaluate the fitness of a reading for the intended purpose we provide three values `max` and `min` tell the developer which range of readings he can expect, and `precision`tell him which level of precision to expect from the sensor. **id** *String* **meaning** *String* **minimum** *Number* **maximum** *Number* **units** *String* **precision** *Number (float)* ## Sensor Reading Definitions [/sensordefinitions/{sensorID}/readings] A SensorDefinition must be able to provide a list of the readings offered by the device it represents. ### Get list of reading definitions available from of a sensor [GET] returns a list of readings as hal+json, with links to navigate the collection, as well as a total length, and the values stored in embedded + Parameters + sensorID (required, string, `550e8400-e29b-41d4-a716-446655456789`) ... String `id` of the Sensor + Response 200 (application/hal+json) + Body { "_links": { "self": { "href": "/sensor/550e8400-e29b-41d4-a716-446655456789/description/readings" }, "first": { "href": "/sensor/550e8400-e29b-41d4-a716-446655456789/description/readings/550e8400-e29b-41d4-a716-446655456711" }, "last": { "href": "/sensor/550e8400-e29b-41d4-a716-446655456789/description/readings/550e8400-e29b-41d4-a716-446655456781" } }, "_embedded": { "readings" : [{ "_links" : { "self": { "href": "/sensor/550e8400-e29b-41d4-a716-446655456789/description/readings/550e8400-e29b-41d4-a716-446655456711" }, "parent" : {"href": "http://example.org/sensor/550e8400-e29b-41d4-a716-446655456789"} }, "id" : '550e8400-e29b-41d4-a716-446655456711', "meaning" : 'temperature', "minimum" : -100, "maximum": 100, "units" : "celsius", "precision" : 0.01 },{ "_links" : { "self": { "href": "/sensor/550e8400-e29b-41d4-a716-446655456711/description/readings/550e8400-e29b-41d4-a716-446655456781" }, "parent" : {"href": "http://example.org/sensor/550e8400-e29b-41d4-a716-446655456789"} }, "id" : '550e8400-e29b-41d4-a716-446655456781', "meaning" : 'humidity', "minimum" : 0, "maximum": 100, "units" : "% Relative Humidity", "precision" : 0.01 }] }, "count": 2 }ยด ### Create a reading definition [POST] Adds a Reading to the list + Request (application/json) { "meaning" : 'humidity', "minimum" : 0, "maximum": 100, "units" : "% Relative Humidity", "precision" : 0.01 } + Response 201 (application/hal+json) + Body { "_links" : { "self": { "href": "/sensor/550e8400-e29b-41d4-a716-446655456789/readings/550e8400-e29b-41d4-a716-446655456781" }, "parent" : {"href": "http://example.org/sensor/550e8400-e29b-41d4-a716-446655456789"} }, "id" : '550e8400-e29b-41d4-a716-446655456781', "meaning" : 'humidity', "minimum" : 0, "maximum": 100, "units" : "% Relative Humidity", "precision" : 0.01 } ## Reading [/sensordefinitions/{sensorID}/readings/{readingID}] + Parameters + readingID (required, string, `550e8400-e29b-41d4-a716-446655456777`) ... String `id` of the Sensor + Model + Body { "_links" : { "self": { "href": "/sensor/550e8400-e29b-41d4-a716-446655456789/description/readings/550e8400-e29b-41d4-a716-446655456777" }, "parent" : {"href": "http://example.org/sensor/550e8400-e29b-41d4-a716-446655456789"} }, "id" : '550e8400-e29b-41d4-a716-446655456777', "meaning" : 'temperature', "minimum" : -100, "maximum": 100, "units" : "celsius", "precision" : 0.01 } ### Get a reading definition from of a sensor [GET] Get an individual reading + Response 200 (application/hal+json) [Reading][] ### Update a reading definition [PATCH] Modifies a reading + Request (application/json) { "maximum" : 120 } + Response 200 (application/hal+json) [Reading][] ### Delete a reading definition [DELETE] removes a reading from the list + Response 204