Warning:
This wiki has been archived and is now read-only.
IoT-Device-Example
Contents
- 1 How to untangle SOSA/SSN's terms when it comes to RESTful Access to SOSA/SSN-described Devices?
- 2 Documenting the E-Mail Discussion Previous to the Teleconference
- 2.1 Question: What should the data in the response of a GET request look like?
- 2.2 Answer (superseded by the teleconference discussion, as the sosa:Observation comes after the act):
- 2.3 Question: How to model state information?
- 2.4 Answer (superseded by teleconference discussion, as we want to look into PUT)
How to untangle SOSA/SSN's terms when it comes to RESTful Access to SOSA/SSN-described Devices?
Concretely, the RDF terms for observation, actuation, results, feature of interest, and property.
Scenario: An IoT board with a REST interface and an LED
The LED has a uri: <http://192.168.1.2/led#id>
GET on <http://192.168.1.2/led> returns "on" (somehow represented in RDF) if the LED is on.
PUT "off" (somehow represented in RDF) to <http://192.168.1.2/led> would switch the LED off.
Aim: To model the state of the LED for the REST interface in RDF using SSN/SOSA
In other words, how to represent "on" (in RDF) and "off" (in RDF) if we want to access and manipulate the state of the LED with HTTP? How do the terms for the representation relate to SOSA/SSN's observation, actuation, results, feature of interest, and property?
Temporally Untangling the Act of Observation/Actuation and their Descriptions in SOSA/SSN
The instances of sosa:Observation and sosa:Actuation are about an observation/actuation that has happened and not that is to be executed.
For the example, we use ex:state as we do not know about a suitable term, and saref:On/saref:Off, but we are open and interested in other suitable terms.
Sequence Diagram for Observation
Scenario: The Web Agent observes the LED on a Printed Circuit Board (PCB) using an HTTP GET request. The Web Agent keeps track of the observations he has made make in a Triple Store. Note that the resource for the sosa:Observation is created after the act of the observation, which has been performed using the HTTP GET request.
------------------------ ---------------------- ------------------------------
| Triple Store | | Web Agent | | REST Server on a LED's PCB |
| With the Agent's Log | | | | http://192.168.1.2/ |
------------------------ ---------------------- ------------------------------
| | |
| | GET /led |
| |--------------------------->|
| | 200 OK |
| | <#id> ex:state saref:On. |
| |<- - - - - - - - - - - - - -|
| | |
| POST /sparqlEndPoint | |
| INSERT { | |
| [] a sosa:Observation ; | |
| sosa:resultTime | |
| "2017-06-14T14:58:00"^^xsd:dateTime ; | |
| sosa:hasFeatureOfInterest | |
| <http://192.168.1.2/led#id> ; | |
| sosa:hasResult saref:On . | |
| } | |
|<------------------------------------------| |
| 200 OK | |
|- - - - - - - - - - - - - - - - - - - - - >| |
| | |
Sequence Diagram for Actuation
Scenario: The Web Agent turns off a LED on a Printed Circuit Board (PCB) using an HTTP PUT request. The Web Agent keeps track of the actuations he has made make in a Triple Store. Note that the resource for the sosa:Actuation is created after the act of the actuation, which has been performed using the HTTP PUT request.
------------------------ ---------------------- ------------------------------
| Triple Store | | Web Agent | | REST Server on a LED's PCB |
| With the Agent's Log | | | | http://192.168.1.2/ |
------------------------ ---------------------- ------------------------------
| | |
| | PUT /led |
| | <#id> ex:state saref:Off. |
| |--------------------------->|
| | 204 No Content |
| |<- - - - - - - - - - - - - -|
| | |
| POST /sparqlEndPoint | |
| INSERT { | |
| [] a sosa:Actuation ; | |
| sosa:resultTime | |
| "2017-06-14T14:59:00"^^xsd:dateTime ; | |
| sosa:hasFeatureOfInterest | |
| <http://192.168.1.2/led#id> ; | |
| sosa:hasResult saref:Off . | |
| } | |
|<------------------------------------------| |
| 200 OK | |
|- - - - - - - - - - - - - - - - - - - - - >| |
| | |
Open Questions
- What are good terms to describe the state of the LED? Especially, what should be the term in predicate position of the triple?
- What is the
sosa:FeatureOfInteresthere?-
<http://192.168.1.2/led#id>?
-
- What/Who is the
sosa:Sensor/sosa:Actuator?- The Web Agent?
- What is the
ssn:Propertyhere and how does it relate to the term in predicate position of the triple, which we are seeking?
Documenting the E-Mail Discussion Previous to the Teleconference
EXAMPLE ---> to be added in index.html, and SDW github directory ssn/integrated/examples/iot-device.ttl
Question: What should the data in the response of a GET request look like?
Scenario: A IoT device accessible throught some Web interaction protocol (HTTP, CoAP) with some sensors and actuators.
Answer (superseded by the teleconference discussion, as the sosa:Observation comes after the act):
A HTTP GET request on </thermometer> would yield the following reading:
@prefix sosa: <http://www.w3.org/ns/sosa/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
@prefix cdt: <http://w3id.org/lindt/custom_datatypes#>.
<#id> a sosa:Sensor ;
sosa:madeObservation [
a sosa:Observation ;
sosa:resultTime "2017-05-28T13:01:54"^^xsd:dateTime ;
sosa:hasResult "20 Cel"^^cdt:ucum ] .
note that the instance of Observation is a blank node. This ensures there is no incoherence if one merges this RDF Graph with another one that contains the previous readings of this temperature sensor.
Question: How to model state information?
Are there terms in the vocabulary to state whether something is on or off? For instance, in case of a LED in a LED matrix, I currently use (excerpt from a response to a GET request):
Answer (superseded by teleconference discussion, as we want to look into PUT)
A light device can have an sensor attached (to read its state), and an actuator attached (to modify it). a GET at device endpoint </light> could yield the following result:
@prefix ssn: <http://purl.oclc.org/NET/ssnx/ssn#> . @prefix sosa: <http://www.w3.org/ns/sosa/> . @prefix saref: <https://w3id.org/saref#> . <#led-state> ssn:isPropertyOf <#led> . # the light is a real-world object, hence it should have a hash-based IRI. [] a sosa:Observation ; sosa:observedProperty <#led-state> ; sosa:hasResult saref:On .
</light> could also be a REST container
To be REST-like, the device API should return the Location of the newly created resource if a client issues an HTTP POST with some actuation in the body. For example, to endpoint </light> with the RDF Graph below as the body could yield the light turn off:
@prefix ssn: <http://purl.oclc.org/NET/ssnx/ssn#> . @prefix sosa: <http://www.w3.org/ns/sosa/> . @prefix saref: <https://w3id.org/saref#> . @prefix pep: <https://w3id.org/pep/> . <#led-state> ssn:isPropertyOf <#led> . [] a sosa:Actuation ; sosa:actsOnProperty <#led-state> ; pep:hasCommand saref:Off .
if the platform can store the previous actuation commands that have
been issues, then the server could respond with 201 Created and a
HTTP Header Field "Location" set to the absolute IRI of the newly
created resource. Else, the server could respond with 200 OK.
