How to publish IoT data/services from your own IoT environment (Scriptshell)

Tutorial showing how to publish your own IoT services/data using the

O-MI/O-DF reference implementation

1

© bIoTope Consortium 2

Tutorial showing how to publish your own IoT services/data using the O-MI/O-DF reference implementation

Internal Agent External Agents

Node-Red Shell scripts …

Available Tutorials

Scala (see GitHub)

Java (see GitHub)

https://github.com/AaltoAsia/O-MI


Tutorial: How to build an external agent with Node-red for publishing (Create) &

Updating (Update) the state of a Philips Hue Light using the O-MI reference implementation (via SHELL scripts)

3

bIoTope 4

Prerequisites1 computer Windows ou Linux/MAC with the following tools installed or directory downloaded:

• the O-MI reference implementation: https://github.com/AaltoAsia/O-MI ✦ direct URL: https://github.com/AaltoAsia/O-MI/releases/tag/0.6.4 (choose “o-mi-node-0.6.4.zip”)

=> Note: Java 1.8 is required.

• Shell scripts: https://github.com/jrobert-github/O-MI_Shell_Agent

• JSON parser library JQ: https://stedolan.github.io/jq/download/


https://github.com/AaltoAsia/O-MI/releases/tag/0.6.4

https://github.com/jrobert-github/O-MI_Shell_Agent

https://stedolan.github.io/jq/download/

Build the O-DF Service Tree related to the Philips Hue light using the

O-MI reference implementation (via SHELL scripts)

5

Build the O-DF Service Tree related to the Philips Hue light using the O-MI reference implementation (via SHELL scripts)

6

1. Start your O-MI node

To start the O-MI ref. implem., run the corresponding startup script from the bin directory for your OS:• Windows: double-click on the file o-mi-node.bat in the bin/ directory• Unix and Mac: open a terminal, and run the file o-mi-node in the bin/ directory (Might be needed to add

the Write access to the directory: chmod +x)

Exemple for Mac

7

2. Launch the reference implementation in your favorite browser at the following URL: http://localhost:8080/html/webclient/index.html


http://localhost:8080/html/webclient/index.html

8

the postal address of the Object named “JeremysHouse”the Object related to the Smart Light (Philips Hue Light in our case)

the state of the light’s brightness (Philips Hue Light’s property)value: "Specify the brightness of the light” (for human understanding)Two Metadata: range of accepted Values & additional Documentation

the state of the light (on or off)value: "Switch on/off the light"

3. Add the O-DF structure related to the Philips Hue light

The following O-DF structure will be created — using — by following the guidelines given in the next slides:


9

Postal address value

Light’s brightness state"Specify the brightness…Range of Values & DocumentationLight state (on or off)"Switch on/off the light"

=

3. Add the O-DF structure related to the Philips Hue light A. Inside the “agent” directory, edit the file: define_odf.sh as follows; Understanding the matching between the O-DF tree

(right picture) and the Shell script (left picture) should be straightforward


Every time you’ll see a red dashed frame, it means that you need to adapt the code depending on your application and the underlying infrastructure (technologies, network configuration…)

10

Postal address value

Light’s brightness state"Specify the brightness…Range of Values & DocumentationLight state (on or off)"Switch on/off the light"

=


(right picture) and the Shell script (left picture) should be straightforward


11


(right picture) and the Shell script (left picture) should be straightforwardB. Edit the file: define_omi.sh to configure the O-MI node that you’re going to update with your “service list/tree”

NOTE:

In this demo, everything is done locally. If you want to use the O-MI write request on remote O-MI reference implementations, you will need to specify/add the write access rights to a configuration file in the O-MI reference implementation (See Appendix A).


12


(right picture) and the Shell script (left picture) should be straightforwardB. Edit the file: define_omi.sh to configure the O-MI node that you’re going to update with your “service list/tree”C. Inside the “bin” directory, execute the following script: ./create_odf.sh

• If you go to your O-MI ref. implem. webpage and click on “Read All” again, you should now see the“service list/tree” (cf. below screenshot)


Creation of the “External agent” for updating and listening the state of the smart light

13


14

1. Write/Update the OMI node (i.e., InfoItem) with the current state of the light

Hue API

O-MI/O-DF

15

1. Write/Update the OMI node (i.e., InfoItem) with the current state of the light A. Inside the “agent” directory, edit the file: define_values.sh as below (technology-/platform-dependent);


Note: This file defines how to access the Philips Hug Light’s API to retrieve the real-time light values (brightness, on…) => the two data items being retrieved — API’s output being a JSON — are “state.on” and “state.bri”.Then, we update with the retrieved values the “SmartLight_values” variable (i.e. InfoItems named “On” and “Brightness” in our Service tree).

Hue API

16

Hue API

O-MI/O-DF


1. Write/Update the OMI node (i.e., InfoItem) with the current state of the light A. Inside the “agent” directory, edit the file: define_values.sh as below (technology-/platform-dependent); B. Inside the “bin” directory, the following script: ./update_ref_implem.sh can

• Without argument/parameter: ✦ Every time you execute the command, the O-MI ref. implem., or the corresponding InfoItems to be more precise

(“Brightness” & “ON”), will be updated with the real-time light values;✦ (UNIX only): you can add the following line to the “crontab” file, which in this specific case will update the values

every 10min. - */10 * * * * /<File_Path>/update_ref_implem.sh> /dev/null

• With argument/parameter: ✦ If you execute the following command, the O-MI ref. implem., or the corresponding InfoItems to be more precise

(“Brightness” & “ON”), will be updated based on the requested period, which is specified as input parameter/argument (in second; 50s in the below example);

- ./update_ref_implem.sh 50

Every time the state of the Philips Hue Light is “crawled/checked”, the O-MI ref. implem., or the corresponding InfoItems to be more precise (named “Brightness” & “ON” in our O-DF Service Tree), will be updated accordingly!

2. "Listen" if any change occurs on the OMI ref. implem. so as to propagate it up to the Smart Hue light

17

O-MI/O-DF

Hue API

Sylvain sends an O-MI Write request to turn Smart bulb OFF!NOTE: Sylvain is not aware of and doesn’t have to care about what Smart Bulb technology Jérémy is using as backend platform (the Write message will remain the same!!)

External actor(Sylvain)

Our Node-Red agent will update the state as requested (if Sylvain has the

sufficient access rights)


Jéré

my’

s Io

T en

viro

nmen

t

18


1. "Listen" the modification of the OMI node to modify the state of the light A. Inside the “bin” directory, the following script: ./update_device can

• Without argument/parameter: ✦ Every time you execute the command, the device (smart light), or the corresponding properties to be more precise

(“bri” & “on”), will be updated with the value specified inside the O-MI Read response;• With argument/parameter:

✦ If you execute the following command, the device (smart light), or the corresponding InfoItems to be more precise (“bri” & “on”), will be updated based on the requested period, which is specified as input parameter/argument;

- ./update_device.sh 50


O-MI/O-DF

Jéré

my’

s Io

T en

viro

nmen

t

To note: Ideally, the “event-based” subscription mechanism supported by O-MI should be used so as to listen and update the device’s values when a change occurs (i.e., we would only need to perform the command: ./update_device).

19

Creation of the “External agent” for updating and listening the state of the smart lightCreation of the “External agent” for updating and listening the state of the smart light

Hue API

O-MI/O-DF

Jéré

my’

s Io

T en

viro

nmen

t

To note: Ideally, the “event-based” subscription mechanism supported by O-MI should be used so as to listen and update the device’s values when a change occurs (i.e., we would only need to perform the command: ./update_device).

1. "Listen" the modification of the OMI node to modify the state of the light A. Inside the “bin” directory, the following script: ./update_device can

• Without argument/parameter: ✦ Every time you execute the command, the device (smart light), or the corresponding properties to be more precise

(“bri” & “on”), will be updated with the value specified inside the O-MI Read response;• With argument/parameter:

✦ If you execute the following command, the device (smart light), or the corresponding InfoItems to be more precise (“bri” & “on”), will be updated based on the requested period, which is specified as input parameter/argument;

- ./update_device.sh 50

20

Standardised Service Description & Messaging Interfaces (O-MI/O-DF)

Smart City

●!

●✇ ●●

●!

●✇ ●● ●!

"●●

ABot

tle

Bank

●● ●●

###

Shopping Center

$$$

%&&%

✈

'❍

●!"!!!

!School

%&&

%●School Bus

●●

Manufacturer

●✇ ●●

●✇ ●●

●✇ ●●

✙

✚●● ●●

H

●●●

ALandfill site

Information-as-a-Service

O-MI n

ode U

RL

1

bIoTope Service Marketplace: IoTBnB

$

http://85.171.192.185

Join the bIoTope ecosystem and Share amazing services &

IoT data with our members

http://jeremyshouse.jeremy-robert.fr







http://85.171.192.185


BIOTOPE H2020 R&I GRANT: N° 688203

Tutorial created by: • Dr. Jérémy ROBERT • Dr. Sylvain KUBLER


APPENDIX A

23

1. To be written A. To be written

24

Specify/add the write access rights to a configuration file in the O-MI reference implementation

Internet

How to publish IoT data/services from your own IoT environment (Scriptshell)