IoT Edge Router BLE Sensor Snappy App

BLE Sensor Reference Application Using Snappy on the IoT Edge Router

Get the IoT Edge Router BLE Sensor Reference App on GitHub
This reference application is an Ubuntu Core application running on the IoT Edge Router. The application collects sensor values from a sensor over Bluetooth low energy (BLE) and sends them to the Itron Networked Solutions Data Platform.

Overview

The BLE sensor reference application is an Ubuntu Core app that will run on Itron IoT Edge Router. The application demonstrates the collection of sensor measurements from sensors connected to the IoT Edge Router over Bluetooth low energy (BLE). The sensor used in this reference application is a TI Sensor tag. Communication between the sensor and the IoT Edge Router is done over BLE.

Hardware Needed

 

Obtain UUID of TI Sensor Tag

  • Power On the TI Sensor-tag so it can be detected from the IoT Edge Router board.
  • Scan the TI sensor tag using the hcitool lescan command (installed as part of BLE Reference Snap. It should provide the UUID that is required to connect to TI sensor tag

 

Obtaining the Security Token from the Itron Data Platform

  • To store data in the Itron Data Platform, the IoT Edge Router reference application should have an OAuth token (API key).
  • Each call must include an Authorization http header that specifies the token. A token is obtained with a Client ID and Secret API key. Your client ID and Secret can be obtained from your developer account. See Create an Account.

 

Software Update if Needed

Log into the dev account on your IoT Edge Router (user=dev; pass=starfish) and

  1. Download the IoT Edge Router reference snap application from GitHub:
    wget https://github.com/silverspringnetworks/developer_program/raw/master/HDK/IoT_Router_BLE/ready_to_use_snaps/armhf/starfish-sensortag-app_0.3_armhf.snap
  2. Install the snap:
    sudo snap install --dangerous --devmode starfish-sensortag-app_0.3_armhf.snap

To upgrade the snap when a new revision becomes available:

  1. Download the new snap from GitHub:
    wget https://github.com/silverspringnetworks/developer_program/raw/master/HDK/IoT_Router_BLE/ready_to_use_snaps/armhf/starfish-sensortag-app_X.XX_armhf.snap
  2. Remove the previous snap:
    sudo snap remove starfish-sensortag-app_0.3_armhf.snap
  3. Install the new snap:
    sudo snap install --dangerous --devmode starfish-sensortag-app_X.XX_armhf.snap

 

Reference Application Step By Step Instructions

  1. With the IOTR powered on, plug in the BLE USB Adapter to one the USB ports on the IOTR.  Assuming the IOTR has the correct drive and identifies the BLE USB adapter successfully you should be able to see if when you run the "hcitool dev" and "hciconfig" command:

    dev@ssniotr:~$ hcitool dev
    Devices:
            hci0    5C:F3:70:8A:51:4E

     

    dev@ssniotr:~$ hciconfig
    hci0:   Type: BR/EDR  Bus: USB
            BD Address: 5C:F3:70:8A:51:4E  ACL MTU: 1021:8  SCO MTU: 64:1
            UP RUNNING
            RX bytes:16810 acl:162 sco:0 events:508 errors:0
            TX bytes:3645 acl:166 sco:0 commands:83 errors:0

    You can also use the "lsusb" command to verify the presence of the BLE USB adapter:

    dev@ssniotr:~$ lsusb
    Bus 004 Device 004: ID 0a5c:21e8 Broadcom Corp. BCM20702A0 Bluetooth 4.0
    Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
    Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
    Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
    Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
    Bus 005 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

     

  2. Turn on the TI SensorTag by clicking the power button once.  The green LED on the back of the SensorTag should start flashing.  From IOTR run the "sudo hcitool lescan" command to see if the BLE USB adapter has found the SensorTag:

    dev@ssniotr:~$ sudo hcitool lescan
    LE Scan ...
    34:F5:69:9A:D3:A2 (unknown)
    60:DB:78:2C:47:EB (unknown)
    60:DB:78:2C:47:EB (unknown)
    3B:77:C7:38:B2:96 (unknown)
    54:6C:0E:53:39:69 (unknown)
    54:6C:0E:53:39:69 CC2650 SensorTag
    40:1D:02:6E:AB:FC (unknown)
    40:1D:02:6E:AB:FC (unknown)
    32:C9:D5:A8:89:B6 (unknown)
    19:F1:72:A0:FE:B0 (unknown)
    5A:B0:65:E6:47:85 (unknown)
    2D:57:FE:6C:BE:16 (unknown)
    5E:38:98:94:35:D1 (unknown)
    C6:90:3D:70:33:31 (unknown)
    C6:90:3D:70:33:31 Flex
    75:9A:05:64:D0:DE (unknown)
    75:9A:05:64:D0:DE (unknown)
    6C:25:21:2B:A6:D9 (unknown)
    37:92:05:13:BF:8D (unknown)
    66:E7:CB:AB:D9:D4 (unknown)
    66:E7:CB:AB:D9:D4 (unknown)
    24:A0:74:F0:35:47 (unknown)
    52:2D:5A:6F:65:11 (unknown)
    ^Cdev@ssniotr:~$

    Once you see a "CC2650 SensorTag" device you can use Ctrl-C to stop the lescan process.  Make a note of the Bluetooth address of your SensorTag (e.g. 54:6C:0E:53:39:69 in the example above) as you will need to use that informaton later (as UUID for the reference app).
    For more details on the TI SensorTag please refer to the CC2650 SensorTag User's Guide
     

  3. Next install the Starfish SensorTag reference snap app on the IOTR:
    1. First use "wget" to obtain the latest version of the snap (i.e. 0.3) from GitHub:

      wget https://github.com/silverspringnetworks/developer_program/raw/master/HDK/IoT_Router_BLE/ready_to_use_snaps/armhf/starfish-sensortag-app_0.3_armhf.snap

       

    2. Install the snap using the snap install command:

      sudo snap install --dangerous --devmode starfish-sensortag-app_0.3_armhf.snap

       

    3. Confirm that the Starfish SensorTag snap is installed and exists in the snap list:

      dev@ssniotr:~$ snap list
      Name                    Version  Rev  Developer  Notes
      core                    16-2.30  x1              core
      netmgr                  1.04     x1              devmode
      ssniotr                 3.06     x1              classic
      ssnmode                 7.05     x1              classic
      starfish-sensortag-app  0.3      x2              devmode

       

      You should also see the following in the /snap/bin directory:

      dev@ssniotr:~$ ls -l /snap/bin
      total 0
      lrwxrwxrwx 1 root root 13 Dec  6 21:28 netmgr -> /usr/bin/snap
      lrwxrwxrwx 1 root root 13 Dec  6 21:28 ssnmode.confstat -> /usr/bin/snap
      lrwxrwxrwx 1 root root 13 Jan  8 18:15 starfish-sensortag-app.blescan -> /usr/bin/snap
      lrwxrwxrwx 1 root root 13 Jan  8 18:15 starfish-sensortag-app.run -> /usr/bin/snap
      lrwxrwxrwx 1 root root 13 Jan  8 18:15 starfish-sensortag-app.sensortag -> /usr/bin/snap

       

    4. Attach the bluetooth-control plug by running the "sudo snap connect starfish-sensortag-app:bluetooth-control core:bluetooth-control" command:

      dev@ssniotr:~$ sudo snap connect starfish-sensortag-app:bluetooth-control core:bluetooth-control

      Verify that the plugs and slots of bluetooth-control for the snap are connected properly by running the "snap interfaces" command:

      dev@ssniotr:~$ snap interfaces
      Slot                       Plug
      :account-control           -
      :alsa                      -
      :autopilot-introspection   -
      :avahi-control             -
      :avahi-observe             -
      :bluetooth-control         starfish-sensortag-app
      :bluez                     -
      :broadcom-asic-control     -
      :browser-support           -
      :camera                    -
      :classic-support           -
      :core-support              core:core-support-plug
      :cups-control              -
      :dcdbas-control            -
      :desktop                   -
      :desktop-legacy            -
      :docker-support            -
      :firewall-control          -
      :framebuffer               -
      :fuse-support              -
      :gpg-keys                  -
      :gpg-public-keys           -
      :greengrass-support        -
      :gsettings                 -
      :hardware-observe          -
      :hardware-random-control   -
      :hardware-random-observe   -
      :home                      -
      :io-ports-control          -
      :joystick                  -
      :kernel-module-control     -
      :kubernetes-support        -
      :kvm                       -
      :libvirt                   -
      :locale-control            -
      :log-observe               -
      :lxd-support               -
      :modem-manager             -
      :mount-observe             -
      :netlink-audit             -
      :netlink-connector         -
      :network                   netmgr,starfish-sensortag-app
      :network-bind              netmgr
      :network-control           -
      :network-manager           -
      :network-observe           -
      :network-setup-control     -
      :network-setup-observe     -
      :ofono                     -
      :opengl                    -
      :openvswitch               -
      :openvswitch-support       -
      :optical-drive             -
      :password-manager-service  -
      :physical-memory-control   -
      :physical-memory-observe   -
      :ppp                       -
      :process-control           -
      :pulseaudio                -
      :raw-usb                   -
      :removable-media           -
      :screen-inhibit-control    -
      :shutdown                  -
      :snapd-control             -
      :ssh-keys                  -
      :ssh-public-keys           -
      :system-observe            -
      :system-trace              -
      :time-control              -
      :timeserver-control        -
      :timezone-control          -
      :tpm                       -
      :uhid                      -
      :unity7                    -
      :upower-observe            -
      :wayland                   -
      :x11                       -

       

  4. Next run the Starfish SensorTag snap app to get the IOTR to read in sensor data from the TI SensorTag via bluetooth and then pushes them to the Starfish Data Platform.  To do you will run the command "starfish-sensortag-app.run" with the following arguments:

    starfish-sensortag-app.run ClientId ClienSecret UUID NoOfObs

    Where:

    1. ClientId : Valid Startfish Studio platform client Id. This is a mandatory parameter.
    2. ClientSecret : Valid Starfish Studio platform client secret. This is a mandatory parameter.
    3. UUID : MAC address of TI SensorTag obtained from hcitool lescan earlier (see Step 3 above). This is a mandatory parameter.
    4. NoOfObs : Number of observations to be fetched from the TI SensorTag. This is a mandatory parameter.

    If everything is working correctly as intended, you will see something like the following:

    dev@ssniotr:~$ starfish-sensortag-app.run e7bb8cc6-a7a6-46a4-8b83-ec1312345678 DfVja0lBDM0rTcKeWpmooN7hSOvRVmm4R8Mys04gBlV7z712345678 54:6c:0e:53:39:69 1
    filename:
    /home/dev/snap/starfish-sensortag-app/x2/data.txt
    exceptionFilename:
    /home/dev/snap/starfish-sensortag-app/x2/exception.txt
    GetToken: {
      "method": "POST",
      "uri": "https://api.data-platform.developer.ssni.com/tokens",
      "headers": {
        "Accept": "application/json"
      },
      "body": {
        "clientId": "e7bb8cc6-a7a6-46a4-8b83-ec1312345678",
        "clientSecret": "DfVja0lBDM0rTcKeWpmooN7hSOvRVmm4R8Mys04gBlV7z712345678"
      },
      "json": true
    }
    Get Tokens Repsonse:{
      "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIvZGF0YSIsInN1YiI6IlROMDBiYWQyZmI0Yy0wYTQ0LTQyMzctOTY3Mi0xMWVjMzkxMDBhYTciLCJzY29wZSI6ImFwaSIsImFjY2Vzc1BvbGljeSI6W3siQWN0aW9uIjoiZXhlY3V0ZS1hcGk6SW52b2tlIiwiRWZmZWN0IjoiQWxsb3ciLCJSZXNvdXJjZSI6IiovYXBpL3NvbHV0aW9ucy8qIn0seyJBY3Rpb24iOiJleGVjdXRlLWFwaTpJbnZva2UiLCJFZmZlY3QiOiJBbGxvdyIsIlJlc291cmNlIjoiR0VUL2FwaS90ZW5hbnRzL3N5c3RlbVRlbmFudC9kZXZpY2V0ZW1wbGF0ZXMifV0sImp0aSI6ImJlMTZhNmM1LTQ2ZmItNGYwZS1hNTQ2LWY1NTdiNGI5OGMxNiIsImlhdCI6MTU0NzA2OTQzMywiZXhwIjoxNTQ3MDczMDMzfQ.xAU3ws7msby689bF49FxdDV1nvj_4ZiE_p_0GZYWDQ4"
    }
    Post Options:{
      "method": "POST",
      "body": {
        "deviceType": "SensorTag",
        "domainInfo": {
          "modelName": "CC2650",
          "macaddress": "54:6c:0e:53:39:69",
          "timestamp": "2019-01-09T21:30:21.416Z"
        }
      },
      "uri": "https://api.data-platform.developer.ssni.com/api/solutions/sandbox/devices/",
      "headers": {
        "Authorization": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIvZGF0YSIsInN1YiI6IlROMDBiYWQyZmI0Yy0wYTQ0LTQyMzctOTY3Mi0xMWVjMzkxMDBhYTciLCJzY29wZSI6ImFwaSIsImFjY2Vzc1BvbGljeSI6W3siQWN0aW9uIjoiZXhlY3V0ZS1hcGk6SW52b2tlIiwiRWZmZWN0IjoiQWxsb3ciLCJSZXNvdXJjZSI6IiovYXBpL3NvbHV0aW9ucy8qIn0seyJBY3Rpb24iOiJleGVjdXRlLWFwaTpJbnZva2UiLCJFZmZlY3QiOiJBbGxvdyIsIlJlc291cmNlIjoiR0VUL2FwaS90ZW5hbnRzL3N5c3RlbVRlbmFudC9kZXZpY2V0ZW1wbGF0ZXMifV0sImp0aSI6ImJlMTZhNmM1LTQ2ZmItNGYwZS1hNTQ2LWY1NTdiNGI5OGMxNiIsImlhdCI6MTU0NzA2OTQzMywiZXhwIjoxNTQ3MDczMDMzfQ.xAU3ws7msby689bF49FxdDV1nvj_4ZiE_p_0GZYWDQ4"
      },
      "json": true
    }
    Device is Created Successfully
    DeviceId= e6d71aff-cff7-410a-89b4-ba99f3bfeee0
    
    
    Notify Event TimeStamp 2019-01-09T21:30:56.285Z
    out
    Connecting to 54:6c:0e:53:39:69
    Temp:  (0.0, 0.0)
    Humidity:  (22.9827880859375, 48.736572265625)
    Barometer:  (22.62, 1018.79)
    Accelerometer:  (-0.1103515625, -0.16845703125, 2.00732421875)
    Magnetometer:  (46.63101343101343, 31.337240537240536, 58.026373626373626)
    Gyroscope:  (-0.25177001953125, 1.82342529296875, -0.11444091796875)
    Light:  126.32000000000001
    Battery:  83
    
    post starfish deviceID sensor_obs
    e6d71aff-cff7-410a-89b4-ba99f3bfeee0
    [object Object]
    Post Options:{
      "method": "POST",
      "body": {
        "observations": [
          {
            "timestamp": "2019-01-09T21:30:56.285Z",
            "temperature": 0,
            "humidity": 48.736572265625,
            "barometer": 1018.79,
            "accelerometer": {
              "x": -0.1103515625,
              "y": -0.16845703125,
              "z": 2.00732421875
            },
            "magnetometer": {
              "x": 46.63101343101343,
              "y": 31.337240537240536,
              "z": 58.026373626373626
            },
            "gyroscope": {
              "x": -0.25177001953125,
              "y": 1.82342529296875,
              "z": -0.11444091796875
            },
            "light": 126.32000000000001,
            "percentlevel": 83
          }
        ]
      },
      "uri": "https://api.data-platform.developer.ssni.com/api/solutions/sandbox/devices/e6d71aff-cff7-410a-89b4-ba99f3bfeee0/observations",
      "headers": {
        "Authorization": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIvZGF0YSIsInN1YiI6IlROMDBiYWQyZmI0Yy0wYTQ0LTQyMzctOTY3Mi0xMWVjMzkxMDBhYTciLCJzY29wZSI6ImFwaSIsImFjY2Vzc1BvbGljeSI6W3siQWN0aW9uIjoiZXhlY3V0ZS1hcGk6SW52b2tlIiwiRWZmZWN0IjoiQWxsb3ciLCJSZXNvdXJjZSI6IiovYXBpL3NvbHV0aW9ucy8qIn0seyJBY3Rpb24iOiJleGVjdXRlLWFwaTpJbnZva2UiLCJFZmZlY3QiOiJBbGxvdyIsIlJlc291cmNlIjoiR0VUL2FwaS90ZW5hbnRzL3N5c3RlbVRlbmFudC9kZXZpY2V0ZW1wbGF0ZXMifV0sImp0aSI6ImJlMTZhNmM1LTQ2ZmItNGYwZS1hNTQ2LWY1NTdiNGI5OGMxNiIsImlhdCI6MTU0NzA2OTQzMywiZXhwIjoxNTQ3MDczMDMzfQ.xAU3ws7msby689bF49FxdDV1nvj_4ZiE_p_0GZYWDQ4"
      },
      "json": true
    }
    Observation is Posted Successfully for DeviceId: e6d71aff-cff7-410a-89b4-ba99f3bfeee0

    Note that you want to make sure the TI SensorTag is powered on with its green LED flashing before you run the snap to gather sensor data.
     

  5. Finally go to Starfish Studio to view the sensor data that has been uploaded.  Go to the "View APIs" tab in Starfish Studio and go the "Observations" section and use the "Get observations for a single device" API.  You will need to put in the following parameters:
    1. solutionName: sandbox
    2. deviceID:  Use the device ID that is created when the Starfish SensorTag snap is run (See Step 5 above)
    3. Authorization:  Use the "SHOW AUTORIZATION TOKEN" button on the Starfish Studio View APIs page to obtain this value
       


     
    Click "Try it out!" and you should see a response that looks like the following:

Build and Install the Reference Application

Complete the following steps to build and install the reference Ubuntu Core application.

  1. Ensure the pre-requisites are met on the Linux machine on which the application is to be built
  • Internet connectivity
  • Latest version (v2.28) of the Snapcraft tool installed on the development machine
     
  1. Build and install the snap. Refer to the Readme file at the Itron Networked Solutions Github repository for detailed instructions about how to build and install the snap application on the IoT Edge Router. 
     
  2. Following are the applications available in the /snap/bin directory when the IoT Edge Router reference snap application (starfish-sensortag-app) is installed on the Ubuntu Core image running on the IoT Edge Router platform board.
  • starfish-sensortag-app.run: This is the main application that obtains sensor data from the TI Sensor-tag, and post to the Itron Networked Solutions Data Platform
  • starfish-sensortag-app.hciconfig: This application provides support to handle Bluetooth controller interfaces configurations on the IoT Edge Router platform board.
  • starfish-sensortag-app.hcitool: This application provides support to scan nearby devices that support the Bluetooth low energy (BLE) profile.