1# The RP2 port
2
3This is a port of MicroPython to the Raspberry Pi RP2 series of microcontrollers.
4Currently supported features are:
5
6- REPL over USB VCP, and optionally over UART (on GP0/GP1).
7- Filesystem on the internal flash, using littlefs2.
8- Support for native code generation and inline assembler.
9- `utime` module with sleep, time and ticks functions.
10- `uos` module with VFS support.
11- `machine` module with the following classes: `Pin`, `ADC`, `PWM`, `I2C`, `SPI`,
12  `SoftI2C`, `SoftSPI`, `Timer`, `UART`, `WDT`.
13- `rp2` module with programmable IO (PIO) support.
14
15See the `examples/rp2/` directory for some example code.
16
17## Building
18
19The MicroPython cross-compiler must be built first, which will be used to
20pre-compile (freeze) built-in Python code.  This cross-compiler is built and
21run on the host machine using:
22
23    $ make -C mpy-cross
24
25This command should be executed from the root directory of this repository.
26All other commands below should be executed from the ports/rp2/ directory.
27
28Building of the RP2 firmware is done entirely using CMake, although a simple
29Makefile is also provided as a convenience.  To build the firmware run (from
30this directory):
31
32    $ make submodules
33    $ make clean
34    $ make
35
36You can also build the standard CMake way.  The final firmware is found in
37the top-level of the CMake build directory (`build` by default) and is
38called `firmware.uf2`.
39
40## Deploying firmware to the device
41
42Firmware can be deployed to the device by putting it into bootloader mode
43(hold down BOOTSEL while powering on or resetting) and then copying
44`firmware.uf2` to the USB mass storage device that appears.
45
46If MicroPython is already installed then the bootloader can be entered by
47executing `import machine; machine.bootloader()` at the REPL.
48
49## Sample code
50
51The following samples can be easily run on the board by entering paste mode
52with Ctrl-E at the REPL, then cut-and-pasting the sample code to the REPL, then
53executing the code with Ctrl-D.
54
55### Blinky
56
57This blinks the on-board LED on the Pico board at 1.25Hz, using a Timer object
58with a callback.
59
60```python
61from machine import Pin, Timer
62led = Pin(25, Pin.OUT)
63tim = Timer()
64def tick(timer):
65    global led
66    led.toggle()
67
68tim.init(freq=2.5, mode=Timer.PERIODIC, callback=tick)
69```
70
71### PIO blinky
72
73This blinks the on-board LED on the Pico board at 1Hz, using a PIO peripheral and
74PIO assembler to directly toggle the LED at the required rate.
75
76```python
77from machine import Pin
78import rp2
79
80@rp2.asm_pio(set_init=rp2.PIO.OUT_LOW)
81def blink_1hz():
82    # Turn on the LED and delay, taking 1000 cycles.
83    set(pins, 1)
84    set(x, 31)                  [6]
85    label("delay_high")
86    nop()                       [29]
87    jmp(x_dec, "delay_high")
88
89    # Turn off the LED and delay, taking 1000 cycles.
90    set(pins, 0)
91    set(x, 31)                  [6]
92    label("delay_low")
93    nop()                       [29]
94    jmp(x_dec, "delay_low")
95
96# Create StateMachine(0) with the blink_1hz program, outputting on Pin(25).
97sm = rp2.StateMachine(0, blink_1hz, freq=2000, set_base=Pin(25))
98sm.active(1)
99```
100
101See the `examples/rp2/` directory for further example code.
102