Difference between revisions of "Getting started with AGILE"

From AGILE IoT Wiki
Jump to: navigation, search
(Created page with "== 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 im...")
 
 
(52 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
== Introduction ==
 
== Introduction ==
This document presents in simple steps how to install and run the '''AGILE''' software on your '''Raspberry Pi 3'''. We will present:
+
This is an easy step-by-step guide 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 install an image of AGILE on a Raspberry Pi (RPi). <br/>This document should work on Mac, Linux or Windows. We made our best to always choose a feature or an application available on all 3 platforms.
 
* How to discover and connect a '''BLE''' (Bluetooth Low Energy) device to the AGILE gateway
 
* 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 '''[https://nodered.org/ Node-RED] flow'''
+
* Finally, we will test the resulting connection by designing and deploying a '''[https://nodered.org/ Node-RED] flow'''
  
 
== 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)  
|* a PC or a laptop ||
+
* a '''microSD reader''' (or an SD reader and a microSD to SD adapter)
|-
+
* a good '''32GB''' '''microSD card''', like 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]
|* a '''Raspberry Pi 3 Model B''' (or a Pi 2 with a BLE dongle) ||  [[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.
|* a '''microSD reader''' (or an SD reader and a microSD to SD adapter) ||
+
<gallery>
|-
+
9815 - Raspberry Pi 3.jpg|Raspberry Pi 3
|* a good '''32GB''' '''microSD card''', such as: ||<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>
|-
 
|* a <a href="http://www.ti.com/tool/TIDC-CC2650STK-SENSORTAG">TI SensorTag</a> || [[File:Cc2650stk-sensortag 1 main.gif|thumb|none|SimpleLink Multi-Standard CC2650 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 ==
 
== 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 contains all the software you need to run this Getting Started and can directly be deployed on a microSD card. This guide was prepared with the Raspbian based v0.3.3 image of AGILE, however, we advise to use the most recent version.
# Download the AGILE image from the following link: , the current one is here: <a href="https://drive.google.com/uc?export=download&amp;id=0B1EQpziYo7krcUctZ1ZZSkNKeGc">agile-rpi23-2016-11-09.img.gz. </a>[PK: his image is currently based on a Raspbian distribution. The next one will certainly be based on <a href="https://resinos.io/">ResinOS</a>.]
+
# Download the AGILE image from the following link: [[AGILE_SD_images]].
# 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 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]]
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/GD-DownloadAnyway.png"><img class="alignnone wp-image-1229 size-full" src="http://agile-iot.eu/wp-content/uploads/2017/03/GD-DownloadAnyway.png" alt="" width="534" height="195" data-wp-pid="1229" /></a>
 
 
# 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
# To flash your microSD card, you can
+
# To flash your microSD card, you can either
** either used your favorite microSD flashing tool,
+
#* use your favorite microSD flashing tool,
** or learn from this page <a href="http://elinux.org/RPi_Easy_SD_Card_Setup">RPi Easy SD Card Setup</a>,
+
#* learn from this page [http://elinux.org/RPi_Easy_SD_Card_Setup RPi Easy SD Card Setup],
** >or directly use the <a href="https://etcher.io/">Etcher by Resin.io</a>, the great open source SD burner developed by our project partner <a href="http://agile-iot.eu/team_member/resin.io/">Resin.io</a>.
+
#* use [https://etcher.io/ Etcher by Resin.io], the great open source SD burner developed by our project partner [http://agile-iot.eu/team_member/resin.io/ Resin.io]. <br />In the next steps, we will describe how to use Etcher to flash your microSD card.
On the next steps, we will describe how to use Etcher for flashing your microSD card.
+
#*# Download and install [https://etcher.io/ Etcher by Resin.io] on your PC/laptop. This tool works on Mac, Linux and Windows.
 
+
#*# Launch the Etcher application
# Download and install <a href="https://etcher.io/">Etcher by Resin.io</a> on your PC/laptop
+
#*# The Etcher UI will ask you first to '''select the image''' (.img) you want to flash. Select the image you previously unzipped
# Launch the Etcher application
+
#*# 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.
# The Etcher UI will ask you first to '''select the image''' (.img) you want to flash. Select the image you previously unzipped
+
#*# Finally, press the '''Flash!''' button to start the transfer. [[File:Etcher.io.png|border|thumb|right|Etcher UI]]
# 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.
+
#*# Your OS will ask you, at least on MacOS, the Admin credential of your PC/laptop. Complete it to proceed with the burning process.
# Finally, press the '''Flash!''' button to start the transfer.
+
#*# Go and grab a coffee. flashing your microSD card will take some time... ;-) Be patient.<br /> Once the flash is complete, close the Etcher app and eject the SD card.
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/Etcher.io_.png"><img class="alignnone wp-image-1230" src="http://agile-iot.eu/wp-content/uploads/2017/03/Etcher.io_.png" alt="" width="500" height="233" data-wp-pid="1230" /></a>
+
# Once the the flashing is completed, eject the SD reader from your PC/laptop and remove the microSD card from the reader.
# Your OS will ask you, at least on MacOS, the Admin credential of your PC/laptop. Complete it to proceed with the burning process.
+
# Verify that your RPi is turned OFF
# Go and grab a coffee. flashing your microSD card will take some time... ;-)
+
# Slide the microSD card into the  RPi microSD driver.
 
 
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
 
 
 
* Once the the flashing is completed, eject your SD reader from your PC/laptop and remove the microSD card from the reader.
 
* Verify that your RPi is turned OFF
 
* Slide the microSD card into the  RPi microSD driver.
 
  
 +
'''Remark:''' Feel free to rebuild this image using the latest AGILE code by following [https://github.com/Agile-IoT/agile-scripts/ these instructions].
  
 
== Run the sample ==
 
== Run the sample ==
 
=== Setup your configuration ===
 
=== Setup your configuration ===
# Connect your RPi to the power supply.
+
[[File:AGILE Config.jpg.jpg|thumb|right|Macbook HW setup]]
You can directly connect it to your PC/laptop; the RPi will not consume too much power in our case.
+
# Connect your RPi to the power supply.<br />You can directly connect it a USB port of your PC/laptop; the RPi will not consume too much power in this case.  
# Connect your RPi to your LAN.
+
# 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
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
 
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/IMG_2521.jpg"><img class="size-medium wp-image-1233 alignnone" src="http://agile-iot.eu/wp-content/uploads/2017/03/IMG_2521-300x225.jpg" alt="" width="300" height="225" data-wp-pid="1233" /></a>
 
  
 
=== 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 '''agilegw.local'''. Open a console and try to ping it to verify that it's there. 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. To do that, you can either retrieve this information, if you have access to your DHCP server, or you can use [http://angryip.org/ Angry IP Scanner]. Downloads are available for Mac, Linux and Windows.
# Load and install PI Finder on your Mac
+
[[File:Angryip.png|thumb|right|Angry IP Scan result]]
# Launch PI Finder
+
# Load and install '''Angry IP Scanner''' on your PC/laptop.
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/PiFinder-01.png"><img class="size-full wp-image-1236 alignnone" src="http://agile-iot.eu/wp-content/uploads/2017/03/PiFinder-01.png" alt="" width="446" height="225" data-wp-pid="1236" /></a>
+
# Launch the application.
# Press the Scan button to start scanning your network.
+
# Specify the IP range to scan on your LAN.
# After while, a new dialog box will pop up providing the IP address found by PI Finder.
+
# Press the '''Start''' button to start scanning your network.
In my case, it found our RPi at the IP address: 192.168.2.6
+
# When the scan is finished, you should be able to retrieve the IP address of your Raspberry Pi in the provided list.
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/PiFinder-02.png"><img class="size-full wp-image-1237 alignnone" src="http://agile-iot.eu/wp-content/uploads/2017/03/PiFinder-02.png" alt="" width="425" height="330" data-wp-pid="1237" /></a>
+
# If the application 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.
 
  
 
=== Access to the AGILE Web UI ===
 
=== Access to 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.
+
[[File:AGILE-01.png|thumb|right|AGILE Welcome page]]
# 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.
+
Now that you know the IP address of the RPi, you can connect to it by launching the AGILE Web UI.
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 this case, use the following URL: http://agilegw.local:8000/
 
# The web browser will display the '''AGILE Welcome page'''. If it doesn't, wait for few more seconds, your image is certainly booting.
 
# The web browser will display the '''AGILE Welcome page'''. If it doesn't, wait for few more seconds, your image is certainly booting.
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/AGILE-01.png"><img class="alignnone wp-image-1239" src="http://agile-iot.eu/wp-content/uploads/2017/03/AGILE-01.png" alt="" width="501" height="371" data-wp-pid="1239" /></a>
+
# Once you are redirected to the login page. You can use the default user '''agile''' and password '''secret'''. If by any chance you get some error during login please check '''https://github.com/Agile-IoT/agile-security/wiki/TroubleShooting'''
  
Congratulations ! Your are connected to your AGILE image !
+
Congratulations! You 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
+
# 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.  
'''<a href="http://agile-iot.eu/wp-content/uploads/2017/03/AGILE-02.png"><img class="size-full wp-image-1241 alignnone" src="http://agile-iot.eu/wp-content/uploads/2017/03/AGILE-02.png" alt="" width="245" height="204" data-wp-pid="1241" /></a>
+
# Click on the Device Manager Setting button and turn on the Device Discovery switch:  
It will open the Device Manager view on the devices currently registered on the platform.
+
# Close the Settings <gallery>
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/AGILE-DM-01.png"><img class="alignnone wp-image-1242" src="http://agile-iot.eu/wp-content/uploads/2017/03/AGILE-DM-01-300x209.png" alt="" width="500" height="348" data-wp-pid="1242" /></a>
+
AGILE-02.png|Device Manager menu item
# Click on the Device Manager Setting button <a href="http://agile-iot.eu/wp-content/uploads/2017/03/AGILE-DM-02.png"><img class="size-full wp-image-1243 alignnone" src="http://agile-iot.eu/wp-content/uploads/2017/03/AGILE-DM-02.png" alt="" width="34" height="29" data-wp-pid="1243" /></a>and turn on the Device Discovery switch:
+
AGILE-DM-01.png|Registered Devices
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/AGILE-DM-03.png"><img class="size-full wp-image-1244 alignnone" src="http://agile-iot.eu/wp-content/uploads/2017/03/AGILE-DM-03.png" alt="" width="253" height="189" data-wp-pid="1244" /></a>
+
AGILE-DM-02.png|Setting button
# Close the Settings
+
AGILE-DM-03.png|Device Discovery switch
# It is time to use the TI SensorTag!
+
</gallery>
Press the '''PowerOn''' button on your sensor tag.
+
# 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.
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/IMG_2526-001.jpg"><img class="alignnone size-medium wp-image-1245" src="http://agile-iot.eu/wp-content/uploads/2017/03/IMG_2526-001-224x300.jpg" alt="" width="224" height="300" data-wp-pid="1245" />
+
# From the Device Manager view, click on the '''DISCOVER''' tab to display all devices AGILE is able to detect.
</a>The green led should start blinking on the TI SensorTag indicating it is on the '''Service Discovery''' mode.
+
# Find a device named '''CC2650 SensorTag'''. It is your TI SensorTag.  
# From the Device Manager view, click on the '''DISCOVER''' tab to display all devices AGILE is able to see currently around you.
+
# Press the '''REGISTER''' link to connect your Sensor to the AGILE gateway.<br/>It will automatically switch back to the DEVICES list and you should be able to see in the list your tag listed.  
# Find a device named '''CC2650 SensorTag'''. It is your TI SensorTag.
+
# Click on the name '''CC2650 SensorTag''' to view the currently available features.<br />As you can see, the current implementation of this device covers only a subset of the feature actually provided by TI:
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/AGILE-DM-04.png"><img class="alignnone size-full wp-image-1246" src="http://agile-iot.eu/wp-content/uploads/2017/03/AGILE-DM-04.png" alt="" width="282" height="164" data-wp-pid="1246" /></a>
+
#* Temperature,
# Press the '''REGISTER''' link to connect your Sensor to the AGILE gateway.
+
#* Humidity,
It will automatically switch back to DEVICES list and you should be able to see in the list your tag listed.
+
#* Pressure, and
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/AGILE-DM-05.png"><img class="alignnone wp-image-1249" src="http://agile-iot.eu/wp-content/uploads/2017/03/AGILE-DM-05.png" alt="" width="501" height="211" data-wp-pid="1249" /></a>
+
#* Optical/Luminosity.
# Click on the name  '''CC2650 SensorTag''' to view the currently available features.
+
<gallery>
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/AGILE-DM-06.png"><img class="alignnone wp-image-1251" src="http://agile-iot.eu/wp-content/uploads/2017/03/AGILE-DM-06.png" alt="" width="196" height="300" data-wp-pid="1251" /></a>
+
SensorTag 01.jpg|Power ON button
As you can notice, the current implementation of this device covers only a subset of the feature actually provided by TI:
+
AGILE-DM-04.png|SensorTag list item
* Temperature,
+
AGILE-DM-05.png|The SensorTag is registered
* Humidity,
+
AGILE-DM-06.png|Feature details on the SensorTag
* Pressure and
+
</gallery>
* Optical/Luminosity.
 
  
 
=== Build a sample with Node-RED ===
 
=== Build a sample with Node-RED ===
Node-RED is the current developer’s environment to create AGILE apps.
+
Node-RED is the developer environment currently used 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.
+
Now, create a Node-RED flow from scratch by 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
+
# Look for the '''websocket''' input node, on the left section.
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/NR-01.png"><img class="alignnone wp-image-1253" src="http://agile-iot.eu/wp-content/uploads/2017/03/NR-01.png" alt="" width="150" height="88" data-wp-pid="1253" /></a>
+
# Drag &amp; Drop the '''websocket''' node into the current flow.
# Drag&amp;Drop the '''websocket''' node into the current flow
 
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/NR-02.png"><img class="alignnone wp-image-1254" src="http://agile-iot.eu/wp-content/uploads/2017/03/NR-02.png" alt="" width="500" height="268" data-wp-pid="1254" /></a>
 
 
# 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
+
## To edit the '''Path''', click on the pencil button; it will open a second editor to specify the WebSocket URL.
# For editing the '''Path''', click on the pencil button <a href="http://agile-iot.eu/wp-content/uploads/2017/03/NR-03.png"><img class="alignnone wp-image-1255" src="http://agile-iot.eu/wp-content/uploads/2017/03/NR-03.png" alt="" width="27" height="29" data-wp-pid="1255" /></a>, 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:
+
##* replace &lt;rpi.ip&gt; by the IP of your RPi
'''ws://&lt;rpi.ip&gt;:8080/ws/device/&lt;device ID&gt;/Temperature/subscribe'''
+
##* 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/>Sample URL: <br/>ws://agilegw.local:8080/ws/device/ble247189E95285/Temperature/subscribe  
* replacing &lt;rpi.ip&gt; by the IP of your RPi
+
## Press the '''Add''' button to return to the node editor
* and &lt;device ID&gt; by the ID of your TI SensorTag.
+
## Type in the '''Name''' field, for example, '''Temperature'''
You can retrieve the ID of your sensor on the Device Manager. Actually, this is the ID specified in the header of the device:
+
## Press the '''Done''' button to save your changes.
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/NR-05.png"><img class="alignnone wp-image-1257 size-medium" src="http://agile-iot.eu/wp-content/uploads/2017/03/NR-05-300x126.png" alt="" width="300" height="126" data-wp-pid="1257" /></a>
+
<gallery>
My URL looks like that:
+
NR-01.png|WebSocket node
ws://192.168.2.6:8080/ws/device/ble247189E95285/Temperature/subscribe
+
NR-03.png|Pencil button
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/NR-04.png"><img class="alignnone wp-image-1258 size-medium" src="http://agile-iot.eu/wp-content/uploads/2017/03/NR-04-300x205.png" alt="" width="300" height="205" data-wp-pid="1258" /></a>
+
NR-05.png|SensorTag ID
 
+
NR-04.png|WebSocket path editor
# Press the '''Add''' button to return to the node editor
+
NR-06.png|WebSocket node editor
# Type in the '''Name''' field, for example, '''Temperature
+
</gallery>
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/NR-06.png"><img class="alignnone wp-image-1259 size-medium" src="http://agile-iot.eu/wp-content/uploads/2017/03/NR-06-300x145.png" alt="" width="300" height="145" data-wp-pid="1259" /></a>'''
+
# Now you'll add a '''debug''' node to display the content of the message payload produced by the '''websocket''' node.
# Press the '''Done''' button to save your changes.
+
## Look for the '''debug''' out node, on the left section.
# We will add now a '''debug''' node to display the content of the message payload produced by the '''websocket''' node
+
## Drag &amp; Drop the '''debug''' node into the current flow.
# Look for the '''debug''' out node, on the left section
+
## Double-click on the '''debug''' node to name it '''Log'''.
# Drag&amp;Drop the '''debug''' node into the current flow
+
## 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.
# Double-click on the '''debug''' node to name it '''Log'''
+
# You can already test this flow:  
# 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.
+
## Press the '''Deploy''' button on the top right of the Node-RED editor.  
# At this point your flow should look like this:
+
## The flow will have changed a bit: the '''websocket''' node informs you it is connected and the '''debug''' node is turned ON:
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/NR-08.png"><img class="alignnone wp-image-1261 size-medium" src="http://agile-iot.eu/wp-content/uploads/2017/03/NR-08-300x115.png" alt="" width="300" height="115" data-wp-pid="1261" /></a>
+
## To see the log, click on the '''debug''' tab on the right part of the editor and you will see the displayed trace.  
# We can already test this flow:
+
## You can interrupt the log, not the flow, anytime by switching the '''debug''' node OFF and re-deploy the flow.  
 
+
<gallery>
# Press the '''Deploy''' button on the top right of the Node-RED editor
+
NR-08.png|Debug node
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/NR-07.png"><img class="alignnone size-full wp-image-1260" src="http://agile-iot.eu/wp-content/uploads/2017/03/NR-07.png" alt="" width="243" height="58" data-wp-pid="1260" /></a>
+
NR-07.png|Deploy button
# The flow has a little bit changed: the '''websocket''' node informs you it is connected and the '''debug''' node is turned ON:
+
NR-09.png|Deployed flow
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/NR-09.png"><img class="alignnone wp-image-1262 size-medium" src="http://agile-iot.eu/wp-content/uploads/2017/03/NR-09-300x107.png" alt="" width="300" height="107" data-wp-pid="1262" /></a>
+
NR-10.png|Flow log
# To see the log, click on the '''debug''' tab on the right part of the editor and you will see the displayed trace
+
NR-11.png|Turn ON/OFF debug node
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/NR-10.png"><img class="alignnone wp-image-1264" src="http://agile-iot.eu/wp-content/uploads/2017/03/NR-10.png" alt="" width="500" height="295" data-wp-pid="1264" /></a>
+
</gallery>
# You can interrupt the log, not the flow, anytime by switching off the '''debug''' node and re-deploy the flow.
+
# Proceed by extracting the value of the temperature from the JSON message. For that a '''function''' node is needed.
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/NR-11.png"><img class="alignnone wp-image-1268" src="http://agile-iot.eu/wp-content/uploads/2017/03/NR-11.png" alt="" width="150" height="62" data-wp-pid="1268" /></a>
+
# Once you have drag &amp; dropped a '''function''' node into your flow, connect the output port of the '''websocket''' (e.g. Temperature) to the input port of the '''function''' node.
 
+
# Double-click on the '''function''' node to edit it.
 
+
## '''Name''' the node '''Extract Temperature'''.
# Let proceed by extracting the value of the temperature from the JSON message . For that we need a '''function''' node.
+
## In the '''Function''' field, type the following JavaScript code: <br/>
# 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.
+
##:<pre>
# Double-click on the '''function''' node to edit it
+
##::var json = JSON.parse(msg.payload);
 
+
##::msg.payload = json.value;
# '''Name''' the node '''Extract Temperature'''
+
##::return msg;</pre>
# In the '''Function''' field, type the following JavaScript code:
+
## Press the Done button to close the '''function''' editor.
 
 
[code language="text"]var json = JSON.parse(msg.payload);
 
msg.payload = json.value;
 
 
 
return msg;
 
[/code]
 
 
 
 
 
# 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.
+
# This value will now be pushed to an MQTT broker on the cloud to be able to subscribe to this data stream from any MQTT client. To do that, an '''MQTT out''' node needs to be added to our current flow.  
<img class="alignnone size-full wp-image-1279" src="http://agile-iot.eu/wp-content/uploads/2017/03/NR-12.png" alt="" width="234" height="100" data-wp-pid="1279" />
+
# Double-click on the '''MQTT out''' node to edit it.
# Double-click on the '''MQTT out''' node to edit it
+
## 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 Server filed, click on the pencil button <a href="http://agile-iot.eu/wp-content/uploads/2017/03/NR-03.png"><img class="alignnone wp-image-1255" src="http://agile-iot.eu/wp-content/uploads/2017/03/NR-03.png" alt="" width="27" height="29" data-wp-pid="1255" /></a> to specify the MQTT broker you want to reach.
+
## Leave the port number (1883) unchanged and close this dialog by pressing the '''Add''' button.
# For the purpose of this Getting Started, we will designate the Eclipse IoT MQTT broker by specifying '''iot.eclipse.org''' in the '''Server''' field.
+
## 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 we wanted to be able to reuse an existing ID. [https://iot.eclipse.org/java/tutorial/ MQTT client demo], we have to use this syntax.
# Leave the port number (1883) unchanged and close this dialog by pressing the '''Add''' button.
+
## At this point name the node, for example, '''iot.eclipse.org''',  and close the editor by pressing the '''Done''' button.
# 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 <a href="https://iot.eclipse.org/java/tutorial/">MQTT client demo</a>, 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
 
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/NR-13.png"><img class="alignnone wp-image-1282" src="http://agile-iot.eu/wp-content/uploads/2017/03/NR-13.png" alt="" width="499" height="270" data-wp-pid="1282" /></a>
 
 
 
 
 
 
# 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.
+
# Now you can deploy the resulting flow by clicking '''Deploy''' on the top right and you should be all set.  
<a href="http://agile-iot.eu/wp-content/uploads/2017/03/NR-14.png"><img class="alignnone wp-image-1285" src="http://agile-iot.eu/wp-content/uploads/2017/03/NR-14.png" alt="" width="500" height="261" data-wp-pid="1285" /></a>
+
<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, the sample is collecting temperature data from the 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:
+
# 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:  
<a href="https://iot.eclipse.org/java/demo/app/#/greenhouses/remote/agile">https://iot.eclipse.org/java/demo/app/#/greenhouses/remote/agile</a>. It will open a web page with the following dashboard:<a href="http://agile-iot.eu/wp-content/uploads/2017/03/AGILE-03.png">
 
<img class="alignnone wp-image-1286" src="http://agile-iot.eu/wp-content/uploads/2017/03/AGILE-03.png" alt="" width="500" height="392" data-wp-pid="1286" /></a>
 
 
# 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 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;

Latest revision as of 10:00, 9 July 2018

Introduction

This is an easy step-by-step guide 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).
    This document should work on Mac, Linux or Windows. We made our best to always choose a feature or an application available on all 3 platforms.
  • 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, like 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 contains all the software you need to run this Getting Started and can directly be deployed on a microSD card. This guide was prepared with the Raspbian based v0.3.3 image of AGILE, however, we advise to use the most recent version.

  1. Download the AGILE image from the following link: AGILE_SD_images.
  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
    • use your favorite microSD flashing tool,
    • learn from this page RPi Easy SD Card Setup,
    • use Etcher by Resin.io, the great open source SD burner developed by our project partner Resin.io.
      In the next steps, we will describe how to use Etcher to flash your microSD card.
      1. Download and install Etcher by Resin.io on your PC/laptop. This tool works on Mac, Linux and Windows.
      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... ;-) Be patient.
        Once the flash is complete, close the Etcher app and eject the SD card.
  6. Once the the flashing is completed, eject the 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.

Remark: Feel free to rebuild this image using the latest AGILE code by following these instructions.

Run the sample

Setup your configuration

Macbook HW setup
  1. Connect your RPi to the power supply.
    You can directly connect it a USB port of your PC/laptop; the RPi will not consume too much power in this 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 agilegw.local. Open a console and try to ping it to verify that it's there. 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. To do that, you can either retrieve this information, if you have access to your DHCP server, or you can use Angry IP Scanner. Downloads are available for Mac, Linux and Windows.

Angry IP Scan result
  1. Load and install Angry IP Scanner on your PC/laptop.
  2. Launch the application.
  3. Specify the IP range to scan on your LAN.
  4. Press the Start button to start scanning your network.
  5. When the scan is finished, you should be able to retrieve the IP address of your Raspberry Pi in the provided list.
  6. If the application 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 you know the IP address of the RPi, you 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 this case, use the following URL: http://agilegw.local: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.
  3. Once you are redirected to the login page. You can use the default user agile and password secret. If by any chance you get some error during login please check https://github.com/Agile-IoT/agile-security/wiki/TroubleShooting

Congratulations! You 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 detect.
    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 the 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 see, 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 developer environment currently used to create AGILE apps.

    Now, create a Node-RED flow from scratch by 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. To edit 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
        • replace <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:
          Sample URL:
          ws://agilegw.local: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. Now you'll add 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. You can already test this flow:
      1. Press the Deploy button on the top right of the Node-RED editor.
      2. The flow will have changed a bit: 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 the debug node OFF and re-deploy the flow.
    1. Proceed by extracting the value of the temperature from the JSON message. For that a function node is needed.
    2. Once you have drag & dropped a function node into your flow, connect the output port of the websocket (e.g. Temperature) 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. This value will now be pushed to an MQTT broker on the cloud to be able to subscribe to this data stream from any MQTT client. To do that, an MQTT out node needs to be added 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 we wanted to be able to reuse an existing ID. 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 by clicking Deploy on the top right and you should be all set.

    Connect to the MQTT broker

    At this point, the sample is collecting temperature data from the 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 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.