Xbee UART Quick Start Guide

In this tutorial, you will learn how to set up the Xbee3 using XCTU, program the Xbee3 with the micropython code and transmit data to the Medium One cloud via the UART/Serial port of the Xbee3.

What you need before you begin:

  • Medium One IoT Platform account
  • Xbee micropython files (request from Medium One), these files are connected to your Medium One IoT Platform account
  • Xbee3 development board with a cellular internet connection
  • A serial terminal on a PC/Mac
  • Basic understanding of the Xbee3 and Digi XCTU software
  • Basic understanding of Medium One IoT Platform 

Notes:

  • This tutorial uses a Mac OS but any terminal software would work
  • This tutorial uses the Digi XCTU Version: 6.5.0
  • This tutorial use the Digi XBee® 3 Cellular Smart Modem, LTE-M/NB-IoT, Development Kit, AT&T kit (part number: XK3-C-A2-UT-U).  Theoretically, other cellular Xbee3 boards such as Cat-1 should work.

Step 1: Setting Up the Xbee3 board on XCTU

Important: This tutorial assumes you're starting with the default settings of the Xbee3. 

Connect your Xbee to XCTU and make sure you have a cellular connection, in our example we use the Hologram sim and data plan.  Check that you have values for IMEI, Cellular Strength and Operator.  This may take a few minutes to populate after the board powers up.

 

Screen_Shot_2020-04-19_at_10.32.40_AM.png

Confirm your Association Indication is 0.  This means you're connected to a network.  If this is not 0 then do not proceed because your board does not have a cellular connection.

Screen_Shot_2020-04-19_at_10.40.00_AM.png 

Make sure you have the latest firmware on the Xbee3, we currently have version 11415.

Set Network Technology to LTE-M Only if you're using Cat-M.  At the time of writing this tutorial, LTE-M/NB-IOT doesn't work.

Screen_Shot_2020-04-19_at_10.35.28_AM.png

Set API Enable to MicroPython

Screen_Shot_2020-04-19_at_10.36.58_AM.png

Enable the main.py micropython code to auto-start when the board powers up.

Screen_Shot_2020-04-19_at_11.01.02_AM.png

 

If you've made any changes, don't forget to write your changes to the Xbee3 by pressing the following button:

Screen_Shot_2020-04-19_at_10.43.15_AM.png

 

Step 2: Program the Xbee3 via XCTU

Next, we will upload the micropython files to the Xbee3.  Open, the File System Manager

 

 Screen_Shot_2020-04-19_at_10.46.34_AM.png

Click Open to connect to your board's filesystem.

Screen_Shot_2020-04-19_at_10.47.39_AM.png

Navigate to the python files on the left pane.  To be safe, we recommend you format the Xbee3 filesystem. 

Drag the main.py and registration.json file to the right (/flash) folder of the Xbee3.  Note, the registration.json file is specific to your Medium One Account.  

TIP: When your board first connects, it will register itself using the unique IMEI number.  This will create a devicecreds.json file in /flash.  This credentials file is specific to your device, while the registration.json file is specific to your project.  In production, you would want to encrypt the filesystem, contact Medium One for more information. 

If you see a devicecreds.json file on the Xbee3, that means this board had already registered in the past and you can ignore that file.  If you delete that file, it will re-register at runtime.

 

Screen_Shot_2020-04-19_at_10.50.08_AM.png

 

Finally, copy the m1mqtt.py file to the lib folder in the Xbee3, the location of this file is important.

Screen_Shot_2020-04-19_at_10.58.52_AM.png

 

Once you finish uploading the files, close XCTU and reset the board by pressing the reset button on the dev board.  You'll need to close XCTU in order for the Serial terminal to connect to the board.

 

Step 3: Connecting to UART over Serial Cable

We will connect to the board using a Serial Terminal over the USB cable.   This will simulate an external host MCU communicating to the Xbee over UART.  We use the screen software on Mac OS  in this example - you can use any terminal software.

On Mac, find the USB port, you can ls the /dev folder and look for files beginning with tty.usbserial*.  You may need to try more than one if you have multiple.  Ours is tty.usbserial-00001014 as an example.

Mac>screen /dev/tty.usbserial-00001014 9600

Once you connect, reset the board. If it prints out the following message or similar, then you know it's connected to the Xbee3

Parsing /flash/main.py...
Compiling /flash/main.py...
Running bytecode...

Wait for the board to connect, this could take up to a couple of minutes.  This process includes:

  • Connecting to the cellular network.  Make sure the antenna is connected.
  • Registering board to Medium One (if not registered)
  • Authenticating board (after registration)
  • Sending connect message to Medium One

If you are successful, you'll see an output that looks similar to this:

Parsing /flash/main.py...
Compiling /flash/main.py...
RunnSuccessfully loaded registration file: registration.json
Waiting for cellular network.. 1
Waiting for cellular network.. 2
Waiting for cellular network.. 3
Waiting for cellular network.. 4
Waiting for cellular network.. 5
Waiting for cellular network.. 6
Waiting for cellular network.. 7
Connected to network
IMEI: 352753090500545
Mqtt Connect Attempt
Mqtt Connect FAILED
Logging in as Registration User
Mqtt Connect Attempt
MQTT Connected
Sending Event @ (2020, 4, 19, 11, 34, 12, 6, 110)
{"event_data": {"connected": true}}

 The last line means the following event was transmitted to Medium One.  After you see this, the Xbee3 is ready to receive the payload to transmit (next step).

{"event_data": {"connected": true}}

Do not disconnect from the screen session and proceed to the next step.

Step 4: Transmit Your First Event over UART

In this step you will send a JSON payload over UART to be sent to the cloud. 

Some notes:

  • The JSON payload must be valid JSON format, main.py will not send invalid json
  • Delimiter must be at the end of the payload, the delimiter can be either (0x0A - hex) or (0x0D hex).  This is to support the enter and return key for Windows and Mac.  Note, you can change the delimiter in the main.py
  • The JSON string will be echoed back after the delimiter is received. We recommend you paste the entire string at once because each character will not be echoed back as you type.
  • main.py will automatically wrap the payload around {"event_data":<your payload>} which is needed for Medium One - do not wrap your payload around {"event_data":<your payload>}
  • Your payload can be any valid JSON; although there's no size limit, be reasonable.

Now we're going to send the following event:

{"ADC0":5}

Paste that event into the terminal and press return (to send the delimiter).  The output will be similar to the following (the actual response may vary slightly depending on your main.py version).

{"ADC0":5}
Sending Event @ (2020, 4, 19, 11, 53, 59, 6, 110)
{"event_data": {"ADC0": 5}}

If you see this, it means the event was transmitted to the cloud.

Note: If the payload is not valid JSON, the XBee3 will respond 0.  For example:

{"ADC0":badJSONNoQuotes}0

TIP: To disconnect from screen press control a + control | on Mac OS.

 

What's Next: 

  • Connect this board to your MCU.  Refer to the Xbee3 schematic on how to connect to the Primary UART pins.  Note, you may need level shifters.
  • Visit docs.mediumone.com to learn how to:
    • Build workflows to process your events in real-time
    • Build a custom dashboard for your customers in the User Portal
    • Push data to the Xbee in real-time from user dashboard or workflow
    • and much more!