Asset Tracking with Nordic and Medium One

Build an Asset Tracker Using Nordic nRF9160 Development Kit and Medium One IoT Cloud

Image Source: metamorworks/shutterstock.com

By Greg Toth for Mouser Electronics

Published January ‎27, ‎2020

The Nordic nRF9160 Development Kit is an IoT development board that supports the design and development of application firmware for the Nordic nRF9160 LTE Cat-M1 and Cat-NB1 (NB-IoT) system-in-package (SiP). The board features two microcontrollers, a variety of input/output interfaces, and wireless support for LTE Cat-M1/NB1, Bluetooth® and IEEE 802.15.4 protocols. The Medium One IoT Prototyping Sandbox is a cloud based IoT platform designed to help early stage developers prototype IoT projects or connect existing hardware to the cloud. In this project, we'll set up an IoT development environment using the nRF9160 development kit (DK) to read Global Positioning System (GPS) location data and send the data to the Medium One cloud using Message Queuing Telemetry Transport (MQTT) over LTE Cat-M1. Once the data is in Medium One, it can be processed and viewed on a dashboard that includes configurable widgets and a map for displaying GPS position data.

Project Materials and Resources

The project bill of materials (BOM) lists components used in this project. Additional hardware and software development tools are also identified.

Project BOM

• Nordic nRF9160 including board, SIM card, and GPS antenna
• Type-A to Micro USB cable
• Medium One IoT Prototyping Sandbox subscription

Hardware

• Personal computer (PC) running Microsoft® Windows® or macOS®

Accounts and Software

• Web browser for accessing software download sites and Medium One IoT Prototyping Sandbox
• Login account for the Medium One IoT Prototyping Sandbox
• Login account for Nordic nRF Connect for Cloud
• Nordic nRF Connect for Desktop
• Nordic nRF Connect SDK
• SEGGER Embedded Studio
• Application project files available in a GitHub repository
• Serial terminal program such as Tera Term on the PC

Project Technology Overview

Nordic nRF9160 DK

The nRF9160 DK (Figure 1) is an IoT development kit based on the nRF9160 SiP – a compact, highly integrated System-in-Package (SiP) providing easy to use low power LTE technology for LTE-M, NB-IoT, and GPS. If offers built-in LTE connectivity for creating Internet of Things (IoT) applications that communicate wirelessly with other systems and devices. The combination of board, microcontroller and onboard components offer developers a number of features for prototyping IoT designs:

• Nordic nRF9160 low power SiP with integrated LTE-M/NB-IoT modem and GPS
• Arm® Cortex®-M33 application processor
• Additional Nordic nRF52840 System on Chip (SoC) supporting Bluetooth Low Energy
• Onboard antennas for LTE-M and NB-IoT, GPS and 2.4GHz Bluetooth Low Energy
• LTE extended discontinuous repitition cycle (eDRX) and power saving mode (PSM) power saving features
• Variety of input/output interfaces including
  • Analog-to-digital-converter (ADC)
  • Real-time clock (RTC)
  • Serial peripheral interface (SPI)
  • Inter-integrated circuit (I²C)
  • Universal asynchronous (UART)
  • Pulse duration modulation (PDM)
  • Pulse-width modulation (PWM)
• Arm TrustZone and Arm CryptoCell supporting secure, trusted IoT applications including high performance cryptography optimized for energy-constrained devices
• Embedded subscriber identify module (eSIM) and SIM support for connecting and authenticating to mobile network operators
• An included iBASIS eSIM card preloaded with 10 MB data credit
• Arduino Uno Rev3 compatible connector pinout
• User-programmable LEDs (four), push buttons (two) and slide switches (two)
• Onboard Segger J-Link OB for programming and debugging

Technical documentation for the nRF9160 DK can be found at Mouser and Nordic.

Figure 1: nRF9160 DK. (Source: Mouser Electronics)

The board is supported by the nRF Connect SDK, the nRF Connect for Desktop cross-platform application development toolset, and nRF Connect for Cloud—Nordic's cloud environment for provisioning and managing SIM cards and LTE devices. It connects to application development tools on a PC using a USB cable to support programming and debugging as well as microcontroller serial port connectivity. An Arduino Uno compatible expansion connector allows you to expand the board capabilities with Arduino compatible sensor and actuator shields.

Nordic nRF connect for Desktop

nRF Connect for Desktop (Figure 2) is a cross-platform development environment for Nordic's cellular IoT and Bluetooth Low Energy products. It runs on Windows, Linux® and macOS personal computers and provides tools for auto-detecting development boards, testing and monitoring LTE-M and NB-IoT connectivity, and a Getting Started Assistant for installing the development tools and SDK needed for application development. Installable development tools include nRF Connect SDK, SEGGER Embedded Studio, and the GNU Arm cross-compiler toolchain.

Figure 2: nRF Connect for Desktop (Source: Mouser Electronics)

Nordic nRF Connect SDK

The nRF Connect SDK offers developers an extensible framework for building applications that run on Nordic's cellular IoT and Bluetooth Low Energy devices. Source code is publicly hosted on GitHub and includes the Zephyr real-time operating system along with a wide range of samples, application protocols, protocol stacks, libraries, and hardware drivers. It contains everything needed to develop nRF9160 applications and works seamlessly with the LTE modem firmware.

Nordic nRF Connect for Cloud

nRF Connect for Cloud (Figure 3) is a versatile IoT connectivity enabler that can be used with Nordic's cellular and Bluetooth Low Energy devices. It's an integral part of the cellular IoT development workflow and supports SIM activation, development kit management, tracking of development kit metrics and geographical location, monitoring cellular data usage, and includes an asset tracker example application based on the nRF Connect for Cloud platform.

Figure 3: nRF Connect for Cloud (Source: Mouser Electronics)

Project Application Source Code Files

For this project, the nRF Connect SDK and nRF Connect for Desktop tools were used to create project source code files that integrate the nRF9160 DK with the Medium One IoT Prototyping Sandbox. The resulting files have been put in a GitHub repository that you can download and use for this project. Source code will be compiled, linked, and downloaded to the nRF9160 DK and consists of a main application program plus supporting functions for LTE connectivity, GPS position readout, LED indicator control, and MQTT message processing.

Medium One IoT Prototyping Sandbox

The Medium One IoT Prototyping Sandbox (Figure 4) is designed to help early-stage developers prototype their IoT project or connect their existing hardware to the cloud. It offers an IoT Data Intelligence platform enabling customers to quickly build IoT applications with less effort. Programmable workflows allow you to quickly build processing logic without having to create your own complex software stack. Configurable dashboards allow you to visualize application data and view real-time data in a variety of formats. Medium One's iOS® and Android® apps allow you to build simple mobile app dashboards that can communicate with your devices through the IoT Prototyping Sandbox.

Figure 4: Medium One IoT Prototyping Sandbox. (Source: Mouser Electronics)

IoT devices can exchange data with Medium One through either a REST API or MQTT. More detailed information about the Medium One IoT Prototyping Sandbox can be found here and on the Medium One site.

The Setup (Hardware)

While setting up the hardware, be sure to remember that electronic components are static-sensitive so handle accordingly.

Personal Computer (PC)

Power up the personal computer and allow it to boot up.

nRF9160 DK

Unbox the nRF9160 DK board and set it up as described in the Getting Started Guides found here and here. This will include updating the modem firmware (which involves installing several software tools on your PC and performing a firmware programming procedure), creating an nRF Cloud account, registering your board and its SIM card, and connecting the board to the PC using a USB cable. The Getting Started Guides walk you through this process including observing the example application program that's pre-programmed on the board.

Setup Tips

• There are different hardware revisions of the nRF9160 DK and some versions have a hardware issue affecting GPS functionality. See Nordic DevZone's External GPS antenna on nRF9160 DK guide for details and workarounds.
• The example asset tracker application provided with the board defaults to using simulated GPS data.
• Update the modem firmware to ensure latest fixes are available.
• Make sure the SIM card is activated in nRF Cloud and is inserted in the board's SIM slot before powering on.
• Make sure the board PROG/DEBUG switch is set in the correct position according to the setup instructions.
• Allow adequate time for LTE to connect the first time.
• Use the LTE Link Monitor application to monitor and troubleshoot LTE operation.
• Use Nordic's DevZone to ask questions and search for answers to common questions and issues.

The Setup (Software)

Download and Install nRF Connect for Desktop and nRF Connect SDK

Web browse to the nRF Connect for Desktop site and locate the installer for your type of PC. Run the installer and then launch the installed nRF Connect application. Detailed steps are described in Getting Started with nRF9160 DK and include installing and running the Getting Started Assistant, the LTE Link Monitor and the Programmer.

The Getting Started Assistant walks you through a number of steps to download and install the compiler toolchain and supporting utility programs, the nRF Connect SDK, and SEGGER Embedded Studio. Each of these steps involve a number of lower-level steps that are described in the Getting Started Assistant and the getting started documentation.

The nRF Connect SDK source code files will be installed into a directory you specify during installation and the top-level SDK directory will be named ncs.

After successfully completing the entire Getting Started Assistant, you should have a functioning software development environment installed on your PC that can be used to build and run applications on the nRF9160 DK board. You can build and run board applications using either the command line tools (west commands) or the SEGGER Embeded Studio IDE.

Setup Tips

• Make sure you're using the latest versions of nRG Connect and Getting Started Assistant.
• Use the Getting Started Assistant verify functions to confirm that each installation step was successful.
• If you get compilation errors about missing header files, check your file paths, environment variables, and potential missing packages that may need to be separately installed on your PC.
• Use Nordic's DevZone site to ask questions and search for answers to common questions and issues.

Download and Open the Project Application Source Code Files

Web browse to the GitHub repository https://github.com/IoTDevLabs/ma10_files and find the nRF9160_MediumOne_1.0.0.zip file. Download that file to your computer and unzip it to create a directory named nrf9160_mediumone. Move that entire directory and place it in the following location within your ncs directory that contains the nRF Connect SDK files: ncs/nrf/samples/nrf9160/nrf9160_mediumone

We'll come back to the source code files after setting up Medium One.

Set Up the Medium One IoT Prototyping Sandbox

Web browse to the Medium One IoT Prototyping Sandbox and log in, after which you should see an initial dashboard resembling Figure 4. Click Setup > Manage Users > Add New User. Set Username to mydevice, create a password of your choosing and enter it in both password fields, then click Save. In the Manage API Users list you should see a new user account having Login ID = mydevice and an auto-generated user MQTT ID (Figure 5).

Figure 5: Newly created user ID with auto-generated MQTT ID (Source: Mouser Electronics)

Click Setup > MQTT and you should see a Project MQTT ID and a set of port numbers (Figre 6).

Figure 6: Project MQTT ID. (Source: Mouser Electronics)

Medium One uses MQTT usernames and passwords for authentication. The MQTT username is created by combining the Project MQTT ID, a forward slash, and the user MQTT ID. For example, if the Project MQTT ID is "ZHxxxxxxx0Y" and the user MQTT ID is "sTxxxxxxx8w" the corresponding MQTT username would be "ZHxxxxxxx0Y/sTxxxxxxx8w".

Next we'll create the MQTT password. Navigate to Setup > Manage API Keys > Add New API Key. Set the description to mydevice, make sure Enabled is check-marked, and click Save. The result should look like Figure 7.

Figure 7: Newly Created API Key. (Source: Mouser Electronics)

The MQTT password is created by combining the API Key, a forward slash, and the mydevice user password. For example, if the API Key is "PZxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxMBQ" and the mydevice user password is "AaaaBbbb3" the corresponding MQTT password would be "PZxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxMBQ/AaaaBbbb3".

The MQTT topic has the following format: "0/Project MQTT ID/User MQTT ID/Device ID".

The Device ID field can be anything, and we'll use "mydevice" as the Device ID. For example, if the Project MQTT ID is "ZHxxxxxxx0Y" and the user MQTT ID is "sTxxxxxxx8w" the corresponding MQTT topic would be "0/ZHxxxxxxx0Y/sTxxxxxxx8w/mydevice".

The MQTT username, MQTT password, and MQTT topic strings will get added to the project source code in the next step.

Update Application Source Code Files for Medium One Account Parameters

The application code can be edited and built using either the command line toolset or SEGGER Embedded Studio. For the next steps we'll use the command line toolset.

Edit the nrf9160_mediumone/Kconfig file and make the following changes:

• In the MQTT_Pub_Topic section set the "default" string value to your Medium One MQTT publish topic.
• In the MQTT_BROKER_USERNAME section set the "default" string value to your Medium One MQTT username.
• In the MQTT_BROKER_PASSWORD section set the "default" string value to your Medium One MQTT password.

Note: This project uses unencrypted MQTT communications between the nRF9160 DK and the Medium One MQTT broker. The MQTT username and password are sent over the Internet in the clear and neither the credentials nor the transmitted data are encrypted.

Save the modified file and then build the project from the command line using this command issued from a shell command prompt within the nrf9160_mediumone directory:

west build -b nrf9160_pca10090ns

Verify the code compiles without errors. If you see compilation errors, check the changes you made to the Kconfig file and make sure your nRF Connect SDK and tools environment are installed.

Each time you modify the Kconfig file, delete the entire build/ directory before building the code again so that the modified Kconfig is used.

Run the Application

Make sure the nRF9160 DK is connected to the PC through USB, then download the program to the board using this shell command:

west flash

The program should be downloaded to the board and start running. You can connect a serial terminal program such as Tera Term to the USB serial com port if necessary to monitor debug messages from the nRF9160 DK while it's running. Set the serial parameters to 115200,N,8,1.

The application program will first connect to the carrier LTE network and after a connection is established, it will begin periodically transmitting MQTT messages to Medium One. LEDs on the nRF9160 board are controlled by the application and used to indicate connection progress:

Table 1: LEDs on the nRF9160 board

	Off	Blinking	On Solid
LED1	LTE connection not yet attempted.	LTE connection attempt in progress.	LTE connected.
LED2	MQTT connection not yet attempted.	MQTT connection in progress.	MQTT Connected to broker.
LED3	GPS fix not being attempted	GPS fix attempt in progress	GPS fix obtained.
LED4	MQTT publish not being performed.	----	MQTT message buing published.

It may take some time for the first GPS fix to be obtained. Make sure the GPS antenna has a clear view of the sky.

MQTT Payload Format

MQTT messages are formatted as JSON strings according to the Medium One MQTT payload specification. Here's an example message:

{"event_data":{"iteration":40,"timestamp":16657,"gpsfix":true,"location": "39.234076 -98.172187","gpstime":"2019-11-18T16:16:43.447000+00:00"}}

Fields:

• iteration = appliation loop counter
• timestamp = milliseconds since application started
• gpsfix = true if GPS fix acquired, false if not
• location = GPS position as "latitude longitude"; present when gpsfix = true
• gpstime = GPS time as "YYY-MM-DDTHH:MM:SS.us+00:00"; present when pgsfix = true

While the application is running, the iteration and timestamp balues should be incrementing, and when a GPS fix is obtained there should be a location and gpstime value.

View Data in the Medium One Dashboard

In the Medium One dashboard, navigate to Data Viewer > Data Streams and click raw Events. You should see raw messages (Figure 8) being received from the nRF9160. Click the "+" sign to view message details.

Figure 8: Raw Message Display. (Source: Mouser Electronics)

Add a Live Map Widget and Last Value Data Display Widget

Navigate to Config > Data Streams and click on raw Events. The Schema Map should be pre-populated with fields detected in the incoming messages, however they are currently disabled. Checkmark the Active box on raw.gpsfix, raw.iteration, raw.location, and raw.timestamp. Set the Use as fields to Boolean - Time Series for raw.gpsfix, Number - Time Series for raw.iteration, GeoPoint - Last Value for raw.location, and Number - Time Series for raw.timestamp, then click Save Data Stream. These fields are now available for use in dashboard widgets.

Click Dashboard on the top left, then click Add Widget > Single User GeoPoint Chart (Figure 9) to add a map widget to the dashboard. In the Select user dropdown, select mydevice. You should see a map display on the dashboard (Figure 9) and if a GPS fix is available a marker should be visible on the map that corresponds to the GPS position sent by the nRF9160 DK Click the Refresh icon to the left of mydevice to refresh the display.

Click the Single User Last Value Table widget and select the mydevice user within the widget. Click the widget's Tag Config icon to the right of the mydevice user selection and check-mark raw:gpsfix, raw:iteration, raw:location, and raw:timestamp, then click Save. The Last Value Table should now populate with the most recent received values for each field (Figure 9). Click the Save icon towards the upper right corner to save the updated dashboard.

Figure 9: Live Map and Last Value Displays. (Source: Mouser Electronics)

At this point, your nRF9160 DK is running continuously, periodically reading the GPS position and transmitting measurements to the Medium One cloud. Remember to power off the nRF9160 DK when you're done, otherwise the board will continue to send messages to Medium One and consume daily message allotments as well as LTE data bandwidth.

Where to Go Next

This project created an end-to-end asset tracker application that uses the Nordic nRF9160 DK to send real-time GPS data to the Medium One IoT Prototyping Sandbox through a LTE wireless data link. It can be modified and extended in a number of ways. Here are a few examples:

• Dive deeper into the application code and board hardware by reading the nRF9160 DK documentation and studying the source code.
• Add more widgets to the Medium One dashboard.
• Create multiple dashboards with different data on each one.
• Learn about the Medium One Workflow Studio, which lets you create data processing workflows to transform sensor data.
• Experiment with the Medium One mobile apps.
• Implement bi-directional communications with the Medium One cloud.
• Modify the sensor data publishing interval by modifying the nRF9160 DK application source code.
• Connect other types of sensors to the nRFP9160 DK and include the data in MQTT messages.
• Enhance the mQtT communications to use MQTT over TLS.

---

Greg is an architect, engineer and consultant with more than 30 years experience in sensors, embedded systems, IoT, telecommunications, enterprise systems, cloud computing, data analytics, and hardware/software/firmware development. He has a BS in Electrical Engineering from the Univ. of Notre Dame and a MS in Computer Engineering from the Univ. of Southern California.