How to Download MicroPython Code Onto XBee 3

MicroPython is a programming language inspired by Python 3.0 that works on microcontrollers, such as the XBee 3. MicroPython can help decrease the amount of supplies and overall bulkiness of your project, and make things a lot easier. However, I found that when I was using MicroPython, the process of uploading and downloading the code onto the device was confusing. So this instructable aims to explain the "simple" process of how to download code onto and off of your XBee.

If you haven't yet, look over the Digi MicroPython Programming Guide. It's useful for getting a broad knowledge of how MicroPython works on the XBees, and also for troubleshooting.

This tutorial doesn't assume you're familiar with XCTU, but if you are, you can read the headings of each section for more basic steps on how to install and uninstall MicroPython code. It does assume that you've already written your code and have it saved as a .py or .mpy file.

The XBee I use is using the 802.15.4 protocol, so any differences you encounter between the tutorial and your own version of XCTU may be due to that.

Some general rules to abide by when using MicroPython on the XBees:

- Keep the baud rate at 115200 or higher. This helps prevent loss of data.

- Make your code run through incoming packets quickly. When using MicroPython, the XBee can only hold a queue of 4 data packets--once the queue is full, it throws out new data coming in.

- Make sure your XBee is an XBee3. MicroPython doesn't work on any other model of the XBee.

• XBee3 (as many as you need)
• An XBee Explorer or similar dongle that lets you plug your XBee into your computer
• A computer with XCTU installed on it
• A .py or .mpy file containing the code you want to install on the XBee

Plug in the XBee you want to program and open XCTU. Click on Add Devices (the icon that looks like an XBee with a + on it) in the upper left corner and select the correct COM port. Make sure the Baud Rate is correct (we left the XBees set to 9600), then click Finish to connect the XBee.

XCTU takes a long time to load a lot of things. When you see the green loading bar, which you will frequently, just be patient.

Click on the XBee’s icon on the left side of the screen to display its settings on the right side. On the right side of the screen, scroll down to the section called MicroPython Commands, and make sure PS is set to Disabled [0]. If it isn’t, change the setting and hit the pencil icon next to the setting on the far right to write the change to the XBee. Do the same in the section called UART Interface for the AP parameter, and make sure it’s set to MicroPython REPL [4].

The PS parameter determines whether or not code automatically runs when the XBee is turned on, and the AP parameter is basically the "operating mode" the XBee is in. To get MicroPython to work, it has to be in it's own "MicroPython mode." If PS is set to Enabled [1], it can cause problems with some of these steps, so I find it best to turn it off until I'm done updating the code on the XBee.

Navigate to the “Tools” section in the bar at the top of the screen and select File System Manager. It opens a window that looks like the one shown above--the files on your computer are shown on the left, and an empty window is shown to the right.

Hit Configure. Select the correct COM port, make sure the Baud Rate is correct, and click OK. You should see the name of the selected COM port in the place where it previously said “Configure the port before working with the file system.”

Hit Open. If you get an error, unplugging and plugging the XBee back in again and then hitting Open usually works. You should now see the files loaded onto the XBee on the right side of the window. If your XBee is brand new, you'll probably only see two folders, but if your XBee has been used before, you may see other files in the directory (on mine, there's one called "main.py").

If your XBee does not have old code on it, you can skip this step.

If you're updating an old code file on the XBee, you have to delete the old one first. The XBee does not automatically delete old versions of code, and it has very limited storage, so you have to manually delete old code files.

MicroPython code on the XBee has to be in a file named “main.py” for the XBee to automatically run the code. You can have multiple files loaded onto the XBee, but the only one it will run on start-up is “main.py,” so you can use multiple modules as long as you import them to “main.py.” If you're using multiple modules, you only need to delete the one you're re-uploading to the XBee.

First, right click the file you want to delete, and select Delete. After a few moments, it will disappear from the File System Manager. The file is now deleted off the main storage of the XBee. However, the XBee also has a working memory, where it stores the last code it was directed to run, and this has to be erased too. Hit Close in the bottom right corner to exit the File System Manager.

In the XBee’s settings on the right side of the screen, scroll to the section that says UART Interface. Change the AP parameter to API Mode Without Escapes [1], and click the pencil icon to write it to the XBee. This allows us to send AT commands to the XBee, which we'll have to do to erase the XBee's working memory. If you're using your XBee from new, you probably don't have to do this step the first time you download code onto it, but it can't hurt confirming that the working memory is erased.

Switch to Consoles Working Mode by pressing Alt-C or by hitting the button in the top right that looks like a TV monitor, and press Open to open the line of communication to your XBee. We use this mode to talk to our XBees.

Toward the right side of the screen, under where it says Send a single packet, click the + icon, and then click Create frame using the ‘Frames Generator’ tool in the pop-up window. This opens the Frames Generator, which is shown above. We use this to generate the message we'll send to the XBee.

Where it says Frame type, click the box to open a drop-down menu and select 0x08 - AT Command. The screen will change to the format shown above.

In the red-highlighted box labeled AT command, type PY. This is the first part of the AT command, essentially telling the XBee we want to do something with MicroPython. In the box labeled Parameter value, type E. This is the specific MicroPython command we want the XBee to perform, which is erasing the working memory of the XBee (I try to remember “E for Erase”). As you type, numbers will appear in the box at the bottom of the screen.

Hit OK. Now you’re back at the window you were in before you went into the Frames Generator. The frame name doesn’t particularly matter for our purposes, so ignore it. You should see the numbers from the last window in the box of this window. If so, select Add frame.

The new “frame_0” frame appears in the box labeled Send frames. Now we can send the AT command to the XBee. Make sure the frame we just made is highlighted, and then click the button with the green arrow that says Send selected frame. Blue and red text will appear in the Frames log above.

The blue text is the command you just sent, and the red text is the XBee’s reply. Click the red text to read it. You can see a line of hexadecimal similar to what we sent to the XBee in the right-hand window. You can copy and paste this into the Frames Interpreter tool (accessed by clicking the arrow next to the tool icon above), but if the second to last pair of digits is a double zero, that means it succeeded in erasing the working memory.

Click Close in the top-left corner to exit communication with the XBee.

Click the gear icon to go back into the XBee’s settings, and scroll back down to UART Interface, and change the AP parameter back to MicroPython REPL [4]. Write the new setting to the XBee by clicking the pencil icon.

Go back into Tools > File System Manager, configure to the correct port, and click Open. On the left side of the window (your computer’s files), navigate to the code you want to upload to the XBee, and click and drag it into the right side (the XBee’s files). You should see the file appear on the right side. The new code is now downloaded onto the XBee.

Hit Close. It’s time to make sure the code is working. Navigate to Tools > MicroPython Terminal. Select Configure, choose the right COM port, and then hit Open. There should be a black, blinking cursor in the window. Hit enter, and you’ll see the MicroPython prompt: >>>

Hit Ctrl-R, and the code in the “main.py” file will run. If everything is working correctly, you’re done! If you want the code to automatically run when the XBee is turned on, close the MicroPython Terminal, and in the XBee’s settings, scroll down to MicroPython Commands, and change the PS parameter to Enabled [1], and hit the pencil icon to write it to the XBee.