The IoTResource Builder allows you to define your IoTResources and automatically generate the necessary IoTResource code stubs. Services can then be built using these IoTResources. The IoTResources are typically used to interface IoTThings (various networked devices, or physical objects associated with devices) in some IoTWorld.
Creating services with actions and state variables
Below is a step by step walk through on how to create service access points to IoT Resources. To do this, we need to create a Service including a set of Service Actions and their related State Variables.
In the case below we will define a service, with related annotations and actions, for an Air Quality monitoring device. This device can be used to read CO2 values measured in ppm´s (parts per million) as an indication of the current indoor air quality (IDA). The air quality can then be presented either as an absolute CO2 value, or, as named intervals: High, Medium, Moderate or Low air quality (formally referred to as IDA1-IDA4 in the EN13779 standard). Each interval defines a CO2 range, e.g., IDA1 (High) is 0 – 400 ppm’s CO2.
Name and describe the service
The first step is to name the service and provide some basic annotations (meta data descriptions) in order to facilitate discovery and help others to understand the service semantics.
As can be seen from the Service annotation above, this service should return two alternative measures: a value for the CO2 level in ppm, or in terms of named intervals following the air quality standard.
Following this the needed set of Actions (methods) and effects for this service should analysed and decided.
Create State Variables for the Actions
Continue to define the returns from the actions. Most actions will need to have their own State Variables defined, in this service they will be used to hold the return values of actions. In some cases state variables may also be needed as input arguments to actions.
A State Variable for the CO2 level
This variable will hold a simple CO2 value. The unit is ppm, based on a simple type .
It is good practice to provide some annotations also for the State Variables, at minimum a description, and above also the unit (ppm). The Reference field can be used to point at some external source used to describe this variable (some controlled vocabulary, or even an ontology).
A State Variable for Air Quality in intervals of ppm (IDA)
The next variable is a bit more interresting, since is also should include a custom value set. This is for representing the CO2 intervals mentioned above (named IDA1 – IDA4).
The UoM is her denoted as IDA, and we use the Reference annotation to make a link to the European standard on which these CO2 intrervals are based. The link is further explained in the Descriptions field. Looking at the State Variables Tab we see the current set of defiend variables.
Summary Tab with the state variables for ppm and IDA intervals
We continue with the definitions of the Actions to be associated with the above variables.
Create Actions for the Service
For this Service we will define two actions that are going to be used to retrieve sensor values (IoTObservations) from the Air Quality Device, using the state variables above. The first action will get the current (last available) CO2 value from the sensor device, in ppm (parts per million). A third Action will be added, which can be used to Turn On/Off the device.
Create an Action to return the CO2 level in ppm’s
Provide the name and a short description. Then select the orresponding state variable is selected in the Aurgument List.
Actions can also be annotated with a list of possible Effects they might have in the applications context, or more specifically on other state variables. As an example, turning off a fan might cause a temperature raise, and perhaps also a decrease in energy consumption. Note that these “effects” are not to be seen as hard dependencies between actions/ state variables maintained by the service run-time, but rather as a way to document possible effects in the application context and IoT Domain. The effect annotations can then, like all service annotations, be made searchable for developers as an aid in service development.
Action for retrieving Indoor Air Quality (IDA) in ppm intervals.
In order to return the CO2 in ppm intervals we link the action to the previousle defined state variable with the value set for IDA intervals.
We also provide a link the EU standard in the Reference field.
Finally we also add an action for turning the sensor device off.
For this action we also add an effect annotation, which simply states that at turn off, the latest observation will be cached.
Summary list of Actions and State Variables for the Service
Generate the code stub for this IoTResource
Now the code stubs for the Service and the IoTResource specified can be genererated.
The generated results include the Service definition in XML, as well as the development project files. The generated VS project is shown below.
This project can then be used by the developer to extend and refine the the service logics, for example, the GetIndoorAirQuality action above needs to provide code for the mapping of the ppm intervals.
The following XML encodes the resulting Service definitions.
