Manual / Guide · 2024

Raspberry Pi Pico-series Python SDK — Documentation

Author: Raspberry Pi Ltd
Year: 2024
Type: Manual / Guide

raspberry pi pico
micropython
sdk
python
microcontroller

Raspberry Pi Pico-series Python SDK 4731426-clean 2024-12-04: A MicroPython environment for Raspberry Pi microcontrollers. Raspberry Pi Pico-series Python SDK Colophon © 2020-2024 Raspberry Pi Ltd (formerly Raspberry Pi (Trading) Ltd.) This documentation is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND). Throughout the text "the SDK" refers to our Raspberry Pi Pico SDK. More details about the SDK can be found in Raspberry Pi Pico-series C/C++ SDK. Source code included in the documentation is Copyright © 2020-2024 Raspberry Pi Ltd (formerly Raspberry Pi (Trading) Ltd.) and licensed under the 3-Clause BSD license. build-date: 2024-12-04 build-version: 4731426-clean Legal disclaimer notice TECHNICAL AND RELIABILITY DATA FOR RASPBERRY PI PRODUCTS (INCLUDING DATASHEETS) AS MODIFIED FROM TIME TO TIME ("RESOURCES") ARE PROVIDED BY RASPBERRY PI LTD ("RPL") "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN NO EVENT SHALL RPL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THE RESOURCES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. RPL reserves the right to make any enhancements, improvements, corrections or any other modifications to the RESOURCES or any products described in them at any time and without further notice. The RESOURCES are intended for skilled users with suitable levels of design knowledge. Users are solely responsible for their selection and use of the RESOURCES and any application of the products described in them. User agrees to indemnify and hold RPL harmless against all liabilities, costs, damages or other losses arising out of their use of the RESOURCES. RPL grants users permission to use the RESOURCES solely in conjunction with the Raspberry Pi products. All other use of the RESOURCES is prohibited. No licence is granted to any other RPL or other third party intellectual property right. HIGH RISK ACTIVITIES. Raspberry Pi products are not designed, manufactured or intended for use in hazardous environments requiring fail safe performance, such as in the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, weapons systems or safety-critical applications (including life support systems and other medical devices), in which the failure of the products could lead directly to death, personal injury or severe physical or environmental damage ("High Risk Activities"). RPL specifically disclaims any express or implied warranty of fitness for High Risk Activities and accepts no liability for use or inclusions of Raspberry Pi products in High Risk Activities. Raspberry Pi products are provided subject to RPL’s Standard Terms. RPL’s provision of the RESOURCES does not expand or otherwise modify RPL’s Standard Terms including but not limited to the disclaimers and warranties expressed in them. Legal disclaimer notice 1 Raspberry Pi Pico-series Python SDK Table of contents Colophon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Legal disclaimer notice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1. The MicroPython Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Getting MicroPython for RP-series Microcontrollers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2. Installing MicroPython on a Pico-series Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.3. Building MicroPython From Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Connecting to the MicroPython REPL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.1. Connecting from a Raspberry Pi over USB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.2. Connecting from a Raspberry Pi using UART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.3. Connecting from a Mac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.4. Say "Hello World". . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.5. Blink an LED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.6. What next? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3. The RP-series microcontroller Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.1. Blinking an LED Forever (Timer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.2. UART. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.3. ADC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.4. Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.5. Multicore Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.6. I2C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.7. SPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.8. PWM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 3.9. PIO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 3.9.1. IRQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 3.9.2. WS2812 LED (NeoPixel) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 3.9.3. UART TX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 3.9.4. SPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 3.9.5. PWM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 3.9.6. Using pioasm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 3.10. Wireless Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4. Using an Integrated Development Environment (IDE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 4.1. Using Thonny. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 4.1.1. Blinking the LED from Thonny . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 4.2. Using Visual Studio Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 4.3. Using Remote MicroPython shell (rshell). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 4.3.1. Blinking the LED from rshell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Appendix A: App Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Using a SSD1306-based OLED graphics display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Wiring information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 List of Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Bill of Materials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Using a SH1106-based OLED graphics display. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Wiring information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 List of Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Bill of Materials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Using PIO to drive a set of NeoPixel Ring (WS2812 LEDs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Wiring information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 List of Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Bill of Materials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Using UART on the Raspberry Pi Pico . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Wiring information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 List of Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Bill of Materials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Documentation Release History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 15 October 2024 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Table of contents 2 Raspberry Pi Pico-series Python SDK 02 May 2024 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 02 Feb 2024 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 14 Jun 2023 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 03 Mar 2023 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 01 Dec 2022 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 30 Jun 2022 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 17 Jun 2022 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 04 Nov 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 03 Nov 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 30 Sep 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 23 Jun 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 07 Jun 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 13 Apr 2021. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 07 Apr 2021. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 05 Mar 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 23 Feb 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 01 Feb 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 26 Jan 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 21 Jan 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Table of contents 3 Raspberry Pi Pico-series Python SDK Chapter 1. The MicroPython Environment Python is the fastest way to get started with embedded software on Pico-series devices. This book is about the official MicroPython port for RP-series microcontroller-based boards. MicroPython is a Python 3 implementation for microcontrollers and small embedded systems. Because MicroPython is highly efficient, and RP-series microcontrollers are designed with a disproportionate amount of system memory and processing power for their price, MicroPython is a serious tool for embedded systems development, which does not compromise on approachability. For exceptionally demanding pieces of software, you can fall back on the SDK (covered in Getting started with Raspberry Pi Pico-series and Raspberry Pi Pico-series C/C++ SDK), or an external C module added to your MicroPython firmware, to wring out the very last drop of performance. For every other project, MicroPython handles a lot of heavy lifting for you, and lets you focus on writing the code that adds value to your project. The accelerated floating point libraries in RP-series microcontrollers' on-board ROM storage are used automatically by your Python code, so you should find arithmetic performance quite snappy. Most on-chip hardware is exposed through the standard machine module, so existing MicroPython projects can be ported without too much trouble. The second processor core is exposed through the _thread module. RP-series microcontrollers have some unique hardware you won’t find on other microcontrollers, with the programmable I/O system (PIO) being the prime example of this: a versatile hardware subsystem that lets you create new I/O interfaces and run them at high speed. In the rp2 module you will find a comprehensive PIO library which lets you write new PIO programs at the MicroPython prompt, and interact with them in real time, to develop interfaces for new or unusual pieces of hardware (or indeed if you just find yourself wanting an extra few serial ports). MicroPython implements the entire Python 3.4 syntax (including exceptions, with, yield from, etc., and additionally async /await keywords from Python 3.5). The following core datatypes are provided: str (including basic Unicode support), bytes, bytearray, tuple, list, dict, set, frozenset, array.array, collections.namedtuple, classes and instances. Builtin modules include sys, time, and struct, etc. Note that only a subset of Python 3 functionality is implemented for the data types and modules. MicroPython can execute scripts in textual source form (.py files) or from precompiled bytecode, in both cases either from an on-device filesystem or "frozen" into the MicroPython executable. 1.1. Getting MicroPython for RP-series Microcontrollers Pre-built Binary A pre-built binary of the latest MicroPython firmware is available from the MicroPython section of the documentation. The fastest way to get MicroPython is to download the pre-built release binary from the Documentation pages. If you can’t or don’t want to use the pre-built release — for example, if you want to develop a C module for MicroPython — you can follow the instructions in Section 1.3 to get the source code for MicroPython, which you can use to build your own MicroPython firmware binary. 1.1. Getting MicroPython for RP-series Microcontrollers 4 Raspberry Pi Pico-series Python SDK 1.2. Installing MicroPython on a Pico-series Device Pico-series devices have a BOOTSEL mode for programming firmware over the USB port. Holding the BOOTSEL button when powering up your board will put it into a special mode where it appears as a USB Mass Storage Device. First make sure your Pico-series device is not plugged into any source of power: disconnect the micro USB cable if plugged in, and disconnect any other wires that might be providing power to the board, e.g. through the VSYS or VBUS pin. Now hold down the BOOTSEL button, and plug in the micro USB cable (which hopefully has the other end plugged into your computer). A drive called RPI-RP2 should pop up. Go ahead and drag the MicroPython firmware.uf2 file onto this drive. This programs the MicroPython firmware onto the flash memory on your Pico-series device. It should take a few seconds to program the UF2 file into the flash. The board will automatically reboot when finished, causing the RPI-RP2 drive to disappear, and boot into MicroPython. By default, MicroPython doesn’t do anything when it first boots. It sits and waits for you to type in further instructions. Chapter 2 shows how you can connect with the MicroPython firmware now running on your board. You can read on to see how a custom MicroPython firmware file can be built from the source code. The Getting started with Raspberry Pi Pico-series book has detailed instructions on getting your Pico-series device into BOOTSEL mode and loading UF2 files, in case you are having trouble. There is also a section going over loading ELF files with the debugger, in case your board doesn’t have an easy way of entering BOOTSEL, or you would like to debug a MicroPython C module you are developing.  NOTE If you are not following these instructions on a Pico-series device, you may not have a BOOTSEL button. If this is the case, you should check if there is some other way of grounding the flash CS pin, such as a jumper, to tell the RPseries microcontroller to enter the BOOTSEL mode on boot. If there is no such method, you can load code using the Serial Wire Debug interface. 1.3. Building MicroPython From Source The prebuilt binary which can be downloaded from the MicroPython section of the documentation should serve most use cases, but you can build your own MicroPython firmware from source if you’d like to customise its low-level aspects.  TIP If you have already downloaded and installed a prebuilt MicroPython UF2 file, you can skip ahead to Chapter 2 to start using your board.  IMPORTANT These instructions for getting and building MicroPython assume you are using Raspberry Pi OS running on a Raspberry Pi 4, or an equivalent Debian-based Linux distribution running on another platform. It’s a good idea to create a pico directory to keep all pico-related checkouts in. These instructions create a pico directory at /home/pi/pico. $ cd ~/ $ mkdir pico $ cd pico Then clone the micropython git repository. These instructions will fetch the latest version of the source code. 1.2. Installing MicroPython on a Pico-series Device 5 Raspberry Pi Pico-series Python SDK $ git clone https://github.com/micropython/micropython.git --branch master Once the download has finished, the source code for MicroPython should be in a new directory called micropython. The MicroPython repository also contains pointers (submodules) to specific versions of libraries it needs to run on a particular board, like the SDK in the case of RP-series microcontroller. We need to fetch these submodules too: $ cd micropython $ make -C ports/rp2 submodules  NOTE The following instructions assume that you are using a Pico-series device. Some details may differ if you are building firmware for a different RP-series microcontroller-based board. The board vendor should detail any extra steps needed to build firmware for that particular board. The version we’re building here is fairly generic, but there might be some differences like putting the default serial port on different pins, or including extra modules to drive that board’s hardware. To build the RP-series microcontroller MicroPython port, you’ll need to install some extra tools. To build projects you’ll need CMake, a cross-platform tool used to build the software, and the GNU Embedded Toolchain for Arm, which turns MicroPython’s C source code into a binary program RP-series microcontrollers' processors can understand. buildessential is a bundle of tools you need to build code native to your own machine — this is needed for some internal tools in MicroPython and the SDK. You can install all of these via apt from the command line. Anything you already have installed will be ignored by apt. $ sudo apt update $ sudo apt install cmake gcc-arm-none-eabi libnewlib-arm-none-eabi build-essential First we need to bootstrap a special tool for MicroPython builds, that ships with the source code: $ make -C mpy-cross We can now build the port we need for RP-series microcontroller, that is, the version of MicroPython that has specific support for Raspberry Pi chips. $ cd ports/rp2 $ make If everything went well, there will be a new directory called build-PICO (ports/rp2/build-PICO relative to the micropython directory), which contains the new firmware binaries. The most important ones are: firmware.uf2 A UF2 binary file which can dragged onto the RPI-RP2 drive that pops up once your Pico-series device enters BOOTSEL mode. The firmware binary you can download from the documentation page is a UF2 file, because they’re the easiest to install. firmware.elf A different type of binary file, which can be loaded by a debugger (such as gdb with openocd) over RP-series microcontroller’s SWD debug port. This is useful for debugging either a native C module you’ve added to MicroPython, or the MicroPython core interpreter itself. The actual binary contents is the same as firmware.uf2. 1.3. Building MicroPython From Source 6 Raspberry Pi Pico-series Python SDK You can take a look inside your new firmware.uf2 using picotool, see the Appendix B in the Getting started with Raspberry Pi Pico-series book for details of how to use picotool, e.g. $ picotool info -a build-PICO/firmware.uf2 File build-PICO/firmware.uf2: Program Information name: MicroPython version: v1.18-412-g965747bd9 features: USB REPL thread support frozen modules: _boot, rp2, _boot_fat, ds18x20, onewire, dht, uasyncio, uasyncio/core, uasyncio/event, uasyncio/funcs, uasyncio/lock, uasyncio/stream, neopixel binary start: 0x10000000 binary end: 0x1004ba24 embedded drive: 0x100a0000-0x10200000 (1408K): MicroPython Fixed Pin Information none Build Information sdk version: 1.3.0 pico_board: pico boot2_name: boot2_w25q080 build date: May build attributes: MinSizeRel 1.3. Building MicroPython From Source 4 2022 7 Raspberry Pi Pico-series Python SDK Chapter 2. Connecting to the MicroPython REPL When MicroPython boots for the first time, it will sit and wait for you to connect and tell it what to do. You can load a .py file from your computer onto the board, but a more immediate way to interact with it is through what is called the readevaluate-print loop, or REPL (often pronounced similarly to "ripple"). Read MicroPython waits for you to type in some text, followed by the enter key. Evaluate Whatever you typed is interpreted as Python code, and runs immediately. Print Any results of the last line you typed are printed out for you to read. Loop Go back to the start — prompt you for another line of code. There are two ways to connect to this REPL, so you can communicate with the MicroPython firmware on your board: over USB, and over the UART serial port on Pico-series GPIOs. 2.1. Connecting from a Raspberry Pi over USB The MicroPython firmware is equipped with a virtual USB serial port which is accessed through the micro USB connector on Pico-series devices. Your computer should notice this serial port and list it as a character device, most likely /dev/ttyACM0.  TIP You can run ls /dev/tty* to list your serial ports. There may be quite a few, but MicroPython’s USB serial will start with /dev/ttyACM. If in doubt, unplug the micro USB connector and see which one disappears. If you don’t see anything, you can try rebooting your Raspberry Pi. You can install minicom to access the serial port: $ sudo apt install minicom and then open it as such: $ minicom -o -D /dev/ttyACM0 Where the -D /dev/ttyACM0 is pointing minicom at MicroPython’s USB serial port, and the -o flag essentially means "just do it". There’s no need to worry about baud rate, since this is a virtual serial port. Press the enter key a few times in the terminal where you opened minicom. You should see this: >>> This is a prompt. MicroPython wants you to type something in, and tell it what to do. If you press CTRL-D on your keyboard whilst the minicom terminal is focused, you should see a message similar to this: 2.1. Connecting from a Raspberry Pi over USB 8 Raspberry Pi Pico-series Python SDK MPY: soft reboot MicroPython v1.13-422-g904433073 on 2021-01-19; Raspberry Pi Pico with RP2040 Type "help()" for more information. >>> This key combination tells MicroPython to reboot. You can do this at any time. When it reboots, MicroPython will print out a message saying exactly what firmware version it is running, and when it was built. Your version number will be different from the one shown here. 2.2. Connecting from a Raspberry Pi using UART  WARNING REPL over UART is disabled by default. The MicroPython port for RP-series microcontrollers does not expose REPL over a UART port by default. However this default can be changed in the ports/rp2/mpconfigport.h source file. If you want to use the REPL over UART you’re going to have to build MicroPython yourself, see Section 1.3 for more details. Go ahead and download the MicroPython source and in ports/rp2/mpconfigport.h change MICROPY_HW_ENABLE_UART_REPL to 1 to enable it. #define MICROPY_HW_ENABLE_UART_REPL (1) // useful if there is no USB Then continue to follow the instructions in Section 1.3 to build your own MicroPython UF2 firmware. This will allow the REPL to be accessed over a UART port, through two GPIO pins. The default settings for UARTs are taken from the C SDK. Table 1. Default UART settings in MicroPython Function Default UART_BAUDRATE 115,200 UART_BITS 8 UART_STOP 1 UART0_TX Pin 0 UART0_RX Pin 1 UART1_TX Pin 4 UART1_RX Pin 5 This alternative interface is handy if you have trouble with USB, if you don’t have any free USB ports, or if you are using some other RP-series microcontroller-based board which doesn’t have an exposed USB connector. 2.2. Connecting from a Raspberry Pi using UART 9 Raspberry Pi Pico-series Python SDK  NOTE This initially occupies the UART0 peripheral on RP-series microcontrollers. The UART1 peripheral is free for you to use in your Python code as a second UART. The next thing you’ll need to do is to enable UART serial on the Raspberry Pi. To do so, run raspi-config, $ sudo raspi-config and go to Interfacing Options → Serial and select "No" when asked "Would you like a login shell to be accessible over serial?" and "Yes" when asked "Would you like the serial port hardware to be enabled?". You should see something like Figure 1. Figure 1. Enabling a serial UART using raspi-config on the Raspberry Pi. Leaving raspi-config you should choose "Yes" and reboot your Raspberry Pi to enable the serial port. You should then wire the Raspberry Pi and the Pico-series device together with the following mapping: Raspberry Pi Pico GND GND GPIO15 (UART_RX0) GPIO0 (UART0_TX) GPIO14 (UART_TX0) GPOI1 (UART0_RX)  IMPORTANT RX matches to TX, and TX matches to RX. You mustn’t connect the two opposite TX pins together, or the two RX pins. This is because MicroPython needs to listen on the channel that the Raspberry Pi transmits on, and vice versa. See Figure 2. 2.2. Connecting from a Raspberry Pi using UART 10 Raspberry Pi Pico-series Python SDK Figure 2. A Raspberry Pi 4 and the Raspberry Pi Pico with UART0 connected together. then connect to the board using minicom connected to /dev/serial0, $ minicom -b 115200 -o -D /dev/serial0 If you press the enter key, MicroPython should respond by prompting you for more input: >>> 2.3. Connecting from a Mac So long as you’re using a recent version of macOS like Catalina, drivers should already be loaded. Otherwise see the manufacturers' website for FTDI Chip Drivers. Then you should use a Terminal program to connect to Serial-over-USB (USB CDC). The serial port will show up as /dev/tty.usbmodem0000000000001 If you don’t already have a Terminal program installed you can install minicom using Homebrew, $ brew install minicom and connect to the board as below. $ minicom -b 115200 -o -D /dev/tty.usbmodem0000000000001 2.3. Connecting from a Mac 11 Raspberry Pi Pico-series Python SDK  NOTE Other Terminal applications like CoolTerm or Serial can also be used. 2.4. Say "Hello World" Once connected you can check that everything is working by typing a Python "Hello World" into the REPL, >>> print("Hello, Pico!") Hello, Pico! >>> 2.5. Blink an LED The on-board LED on Raspberry Pi Pico and Pico is connected to GPIO pin 25, whereas on Raspberry Pi Pico W it is connected to the wireless chip. On both boards you can use the "LED" string. You can blink this on and off from the REPL. When you see the REPL prompt enter the following, >>> from machine import Pin >>> led = Pin("LED", Pin.OUT) The machine module is used to control on-chip hardware. This is standard on all MicroPython ports, and you can read more about it in the MicroPython documentation. Here we are using it to take control of a GPIO, so we can drive it high and low. If you type this in, >>> led.value(1) The LED should turn on. You can turn it off again with >>> led.value(0) 2.6. What next? At this point you should have MicroPython installed on your board, and have tested your setup by typing short programs into the prompt to print some text back to you, and blink an LED. You can read on to the next chapter, which goes into the specifics of MicroPython on RP-series microcontrollers, and where it differs from other platforms. Chapter 3 also has some short examples of the different APIs offered to interact with the hardware. You can learn how to set up an integrated development environment (IDE) in Chapter 4, so you don’t have to type programs in line by line. You can dive straight into Appendix A if you are eager to start connecting wires to a breadboard. 2.4. Say "Hello World" 12 Raspberry Pi Pico-series Python SDK Chapter 3. The RP-series microcontroller Port Currently supported features include: • REPL over USB and UART (on GP0/GP1). • 1600 kB filesystem using littlefs2 on the on-board flash. (Default size for Raspberry Pi Pico) • utime module with sleep and ticks functions. • ubinascii module. • machine module with some basic functions. ◦ machine.Pin class. ◦ machine.Timer class. ◦ machine.ADC class. ◦ machine.I2C and machine.SoftI2C classes. ◦ machine.SPI and machine.SoftSPI classes. ◦ machine.WDT class. ◦ machine.PWM class. ◦ machine.UART class. • rp2 platform-specific module. ◦ PIO hardware access library ◦ PIO program assembler ◦ Raw flash read/write access • Multicore support exposed via the standard _thread module • Accelerated floating point arithmetic using the RP-series microcontroller ROM library and hardware divider (used automatically) Documentation around MicroPython is available from https://docs.micropython.org. For example the machine module, which can be used to access a lot of on-chip hardware, is standard, and you will find a lot of the information you need in the online documentation for that module. This chapter will give a very brief tour of some of the hardware APIs, with code examples you can either type into the REPL (Chapter 2) or load onto the board using a development environment installed on your computer (Chapter 4). 3.1. Blinking an LED Forever (Timer) In Chapter 2 we saw how the machine.Pin class could be used to turn an LED on and off, by driving a GPIO high and low. >>> from machine import Pin >>> led = Pin("LED", Pin.OUT) >>> led.value(1) >>> led.value(0) 3.1. Blinking an LED Forever (Timer) 13 Raspberry Pi Pico-series Python SDK This is, to put it mildy, quite a convoluted way of turning a light on and off. A light switch would work better. The machine.Timer class, which uses RP-series microcontrollers' hardware timer to trigger callbacks at regular intervals, saves a lot of typing if we want the light to turn itself on and off repeatedly, thus bringing our level of automation from "mechanical switch" to "555 timer". Pico MicroPython Examples: https://github.com/raspberrypi/pico-micropython-examples/blob/master/blink/blink.py 1 from machine import Pin, Timer 2 3 led = Pin("LED", Pin.OUT) 4 tim = Timer() 5 def tick(timer): 6 global led 7 led.toggle() 8 9 tim.init(freq=2.5, mode=Timer.PERIODIC, callback=tick) Typing this program into the REPL will cause the LED to start blinking, but the prompt will appear again: >>> The Timer we created will run in the background, at the interval we specified, blinking the LED. The MicroPython prompt is still running in the foreground, and we can enter more code, or start more timers. 3.2. UART  NOTE REPL over UART is disabled by default. See Section 2.2 for details of how to enable REPL over UART. Example usage looping UART0 to UART1. Pico MicroPython Examples: https://github.com/raspberrypi/pico-micropython-examples/blob/master/uart/loopback/uart.py 1 from machine import UART, Pin 2 import time 3 4 uart1 = UART(1, baudrate=9600, tx=Pin(8), rx=Pin(9)) 5 6 uart0 = UART(0, baudrate=9600, tx=Pin(0), rx=Pin(1)) 7 8 txData = b'hello world\n\r' 9 uart1.write(txData) 10 time.sleep(0.1) 11 rxData = bytes() 12 while uart0.any() > 0: 13 rxData += uart0.read(1) 14 15 print(rxData.decode('utf-8')) For more detail, including a wiring diagram, see Appendix A. 3.2. UART 14 Raspberry Pi Pico-series Python SDK 3.3. ADC An analogue-to-digital converter (ADC) measures some analogue signal and encodes it as a digital number. The ADC on RP-series microcontrollers measures voltages. An ADC has two key features: its resolution, measured in digital bits, and its channels, or how many analogue signals it can accept and convert at once. The ADC on RP2350 and RP2040 has a resolution of 12-bits, meaning that it can transform an analogue signal into a digital signal as a number ranging from 0 to 4095 – though this is handled in MicroPython transformed to a 16-bit number ranging from 0 to 65,535, so that it behaves the same as the ADC on other MicroPython microcontrollers. RP2350 and RP2040 have five ADC channels total, four of which are brought out to chip GPIOs: GP26, GP27, GP28 and GP29. On Pico W and Pico, the first three of these are brought out to GPIO pins, and the fourth can be used to measure the VSYS voltage on the board. The ADC’s fifth input channel is connected to a temperature sensor built into RP2350 and RP2040. You can specify which ADC channel you’re using by pin number: adc = machine.ADC(26) # Connect to GP26, which is channel 0 or by channel: adc = machine.ADC(4) # Connect to the internal temperature sensor adc = machine.ADC(0) # Connect to channel 0 (GP26) An example reading the fourth analogue-to-digital (ADC) converter channel, connected to the internal temperature sensor: Pico MicroPython Examples