MicroPython Examples for Digi XBee Part 1: Edge Computing

Rob Faludi Rob Faludi, IoT Consultant, Faludi.com
October 29, 2018

The new Digi XBee® 3 line of embedded RF modules feature edge intelligence to help execute business rules and a whole lot more. By running simple Python-based scripts on Digi XBee 3, you can save money, extend battery life, improve responsiveness and enhance system reliability.

The best way to understand the power of edge intelligence is hands-on. In this series well take you through some simple examples that you can use directly, then customize and extend to bring the power of programming to everyones favorite line of radio modules.

MicroPython is an open-source programming language based on Python 3, modified to fit on small devices and optimized for microcontrollers. Using MicroPython, an easy-to-learn scripting and programming language, you can rapidly prototype intelligent behaviors at the edges of your network. Cryptic sensor readings can be transformed into useful data, excess transmissions can be intelligently filtered out, and modern sensors and actuators can be employed directly, with complex procedures carried out locally when needed.

Getting Started with Digi XBee MicroPython Programming

XCTU v6.3.8 and later feature a new MicroPython terminal, allowing the user to interact with MicroPython on the Digi XBee 3 modules. Through the serial interface in the terminal, users can write, test, load, and run MicroPython code using the familiar REPL interactive prompt.

Its simple to get started. Well begin with the Digi XBee 3 Cellular LTE-M Kit. (Other Digi XBee 3 Cellular Kits are similar.)

MicroPython Terminal

  1. Assemble the hardware and connect it to the XCTU configuration software. Complete instructions, if needed, can be found in the Getting Started Guide.
  2. Open the XCTU program.
  3. Add a device (help).
  4. The XBee Cellular Modem appears as a box in the Radio Modules information panel. Click this box to select the device and load its current settings.
  5. Set the devices baud rate to 115200 bps for the best experience. In the BD field, select 115200 [7] and click the Write button.
  6. To put the XBee Cellular Modem into MicroPython mode, in the AP field select MicroPython REPL [4] and click the Write button.
  7. Note what COM port(s) the XBee Cellular Modem is using, because you will need this information when you use terminal communication. The Radio Modules information panel lists the COM port in use.

To use the MicroPython Terminal in XCTU:

  1. Click the Tools drop-down menu and select MicroPython Terminal.
  2. Click Open. If you have not already added devices to XCTU:
    1. In the Select the Serial/USB port area, click the COM port that the device uses.
    2. Verify that the baud rate and other settings are correct.
  3. Click OK. (The Open icon changes to Close, indicating that the device is properly connected.)
  4. Press Ctrl+B to get the MicroPython version banner and prompt.

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

Hello World Example

Lets upload some simple "Hello World" code to confirm everything is working. Using a text editor, such as Notepad in Windows or TextEdit on MacOS, type in this short script:

1
2 3 4
import sleep
2)
    1. In XCTU at the MicroPython Terminal, press Ctrl+F at the >>> prompt to put MicroPython into Flash Compile mode.
    2. Copy the script from your text editor and paste it into the MicroPython Terminal, then press Ctrl+D to finish.
    3. You wont need to run this code at startup, so answer N when youre asked.
    4. Finally press Ctrl+R to run your code. It will begin printing Hello World to the screen every two seconds. You can stop execution by pressing Ctrl-C. Heres how your entire session should look:
 
MicroPython v1.9.4-797-g4361c12 on 2018-09-20; XBC LTE-M/NB-IoT Global with EFR32MG
Type "help()" for more information. >>> flash compile mode; Ctrl-C to cancel, Ctrl-D to finish 1^^^ from time import sleep 2^^^ while True: 3^^^ print("Hello World!") 4^^^ sleep(2) 5^^^ Compiling 67 bytes of code... Used 10/371 QSTR entries. stack: 424 out of 3584 GC: total: 32000, used: 224, free: 31776 No. of 1-blocks: 6, 2-blocks: 2, max blk sz: 4, max free sz: 1933 Compiled 67 bytes of code to 108/31232 bytes of flash. Automatically run this code at startup [y/N]? N Stored code will not run at startup. Press CTRL-R in the REPL to run the code at any time. MicroPython v1.9.4-797-g4361c12 on 2018-09-20; XBC LTE-M/NB-IoT Global with EFR32MG Type "help()" for more information. >>> Running 108 bytes of stored bytecode... Hello World! Hello World! Hello World! Hello World! Hello World! Traceback (most recent call last): File "<stdin>", line 4, in <module> KeyboardInterrupt: >>>
Hello World Summary

By completing this Hello World example you now have all the skills needed to start using edge intelligence. You have set up the Digi XBee 3 hardware, connected it to the configuration software, opened MicroPython, loaded working code, and run it yourself. You are ready to run your first real application.

Sense, Transform and Send a Value

Now that we know how to create MicroPython code on the Digi XBee 3 platform, lets do something useful with it. Many IoT systems are fundamentally sensor networks. They sample some value locally, such as temperature, water pressure or human presence, then send that information for logging, processing and decision-making by online applications. For our next project, were going to take a temperature measurement using a simple sensor, then send it to your phone as an SMS text message. This measurement cycle repeats every minute, stopping after 10 rounds to protect your sanity.

Many sensors produce a simple varying voltage that needs to be transformed into the proper units. For example, at 25º Celsius a temperature sensor might output 750 mV. While its possible to send the meaningless number 750 to the cloud application, it would be much clearer to send 25ºC instead—thats the actual temperature. This is easily accomplished in MicroPython, and these transformations will be increasingly helpful as we build more intelligent systems.

First, lets attach a sensor to our Digi XBee 3 Cellular modem. To make things easy, we will use a the TMP36 temperature sensor, which is self-calibrating and communicates over a single wire.

Parts to Order
Prepare the Board to Connect Components

20-pin headerThe easiest way to connect additional components to the XBIB development board is to solder one of these headers to the 20-pin socket on the XBIB labeled P1. Now you can use jumper wires to attach peripherals like sensors or motors.

Note: If you dont have jumper wires or a header, soldering wires or sensors directly to the XBIB board will also work.

Assemble the Hardware

Use jumper wires to connect the TMP36 temperature sensor to the XBIB board.

  1. With the flat side of the TMP36 facing you, the leftmost lead gets connected to pin 1, VCC on the XBIB board.
  2. The middle lead connects to pin 20 (right next to it) DIO0.
  3. The rightmost lead goes to pin 10, GND.

TMP36 temperature layout

Configure the XBee

With the Digi XBee 3 Cellular on the XBIB board and connected to your computer over USB, launch the XCTU program.

  1. Add a radio module, then click on that device in the list to configure it.
  2. BD Baud Rate should already be set to 115200 [7]  and AP API Enable set to MicroPython REPL [4].
  3. With these two confirmed, locate the P# Destination Phone Number field and enter the mobile phone number you want to receive the temperature texts.
  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 phone number, replacing "your_mobile_number_here" before uploading the code. Enter it just as you would dial it on a cell phone, including the + symbol if needed. By default, this program sends a temperature reading once per minute, 10 times total. 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
# Digi XBee 3 Cellular Basic Example
#wait between cycles sleep(wait_time)

Once the code has been edited by adding your mobile phone number, it can be uploaded in XCTU at the MicroPython Terminal in the usual way:

  1. Press Ctrl+F at the >>> prompt to put MicroPython into Flash Compile mode.
  2. Copy the script from your text editor and paste it into the MicroPython Terminal.
  3. Press Ctrl+D to finish and answer N when youre asked.
  4. Finally press Ctrl+R to run your code. You can stop execution by pressing Ctrl-C.

Use It

With the temperature SMS example running, you should begin receiving text messages. If you left the settings at their default, you will receive ten messages, one minute apart. The results on your phone should look like this:

temp.png

Summary

By completing this SMS example you have created real, if basic, edge intelligence. Now you have experience hooking up a sensor, recording its values, transforming them into useful units and sending them to a mobile phone. In future posts, we will look at uploading data to cloud applications, triggering alerts, improving battery life, reducing bandwidth costs and much more.

>>> Learn more about the Digi XBee Ecosystem of wireless modules, or contact us to discuss your needs.
Get Our OEM Guide
Learn about the tools for launching your next project