Difference between revisions of "Getting started with AGILE"

From AGILE IoT Wiki
Jump to: navigation, search
Line 7: Line 7:
 
== System Requirements ==
 
== System Requirements ==
 
What do you need to be able to install an run this Getting Started?
 
What do you need to be able to install an run this Getting Started?
{|
+
* a PC or a laptop
|-
+
* a '''Raspberry Pi 3 Model B''' (or a Pi 2 with a BLE dongle)  
|<ul><li>a PC or a laptop</li></ul> ||
+
* a '''microSD reader''' (or an SD reader and a microSD to SD adapter)
|-
+
* a good '''32GB''' '''microSD card''', such as a [http://www.samsung.com/us/computing/memory-storage/memory-cards/micro-sd-evo-32gb-memory-card-w-adapter-mb-mc32da-am/ Samsung EVO+] or a [https://www.sandisk.com/home/memory-cards/microsd-cards/ultra-microsd-48mbs SanDisk Ultra]
|<ul><li>a '''Raspberry Pi 3 Model B''' (or a Pi 2 with a BLE dongle)</li></ul> ||  [[File:9815 - Raspberry Pi 3.jpg|thumb|none|Raspberry Pi 3]]
+
* a [http://www.ti.com/tool/TIDC-CC2650STK-SENSORTAG TI SensorTag]
|-
+
* a LAN that assigns IP addresses through '''DHCP''', to which you are allowed to attach both the laptop and the Raspberry Pi.
|<ul><li>a '''microSD reader''' (or an SD reader and a microSD to SD adapter) </li></ul>||
+
<gallery>
|-
+
9815 - Raspberry Pi 3.jpg|Raspberry Pi 3
|<ul><li>a good '''32GB''' '''microSD card''', such as:</li></ul> ||<gallery>
+
Cc2650stk-sensortag 1 main.gif|SimpleLink Multi-Standard CC2650 SensorTag
 
Samsung SD32.png|[http://www.samsung.com/us/computing/memory-storage/memory-cards/micro-sd-evo-32gb-memory-card-w-adapter-mb-mc32da-am/ Samsung EVO+]
 
Samsung SD32.png|[http://www.samsung.com/us/computing/memory-storage/memory-cards/micro-sd-evo-32gb-memory-card-w-adapter-mb-mc32da-am/ Samsung EVO+]
 
SanDisk32.png|[https://www.sandisk.com/home/memory-cards/microsd-cards/ultra-microsd-48mbs SanDisk Ultra]
 
SanDisk32.png|[https://www.sandisk.com/home/memory-cards/microsd-cards/ultra-microsd-48mbs SanDisk Ultra]
 
</gallery>
 
</gallery>
|-
 
|<ul><li>a [http://www.ti.com/tool/TIDC-CC2650STK-SENSORTAG TI SensorTag]</li></ul> || [[File:Cc2650stk-sensortag 1 main.gif|thumb|none|SimpleLink Multi-Standard CC2650 SensorTag]]
 
|-
 
|<ul><li>a LAN that assigns IP addresses through '''DHCP''', <br />to which you are allowed to attach both the laptop and the Raspberry Pi.</li></ul>||
 
|}
 
  
 
== Install an AGILE image ==
 
== Install an AGILE image ==
 
We have prepared an image of the AGILE software that you can directly deploy on a microSD card which contains all the software you need to run this Getting Started. Another article will explain later on how to create such image. For a Getting Started we wanted to be as simple as possible on the setup to concentrate our work on AGILE by itself.
 
We have prepared an image of the AGILE software that you can directly deploy on a microSD card which contains all the software you need to run this Getting Started. Another article will explain later on how to create such image. For a Getting Started we wanted to be as simple as possible on the setup to concentrate our work on AGILE by itself.
 
# Download the AGILE image from the following link: [https://drive.google.com/uc?export=download&amp;id=0B1EQpziYo7krcUctZ1ZZSkNKeGc agile-rpi23-2016-11-09.img.gz]. This image is currently based on a Raspbian distribution. The next one will certainly be based on [https://resinos.io/ ResinOS].]
 
# Download the AGILE image from the following link: [https://drive.google.com/uc?export=download&amp;id=0B1EQpziYo7krcUctZ1ZZSkNKeGc agile-rpi23-2016-11-09.img.gz]. This image is currently based on a Raspbian distribution. The next one will certainly be based on [https://resinos.io/ ResinOS].]
# Google Drive will inform you that it can't scan this file for viruses. So you will have to trust us on this one ;-), and press the button '''Download anyway'''.<br/>[[File:GD-DownloadAnyway.png|border|thumb|none]]
+
# Google Drive will inform you that it can't scan this file for viruses. So you will have to trust us on this one ;-), and press the button '''Download anyway'''. [[File:GD-DownloadAnyway.png|border|thumb|right|Google Drive security question]]
 
# The AGILE image is compressed on a GZip format. Once the image is downloaded, '''unzip it''' with your favorite tool.
 
# The AGILE image is compressed on a GZip format. Once the image is downloaded, '''unzip it''' with your favorite tool.
 
# Connect your SD Reader containing your microSD card to your PC/laptop
 
# Connect your SD Reader containing your microSD card to your PC/laptop
Line 39: Line 34:
 
#*# The Etcher UI will ask you first to '''select the image''' (.img) you want to flash. Select the image you previously unzipped
 
#*# The Etcher UI will ask you first to '''select the image''' (.img) you want to flash. Select the image you previously unzipped
 
#*# Then the UI will ask you to '''select the SD Reader'''. Unless you have several SD readers connected to your machine, you should only have one choice.
 
#*# Then the UI will ask you to '''select the SD Reader'''. Unless you have several SD readers connected to your machine, you should only have one choice.
#*# Finally, press the '''Flash!''' button to start the transfer. <br />[[File:Etcher.io.png|border|thumb|none]]
+
#*# Finally, press the '''Flash!''' button to start the transfer. [[File:Etcher.io.png|border|thumb|right|Etcher UI]]
 
#*# Your OS will ask you, at least on MacOS, the Admin credential of your PC/laptop. Complete it to proceed with the burning process.
 
#*# Your OS will ask you, at least on MacOS, the Admin credential of your PC/laptop. Complete it to proceed with the burning process.
 
#*# Go and grab a coffee. flashing your microSD card will take some time... ;-) So, be patient, it might take some time to flash your SD card.<br /> One the flash is complete, close the Etcher app and eject the SD card
 
#*# Go and grab a coffee. flashing your microSD card will take some time... ;-) So, be patient, it might take some time to flash your SD card.<br /> One the flash is complete, close the Etcher app and eject the SD card
Line 48: Line 43:
 
== Run the sample ==
 
== Run the sample ==
 
=== Setup your configuration ===
 
=== Setup your configuration ===
# Connect your RPi to the power supply.<br />You can directly connect it to your PC/laptop; the RPi will not consume too much power in our case.
+
[[File:AGILE Config.jpg.jpg|thumb|right|Macbook HW setup]]
 +
# Connect your RPi to the power supply.<br />You can directly connect it to your PC/laptop; the RPi will not consume too much power in our case.  
 
# Connect your RPi to your LAN.<br />You can connect it to your router/switch or, if you have the adapter, you can directly connect it to the RJ45 attached to your PC/laptop
 
# Connect your RPi to your LAN.<br />You can connect it to your router/switch or, if you have the adapter, you can directly connect it to the RJ45 attached to your PC/laptop
# Here is how my configuration looks like : <br/>[[File:AGILE Config.jpg.jpg|thumb|none]]
 
  
 
=== Retrieve the IP address of your RPi ===
 
=== Retrieve the IP address of your RPi ===
 
Your RPi should be declared on your LAN with the name "agile". Open a console and try to ping it to verify. If the ping says it cannot resolve the agile name, it means that you will have to retrieve the IP address provided by the DHCP server of your LAN. For that, you can either retrieve this information if you have access to your DHCP server or you can use the great tool (for Mac) <a href="http://ivanx.com/raspberrypi/">PI Finder</a>. If you know another tool for Windows or Linux, please use the comments to share the information with us.
 
Your RPi should be declared on your LAN with the name "agile". Open a console and try to ping it to verify. If the ping says it cannot resolve the agile name, it means that you will have to retrieve the IP address provided by the DHCP server of your LAN. For that, you can either retrieve this information if you have access to your DHCP server or you can use the great tool (for Mac) <a href="http://ivanx.com/raspberrypi/">PI Finder</a>. If you know another tool for Windows or Linux, please use the comments to share the information with us.
 
# Load and install PI Finder on your Mac
 
# Load and install PI Finder on your Mac
# Launch PI Finder <br/> [[File:PiFinder-01.png|thumb|none]]
+
# Launch PI Finder  
 
# Press the Scan button to start scanning your network.
 
# Press the Scan button to start scanning your network.
# After while, a new dialog box will pop up providing the IP address found by PI Finder.<br/>In my case, it found our RPi at the IP address: '''192.168.2.6'''<br/>[[File:PiFinder-02.png|thumb|none]]
+
# After while, a new dialog box will pop up providing the IP address found by PI Finder.<br/>In my case, it found our RPi at the IP address: '''192.168.2.6'''  
 
# If PI Finder cannot find a RPi on your LAN, please verify you correctly installed the microSD card and you are correctly connected to your LAN.
 
# If PI Finder cannot find a RPi on your LAN, please verify you correctly installed the microSD card and you are correctly connected to your LAN.
 +
<gallery>
 +
PiFinder-01.png|PI Finder
 +
PiFinder-02.png|PI Finder results
 +
</gallery>
  
 
=== Access to the AGILE Web UI ===
 
=== Access to the AGILE Web UI ===
 +
[[File:AGILE-01.png|thumb|right|AGILE Welcome page]]
 
Now that we know the IP address of our RPi, we can connect to it by launching the AGILE Web UI.
 
Now that we know the IP address of our RPi, we can connect to it by launching the AGILE Web UI.
 
# Open a web browser and access to the following URL: '''http://&lt;rpi.ip&gt;:8000''' replace &lt;rpi.ip&gt; by the IP address you got on the previous step.. <br />In our case, we will use the following URL: http://192.168.2.6:8000/
 
# Open a web browser and access to the following URL: '''http://&lt;rpi.ip&gt;:8000''' replace &lt;rpi.ip&gt; by the IP address you got on the previous step.. <br />In our case, we will use the following URL: http://192.168.2.6:8000/
# The web browser will display the '''AGILE Welcome page'''. If it doesn't, wait for few more seconds, your image is certainly booting. <br />[[File:AGILE-01.png|thumb|none|AGILE Welcome page]]
+
# The web browser will display the '''AGILE Welcome page'''. If it doesn't, wait for few more seconds, your image is certainly booting.
  
 
Congratulations ! Your are connected to your AGILE image !
 
Congratulations ! Your are connected to your AGILE image !
  
 
=== Discover and connect to the BLE Sensor Tag ===
 
=== Discover and connect to the BLE Sensor Tag ===
# From the top left menu, launch the Device Manager by selecting the menu item '''Agile &gt; Device Manager''' <br />[[File:AGILE-02.png|thumb|none]] <br />It will open the Device Manager view on the devices currently registered on the platform. <br />[[File:AGILE-DM-01.png|thumb|none]]
+
# From the top left menu, launch the Device Manager by selecting the menu item '''Agile &gt; Device Manager''' <br />It will open the Device Manager view on the devices currently registered on the platform.  
# Click on the Device Manager Setting button [[File:AGILE-DM-02.png|none|none]] and turn on the Device Discovery switch: br />[[File:AGILE-DM-03.png|thumb|none]]
+
# Click on the Device Manager Setting button and turn on the Device Discovery switch:
# Close the Settings
+
# Close the Settings <gallery>
# It is time to use the TI SensorTag! <br/>Press the '''PowerOn''' button on your sensor tag. <br />[[File:SensorTag 01.jpg|thumb|none]] <br/>The green led should start blinking on the TI SensorTag indicating it is on the '''Service Discovery''' mode.
+
AGILE-02.png|Device Manager menu item
 +
AGILE-DM-01.png|Registered Devices
 +
AGILE-DM-02.png|Setting button
 +
AGILE-DM-03.png|Device Discovery switch
 +
</gallery>
 +
# It is time to use the TI SensorTag! <br/>Press the '''PowerOn''' button on your sensor tag. <br/>The green led should start blinking on the TI SensorTag indicating it is on the '''Service Discovery''' mode.
 
# From the Device Manager view, click on the '''DISCOVER''' tab to display all devices AGILE is able to see currently around you.
 
# From the Device Manager view, click on the '''DISCOVER''' tab to display all devices AGILE is able to see currently around you.
# Find a device named '''CC2650 SensorTag'''. It is your TI SensorTag. <br />[[File:AGILE-DM-04.png|thumb|none]]
+
# Find a device named '''CC2650 SensorTag'''. It is your TI SensorTag.  
# Press the '''REGISTER''' link to connect your Sensor to the AGILE gateway.<br/>It will automatically switch back to DEVICES list and you should be able to see in the list your tag listed. <br />[[File:AGILE-DM-05.png|thumb|none]]
+
# Press the '''REGISTER''' link to connect your Sensor to the AGILE gateway.<br/>It will automatically switch back to DEVICES list and you should be able to see in the list your tag listed.  
# Click on the name  '''CC2650 SensorTag''' to view the currently available features.<br />[[File:AGILE-DM-06.png|thumb|none]]<br />As you can notice, the current implementation of this device covers only a subset of the feature actually provided by TI:
+
# Click on the name  '''CC2650 SensorTag''' to view the currently available features.<br />As you can notice, the current implementation of this device covers only a subset of the feature actually provided by TI:
 
#* Temperature,
 
#* Temperature,
 
#* Humidity,
 
#* Humidity,
 
#* Pressure and
 
#* Pressure and
 
#* Optical/Luminosity.
 
#* Optical/Luminosity.
 +
<gallery>
 +
SensorTag 01.jpg|Power ON button
 +
AGILE-DM-04.png|SensorTag list item
 +
AGILE-DM-05.png|The SensorTag is registered
 +
AGILE-DM-06.png|Feature details on the SensorTag
 +
</gallery>
  
 
=== Build a sample with Node-RED ===
 
=== Build a sample with Node-RED ===
Line 86: Line 97:
 
We will create from scratch a Node-RED flow connecting to a Web Socket gathering data from your BLE Sensor and sending them to a MQTT broker to be displayed on a web UI.
 
We will create from scratch a Node-RED flow connecting to a Web Socket gathering data from your BLE Sensor and sending them to a MQTT broker to be displayed on a web UI.
 
# From the AGILE Web UI, launch the Node-RED editor by selecting the menu item '''Agile &gt; NodeRed'''
 
# From the AGILE Web UI, launch the Node-RED editor by selecting the menu item '''Agile &gt; NodeRed'''
# Look for the '''websocket''' input node, on the left section <br/>[[File:NR-01.png|thumb|none]]
+
# Look for the '''websocket''' input node, on the left section  
# Drag&amp;Drop the '''websocket''' node into the current flow <br />[[File:NR-02.png|thumb|none]]
+
# Drag&amp;Drop the '''websocket''' node into the current flow  
 
# Double-click on the node you just dropped to edit it.
 
# Double-click on the node you just dropped to edit it.
 
## Select '''Connect to''' on the '''Type''' combo-box field
 
## Select '''Connect to''' on the '''Type''' combo-box field
## For editing the '''Path''', click on the pencil button [[File:NR-03.png|none]], it will open a second editor to specify the WebSocket URL
+
## For editing the '''Path''', click on the pencil button, it will open a second editor to specify the WebSocket URL
 
## Type the following URL in the '''Path''' field:<br />'''ws://&lt;rpi.ip&gt;:8080/ws/device/&lt;device ID&gt;/Temperature/subscribe'''
 
## Type the following URL in the '''Path''' field:<br />'''ws://&lt;rpi.ip&gt;:8080/ws/device/&lt;device ID&gt;/Temperature/subscribe'''
 
##* replacing &lt;rpi.ip&gt; by the IP of your RPi
 
##* replacing &lt;rpi.ip&gt; by the IP of your RPi
##* and &lt;device ID&gt; by the ID of your TI SensorTag.<br/>You can retrieve the ID of your sensor on the Device Manager. Actually, this is the ID specified in the header of the device:<br/>[[File:NR-05.png|thumb|none]] <br/>My URL looks like that: <br/>ws://192.168.2.6:8080/ws/device/ble247189E95285/Temperature/subscribe <br/>[[File:NR-04.png|thumb|none]]
+
##* and &lt;device ID&gt; by the ID of your TI SensorTag.<br/>You can retrieve the ID of your sensor on the Device Manager. Actually, this is the ID specified in the header of the device:<br/>My URL looks like that: <br/>ws://192.168.2.6:8080/ws/device/ble247189E95285/Temperature/subscribe  
 
## Press the '''Add''' button to return to the node editor
 
## Press the '''Add''' button to return to the node editor
## Type in the '''Name''' field, for example, '''Temperature'''<br/>[[File:NR-06.png|thumb|none]]
+
## Type in the '''Name''' field, for example, '''Temperature'''
 
## Press the '''Done''' button to save your changes.
 
## Press the '''Done''' button to save your changes.
# We will add now a '''debug''' node to display the content of the message payload produced by the '''websocket''' node
+
<gallery>
 +
NR-01.png|WebSocket node
 +
NR-03.png|Pencil button
 +
NR-05.png|SensorTag ID
 +
NR-04.png|WebSocket path editor
 +
NR-06.png|WebSocket node editor
 +
</gallery>
 +
# We will add now a '''debug''' node to display the content of the message payload produced by the '''websocket''' node  
 
## Look for the '''debug''' out node, on the left section
 
## Look for the '''debug''' out node, on the left section
 
## Drag&amp;Drop the '''debug''' node into the current flow
 
## Drag&amp;Drop the '''debug''' node into the current flow
 
## Double-click on the '''debug''' node to name it '''Log'''
 
## Double-click on the '''debug''' node to name it '''Log'''
 
## Connect the output port of the '''websocket''' node to the input port of the '''debug''' node by dragging between the output port of one to the input port of the other.
 
## Connect the output port of the '''websocket''' node to the input port of the '''debug''' node by dragging between the output port of one to the input port of the other.
## At this point your flow should look like this: <br/>[[File:NR-08.png|thumb|none]]
+
# We can already test this flow:  
# We can already test this flow:
+
## Press the '''Deploy''' button on the top right of the Node-RED editor  
## Press the '''Deploy''' button on the top right of the Node-RED editor <br/>[[File:NR-07.png|thumb|none]]
+
## The flow has a little bit changed: the '''websocket''' node informs you it is connected and the '''debug''' node is turned ON:
## The flow has a little bit changed: the '''websocket''' node informs you it is connected and the '''debug''' node is turned ON:<br />[[File:NR-09.png|thumb|none]]
+
## To see the log, click on the '''debug''' tab on the right part of the editor and you will see the displayed trace  
## To see the log, click on the '''debug''' tab on the right part of the editor and you will see the displayed trace <br />[[File:NR-10.png|thumb|none]]
+
## You can interrupt the log, not the flow, anytime by switching off the '''debug''' node and re-deploy the flow.  
## You can interrupt the log, not the flow, anytime by switching off the '''debug''' node and re-deploy the flow. <br />[[File:NR-11.png|thumb|none]]
+
<gallery>
 +
NR-08.png|Debug node
 +
NR-07.png|Deploy button
 +
NR-09.png|Deployed flow
 +
NR-10.png|Flow log
 +
NR-11.png|Turn ON/OFF debug node
 +
</gallery>
 
# Let proceed by extracting the value of the temperature from the JSON message . For that we need a '''function''' node.
 
# Let proceed by extracting the value of the temperature from the JSON message . For that we need a '''function''' node.
 
# Once you have drag&amp;dropped a '''function''' node into your flow, connect the output port of the '''websocket''' to the input port of the '''function''' node.
 
# Once you have drag&amp;dropped a '''function''' node into your flow, connect the output port of the '''websocket''' to the input port of the '''function''' node.
Line 119: Line 143:
 
## Press the Done button to close the '''function''' editor.
 
## Press the Done button to close the '''function''' editor.
 
# Feel free to redirect the output port to the debug node to verify that the code you wrote extracts properly the value of the temperature.
 
# Feel free to redirect the output port to the debug node to verify that the code you wrote extracts properly the value of the temperature.
# We will now push this value to an MQTT broker on the cloud to be able to subscribe to this data stream from any MQTT client. To do that, we need to add a '''MQTT out''' node to our current flow. <br/>[[File:NR-12.png|thumb|none]]
+
# We will now push this value to an MQTT broker on the cloud to be able to subscribe to this data stream from any MQTT client. To do that, we need to add a '''MQTT out''' node to our current flow.  
 
# Double-click on the '''MQTT out''' node to edit it
 
# Double-click on the '''MQTT out''' node to edit it
## For the Server filed, click on the pencil button [[File:NR-03.png|none|none]] to specify the MQTT broker you want to reach.
+
## For the Server field, click on the pencil button to specify the MQTT broker you want to reach.
 
## For the purpose of this Getting Started, we will designate the Eclipse IoT MQTT broker by specifying '''iot.eclipse.org''' in the '''Server''' field.
 
## For the purpose of this Getting Started, we will designate the Eclipse IoT MQTT broker by specifying '''iot.eclipse.org''' in the '''Server''' field.
 
## Leave the port number (1883) unchanged and close this dialog by pressing the '''Add''' button.
 
## Leave the port number (1883) unchanged and close this dialog by pressing the '''Add''' button.
 
## You should be back at the '''MQTT out''' node editor. On the Topic field, type the following topic name: <br/>'''javaonedemo/agile/sensors/temperature''' <br/>This ID could be simpler but, because we want to be able to reuse to an existing [https://iot.eclipse.org/java/tutorial/ MQTT client demo], we have to use this syntax.
 
## You should be back at the '''MQTT out''' node editor. On the Topic field, type the following topic name: <br/>'''javaonedemo/agile/sensors/temperature''' <br/>This ID could be simpler but, because we want to be able to reuse to an existing [https://iot.eclipse.org/java/tutorial/ MQTT client demo], we have to use this syntax.
## At this point name the node , for example, '''iot.eclipse.org''',  and close the editor by pressing the '''Done''' button <br/>[[File:NR-13.png|thumb|none]]
+
## At this point name the node , for example, '''iot.eclipse.org''',  and close the editor by pressing the '''Done''' button  
 
# You still need to connect to output port of your '''function''' node to the input port of the''' MQTT out''' node and you should be all set.
 
# You still need to connect to output port of your '''function''' node to the input port of the''' MQTT out''' node and you should be all set.
# Now you can deploy the resulting flow and you should be all set. <br />[[File:NR-14.png|thumb|none]]
+
# Now you can deploy the resulting flow and you should be all set.  
 +
<gallery>
 +
NR-12.png|MQTT output node
 +
NR-13.png|MQTT node editor
 +
NR-14.png|Completed flow
 +
</gallery>
  
 
=== Connect to the MQTT broker ===
 
=== Connect to the MQTT broker ===
At this point, our sample is collecting temperature data from our Sensor and it is sending them to a MQTT broker on the cloud.
+
At this point, our sample is collecting temperature data from our Sensor and it is sending them to a MQTT broker on the cloud. [[File:AGILE-03.png|thumb|right|Web interface]]
  
# You can directly test if the sample works properly by opening this page from any web browser: https://iot.eclipse.org/java/demo/app/#/greenhouses/remote/agile. It will open a web page with the following dashboard: <br/>[[File:AGILE-03.png|thumb|none]]
+
# You can directly test if the sample works properly by opening this page from any web browser: https://iot.eclipse.org/java/demo/app/#/greenhouses/remote/agile. It will open a web page with the following dashboard:  
 
# If you warm up your TI SensorTag, the dashboard should display a new value.
 
# If you warm up your TI SensorTag, the dashboard should display a new value.
 +
# You can also test this URL from your smartphone, you will be able to access to the same realtime value
  
 
<blockquote>If the UI doesn't seem to behave as expected, maybe somebody else is already running this Getting Started. In this case, we recommend you to change the MQTT broker topic we defined in the previous section for something else. Actually, the only token you can really change in the provided syntax will be the "'''agile'''" name in "javaonedemo/'''agile'''/sensors/temperature". For example, you could change to "javaonedemo/'''agile-01'''/sensors/temperature". In this case, the URL to reach your temperature sensor will have to change as well for https://iot.eclipse.org/java/demo/app/#/greenhouses/remote/'''agile-01'''. Don't forget to re-deploy your flow.</blockquote>
 
<blockquote>If the UI doesn't seem to behave as expected, maybe somebody else is already running this Getting Started. In this case, we recommend you to change the MQTT broker topic we defined in the previous section for something else. Actually, the only token you can really change in the provided syntax will be the "'''agile'''" name in "javaonedemo/'''agile'''/sensors/temperature". For example, you could change to "javaonedemo/'''agile-01'''/sensors/temperature". In this case, the URL to reach your temperature sensor will have to change as well for https://iot.eclipse.org/java/demo/app/#/greenhouses/remote/'''agile-01'''. Don't forget to re-deploy your flow.</blockquote>
 
&nbsp;
 
&nbsp;

Revision as of 16:42, 22 March 2017

Introduction

This document presents in simple steps how to install and run the AGILE software on your Raspberry Pi 3. We will present:

  • How to install an image of AGILE on a Raspberry Pi (RPi)
  • How to discover and connect a BLE (Bluetooth Low Energy) device to the AGILE gateway
  • Finally, we will test the resulting  connection by designing and deploying a Node-RED flow

System Requirements

What do you need to be able to install an run this Getting Started?

  • a PC or a laptop
  • a Raspberry Pi 3 Model B (or a Pi 2 with a BLE dongle)
  • a microSD reader (or an SD reader and a microSD to SD adapter)
  • a good 32GB microSD card, such as a Samsung EVO+ or a SanDisk Ultra
  • a TI SensorTag
  • a LAN that assigns IP addresses through DHCP, to which you are allowed to attach both the laptop and the Raspberry Pi.

Install an AGILE image

We have prepared an image of the AGILE software that you can directly deploy on a microSD card which contains all the software you need to run this Getting Started. Another article will explain later on how to create such image. For a Getting Started we wanted to be as simple as possible on the setup to concentrate our work on AGILE by itself.

  1. Download the AGILE image from the following link: agile-rpi23-2016-11-09.img.gz. This image is currently based on a Raspbian distribution. The next one will certainly be based on ResinOS.]
  2. Google Drive will inform you that it can't scan this file for viruses. So you will have to trust us on this one ;-), and press the button Download anyway.
    Google Drive security question
  3. The AGILE image is compressed on a GZip format. Once the image is downloaded, unzip it with your favorite tool.
  4. Connect your SD Reader containing your microSD card to your PC/laptop
  5. To flash your microSD card, you can
    • either used your favorite microSD flashing tool,
    • or learn from this page RPi Easy SD Card Setup,
    • or directly use the Etcher by Resin.io, the great open source SD burner developed by our project partner Resin.io.
      On the next steps, we will describe how to use Etcher for flashing your microSD card.
      1. Download and install Etcher by Resin.io on your PC/laptop
      2. Launch the Etcher application
      3. The Etcher UI will ask you first to select the image (.img) you want to flash. Select the image you previously unzipped
      4. Then the UI will ask you to select the SD Reader. Unless you have several SD readers connected to your machine, you should only have one choice.
      5. Finally, press the Flash! button to start the transfer.
        Etcher UI
      6. Your OS will ask you, at least on MacOS, the Admin credential of your PC/laptop. Complete it to proceed with the burning process.
      7. Go and grab a coffee. flashing your microSD card will take some time... ;-) So, be patient, it might take some time to flash your SD card.
        One the flash is complete, close the Etcher app and eject the SD card
  6. Once the the flashing is completed, eject your SD reader from your PC/laptop and remove the microSD card from the reader.
  7. Verify that your RPi is turned OFF
  8. Slide the microSD card into the  RPi microSD driver.

Run the sample

Setup your configuration

Macbook HW setup
  1. Connect your RPi to the power supply.
    You can directly connect it to your PC/laptop; the RPi will not consume too much power in our case.
  2. Connect your RPi to your LAN.
    You can connect it to your router/switch or, if you have the adapter, you can directly connect it to the RJ45 attached to your PC/laptop

Retrieve the IP address of your RPi

Your RPi should be declared on your LAN with the name "agile". Open a console and try to ping it to verify. If the ping says it cannot resolve the agile name, it means that you will have to retrieve the IP address provided by the DHCP server of your LAN. For that, you can either retrieve this information if you have access to your DHCP server or you can use the great tool (for Mac) <a href="http://ivanx.com/raspberrypi/">PI Finder</a>. If you know another tool for Windows or Linux, please use the comments to share the information with us.

  1. Load and install PI Finder on your Mac
  2. Launch PI Finder
  3. Press the Scan button to start scanning your network.
  4. After while, a new dialog box will pop up providing the IP address found by PI Finder.
    In my case, it found our RPi at the IP address: 192.168.2.6
  5. If PI Finder cannot find a RPi on your LAN, please verify you correctly installed the microSD card and you are correctly connected to your LAN.

Access to the AGILE Web UI

AGILE Welcome page

Now that we know the IP address of our RPi, we can connect to it by launching the AGILE Web UI.

  1. Open a web browser and access to the following URL: http://<rpi.ip>:8000 replace <rpi.ip> by the IP address you got on the previous step..
    In our case, we will use the following URL: http://192.168.2.6:8000/
  2. The web browser will display the AGILE Welcome page. If it doesn't, wait for few more seconds, your image is certainly booting.

Congratulations ! Your are connected to your AGILE image !

Discover and connect to the BLE Sensor Tag

  1. From the top left menu, launch the Device Manager by selecting the menu item Agile > Device Manager
    It will open the Device Manager view on the devices currently registered on the platform.
  2. Click on the Device Manager Setting button and turn on the Device Discovery switch:
  3. Close the Settings
  • Device Manager menu item

  • Registered Devices

  • Setting button

  • Device Discovery switch

    1. It is time to use the TI SensorTag!
      Press the PowerOn button on your sensor tag.
      The green led should start blinking on the TI SensorTag indicating it is on the Service Discovery mode.
    2. From the Device Manager view, click on the DISCOVER tab to display all devices AGILE is able to see currently around you.
    3. Find a device named CC2650 SensorTag. It is your TI SensorTag.
    4. Press the REGISTER link to connect your Sensor to the AGILE gateway.
      It will automatically switch back to DEVICES list and you should be able to see in the list your tag listed.
    5. Click on the name  CC2650 SensorTag to view the currently available features.
      As you can notice, the current implementation of this device covers only a subset of the feature actually provided by TI:
      • Temperature,
      • Humidity,
      • Pressure and
      • Optical/Luminosity.

    Build a sample with Node-RED

    Node-RED is the current developer’s environment to create AGILE apps.

    We will create from scratch a Node-RED flow connecting to a Web Socket gathering data from your BLE Sensor and sending them to a MQTT broker to be displayed on a web UI.

    1. From the AGILE Web UI, launch the Node-RED editor by selecting the menu item Agile > NodeRed
    2. Look for the websocket input node, on the left section
    3. Drag&Drop the websocket node into the current flow
    4. Double-click on the node you just dropped to edit it.
      1. Select Connect to on the Type combo-box field
      2. For editing the Path, click on the pencil button, it will open a second editor to specify the WebSocket URL
      3. Type the following URL in the Path field:
        ws://<rpi.ip>:8080/ws/device/<device ID>/Temperature/subscribe
        • replacing <rpi.ip> by the IP of your RPi
        • and <device ID> by the ID of your TI SensorTag.
          You can retrieve the ID of your sensor on the Device Manager. Actually, this is the ID specified in the header of the device:
          My URL looks like that:
          ws://192.168.2.6:8080/ws/device/ble247189E95285/Temperature/subscribe
      4. Press the Add button to return to the node editor
      5. Type in the Name field, for example, Temperature
      6. Press the Done button to save your changes.
    1. We will add now a debug node to display the content of the message payload produced by the websocket node
      1. Look for the debug out node, on the left section
      2. Drag&Drop the debug node into the current flow
      3. Double-click on the debug node to name it Log
      4. Connect the output port of the websocket node to the input port of the debug node by dragging between the output port of one to the input port of the other.
    2. We can already test this flow:
      1. Press the Deploy button on the top right of the Node-RED editor
      2. The flow has a little bit changed: the websocket node informs you it is connected and the debug node is turned ON:
      3. To see the log, click on the debug tab on the right part of the editor and you will see the displayed trace
      4. You can interrupt the log, not the flow, anytime by switching off the debug node and re-deploy the flow.
    1. Let proceed by extracting the value of the temperature from the JSON message . For that we need a function node.
    2. Once you have drag&dropped a function node into your flow, connect the output port of the websocket to the input port of the function node.
    3. Double-click on the function node to edit it
      1. Name the node Extract Temperature
      2. In the Function field, type the following JavaScript code:
        var json = JSON.parse(msg.payload);
        msg.payload = json.value;
        return msg;
      3. Press the Done button to close the function editor.
    4. Feel free to redirect the output port to the debug node to verify that the code you wrote extracts properly the value of the temperature.
    5. We will now push this value to an MQTT broker on the cloud to be able to subscribe to this data stream from any MQTT client. To do that, we need to add a MQTT out node to our current flow.
    6. Double-click on the MQTT out node to edit it
      1. For the Server field, click on the pencil button to specify the MQTT broker you want to reach.
      2. For the purpose of this Getting Started, we will designate the Eclipse IoT MQTT broker by specifying iot.eclipse.org in the Server field.
      3. Leave the port number (1883) unchanged and close this dialog by pressing the Add button.
      4. You should be back at the MQTT out node editor. On the Topic field, type the following topic name:
        javaonedemo/agile/sensors/temperature
        This ID could be simpler but, because we want to be able to reuse to an existing MQTT client demo, we have to use this syntax.
      5. At this point name the node , for example, iot.eclipse.org,  and close the editor by pressing the Done button
    7. You still need to connect to output port of your function node to the input port of the MQTT out node and you should be all set.
    8. Now you can deploy the resulting flow and you should be all set.

    Connect to the MQTT broker

    At this point, our sample is collecting temperature data from our Sensor and it is sending them to a MQTT broker on the cloud.
    Web interface
    1. You can directly test if the sample works properly by opening this page from any web browser: https://iot.eclipse.org/java/demo/app/#/greenhouses/remote/agile. It will open a web page with the following dashboard:
    2. If you warm up your TI SensorTag, the dashboard should display a new value.
    3. You can also test this URL from your smartphone, you will be able to access to the same realtime value
    If the UI doesn't seem to behave as expected, maybe somebody else is already running this Getting Started. In this case, we recommend you to change the MQTT broker topic we defined in the previous section for something else. Actually, the only token you can really change in the provided syntax will be the "agile" name in "javaonedemo/agile/sensors/temperature". For example, you could change to "javaonedemo/agile-01/sensors/temperature". In this case, the URL to reach your temperature sensor will have to change as well for https://iot.eclipse.org/java/demo/app/#/greenhouses/remote/agile-01. Don't forget to re-deploy your flow.