How To: Use Upip to Load MicroPython Libraries onto a Microcontroller Over Wi-Fi

MicroPython is an exciting language to use on ESP8266 boards and ESP32-based microcontrollers, but it doesn't always include all of the libraries you'll need for a specific project. This issue is less of a problem, thanks to the upip package manager.

Upip lets you download any package in the standard MicroPython library over a Wi-Fi connection. That's really useful if you're in a project that needs another library and you don't want to go through the tedious process of trying to load it yourself.

To follow along, you'll need to have an ESP8266, ESP8285, or ESP32 board, such as the NodeMCU or D1 Mini. Designed for wearables, the ESP8285 is a smaller version of the ESP8266 with less flash memory. The ESP32 is the successor to the other models and has faster Wi-Fi, an extra CPU core, touch-sensitive pins, more GPIOs, and more.

• Buy on Amazon: D1 Mini ESP8266 Board for $8.99
• Buy on Amazon: D1 Mini ESP8285 Board for $10.99
• Buy on Amazon: D1 Mini ESP32 Acrobotic WeMos Board for $12.49
• Buy on Amazon: NodeMCU ESP8266 Board (3 Pack) for $13.95
• Buy on Amazon: NodeMCU ESP8285 Board for $11.06
• Buy on Amazon: MELIFE ESP32 Board (2 Pack) for $14.99
• Buy on Amazon: HiLetgo ESP-WROOM-32 Board for $10.99

Once you have a board, you'll have to connect it to a computer, so you'll need a Micro-USB cable if you don't already have one. You'll want to make sure it's one that is both for charging and data transfer. It can be hard to tell, but a lot of your older cords may be charging-only, and you'll know if you can't connect your board to your computer.

• Buy on Amazon: Nylon Braided Micro-USB Data Cable for $3.96

Step 1: Access MicroPython on Your Board

We'll assume that you already have MicroPython installed on your board, so we won't go over that process again since we covered it in depth in our guide on getting started with MicroPython on microcontrollers. That article has lots of good information in it, such as erasing your board, installing MicroPython, and accessing the board afterward. Check it out if you don't know how to find your board's serial port to connect to it.

• More Info: Get Started with MicroPython for ESP8266 Microcontrollers

Step 2: Connect to Your Board

If you just set up your board via Step 1, you're already connected to your computer. If not, make sure to connect your microcontroller to your computer via the Micro-USB cable. Then, use screen to connect to it.

~$ screen /dev/ttyUSB3 115200

MicroPython v1.13.bin-g48dcbbe60 on 2020-09-11; ESP module with ESP8266
Type "help()" for more information.
>>>

As instructed, let's run help() to see what's going on here.

>>> help()
Welcome to MicroPython!

For online docs please visit http://docs.micropython.org/en/latest/esp8266/ .
For diagnostic information to include in bug reports execute 'import port_diag'.

Basic WiFi configuration:

import network
sta_if = network.WLAN(network.STA_IF); sta_if.active(True)
sta_if.scan()                             # Scan for available access points
sta_if.connect("<AP_name>", "<password>") # Connect to an AP
sta_if.isconnected()                      # Check for successful connection
# Change name/password of ESP8266's AP:
ap_if = network.WLAN(network.AP_IF)
ap_if.config(essid="<AP_NAME>", authmode=network.AUTH_WPA_WPA2_PSK, password="<password>")

Control commands:
  CTRL-A        -- on a blank line, enter raw REPL mode
  CTRL-B        -- on a blank line, enter normal REPL mode
  CTRL-C        -- interrupt a running program
  CTRL-D        -- on a blank line, do a soft reset of the board
  CTRL-E        -- on a blank line, enter paste mode

For further help on a specific object, type help(obj)
>>>

Step 3: Set Up the Network

Now, let's set up the network interface. Per the network setup instructions on the MicroPython site, we'll use the network module. And there are two Wi-Fi interfaces to create. First, one for the station, i.e., when your microcontroller connects to your router. Second, the access point on your microcontroller so that other devices can connect to it. We're only worried about the first one since we just want to get libraries onto the board.

• Don't Miss: Program a Microcontroller Over Wi-Fi with MicroPython

>>> import network
>>> sta_if = network.WLAN(network.STA_IF)

Now, you can check to see if they are active:

>>> sta_if.active()
True

If you see "False" for your Wi-Fi router, set it to true manually with:

>>> sta_if.active(True)
#5 ets_task(4020f4d8, 28, 3fff9df0, 10)

If you're not sure what your Wi-Fi network is, you can scan to remind yourself.

>>> sta_if.scan()
[(b'SO YOUNG BEAUTY', b'\x0c\xea\xc9w\x83\x00', 1, -63, 3, 0), (b'WIFIEA18FD', b'\xa8\xa7\x95\xea\x19\x01', 1, -79, 3, 0), (b'CableWiFi', b'\xc4\x01|\x13\x1c\xc8', 4, -76, 0, 0), (b'SpectrumWiFi Plus', b'\xc4\x01|S\x1c\xc8', 4, -76, 5, 0), (b'SpectrumWiFi', b'\xc4\x01|\x93\x1c\xc8', 4, -75, 0, 0), (b'piccadilly', b'\x90\x1a\xcal\xd7\x00', 6, -70, 3, 0), (b'spot 2.4 ghz', b'@p\tzd\x90', 11, -52, 3, 0)]

With the network known, we can now connect the board to it with:

>>> sta_if.connect('<your ESSID>', '<your password>')

In my case, that's:

>>> sta_if.connect("spot 2.4 ghz", "CafeSpot000")

Now, you can check to see if you're connected with:

>>> sta_if.isconnected()
True

Step 4: Install a MicroPython Library

Now we're ready to start using upip. We're going to download a MicroPython library from the /micropython/micropython-lib GitHub page. For our example, we're going with pystone_lowmen to perform a benchmarking test.

>>> import upip

Now we're ready to start downloading a package over the internet. If you want to see the usage, use upip.help() to get more info.

>>> upip.help()
upip - Simple PyPI package manager for MicroPython
Usage: micropython -m upip install [-p <path>] <package>... | -r <requirements.txt>
import upip; upip.install(package_or_list, [<path>])

If <path> is not given, packages will be installed into sys.path[1]
(can be set from MICROPYPATH environment variable, if current system
supports that).
Current value of sys.path[1]: /lib

Note: only MicroPython packages (usually, named micropython-*) are supported
for installation, upip does not support arbitrary code in setup.py.

To install a package in upip, you'd use the following format.

>>> upip.install("micropython-pystone_lowmem")
Installing to: /lib/
Warning: micropython.org SSL certificate is not validated
Installing micropython-pystone_lowmem 3.4.2.post4 from https://micropython.org/pi/pystone_lowmem/pystone_lowmem-3.4.2.post4.tar.gz

To use the new package, you can import it like you would any standard library using import. Then, you can run the module as a function as formatted below.

>>> import pystone_lowmem
>>> pystone_lowmem.main()
Pystone(1.2) time for 500 passes = 1137ms
This machine benchmarks at 439 pystones/second

If you want to see all of the libraries that are installed, you can import uos and use that to list all of the libraries in the current directory.

>>> import uos
>>> uos.listdir()
['boot.py', 'lib']

This is basically how you would get up and running with libraries that aren't already installed on your MicroPython system. To see all of the packages you can use, make sure to check out /micropython/micropython-lib on GitHub.