Getting started with AGILE
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
What do you need to be able to install an run this Getting Started?
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.
- 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.]
- 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.
- 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
- 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.
- Download and install Etcher by Resin.io on your PC/laptop
- Launch the Etcher application
- 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.
- Finally, press the Flash! button to start the transfer.
- 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.
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.
Run the sample
Setup your configuration
- 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.
- 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
- Here is how my configuration looks like :
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.
- Load and install PI Finder on your Mac
- Launch PI Finder
- 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.
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.
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.
- 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/
- 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
- 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.
- Click on the Device Manager Setting button
- Close the Settings
- 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.
- 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.
- 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.
- 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:
- Pressure and
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.
- From the AGILE Web UI, launch the Node-RED editor by selecting the menu item Agile > NodeRed
- 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&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.
- Select Connect to on the Type combo-box field
- 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:
- 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: <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> My URL looks like that: ws://192.168.2.6:8080/ws/device/ble247189E95285/Temperature/subscribe <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>
- Press the Add button to return to the node editor
- Type in the Name field, for example, Temperature
<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>
- 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
- Look for the debug out node, on the left section
- Drag&Drop the debug node into the current flow
- 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.
- At this point your flow should look like this:
<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>
- We can already test this flow:
- Press the Deploy button on the top right of the Node-RED editor
<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>
- The flow has a little bit changed: 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-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>
- To see the log, click on the debug tab on the right part of the editor and you will see the displayed trace
<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>
- You can interrupt the log, not the flow, anytime by switching off the debug node and re-deploy the flow.
<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>
- Let proceed by extracting the value of the temperature from the JSON message . For that we need a function node.
- 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.
- Double-click on the function node to edit it
- Name the node Extract Temperature
[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.
- 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.
<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
- 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.
- 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.
- 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.
- Now you can deploy the resulting flow 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>
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.
- You can directly test if the sample works properly by opening this page from any web browser:
<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 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.