MicroPython is an implementation of the Python 3 programming language, optimized to run microcontrollers. It's one of the options available for programming your Raspberry Pi Pico and a nice friendly way to get started with microcontrollers.
MicroPython can be installed easily on your Pico, by following the instructions on the Raspberry Pi website (click the Getting Started with MicroPython tab and follow the instructions).
After that point you might get a bit stuck. The Pico documentation covers connecting to the Pico from a Pi, so if you're wanting to code from your own computer you'll need something else. One option is the Thonny IDE which you use to write and upload code to your Pico. It's got a nice friendly interface for working with Python.
But if you don't want to change your IDE, or want a way to communicate with your Pico from the command line? You're in luck: there is a simple tool for accessing the MicroPython REPL on your Pico and uploading custom Python scripts or libraries you may wish to use: rshell
In this tutorial I'll take you through working with MicroPython in rshell, coding live and uploading custom scripts to your Pico.
Rshell itself is built on Python (not MicroPython) and can be installed and run locally on your main machine. You can install it like any other Python library.
python -m pip install rshell
Unfortunately, the current version of
rshell does not always play nicely with the Raspberry Pico. If you have problems you can install a fixed version in the pico branch from the rshell repository. You can install this directly from Github with the following --
python -m pip install https://github.com/dhylands/rshell/archive/pico.zip
This will download the latest version of the
pico branch (as a
.zip) and install this in your Python environment.
Once installed, you will have access to a new command line tool
The rshell interface
To use rshell from the command line, enter
rshell at your command prompt. You will see a welcome message and the prompt will turn green, to indicate you're in rshell mode.
The rshell interface on Windows 10
The rshell interface on macOS
pip install worked but the
rshell command doesn't work, then you may have a problem with your Python paths.
To see the commands available in rshell, enter
help and press Enter.
help Documented commands (type help <topic>): ======================================== args cat connect date edit filesize help mkdir rm shell boards cd cp echo exit filetype ls repl rsync Use the exit command to exit rshell.
You can exit
rshell at any time by entering
exit or pressing
Ctrl-C. Once exited the prompt will turn white.
The basic file operation commands are shown below.
cd <dirname>change directory
cp <from> <to>copy a file
lslist current directory
rm <filename>remove (delete) a file
filesize <filename>give the size of a file in bytes
If you type
ls and press enter you will see a listing of your current folder on your host computer. The same goes
for any of the other file operations, until we've connect a board and opened it's file storage -- so be careful!
We'll look at how to connect to a MicroPython board and work with the files on it next.
Connecting to your Pico with rshell
boards to see a list of MicroPython boards connected to your computer. If you don't
have any connected boards, you'll see the message
No boards connected.
If your board isn't connected plug your Pico in now. You can use the
connect command to connect to the board,
but for that you'll need to know which port it is on. Save yourself some effort and just restart rshell to connect
automatically. To do this, type
exit and press Enter (or press
Ctrl-C) to exit and then restart rshell by entering
rshell again at the prompt.
If a board is connected when you start rshell you will see something like the following...
C:\Users\Gebruiker>rshell Connecting to COM4 (buffer-size 128)... Trying to connect to REPL connected
Or an equivalent on macOS...
Martins-Mac: ~ mfitzp$ rshell Connecting to /dev/cu.usbmodem0000000000001 (buffer-size 128) Trying to connect to REPL connected
...which shows you've connected to the MicroPython REPL on the Raspberry Pi Pico. Once connected the
will return some information about the connected board, like the following.
pyboard @ COM4 connected Epoch: 1970 Dirs:
The name on the left is the type of board (Pico appears as
pyboard) and connected port (here COM4). The label at the end
Dirs: will list any files
on the Pico -- currently none.
Starting a REPL
With the board connected, you can enter the Pico's REPL by entering the
repl command. This will return something like the following
repl Entering REPL. Use Control-X to exit. > MicroPython v1.14 on 2021-02-14; Raspberry Pi Pico with RP2040 Type "help()" for more information. >>> >>>
You are now writing Python on the Pico! Try entering
print("Hello!") at the REPL prompt.
MicroPython v1.14 on 2021-02-14; Raspberry Pi Pico with RP2040 Type "help()" for more information. >>> >>> print("Hello!") Hello!
As you can see, MicroPython works just like normal Python. If you enter
help() and press Enter,
you'll get some basic help information about MicroPython on the Pico. Helpfully, you also get a
small reference to how the pins on the Pico are numbered and the different ways you have to control them.
Type "help()" for more information. >>> help() Welcome to MicroPython! For online help please visit https://micropython.org/help/. For access to the hardware use the 'machine' module. RP2 specific commands are in the 'rp2' module. Quick overview of some objects: machine.Pin(pin) -- get a pin, eg machine.Pin(0) machine.Pin(pin, m, [p]) -- get a pin and configure it for IO mode m, pull mode p methods: init(..), value([v]), high(), low(), irq(handler) machine.ADC(pin) -- make an analog object from a pin methods: read_u16() machine.PWM(pin) -- make a PWM object from a pin methods: deinit(), freq([f]), duty_u16([d]), duty_ns([d]) machine.I2C(id) -- create an I2C object (id=0,1) methods: readfrom(addr, buf, stop=True), writeto(addr, buf, stop=True) readfrom_mem(addr, memaddr, arg), writeto_mem(addr, memaddr, arg) machine.SPI(id, baudrate=1000000) -- create an SPI object (id=0,1) methods: read(nbytes, write=0x00), write(buf), write_readinto(wr_buf, rd_buf) machine.Timer(freq, callback) -- create a software timer object eg: machine.Timer(freq=1, callback=lambda t:print(t)) Pins are numbered 0-29, and 26-29 have ADC capabilities Pin IO modes are: Pin.IN, Pin.OUT, Pin.ALT Pin pull modes are: Pin.PULL_UP, Pin.PULL_DOWN Useful control commands: 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) For a list of available modules, type help('modules')
You can run
help() in the REPL any time you need a reminder.
While we're here, lets flash the LED on the Pico board.
Enter the following at the REPL prompt...
from machine import Pin led = Pin(25, Pin.OUT) led.toggle()
Every time you call
led.toggle() the LED will toggle from ON to OFF or OFF to ON.
To exit the REPL at any time press
Uploading a file
MicroPython comes with a lot of built-in support for simple devices and communication protocols -- enough to build some quite fun things just by hacking in the REPL. But there are also a lot of libraries available for working with more complex hardware. To use these, you need to be able to upload them to your Pico! Once you can upload files, you can also edit your own code locally on your own computer and upload it from there.
To keep things simple, lets create our own "library" that adjusts the brightness of the LED on the Pico board -- exciting I know. This library contains a single function
ledon which accepts a single parameter
brightness between 0 and 65535.
from machine import Pin, PWM led = PWM(Pin(25)) def ledon(brightness=65535): led.duty_u16(brightness)
Don't worry if you don't understand it, we'll cover how this works later. The important bit now is getting this on your Pico.
Take the code above and save it in a file named
picoled.py on your main computer, in the same folder you're executing rshell from. We'll upload this file to the Pico next.
Start rshell if you are not already in it -- look for the green prompt. Enter
boards at the prompt to get a list of connected boards.
pyboard @ COM4 connected Epoch: 1970 Dirs:
To see the directory contents of the
pyboard device, you can enter:
You should see nothing listed. The path
/pyboard works like a virtual folder meaning you can copy files to this
location to have the uploaded to your Pico. It is only available by a pyboard is connected. To upload a file, we
copy it to this location. Enter the following at the prompt.
cp picoled.py /pyboard/picoled.py
After you press Enter you'll see a message confirming the copy is taking place
C:\Users\Gebruiker> cp picoled.py /pyboard Copying 'C:\Users\Gebruiker/picoled.py' to '/pyboard/picoled.py' ...
Once the copy is complete, run
boards again at the prompt and you'll see the file listed after the
Dirs: section, showing that it's on the board.
C:\Users\Gebruiker> boards pyboard @ COM4 connected Epoch: 1970 Dirs: /picoled.py /pyboard/picoled.py
You can also enter
ls /pyboard to see the listing directly.
C:\Users\Gebruiker> ls /pyboard picoled.py
If you ever need to upload multiple files, just repeat the upload steps until everything is where it needs to be. You can always drop in and out of the REPL to make sure things work.
Using uploaded libraries
Now we've uploaded our library, we can use it from the REPL. To get to the MicroPython REPL enter the
repl command in
rshell as before.
To use the library we uploaded, we can import it, just like any other Python library.
MicroPython v1.14 on 2021-02-14; Raspberry Pi Pico with RP2040 Type "help()" for more information. >>> >>> import picoled >>> picoled.ledon(65535) >>> picoled.ledon(30000) >>> picoled.ledon(20000) >>> picoled.ledon(10000)
Or to pulse the brightness of the LED...
>>> import picoled >>> import time >>> while True: ... for a in range(0, 65536, 10000): ... picoled.ledon(a) ... time.sleep(0.1)
So far we've been uploading code and running it manually, but once you start building projects you'll want your code to run automatically.
When it starts, MicroPython runs two scripts by default:
main.py, in that order. By uploading your own
script with the name
main.py it will run automatically every time the Raspberry Pico starts.
Let's update our "library" to become an auto script that runs at startup. Save the following code to a script named
from machine import Pin, PWM from time import sleep led = PWM(Pin(25)) def ledon(brightness=65535): led.duty_u16(brightness) while True: for a in range(0, 65536, 10000): ledon(a) sleep(0.1)
In rshell run the command to copy the file to
main.py on the board.
cp main.py /pyboard/main.py
Don't copy this file to
boot.py -- the loop will block the REPL startup and you won't be able to connect to your Pico to delete it again!
If you do this, use the Resetting Flash memory instructions to clear your Pico. You will need to re-install MicroPython afterwards.
main.py file is uploaded, restart your Pico -- either unplug and re-plug it, or press
Ctrl-D in the REPL -- and the LED will start pulsing automatically.
The script will continue running until it finishes, or the Pico is reset. You can replace the
main.py script at any time to
change the behavior, or delete it with.
Now you can upload libraries to your Pico you can get experimenting with the many MicroPython libraries that are available.
If you're looking for some more things to do with MicroPython on your Pico, there are some MicroPython examples available from Raspberry Pi themselves, and also the MicroPython documentation for language/API references.