Getting started with AGILE

From AGILE IoT Wiki
Jump to: navigation, search

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. Another article will explain how to create such an image, but for now let's use the prepared image.

  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
    • 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.