The global roll-out of cellular communication technologies continues to accelerate at breakneck speeds. With the new tech also comes new business opportunities for a broad swath of the economy. Logistics is one such industry that will be revolutionized by the proliferation of such technology and services. Instead of relying on static and infrequent barcode scans, imagine every single package continuously trackable down to an exact latitude and longitude.

Building just such a device is possible today using globally certified, Digi XBee LTE-M/NB-IoT wireless communications technology and cloud-based Internet of Things (IoT) services of Medium One. This project will demonstrate how to use LTE-M/NB-IoT wireless communications technology to connect a mobile low-power device to the cloud. The device will be capable of being mounted inside a container and wirelessly reporting its position, ambient temperature, and humidity. This project will also allow developers to learn MicroPython, an emerging programming language aimed at bringing traditional programmers into embedded system development.

Project Materials and Resources

This project will leverage the Digi XBee3 Cellular embedded smart modem (LTE-M/NB-IoT) development kit with the XBIB-C development board for the embedded hardware. The XBIB-C board provides battery power management as well as temperature and humidity sensors. The project will also take advantage of the XBIB-C's expansion port to add Digi's GPS expansion board.

Bill of Material (BOM)

You can click this Mouser project share link to access the BOM along with the current pricing. Table 1 lists the items in the BOM.

Table 1: 5G Cold Asset Tracker BOM

Resources

All source files for this project are on Mouser's GitHub repository. The repository is divided into three main folders:

Documentation

The Documentation folder contains graphic files of schematics and other important reference materials.

3D Files

The 3D Files folder contains 3D files needed to view and 3D print (.stl, .obj) an enclosure that will house the electronics, antenna, battery, and four small neodymium magnets to help mount the device inside of a refrigerator or similar type of container.

The files can be viewed for free here.

Figure 1: 3D model of the project enclosure. (Source: Green Shoe Garage)

Software

The Software folder contains the source code, including the following files:

• py
• json
• lib/hdc1080.py
• lib/umqtt/__init__.py
• lib/umqtt/simply.py

More details about these files can be found in the Software section below.

Tools

This project assumes that you have access to the following tools:

• Computer with a high-speed internet connection
• fx is a useful test application for MQTT communications, available here.
• Digital Multimeter (DMM)
• Small screwdriver kit
• OPTIONAL: 3D printer to print the enclosure. Recommend use of PETG filament because of its mechanical and thermal resilience. Or use an online 3D printing service using the provided files.
•  

Building the Project

In this section, we will examine the necessary steps to get your project up and running. The section is broken down into the following subsections:

1. Hardware Setup
2. Setting up the Software Development Toolchain
3. Software Development
4. Final Assembly and Installation

Figure 2: Functional prototype of the asset tracking device. (Source: Green Shoe Garage)

A quick word on the use of the Hologram eUICC Global SIM Card. Per Hologram, their SIM cards are compatible with global cell networks built for M2M data and offer easy activation, transparent pricing, and developer-friendly tools. The cards automatically connect to the best signal available on the network. Many SIM cards can be ordered, and connectivity can be managed on Hologram's dashboard, from one for testing to thousands for manufacturing.

Hardware Setup

The hardware for this project consists of three main circuit boards. The first is Digi's XBee3 Cellular embedded smart modem designed for LTE-M and NB-IoT wireless networks. This board is the key component to ensuring the M2M wireless connectivity between the endpoint device and the Medium One IoT cloud service. The board contains the wireless communication components, including the radio, antenna, and SIM card reader. The modem board is intended to be a sort of plug-and-play component that can insert into any prototype or even a production-ready IoT device. This frees product developers from worrying about designing, building, and testing their products’ RF aspects. Instead, they can focus their efforts on the unique components of their product.

Figure 3: Xbee3 LTE-M/NB-IoT radio module. (Source: Mouser)

The second circuit board is the XBIB-C development board. The XBIB-C is intended to be a way for developers to rapidly develop functional prototypes of devices built around the Xbee3 modem. It provides many features that make it appealing to those in the very early phases of product development. Some of these features include:

• Current monitoring pins for testing power consumption
• Onboard temperature and humidity sensors
• Grove adapter to additional Grove sensors
• Can be powered by USB-C or battery (via JST connector)
• Programmable user buttons
• 40-pin expansion header for accessories

Figure 4: Digi's Xbee3 Development Kit. (Source: Digi)

The last board, the GPS board, will leverage the 40-pin expansion header on the XBIB-C development board’s right side. The expansion board offers a u-blox M8 GPS solution. Digi offers a robust MicroPython library and several reference designs should one decide to incorporate the GPS solution into their custom asset tracking product.

The following steps are required to configure the hardware for mobile operations. Please note that failure to follow the prescribed steps will result in faulty operation at best and failure at worst.

1. Connect the GPS expansion board to the XBIB-C development board using the 40-pin connector. Ensure the GPS module is face-up as the connector is not keyed.
2. Insert the Xbee3 modem board into the XBIB-C development so that the modem board’s angled edges are facing toward the top of the XBIB-C board. NOTE: This step might not be required as the modem board might already be inserted into the XBIB-C board at the factory if purchased as a bundle.
3. Follow these instructions from Hologram to activate the SIM card. After the SIM card has been activated, insert the SIM card into the SIM card reader onboard the Xbee3 modem board.
4. Snap the U.FL connector of the large, flexible cellular antenna into the U.FL connector onboard the Xbee3 circuit board. Be sure to align the two connectors and use minimal force as the U.FL connectors are tiny and can be damaged if not done with care.
5. Move the two USB Direct Connect switches aboard the XBIB-C development board to the closed position (slide to the right). Failure to do so will prevent the HDC1080 temperature and humidity sensor from working correctly. Also, ensure a micro-USB cable is not plugged into the USB Direct Connect micro-USB port.
6. Plug a USB-C cable into the USB to UART USB-C port along the bottom of the XBIB-C board. Plug the other end into the computer used for firmware development.
7. Flash the firmware to the device. For more information on this process, skip to the Setting up the Software Development Toolchain section below. Once those procedures are complete, return here to continue the hardware setup.
8. Verify that the telemetry is being read out to the serial com port on the development computer and transmitted to Medium One over cellular. Ensure the serial port is set 9600 baud rate.
9. Disconnect the USB-C cable from the XBIB-C board. The following steps will be used to prepare the project for battery operation.
10. Toggle all UART Dip Switches on the XBIB-C board to the OFF
11. Insert the JST connector of the battery to the JST connector on the XBIB-C board. Ensure the ground terminal (typically black) is to the right and the positive terminal (typically red) is to the left. If the battery does not have a power switch, the board will immediately turn on.
12. On an internet-connected computer, verify that telemetry is being transmitted to Medium One via the cellular connection.

Setting up the Software Development Toolchain

To develop the firmware for this project, we will be using the PyCharm IDE, which can be downloaded here. PyCharm is offered as both a paid and free, community-supported version. This project was completed with a community edition. Digi provides a plugin for the PyCharm IDE that makes getting started developing for Digi products straightforward. The plugin can be downloaded from here. Be sure to install PyCharm first, then the plugin.

Figure 5: Firmware development is completed in PyCharm IDE with Digi's MicroPython plugin. (Source: Green Shoe Garage)

A third application that must be installed is Digi's XCTU configuration tool for their Xbee solutions. This will allow us to make configuration changes to the radio and upload files to the onboard storage. XCTU can be downloaded here. XCTU is also used to update the Xbee3 radio firmware. Please note that this project requires Digi XBee3 Cellular LTE-M/NB-IoT to have at least firmware version 11410. Furthermore, the radio must be configured to work with the Hologram SIM card by following the procedures found here.

Figure 6: The XCTU test and configuration application for Digi RF products. (Source: Digi)

Digi offers a fantastic website to help you get started and get your development to the point of talking to a cellular network. You can find those resources here. Once you have installed all the tools and completed the setup procedures for both the Hologram SIM card and your Digi Xbee3 board, it's time to create the firmware for this project.

First, find the source code from our GitHub repository. Open your command prompt, navigate to where you want to save the source code, then enter:

#git clone https://github.com/Mouser-Electronics/5G-Cold-Asset-Tracking-Project

Next, startup PyCharm. Once opened, follow these steps:

1. Click File > New Digi Project
2. Select Xbee module
3. Click Next
4. Select Digi Xbee3 Cellular LTE-M/NB-IoT
5. Click Next
6. Place a checkmark next to the hdc1080 and umqtt libraries
7. Click Next
8. Leave everything as default and finally click Create

Next, we need to create a Medium One account. Medium One provides IoT developers a platform from which their IoT devices can communicate and compile data sets across multiple IoT devices. It will also provide us with our security credentials to ensure that only our approved devices send data to our project.

Figure 7: Medium One sandbox is an easy way to configure your IoT devices and to view IoT device data (Source: Medium One)

In the Medium One sandbox, notice that our device's data will be displayed in the center window of the sandbox. Passwords and API keys are accessible from the left-hand navigation bar. This project will leverage Message Queuing Telemetry Transport (MQTT), a lightweight communications protocol built around the publish-subscribe (pub/sub)-based messaging concept. MQTT sits atop the TCP/IP protocol. Medium One provides excellent documentation on how to interact with their service via MQTT. To begin, create a new project at the top-right corner of their web-based user interface. After the new project is activated, navigate to the Setup tab on the left-hand navigation bar. A few critical pieces of information are needed to connect our device to Medium One securely. These should be guarded tightly and not shared with anyone who does not need to know. Be careful if posting your source code to GitHub that you do not accidentally expose this information. The key fields include:

• Project ID: This alphanumeric string is a unique identifier assigned to this specific project. It lets Medium One know what particular project to direct the environmental data to if we have multiple projects hosted with their web service. The Project ID is accessible from Setup→Project Info.
• API Key: This is an auto-generated alphanumeric string created to allow us to log in and use Medium One's API services. The API Key is accessible from Setup→Manage API Keys.
• MQTT ID: The MQTT ID is an alphanumeric string generated by Medium One. It's important to note that the Login ID is not the same as the MQTT ID. The Login ID is an end-user-created, human-readable string (for example, janedoe). The piece of information we need for the firmware is the MQTT ID. This is important, considering each project can have multiple contributors. MQTT ID is accessible from Setup→Manage Users.
• User Password: This is created by each user when their account is established for the project. For security reasons, it is not displayed anywhere, so be sure to remember this password.

Next, the firmware will require two other critical pieces of information. These are standard for all devices connecting to Medium One:

• Medium One MQTT server URL: mqtt.mediumone.com
• The TCP Port: 61617 (unsecured) or 61618 (secured)

At this point, all the tools have been installed, the example source code has been downloaded, the Xbee3 modem has been configured, and we have all the crucial information needed to connect to Medium One securely. Time to start modifying the source code.

Software Development

The codebase for this project is written in MicroPython. For those involved with embedded systems development for any considerable amount of time, it might come as a shock to not program in C/C++. MicroPython is an offshoot of the desktop-oriented CPython programming language. It has been tailored for the resource constraints and other realities of developing for embedded systems. Those coming from Python development of desktop applications will likely find the syntax very familiar. Traditional embedded C developers should find that MicroPython, while different, is very approachable.

Five files of interest will be found in the Software folder of the GitHub repository project structure. Files with the .py extension can contain both the main loop of your program and support libraries. You might also encounter the .mpy extension, which will contain versions of popular libraries that have been optimized for MicroPython.

The critical files for this project:

• py: Contains the main loop for the project and a few support functions to interact with the sensors and communicate with Medium One server using the MQTT protocol. Replace the main.py that PyCharm automatically generates with the contents of the main.py file you downloaded from GitHub.
• json: Holds the secure information needed to communicate with the Medium One servers, including publishing topic ID, client ID, username, and password.
• lib/hdc1080.py: This library allows users to interrogate the temperature and humidity sensors on the XBIB-C board via the I2C protocol.
• lib/umqtt/__init__.py: umqtt is implemented as a regular package, and this file helps to initialize instances of umqtt in the main code.
• lib/umqtt/simple.py: This contains the umqtt library code to allow our code to send MQTT messages.
•  

Key Variables and Constants

You might want to tweak a few variables depending on your particular design choices. These variables and can be found in main.py:

• PORT = 61618: If you would prefer to use an insecure TCP port, change this to 61617.
• DEVICE_ID = "cold_asset_tracker_0001": This can be changed to anything you desire to help identify each unique physical device you add to your Medium One project. It should be unique for each device.
• DELAY_AMOUNT=30: Sets a delay of 30 seconds between sensor readings.
•  

Key Functions

The main.py file contains six functions, in addition to a bit of initialization code and the main while loop. The main loop repeats on a 30-second interval. Every 30-seconds, it takes a reading from the GPS as well as the HDC1080 sensor. If the latitude and longitude values are valid, the data is transmitted to Medium One.

The support functions include:

• def sub_cb(topic, msg): Permits our device to read any commands or messages sent from Medium One.
• def read_gps_sample(): Reads the raw serial data from the GPS module.
• def extract_gps(serial_data): Extracts the GPS data from the serial data received.
• def extract_latitude(input_string): From the string of GPS data, extracts the latitude as floating-point number.
• def extract_longitude(input_string): From the string of GPS data, extracts the longitude as a floating-point number.
• def connect_device(): Connects the device to Medium One cloud services.

One nifty feature of MicroPython is the ability to returning multiple variables from a function call. Let's take a look at the def read_gps_sample() function, which returns two variables: lat and lon. Scroll to line 179 in main.py, which contains the following bit of code:

return lat, lon

Thus instead of having two functions to return a properly formatted latitude and longitude, it’s only a single function. Now scroll to line 270 in main.py to see how MicroPython handles two returned values:

latitude_dec, longitude_dec = read_gps_sample()

Now in the calling function, two variables (latitude_dec, longitude_dec) contain the latitude and longitude from the GPS receiver.

Figure 8: Data from the device can be sent over a virtual serial COM port for debugging purposes. (Source: Green Shoe Garage)

Key Files

Let's take a moment to discuss the secrets.json file. This file contains four critical pieces of information stored as strings: PUB_TOPIC, CLIENT_ID, USER(NAME), and PASS(WORD). These four strings are themselves created by combing five other pieces of information. The first four are provided by Medium One: Project ID, MQTT ID, API Key, and a user-generated password. See the Setting up the Software Development Toolchain section of this post to recall where these are found. The fifth and final piece of information is the user-generated DEVICE_ID that is defined in the main.py file. The five substrings are combined to create the four main strings as such:

• PUB_TOPIC = "0/<MQTT Project ID>/<MQTT User ID>/<DEVICE_ID>"
• CLIENT_ID = "<MQTT Project ID>+<MQTT User ID>+<DEVICE_ID>"
• USER = "<MQTT Project ID>/<MQTT User ID>"
• PASS = "<API Key>/<MQTT User Password>"

NOTE: CLIENT_ID is unique in that it is a concatenation of the Project ID, MQTT ID, and DEVICE ID with no space, plus signs or slashes—just one long string of numbers and letters.

These four strings are crucial to securely communicating with Medium One. We place this information in a JSON formatted text file (secrets.json) to make it easy for both the microcontroller and a human to read and manipulate. Never hardcode these strings in your firmware. Keep them secure!

The full secrets.json file should look like this:

{

    "mqtt": {

    "topic": "0/<MQTT Project ID>/<MQTT User ID>/<DEVICE_ID>",

    "client": "<MQTT Project ID>+<MQTT User ID>+<DEVICE_ID>" ,

    "user": "<MQTT Project ID>/<MQTT User ID>",

    "pass": "<API Key>/<MQTT User Password>"

    }

}

Next, we will use the XCTU application to upload the secrets.json file to the onboard storage of the Xbee3. With the USB-C cable connected between the computer and the XBIB-C's USB to UART port, fire up the XCTU application. Then perform the following steps:

1. Click the Tools icon (crossed wrench and screwdriver) in the top right of the XCTU application.
2. Click the File System Manager icon from the Tools dropdown menu.
3. Click the Open icon to launch the connection wizard.
4. Select the COM port of the Xbee3 board and ensure the following settings:
   1. Baud Rate: 9600
   2. Data Bits: 8
   3. Parity: None
   4. Stop Bit: 1
   5. Flow Control: None
5. Click OK
6. From the left column (Local Path), navigate to the location of the secrets.json file and select it.
7. Ensure that the Remote Path is at the root level, drag the secrets.json file from the Local Path to the Remote Path. Or simply double-click the secrets.json file.

With the secrets.json file uploaded to the Xbee3 onboard storage and the firmware complete, it's time to flash the firmware to the device. Back in PyCharm, let's open up our project folder then complete the following steps:

1. Select the COM port connected to the Xbee3 development board from the Select a Digi Device to Connect to dropdown in the top right of the IDE.
2. Select the board you wish to flash the firmware to and click OK.
3. Click on the Select/Run Debug Configuration dropdown, then click on Edit Configuration.
4. Verify that the checkbox has a checkmark next to the Automatically run MicroPython application at module startup.
5. Click the green Run arrow to flash the firmware to the device.
6. If you are setting up the device for the first time, the software setup is now complete. Please return to Step 8 of the Hardware Setup

Constructing the MQTT Message

The MESSAGE variable is a string constructed in a particular way to encapsulate the telemetry data (latitude, longitude, temperature, and humidity) in a manner that Medium One can ingest. In addition to the individual latitude and longitude variables, an additional variable named loc (short for location) is a concatenation of the latitude and longitude variables. Medium One geographical mapping functionality expects such a string to plot GPS data on a map. The message is constructed as follows:

MESSAGE = """{"event_data":{"temperature":""" + str(temp_celsius) + ""","humidity":""" + \ str(humidity_hr) + ""","loc":""" + "\"" + str(latitude_dec) + " " + str(longitude_dec) \ + "\"" + ""","lat":""" + str(latitude_dec) + ""","lon":""" + str(longitude_dec) + """}}"""

The above code generates a JSON string that in human-readable format would look as follows:

{"event_data":{"temperature":75,"humidity":35,”loc”:45.5335 -75.3432,"lat":45.5335,"lon":-75.3432}}

This is what Medium One sees when it receives the telemetry from our device.

Setting Up Medium One to Display Telemetry

Figure 9: Data from the asset tracking device being streamed to Medium One via MQTT messages. (Source: Medium One)

Raw data is excellent, but context is king. Visualizing the data in meaningful ways is crucial to the value proposition of the Internet of Things and big data analysis. Medium One provides many ways to turn the raw data into useful, actionable information—information that can be viewed both on desktop and mobile devices. To get started, log in to app.mediumone.com and click on Dashboard from the left-hand navigation bar. From the Dashboard screen:

1. Select the Single User Real Time Events Stream widget option at the bottom-right corner of the screen.
2. Select the user you want to view using the dropdown menu.

This step should create a dashboard that listens for incoming data. If a green play button is visible, then click it to begin listening. Otherwise, a red pause button will appear to pause the feed if necessary. If the dashboard works, then raw MQTT packets from the Xbee3 development board should begin displaying in the browser. For more information on getting started with Medium One, visit their Getting Started Guide here.

Final Assembly and Installation

Figure 10: The device wired up and ready for final assembly and installation. (Source: Green Shoe Garage)

With the electronic hardware built and the firmware flashed, it is time to finalize and install the asset tracking device we have designed.

The bottom of the enclosure provides a recess for the battery and four small neodymium magnets that can be used to secure the device to a magnetic surface. This allows the devices to be moved quickly from one container to another, as needed.

Carefully slide the flexible circuit board housing the cellular antenna into the slots in the enclosure lid. It’s recommended that you slide it in slowly from left to right.

Lastly, a few troubleshooting tips:

• Do not forget to set the UART Dip Switches on the XBIB-C board to the OFF
• Do not forget to set the two USB Direct Connect switches aboard the XBIB-C development board to the closed position (slide to the right).
• Ensure nothing is plugged into the micro-USB port labeled USB Direct Connect.
• Ensure the battery is fully charged.
• Ensure the antenna is connected to the correct U.FL connector on the XBee3 board. It should be the connector labeled CELL.
•  

Project in Action

Figure 11: a) Device being tracked in a browser in real-time. b) Device installed in cooler. (Source: Green Shoe Garage)

With the project finally assembled and installed into the thermally controlled container, let us hit the road to the device in action. Ensuring our battery is fully charged and our laptop is tethered to a smartphone, we begin to drive our essential package to its destination. Every 30 seconds, the map updates with a new marker indicating where our package is located and its current temperature and humidity.

Using a battery-monitoring device, it is estimated that the 1000mAh should provide approximately 50 hours of service between charges. Although lithium-ion batteries do better in the cold than lead-acid batteries, a production-ready model of this asset tracking device might be redesigned so that only the sensors are physically in the cold cavity and the communications and power management components remain on the outside of the container—just some food for thought.

Digi Remote Manager

Figure 12: Digi Remote Manager gives asset manager access to numerous features to deploy, monitor and maintain edge devices. (Source: Digi)

Getting an IoT device fielded is only half the story. Long-term maintenance and upgrades are a necessary reality to keep devices working securely. This is especially a challenge when you are trying to significantly scale the number of edge devices on your network. Enter Digi Remote Manager (DRM) toolset. Available in the browser at remotemanager.digi.com, DRM offers asset managers a wide range of useful capabilities, including:

• Simplified provisioning of new devices to the network, even in bulk
• Automated mass firmware updates
• Real-time alerts and detailed reports on network health and device conditions
• Open APIs allowing product developers to monitor and control with third-party applications built upon Amazon Web Services (AWS) or Microsoft Azure
• Recently introduced to DRM is a featured call Automations, which allows users to create customizable tasks and scripts to be run against a set of target devices, which can be scheduled to run periodically or triggered manually
• Access DRM via the browser on your PC, smartphone, or tablet

Figure 13: Automations are short scripts that can be scheduled to run on a schedule or based on changes to devices on a network. (Source: Digi)

Medium One User Portal

The question you must ask yourself once you’ve developed and built your fleet of devices and have them connected to the Cloud is how do I display? On top of providing an easy-to-use sandbox for development, Medium One provides the ability to create and deploy a full-featured frontend for your application. Medium One’s User Portal provides a full-featured dashboard with visualization and alerting that can be deployed as-is or customized to your, or your customers' needs.

The User Portal is a dedicated customer-facing portal that will allow you or your customer to customize many features such as creating multiple accounts, allowing self-registration for creating accounts, customizing the desktop for both desktop and mobile use, and support for localization with multi-language support.