Hands-on MicroPython Programming Examples for Edge Computing: Part 2

In our first post in the MicroPython programming for the edge series, we talked about how to collect sensor readings and make sense of them using the Digi XBee3 Cellular LTE-M Kit, as well as Digi’s free configuration software, XCTU, and some simple MicroPython code. Welcome to Part 2 of this series.

The edge intelligence provided in Digi’s XBee3 line of embedded RF modules makes sending data to the cloud a snap. For our second project in this hands-on series, we show how to upload temperature readings measured from a Digi XBee3 Cellular LTE-M module to “data streams” on Digi Remote Manager (DRM). Developers can use this data and device management platform for free. The Digi XBee3 Cellular line supports open communications standards, so it can also share data with Amazon’s IoT Platform, Microsoft Azure, Adafruit.io, Google Cloud IoT, ThingSpeak, IBM Watson and many others. Look for hands-on tutorials or several of those in future projects. Readers of our first project will recall that MicroPython is an open-source programming language based on Python 3, modified to fit on small devices and optimized for microcontrollers. By using MicroPython you can rapidly create connections to cloud services right from the edges of your network.

Send Data to Digi Remote Manager

Many IoT systems feed data to online cloud platforms on the Internet. They typically sample some value locally, like temperature, then send the readings to any one of a dizzying number of online application for logging, processing and data visualization. In this project, we will take some temperature measurements using a simple sensor, then send them to Digi Remote Manager® as a “data stream” that can be visualized in different ways, accessed via an open API or stored for later use.

We begin with the exact same hardware setup used in the “Sense, Transform and Send a Value” project, including the TMP36 temperature sensor.

Set up the Hardware

If you missed our first post, please visit Hands-on MicroPython Programming Examples for Edge Computing: Part 1 and work through the following items to prepare for this second project:

1. Getting Started: Demonstrates how to set up the hardware and software you’ll need.
2. Hello World Example: Teaches how to upload code to Digi XBee3.
3. Sense, Transform and Send a Value: Shows how to take a temperature reading and send it as a text message.

Once you have set up the Digi XBee3 hardware, hooked up the TMP36 temperature sensor, connected it to the configuration software, and opened the MicroPython terminal in XCTU, you are ready to begin. Your setup should look similar to this one:

If you need help setting up or using your account, see the Remote Manager User Guide.

Your Remote Manager account username and password will let your Digi XBee3 Cellular upload data streams, in this case temperature measurements. It provides a layer of security that’s appropriate to this simple example. Many additional layers of security and authentication are available to provide increased protection for production applications, though we won’t look at those right now so we can focus on the basics.

Library Uploads

To make our code simpler and more readable, we rely on two libraries uploaded to the file system inside the Digi XBee3 Cellular module. These libraries are collections of pre-written code. They provide simple ways to call complex routines without the routines themselves cluttering up your program. For this example we will use the remotemanager library, and the urequests library that remotemanager requires.

1. Locate the remotemanager.py and urequests.py libraries on this GitHub page: https://github.com/digidotcom/xbee-micropython/tree/master/lib.
2. Right-click on each filename and select Download to create a local copy of each on your computer. (GitHub users could also Clone or Download the entire repository here: https://github.com/digidotcom/xbee-micropython).
3. With your Digi XBee3 and XBIB board added to XCTU, open the Tools menu and select File System Manager.
4. Click Open to connect the File System Manager to your Digi XBee3’s file system.
5. Navigate the “Local Path” folders in the left-hand column to find the remotemanager.py and urequests.py files you just downloaded.
6. Use the “Remote Path” folders in the right-hand column to open the “lib” directory (“/flash/lib”).
7. Drag the remotemanager.py and urequests.py files from your local directory and drop them in the remote “lib” directory to store them on the XBee3.
8. When you are done, close the File System Manager window.

Configure the XBee

The module is configured identically to our first Sense, Transform and Send a Value project. If anything might have changed, mount the Digi XBee3 Cellular on the XBIB board and connected to your computer over USB, launch the XCTU program.

• Add a radio module, then click on that device in the list to configure it.
• BD Baud Rate should be set to 115200 [7]  and AP API Enable set to MicroPython REPL [4].
• Write these settings to the module, using the pencil icon at the top.

Load the Code

Copy the below code to a text editor like Notepad. Be sure to enter your own username and password, replacing “your_username_here” and “your_password_here” before uploading the code. By default, this program sends a temperature reading to Digi Remote Manager data stream once per minute, over 24 hours (1440 samples).  You can customize that by changing the wait_time or cycles variables as desired.

Remember, this sample code must be edited before you upload it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

# Digi XBee3 Cellular DRM Example
# uses a TMP36 to measure temperature and post it to Digi Remote Manager
# by default repeating once per minute, 1440 times total, stopping after a day
# ENTER YOUR DRM username and password, REPLACING "your_username_here" etc. BEFORE UPLOADING THIS CODE!
from remotemanager import RemoteManagerConnection
from machine import ADC
from time import sleep
from xbee import atcmd
cycles = 1440 # number of repeats
wait_time = 60 # seconds between measurements
username = 'your_username_here' #enter your username!
password = 'your_password_here' #enter your password!
# Device Cloud connection info
stream_id = 'temperature'
stream_type = 'FLOAT'
stream_units = 'degrees F'
description = "temperature example"
# prepare for connection
credentials = {'username': username, 'password': password}
stream_info = {"description": description,
                   "id": stream_id,
                   "type": stream_type,
                   "units": stream_units}
ai_desc = {
    0x00: 'CONNECTED',
    0x22: 'REGISTERING_TO_NETWORK',
    0x23: 'CONNECTING_TO_INTERNET',
    0x24: 'RECOVERY_NEEDED',
    0x25: 'NETWORK_REG_FAILURE',
    0x2A: 'AIRPLANE_MODE',
    0x2B: 'USB_DIRECT',
    0x2C: 'PSM_DORMANT',
    0x2F: 'BYPASS_MODE_ACTIVE',
    0xFF: 'MODEM_INITIALIZING',
}
def watch_ai():
    old_ai = -1
    while old_ai != 0x00:
        new_ai = atcmd('AI')
        if new_ai != old_ai:
            print("ATAI=0x%02X (%s)" % (new_ai, ai_desc.get(new_ai, 'UNKNOWN')))
            old_ai = new_ai
        else:
            sleep(0.01)
# Main Program
# create a connection
rm = RemoteManagerConnection(credentials=credentials)
# update data feed info
print("updating stream info...", end ="")
try:
    rm.update_datastream(stream_id, stream_info)
    print("done")
except Exception as e:
    status = type(e).__name__ + ': ' + str(e)
    print('\r\nexception:', e)
    
while True:
    print("checking connection...")
    watch_ai()
    print("connected")
    for x in range(cycles):
        # read temperature value & print to debug
        temp_pin = ADC("D0")
        temp_raw = temp_pin.read()
        print("raw pin reading: %d" % temp_raw)
    
        # convert temperature to proper units
        temperatureC = (int((temp_raw * (2500/4096)) - 500) / 10)
        print("temperature: %d Celsius" % temperatureC)
        temperatureF = (int(temperatureC * 9.0 / 5.0) + 32.0);
        print("temperature: %d Fahrenheit" % temperatureF)
    
        # send data points to DRM
        print("posting data...", end ="")
        try:
            status = rm.add_datapoint(stream_id, temperatureF) # post data to Device Cloud
            print("done")
            print('posted to stream:', stream_id, '| data:', round(temperatureF), '| status:', status.status_code)
        except Exception as e:
            print('\r\nexception:', e)
        # wait between cycles
        sleep(wait_time)

Use It

With the Data to Digi Remote Manager example running, a new temperature measurement will be uploaded to a DRM data stream each minute. If you left the settings at their default, you will receive 1440 uploads, one minute apart, or 24 hours worth. To monitor the data stream:

1. Log in to Digi Remote Manager and select the Data Services tab.

    

   

2. Click on the Stream named “temperature” to select it.
3. Locate the Charts and Raw Data area below. It may be helpful to drag the separator line upwards to enlarge this area.
4. Click on Raw Data to see the data points that have been uploaded

    

   

5. Click on Charts to see line graphs of the temperature data. Daily, weekly, monthly and yearly summary graphs can be generated.

    

   

Related white paper: 5 Reasons You Should Consider Embedded Cellular Connectivity.

Digi Remote Manager has a complete API for sharing your data with other online systems. Thanks to its RESTful interface, it can accept standard requests (using HTTP GET) from a web browser. Use this link to see your temperature data. You’ll be prompted to enter your username and password:

https://remotemanager.digi.com/ws/DataPoint/temperature

The output will be in XML format, and will look like this:

Summary

This Digi Remote Manager example demonstrates one way to centralize your IoT system’s data uploads. You can now create multiple sensors that all transfer data to a central location online. You created your first DRM account, located your data and visualized it. We also covered uploading libraries to Digi XBee3 Cellular using the File System Manager in XCTU. The File System Manager can also manage key files and security certificates that are required by many online IoT platforms. In future posts, we will look at uploading data to other cloud applications, triggering alerts, improving battery life, reducing bandwidth costs and much more.

Your feedback about this series is welcome. Please post any questions or suggestions in the comments below.

>>> Learn more about the Digi XBee Ecosystem of wireless modules, or contact us to discuss your needs.