AWS Out-of-Box (OOB) Demo

Table of Contents

  1. Introduction
  2. Resources
  3. Prerequisites
  4. Setup
  5. Using the Demo
    Signup and Login
    Scan for Devices
    Home Page
    Provision
    Device Information
    MG100 Settings
    Cellular Settings
    Ethernet Settings
    Power Settings
    Firmware Updates
  6. Cloud Data
    BT510 Sensor Data
  7. LED Behavior
  8. My Own AWS Connection
  9. Building the Firmware
    Pinnacle 100/MG100
    BL5340
  10. Development

Introduction

The firmware in the AWS configuration gathers sensor data over BLE and sends the data to the cloud (AWS) via LTE-M (for Pinnacle 100 and MG100) or Ethernet (for BL5340).

One sensor that can be used is the BL654 Sensor Board. This sensor ships with the Pinnacle 100 development kit (DVK) and measures temperature, humidity, and pressure - alternatively the BL5340 ESS demo application can be loaded to a second BL5340 which provides the same service, this is available in the sample_apps_common/ess_demo folder as seen here and a pre-built image can be downloaded from here.

Another supported sensor is the BT510. It records temperature and movement. The BT510 can also be configured to detect a door opened/closed.

The Pinnacle 100/MG100/BL5340 device scans for the BL654 Sensor Board/ESS sensor and connects to the first one it finds. At the same time, the device gathers data for the BT510 sensors from advertisements without creating a connection. The demo supports up to one BL654 Sensor Board/ESS sensor and up to five BT510 sensors. The demo can be recompiled to remove support for either sensor.

Using the Laird Pinnacle Connect mobile app, the user can provision the Pinnacle 100/MG100/BL5340 device to connect to AWS. Once connected to AWS, the device sends sensor data (if a sensor is found) to the cloud every 60 seconds. Once a BT510 is discovered and enabled via the web portal, its sensor data is reported. The details of the BT510 data reporting are detailed below.

                XXXXX
              XXX   XXX
    XXXXX   XX        XX
 XXX    XX XX          X XXXXXXX
 X        XX            X       XX
X                                X
 X         AWS Cloud              X
 XX                              X
  XXXXXXX                       XX
        XX          XXXX    XXXX
         XXX      XXX   XXXX
           XXXXXXX
               ^
               +
 LTE-M or Ethernet (MQTT with TLS)
               +
               v
     +---------+----------+
     |                    |
     |      DVK/MG100     |
     |                    |
     +---------+----------+
               ^
               +
              BLE
               +-------------------------------+
               v                               v
    +----------+------------+      +-----------+-----------+
    |                       |      |                       |
    |  BL654 Sensor         |      |  BT510 Sensor (0-5)   |
    |        (0-1)          |      |                       |
    +-----------------------+      +-----------------------+

Resources

Prerequisites

The following are required to fully exercise this demo firmware:

  • An activated SIM card. See here for instructions on activating the SIM card that came with your kit (Pinnacle 100 and MG100 only).
  • Pinnacle 100 DVK, MG100, or BL5340 DVK programmed with the latest AWS firmware. Releases available here for Pinnacle 100 and MG100 and here for BL5340.
    • Connect to the FTDI UART on the development kit to view firmware logs
  • Laird Pinnacle Connect app installed on a mobile device. An active internet connection on the mobile device is required.

Setup

To set up the device, follow these steps:

  1. Ensure an activated SIM card is inserted into the Pinnacle 100 SIM slot (Pinnacle 100/MG100 only).
  2. On your phone, launch the Pinnacle mobile app and follow the on-screen prompts.

Using the Demo

Signup and Login

If you do not have an account (https://demo.lairdconnect.com/), you must create one. Use an email address for the username.

Sign-up screen Login screen
Sign-up and Login screens

Scan for Devices

Once logged in, the scan screen displays.

Scan screen
Scan screen

To scan for devices, follow these steps:

  1. Click Find Pinnacle Devices. Discovered devices are displayed.

    Note: The device name contains the last seven digits of the IMEI of the device so that you can easily identify the device to which you wish to connect. The IMEI is printed on the label on the bottom of the MG100 housing or on the Pinnacle 100 Modem label. For the BL5340 it will show the last digits of the BLE address.

Scan screen - devices found
Scan screen - devices found

  1. Click on the desired device to connect to it.

Home Page

The home screen displays status information related to the OOB demo. From the home page you can commission or decommission the device and navigate to other settings or info pages.

Note: Provisioning is only allowed if the device is in an un-provisioned state.

Home screen
Home screen

Provision

To provision the device click Provision. During provisioning, certificates are generated for the device and then programmed into the device over BLE.

Provision in process
Provision in process

Once sending provisioning data is complete, a prompt displays and you are directed back to the information page.

Provisioning is complete
Provisioning is complete

The provisioning data is committed to non-volatile memory in the Pinnacle 100 or BL5340 module.

Device commissioned and connected to AWS
Device commissioned and connected to AWS

Note: You can decommission a device if you no longer want it to connect to AWS. Just click Decommission

Device decommissioned
Device decommissioned

Device Information

The device information page displays relevant version information of the connected device.

Device information
Device info

MG100 Settings

Note: Only available if you are connected to an MG100.

All MG100 variants have an onboard accelerometer. It is currently configured to detect movement on the gateway and report that over BLE or to the cloud via the shadow. The MG100 application will send a notification when motion is detected and another notification 30 seconds after movement has stopped. Currently, no accelerometer parameters are configurable. Subsequent versions of the MG100 firmware will allow some configuration of the accelerometer via the shadow. This view shows the status of the motion sensor.

MG100 Settings
MG100 settings

Cellular Settings

The cellular settings page displays status information related to the cellular radio and allows the user to change the APN.

Cellular settings
Cell settings

Ethernet Settings

The ethernet settings page displays status information related to the ethernet configuration and allows changing the configuration of it. Note that a reboot of the module is required for the changes to be applied.

Ethernet settings
Ethernet settings

Power Settings

The power settings page displays the battery voltage and allows the user to reboot the modem. MG100 variants, 450-00038-K1 and 450-00054-K1 are equipped with a rechargeable Li-ion battery used for backup power when external power is lost. The battery will automatically start charging again once external power is restored and the the battery is not fully charged. The firmware monitors the battery voltage and temperature to provide remaining capacity left in the battery. This data is sent over BLE or cellular to report voltage and remaining battery capacity. The battery thresholds are defaulted to reasonable values, but they can be modified via BLE or the shadow if customization is desired. The threshold defaults are as follows. The lowest the battery is allowed to discharge to is 2.75V before the under-voltage protection hardware kicks in.

Battery Threshold 4 - 4200 mV
Battery Threshold 3 - 3800 mV
Battery Threshold 2 - 3400 mV
Battery Threshold 1 - 3000 mV

These thresholds are designed to provide approximately equal discharge time between thresholds 4-3 and 3-2. Below threshold 2, the amount of time left before the battery discharges completely, drops off quickly. This behavior can vary depending on conditions and battery health.

This view displays the battery information. Note the MG100 does not allow for measuring the voltage of the external power supply like the Pinnacle 100 DVK. That is why power supply voltage is always shown as -1 for MG100 devices.

Power settings
Power settings

Firmware Updates

If the Pinnacle 100/BL5340 module is running firmware 3.0.0 or greater, firmware updates will be available in the mobile app or via the web UI. In LwM2M mode, firmware update can only be done using the mobile app (Bluetooth).

FOTA Updates via BLE

After connecting to the device with the mobile app, click Device Firmware Upgrade.

The firmware upgrade view will fetch any available updates from the cloud. Selecting a file will enable the update button, clicking the update button will start the firmware update.

When a firmware file is selected, a download icon will appear on the file to indicate that the file is currently in the cloud and not saved on the mobile device. You can click the download button to save it to the mobile device. The firmware update can be started without downloading the file first. During the update the file will automatically download and save to the mobile device.

Cloud file
Cloud file

If the selected file is local on the mobile device, a delete button will be displayed. You can click it to remove the file from the mobile device.

Local file
Local file

FOTA Updates via the Cloud

After the device has been commissioned and connected to the cloud, it can receive firmware updates from the cloud.

Cloud FOTA
Cloud FOTA

The application firmware or HL7800 cellular firmware can be scheduled for update. Each firmware update can be scheduled when to download the image to the Pinnacle 100 device, and when to apply the update (switchover date).

Cloud Data

Once the Pinnacle 100 or BL5340 module is commissioned with the mobile app and it is connected to AWS, the user can log into the web portal to view sensor data.

The web portal is located at: https://demo.lairdconnect.com

Log in with the same credentials used to login to the mobile app.

Once logged in go to the devices page to see devices that have been added to the user account.

Web portal devices page
Web portal devices page

Each device that is added is identified by its IMEI.

Click on the device ID to display its data.

Pinnacle 100 data
Pinnacle 100 data

If a BL654 sensor or ESS demo sensor is discovered, the module connects and reports sensor data every 60 seconds. The graph only displays live data that is logged while viewing the webpage. If the user leaves the web page and returns, the graph starts over with the most recent data that was received when returning to the page.

BT510 Sensor Data

If a BT510 sensor is discovered, it is displayed in the Sensor Network list.

BT510 discovered
BT510 discovered

In order to receive sensor readings from a BT510 sensor, the sensor must be enabled via the web portal. Click the check box and then hit Submit to enable the sensor.

BT510 enabling
BT510 enabling

BT510 enabled
BT510 enabled

Once enabled, it can take up to 30 seconds for the sensor to subscribe. Once subscribed, the sensor begins to send data.

BT510 subscribed
BT510 subscribed

By default a BT510 sensor reports temperature data every two minutes, battery data once an hour, and movement and button presses immediately.

Click on the BT510 sensor name to view the details and settings of the sensor.

BT510 graph
BT510 graph

BT510 parameters
BT510 parameters

BT510 log
BT510 log

LED Behavior

Pinnacle 100/MG100

The Blue LED blinks when the module is advertising and allowing another device to connect to and configure it. When a central device connects, the LED remains on. When advertising stops, the LED remains off. Button 1 (SW1) can be pressed to restart advertising.

The Green LED turns on when connected to AWS. When data is sent to AWS the LED turns off and then turns back on. When disconnected from AWS, the LED remains off.

The Red LED blinks when the device is searching for a cellular network. It remains on and does not blink when connected to a network. If there is an error with the SIM card or network registration, then the LED remains off.

Note: Before to version 3.x of the firmware, Red LED performed the Blue LED function. Blue LED performed the Green LED function. Green LED performed the Red LED function.

BL5340

There are 4 blue LEDs on the BL5340 development kit with buttons above them, the first LED is located on the left and last LED on the right.

The first blue LED blinks once a second when the BL5340 is advertising which allows a phone to connect to it. When a device connects to it, the LED remains on. When the BL5340 stops advertising, the LED remains off. Note that the button above the LED can be used to start the device advertising if it has stopped.

The second blue LED blinks once a second when the BL5340 is searching for a BL654/ESS sensor. When it finds a sensor and successfully connects to it, the LED remains on.

The third blue LED turns on when an ethernet cable is connected and remains off if no cable is detected.

The forth blue LED turns on when connected to AWS. When data is sent to AWS the LED turns off and then turns back on. When disconnected from AWS, the LED remains off.

My Own AWS Connection

If you wish to connect to your own AWS instance, See here for instructions.

Building the Firmware

Pinnacle 100/MG100

The firmware can be built to work with or without the mcuboot bootloader. Building without mcuboot is faster and easier for development and debug, but gives up the ability to update the Zephyr app via UART or BLE.

Note: If using VS Code for development the build with mcuboot and build tasks can be used to easily build the firmware.

Note: The OOB demo integrates the Memfault SDK. See here for more details.

Issue these commands from the ble_gateway_firmware directory.

WARNING: If using windows, checkout code to a path of 12 characters or less to avoid build issues related to path length limits.

Build without mcuboot:

Note: [board] should be replaced with mg100 or pinnacle_100_dvk

# Linux and macOS

rm -f app/pm_static.yml && west build -b [board] -d build/[board]/aws app

# Windows

del app\pm_static.yml && west build -b [board] -d build\[board]\aws app

Note: When switching between builds with or without mcuboot, be sure to delete the build directory before building.

Build with mcuboot:

Note: [board] should be replaced with mg100 or pinnacle_100_dvk

# Linux and macOS

cp ../modules/zephyr_lib/mcuboot_config/pm_static.[board].yml app/pm_static.yml

west build -b [board] -d ${PWD}/build/[board]/aws ${PWD}/app -- -DOVERLAY_CONFIG=${PWD}/../modules/zephyr_lib/mcumgr_wrapper/config/overlay-mcuboot.conf -Dmcuboot_DTC_OVERLAY_FILE="${PWD}/app/boards/pinnacle_100.overlay" -Dmcuboot_CONF_FILE=${PWD}/../modules/zephyr_lib/mcuboot_config/pinnacle_100.conf

# Windows

copy ..\modules\zephyr_lib\mcuboot_config\pm_static.[board].yml app\pm_static.yml

west build -b [board] -d %CD%\build\[board]\aws %CD%\app -- -DOVERLAY_CONFIG=%CD%\..\modules\zephyr_lib\mcumgr_wrapper\config\overlay-mcuboot.conf -Dmcuboot_DTC_OVERLAY_FILE="%CD%\app\boards\pinnacle_100.overlay" -Dmcuboot_CONF_FILE=%CD%\..\modules\zephyr_lib\mcuboot_config\pinnacle_100.conf

After building the firmware, it can be flashed with the following command:

Note: [board] should be replaced with mg100 or pinnacle_100_dvk

# Linux and macOS

west flash -d build/[board]/aws

# Windows

west flash -d build\[board]\aws

If the firmware was built with mcuboot, west flash will program merged.hex which contains the mcuboot bootloader and app in a combined image.

BL5340

The firmware must be built to work with the mcuboot bootloader.

Issue these commands from the BLE_Gateway_Firmware directory.

WARNING: If using windows, checkout code to a path of 12 characters or less to avoid build issues related to path length limits.

# Linux and macOS

cp app/boards/pm_static_bl5340_dvk.yml app/pm_static.yml

west build -b bl5340_dvk_cpuapp -d ${PWD}/build/bl5340_dvk_cpuapp/aws ${PWD}/app -- -DOVERLAY_CONFIG=${PWD}/../modules/zephyr_lib/mcumgr_wrapper/config/overlay-mcuboot.conf -Dmcuboot_CONF_FILE=${PWD}/../modules/zephyr_lib/mcuboot_config/bl5340.conf

# Windows

copy app\boards\pm_static_bl5340_dvk.yml  app\pm_static.yml

west build -b bl5340_dvk_cpuapp -d %CD%\build\bl5340_dvk_cpuapp\aws %CD%\app -- -DOVERLAY_CONFIG=%CD%\..\modules\zephyr_lib\mcumgr_wrapper\config\overlay-mcuboot.conf -Dmcuboot_CONF_FILE=%CD%\..\modules\zephyr_lib\mcuboot_config\bl5340.conf

After building the firmware, it can be flashed with the following command:

# Linux and macOS

west flash -d build/bl5340_dvk_cpuapp/aws

# Windows

west flash -d build\bl5340_dvk_cpuapp\aws

The full firmware comprising of the application and mcuboot for the application code and Bluetooth stack and mcuboot for the network core will be flashed to the module. Note that if flashing fails, it might need to be performed by doing a recover which an be done by using the following command instead:

# Linux and macOS

west flash --recover -d build/bl5340_dvk_cpuapp/aws

# Windows

west flash --recover -d build\bl5340_dvk_cpuapp\aws

Development

See here for help on getting started with custom development.

Cellular Network Information

See here for instructions on how to get details about the cell network (Pinnacle 100/MG100 only).