2.11. NXP Thread Demo - User Guide

2.11.1. Overview

Rigado has collaborated with NXP to bring the NXP Modular gateway Thread Demo via NXP’s IDEx to the Vesta-200R and Vesta-300R Gateways. This collaboration allows NXP’s Out-of-Box Thread Demo to run using Rigado Vesta Gateways in place of NXP’s IoT Modular Gateway. The NXP’s Thread Demo code allows for:

  • a Vesta Gateway to be commissioned as a Thread router,
  • one or more Rigado R41Z evaluation boards to be commissioned as endpoints in the Vesta’s Thread network,
  • messages to be sent between NXP’s Modular Gateway Manager Android application (running on a mobile device) and Thread endpoint devices by way of an MQTT server residing in the Amazon Web Services (AWS) cloud.

This document provides instructions on how to install and/or activate the code necessary to run NXP’s Out-of-Box Thread Demo, and how to run the Demo itself. It is largely based on NXP’s document of the Demo found here: NXP Modular Gateway Documents.

Note

NXP requires account registration to view the documents.

Specifically, this document describes how to:

  1. Load Thread endpoint firmware supporting the NXP Demo onto one or more R41Z evaluation boards
  2. Activate code that supports the NXP Demo on a Rigado 200R or 300R Gateway
  3. Obtain and register NXP’s Modular Gateway Manager Android application
  4. Commission the Rigado Gateway as a Thread router using the Modular Gateway Manager
  5. Commission R41Z evaluation boards as Thread endpoints using the Modular Gateway Manager
  6. Send commands to and receive data from R41Z evaluation boards commissioned as Thread endpoints using the Modular Gateway Manager

2.11.2. Prerequisites

2.11.2.1. Hardware

The following hardware is required:

  • A Rigado Vesta Gateway (Vesta-200R or 300R), running Rigado Gateway OS’s Lithium Developer image version 3.2 or higher. The unit’s packaging must also contain a Thread Demo card insert.
  • One or more Rigado R41Z evaluation board units.
  • An Android device running release 5.0 (Lollipop) or greater. The device must have a rear-facing camera.
  • A Windows computer running a virtual terminal application such as Putty or Tera Term.

2.11.3. NXP Thread Demo Architecture

../_images/nxpdemo-1.jpg

Figure 2.9 The architecture of NXP’s Out-of-Box Thread Demo

As shown in Figure 2.9, the Rigado Vesta Gateway serves as a Thread router, providing connectivity between Thread endpoint devices (Rigado R41Z evaluation boards running NXP Thread endpoint firmware) and an NXP MQTT broker residing on an Amazon Web Services server. NXP’s Modular Gateway Manager—an Android application running on a mobile device—also connects with the NXP MQTT Broker, and uses MQTT publish and subscribe messages to send commands to and receive data from the Thread endpoint devices.

2.11.4. Loading End Device firmware

2.11.4.1. Obtaining NXP Thread Endpoint firmware for R41Z Evaluation Boards

NXP’s Thread endpoint firmware binary for Rigado’s R41Z evaluation board is available for download from Rigado at Thread binary for R41Z module.

2.11.4.2. Flashing R41Z Evaluation board

The following instructions describe how to load the NXP Thread endpoint firmware binary to an R41Z evaluation board from a Windows PC:

  1. Plug a Micro USB cable into the J1 connector of an R41Z evaluation board, as shown below, and plug the other end into a Windows PC:

    ../_images/nxpdemo-2.jpg

    Figure 2.10 Connecting the R41Z evaluation board via USB

  2. The device will appear as a device labeled “FRDM-KW41ZJ” on the PC’s File Explorer.

    ../_images/nxpdemo-3.jpg

    Figure 2.11 The R41Z evaluation board in File Explorer

  3. Click on the “FRDM-KW41ZJ” device, as if it were a disk drive, to select the unit.

  4. Copy the “FRDM-KW41Z_REED_Flash_v1_4_0.bin” firmware that you downloaded from Rigado’s web site to the device.

    ../_images/nxpdemo-4.jpg

    Figure 2.12 Copying the firmware onto the evaluation board

  5. Wait for the file to finish loading, as indicated by the progress bar.

  6. Power cycle the board by unplugging and re-plugging the micro USB from the board.

2.11.5. Activating Rigado Gateway code that supports NXP’s Thread Demo

Starting with the Lithium developer release, Rigado’s Vesta Gateway Operating System comes packaged with all the code needed to support NXP’s Out-of-Box Thread Demo. To activate this code on a Vesta 200R or 300R unit, you’ll need to run a simple shell script and then reboot your Vesta unit.

Be aware that the script that activates the code supporting the NXP Thread Demo will also disable the Gateway’s IoT Gateway setup feature, which lets you access the Gateway over a temporary, open-access Wi-Fi channel to administer local parameters, such as your site’s Wi-Fi SSIDs and Passwords. Be sure you’ve completed all site-specific configuration of your Gateway unit before activating the NXP Thread Demo support code.

To activate the NXP Demo support code, SSH into the Gateway as the root user:

ssh root@XXX.XXX.XXX.XXX

where XXX.XXX.XXX.XXX is the IP address that was assigned to your Gateway by your local DHCP server.

Note

One way to determine the IP address assigned to your Gateway unit is to install avahi on your system, and run the command avahi-browse -ar. The avahi output generated by Vesta Gateway units includes the unit’s serial number. You can find the serial number of your unit by looking at the label on the bottom side of the unit.

Note

If you are working on a Windows PC, you can use an Xserver application, such a MobaXTERM, to establish a remote connection to the gateway.

Once you’ve established a connection to the Gateway, run the command sequence as shown here:

root@B013012517-00005:/home/root# cd /usr/rigado/scripts

root@B013012517-00005:/usr/rigado/scripts# ./load_nxp_demo.sh

This script will configure your Vesta Gateway to support the NXP
Thread Demo. To do this, it will load NXP's KW41Z Thread binary
onto the Gateway's R41Z unit, and reconfigure the Gateway's kernel
initialization scripts to enable communication with NXP's Volansys
Modular Gateway Manager Android application. Due to resource
conflicts, this script will also disable the Gateway's wireless
configuration capability.

Do you wish to proceed? (Y/N)
Y

loading NXP's thread firmware to R41Z . . . .

writing files /lib/firmware/r41z/nxp-thread-r41z.bin.hex to R41Z . . . .
Open On-Chip Debugger 0.10.0+dev-00157-g2c8602ed-dirty (2017-09-04-13:27)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
imx_gpio GPIO nums: swclk = 78, swdio = 77
none separate
Info : add flash_bank kinetis kx.pflash
adapter speed: 1000 kHz
none separate
cortex_m reset_config sysresetreq
Info : imx_gpio GPIO JTAG/SWD bitbang driver
Info : SWD only mode enabled (specify tck, tms, tdi and tdo gpios to add JTAG mode)
Info : imx_gpio mmap: pagesize: 4096, regionsize: 131072
Info : clock speed 1000 kHz
Info : SWD DPIDR 0x0bc11477
Error: MDM: failed to read ID register
Info : SWD DPIDR 0x0bc11477
Info : kx.cpu: hardware has 2 breakpoints, 2 watchpoints
target halted due to debug-request, current mode: Thread
xPSR: 0x61000000 pc: 0xfffffffe msp: 0xfffffffc
Info : MDM: Chip is unsecured. Continuing.
target halted due to debug-request, current mode: Thread
xPSR: 0x61000000 pc: 0xfffffffe msp: 0xfffffffc
Info : Kinetis MKW41Z512xxx4 detected: 2 flash blocks
Info : 2 PFlash banks: 512k total
Info : Disabling Kinetis watchdog (initial SIM_COPC 0x0c)
\*\* Programming Started \*\*
auto erase enabled
Info : This device supports Program Longword execution only.
Info : This device supports Program Longword execution only.
Warn : Flash Configuration Field written.
Warn : Reset or power off the device to make settings effective.
Info : This device supports Program Longword execution only.
Info : This device supports Program Longword execution only.
wrote 524288 bytes from file /lib/firmware/r41z/nxp-thread-r41z.bin.hex in 14.592115s (35.087 KiB/s)

** Programming Finished **
** Verify Started **
verified 524288 bytes in 3.403894s (150.416 KiB/s)
** Verified OK **
Info : MDM: Chip is unsecured. Continuing.

Modifying Kernel init to start NXP demo processes during boot . . .

update-rc.d: /etc/init.d/iot-gateway-setup-buttond exists during rc.d purge (continuing)
Removing any system startup links for iot-gateway-setup-buttond ...
/etc/rc0.d/K99iot-gateway-setup-buttond
/etc/rc2.d/S99iot-gateway-setup-buttond
/etc/rc3.d/S99iot-gateway-setup-buttond
/etc/rc4.d/S99iot-gateway-setup-buttond
/etc/rc5.d/S99iot-gateway-setup-buttond
/etc/rc6.d/K99iot-gateway-setup-buttond

update-rc.d: /etc/init.d/hciattach.sh exists during rc.d purge (continuing)
Removing any system startup links for hciattach.sh ...
/etc/rcS.d/S61hciattach.sh
Adding system startup for /etc/init.d/BRDeamons.
The gateway must be rebooted to finish setting up support
for the NXP Thread Demo. Do you wish to reboot now? (Y/n)
Y

On every subsequent Gateway boot after the load_nxp_demo.sh script has been run, a set of processes that support the NXP Thread Demo will start automatically as part of the Gateway’s initialization sequence.

2.11.6. Obtaining and Registering the NXP Modular Gateway Manager Application

2.11.6.1. Obtaining the NXP Modular Gateway Manager Android Application

  1. Go to the Google Play store on your Android phone, and search for “Modular Gateway”.
  2. Select the application named “Modular Gateway” from Volansys Technologies, and install the application to your phone.
  3. Accept all permissions requested as the install progresses.

Note

Your mobile device must be running Android 5.0 (Lollipop) or higher. Google Play will not display the Modular Gateway application in its search results on phones that are running older versions of Android.

2.11.6.2. Registering the Modular Gateway Application with NXP’s Cloud Server

To use the Modular Gateway Application, you must register it with NXP’s cloud server. To do this, you will need information from the Thread Demo card that was shipped with your Rigado Gateway (Vesta 200R and 300R units only). A sample of this card is shown below:

../_images/nxpdemo-5.png

Figure 2.13 The Thread Demo card

Follow these steps to register the Modular Gateway application:

  1. Launch the NXP Modular Gateway Manager application. You will see the following screen:

    ../_images/nxpdemo-6.jpg

    Figure 2.14 Volansys Modular Gateway Manager: start screen

  2. Click on Next button to go to the next page.

    ../_images/nxpdemo-7.jpg

    Figure 2.15 Volansys Modular Gateway Manager: User Authentication screen

  3. Enter the requested Authentication ID, using the NXP Demo Serial Number from the Thread Demo card provided with your Vesta unit.

    Note

    This Serial number is derived from, but not identical to, your Rigado Gateway’s actual unit serial number.

  4. Check the “remember me” box so you won’t need to re-enter this Serial Number each time you start the Modular Gateway application.

  5. Click the Submit button.

  6. If your Serial Number is recognized as legitimate by NXP’s cloud server, you will be prompted to enter your name and email address. Enter this information, and press Submit.

  7. An email will be sent to the email address you provided with a verification code that needs to be added into the OTP field (One-Time-Password).

  8. Enter the verification code, and press the Submit button. If the code is accepted, you will be returned to the User Authentication Screen.

  9. Press the Submit button to be redirected to the Commissioned Gateway Listing screen, which will state that “None of the Gateway is commissioned yet”.

    ../_images/nxpdemo-8.jpg

2.11.7. Commissioning a Rigado Gateway as a Thread Router

Once you’ve successfully registered the NXP Modular Gateway Application, you’ll need to commission your Rigado Gateway as a Thread border router for the NXP Thread Demo. Follow these steps to commission your Gateway:

  1. Open the NXP Managed Gateway Manager Android application, and proceed to the “Commissioned Gateway Listing” screen. If no Gateways have previously been commissioned, you’ll see the following screen (If one or more Gateways have previously been commissioned, you’ll see a list of these Gateways instead):

    ../_images/nxpdemo-9.jpg

    Figure 2.16 Volansys Modular Gateway Manager: Commissioned Gateway Listing screen

  2. Press the button on the bottom right of the screen that has the QR code icon. This will activate your phone’s rear camera. Move the phone until you see a clear view of the QR code on the Thread Demo card that shipped with your Gateway on the phone’s screen, and then capture the QR code’s image (on many phones this is done simply by touching the phone’s screen). If you capture the QR code clearly, you will be returned to the Commissioned Gateway Listing screen, and you’ll see a new Gateway added to the list, with the name VTBR_XXXXXXXXXXXX, where XXXXXXXXXXXX is the MAC address of your Rigado Gateway.

  3. Power up the Rigado Gateway, and after it has finished booting, place it in “commissioning mode”, which activates the unit’s Bluetooth Low Engergy (BLE) interface, by pressing and holding the Gateway’s “User button” (on the top of Gateway, immediately adjacent to the LED) for more than 5 seconds, but less than 15 seconds. If you’ve held the button down for the correct duration, the Green LED will start blinking shortly after you release the button, indicating that the unit has entered commissioning mode. The unit will remain in commissioning mode for up to 10 minutes. After 10 minutes, the unit will automatically exit commissioning mode.

    ../_images/nxpdemo-10.jpg

    Figure 2.17 A Vesta Gateway in “commissioning mode”

  4. In the Modular Gateway Manager Android application, go to the “Commissioned Gateway Listing” screen, and select the Gateway to be commissioned by tapping on its list entry.

  5. Press the button with three vertical dots at the top right corner of the screen, then select Properties from the drop down menu. This will bring up the Gateway Properties screen.

    ../_images/nxpdemo-11.jpg

    Figure 2.18 Volansys Modular Gateway Manager: Gateway Properties screen

  6. Select Ethernet as the network interface (do this even if you are using the Gateway’s Wi-Fi interface to connect to the internet).

  7. Select BLE as the mode of transfer.

  8. Click on the Submit button to initiate the commissioning process via BLE.

  9. You will be redirected to “Exchange Credential over BLE” screen. The next step is to have the Modular Gateway Manager perform a Bluetooth scan to search for Gateways that are in commissioning mode. To trigger this scan, press the blue button with the Bluetooth icon that is located on the bottom right hand corner of the screen:

    ../_images/nxpdemo-13.jpg

    Figure 2.19 Volansys Modular Gateway Manager: Exchange Credential over BLE screen

    ../_images/nxpdemo-14.jpg

    Figure 2.20 Volansys Modular Gateway Manager: scanning to exchange credentials over BLE

  10. If the scan is successful, the Rigado Gateway that you’ve placed in commissioning mode should appear on the list, as shown below. If your Gateway does not appear, please verify that the unit has successfully been placed in Commissioning mode, and try running the search again.

../_images/nxpdemo-15.jpg

Figure 2.21 The Rigado Gateway listed in Volansys Modular Gateway

  1. Select the Rigado Gateway to commission it by tapping its list entry. This will trigger a data exchange between the Modular Gateway Manager and the Rigado Gateway via BLE, which may take a couple of seconds to complete.
  2. You should see an indication that the Gateway has been successfully commissioned.
  3. Remove the Gateway unit from commissioning mode by pressing its user button for a duration between 5 and 15 seconds. If you’ve held the button down for the correct duration, you should see the Green LED stop blinking and revert to steady green shortly after you release the user button.

Note

If for some reason the commissioning process fails (e.g. loss of Bluetooth connectivity) you will need to reboot the Gateway and put it back in commissioning mode. This is required before attempting to rerun the commissioning sequence within the NXP Modular Gateway Manager application. In rare cases, it may also be necessary to power down and reboot the Android phone before rerunning the commissioning sequence.

Note

If you’ve previously configured the Rigado Gateway to connect to the internet via Wi-Fi, rather than wired ethernet, the commissioning process and the rest of the NXP Thread Demo should still work, even though the “Ethernet” option was selected on the “Gateway Properties” screen during the commissioning process.

2.11.8. Commissioning Thread Endpoints

2.11.8.1. Obtaining the EUI-64 of an R41Z Evaluation Board

The following steps assume that NXP Thread endpoint firmware has previously been loaded onto the R41Z Evaluation board, as described in Flashing R41Z Evaluation board.

  1. Connect the R41Z evaluation board to a USB port on your PC, as shown in Figure 2.10.

  2. Use your computer’s Device Manager to determine the COM port to which the R41Z evaluation board has been assigned. The board will show up as “JLink CDC UART Port” in Device Manager’s Port Listings.

  3. Open a terminal emulation application on host PC. The following example shows Tera Term, but any serial terminal emulator will work.

  4. Select Serial Communication mode.

    ../_images/nxpdemo-17.jpg

    Figure 2.22 Tera Term: New connection dialog

  5. Select the correct COM port, and set the serial post configuration as: 115200-8-none-1-stop-bit no-flow-control.

    ../_images/nxpdemo-18.jpg

    Figure 2.23 Tera Term: serial port setup dialog

  6. Initiate the serial connection. You may need to press the carriage return once the window has opened in order to receive the command prompt.

  7. Enter the command:

    $ thr get eui
    

    This will display the EUI-64 of the Thread device. Be sure to make a note of the entire eui (16 hex digits), including any leading zeros.

    ../_images/nxpdemo-19.jpg

    Figure 2.24 Example EUI-64 of an R41Z evaluation board

2.11.8.2. Thread End Device Commissioning

Follow the steps below to commission an R41Z evaluation board running NXP’s Thread endpoint firmware as a Thread endpoint behind a previously-commissioned Rigado Gateway:

  1. Open the NXP Modular Gateway Manager Android application, and proceed to the screen showing the list of registered gateway units.

    ../_images/nxpdemo-16.jpg

    Figure 2.25 Volansys Modular Gateway Manager: Commissioned Gateway Listing screen

  2. Tap the list entry of the Gateway you wish to serve as the Thread Router for the R41Z evaluation board in question. This will place you on the “Gateway End Node Listing” screen. The screen will show the list of Thread endpoint devices that are currently registered for the selected Gateway. If no devices have yet been registered, the following screen is displayed:

    ../_images/nxpdemo-20.jpg

    Figure 2.26 Volansys Modular Gateway Manager: empty Gateway End Node Listing screen

  3. Press the button with three vertical dots at the top right corner of the screen, then select End node commissioning from the menu.

  4. The application has two options for commissioning and registering end nodes. However, Rigado’s implementation of the NXP demo only supports the Manual Commissioning method. Select this radio button.

    ../_images/nxpdemo-21.jpg

    Figure 2.27 Volansys Modular Gateway Manager: End Node Commissioning Option screen

  5. This will bring you to the End Node Manual Commissioning screen. Follow these steps to manually commission and register the end node:

    1. Select End node type Thread and enter the unique id EUI-64 of the end device in hex format.

    2. Ignore leading 0x from EUI-64 string if present (e.g. if the EUI-64 string is 0x00049f075351003a then enter unique id as 00049f075351003a).

    3. If the EUI-64 string has less than 16 hexadecimal characters, then prepend 0 while entering unique ID (e.g. if the EUI-64 string is 0x49f075351003a then enter unique id as 00049f075351003a).

    4. Click the Submit button.

      ../_images/nxpdemo-22.jpg

      Figure 2.28 Volansys Modular Gateway Manager: End Node Manual Commissioning screen

  6. When the NXP cloud service accepts the new end node, you’ll see a message appear on the bottom of the screen, indicating the end node has been successfully commissioned:

    ../_images/nxpdemo-29.jpg

    Figure 2.29 Volansys Modular Gateway Manager: End Node Manual Commissioning success notification

  7. Push the OK button. You’ll then see the following screen:

    ../_images/nxpdemo-31.jpg

    Figure 2.30 Volansys Modular Gateway Manager: Make End Node Online screen

  8. Now put the R41Z evaluation board in network-joining or discovery mode. This is done by powering up the board, and then pressing the Switch 3 button. After pressing the SW3 button, the R41Z evaluation board’s LEDs should flash rapidly changing colors.

    ../_images/nxpdemo-24.jpg

    Figure 2.31 R14Z evaluation board Switch 3 (SW3)

  9. You should get a notification in the NXP Modular Gateway Manager application, at the bottom of the screen, as shown below, when the R41Z evaluation device joins the network. The LEDs on the R41Z evaluation board should also stop flashing if this step completes successfully:

    ../_images/nxpdemo-30.jpg

    Figure 2.32 Volansys Modular Gateway Manager: Make End Node Online success notification

  1. Press the NO option to acknowledge the notification. The Managed Gateway Manager application will return to the “Gateway End Node Listing” screen, and a new entry with the R41Z evaluation board’s EUI should be present on the list.

    ../_images/nxpdemo-26.jpg

    Figure 2.33 Volansys Modular Gateway Manager: Gateway End Node Listing with R41Z listed

Note

If the notification fails to appear when the R41Z board attempts to join the network, make sure there are no other Vesta Gateway units powered up in the area that have previously been configured to run the NXP demo (e.g. the ./load_nxp_demo.sh script has been run on that unit). Rigado has observed end node devices failing to connect to the designated Gateway unit when more than one Gateway unit is running the Thread Demo code at the site.

2.11.9. Thread End Device Control

To demonstrate communication between the NXP Modular Gateway Manager application and a Thread endpoint, do the following:

  1. Start the NXP Modular Gateway application, and proceed to the “Commissioned Gateway List” screen.

  2. Select a Gateway from the list. This will take you to the “Gateway End Node Listing” screen, and show you the list of currently commissioned Thread end devices associated with that Gateway.

  3. Tap one of the listed Thread end device in mobile application. If the device is powered on and connected to the Gateway, you will enter the control screen for the selected device:

    ../_images/nxpdemo-27.jpg

    Figure 2.34 Volansys Modular Gateway Manager: End Node Attribut Control screen

  4. Using this screen, you can do the following:

  • LED: Press one of the LED color buttons. This will cause the R41Z evaluation board’s LED to change to the selected color.
  • Accelerometer: Press the circular arrows button in the upper right corner of the Accelerometer portion of the window to obtain the current X, Y, and Z readings from the R41Z evaluation board. If you re-orient the R41Z evaluation board between button presses, you should see a significant change in the reported values.
  • Button Press: Each time you press the SW3 button on the R41Z evaluation board, the button press counter on the Modular Gateway Manager’s screen should increment by one.