Manual / Guide · 2024

Raspberry Pi Pico-series — Getting Started (C/C++ Development)

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

raspberry pi pico
getting started
c/c++
sdk
microcontroller

Getting started with Raspberry Pi Pico-series 2b6018e-clean 2024-10-15: C/C++ development with Raspberry Pi Pico-series and other Raspberry Pi microcontroller-based boards. Getting started with Raspberry Pi Pico-series 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). build-date: 2024-10-15 build-version: 2b6018e-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 Getting started with Raspberry Pi Pico-series Table of contents Colophon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Legal disclaimer notice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Install Visual Studio Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Install the Raspberry Pi Pico VS Code Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.1. Install Dependencies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.1.1. Raspberry Pi OS and Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.1.2. Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.1.3. macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2. Install the Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4. Load and debug a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.1. Compile and Run blink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.2. Make a Code Change and Re-run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.3. Debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 5. Say "Hello World" in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 5.1. Serial input and output on Pico-series devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 5.2. Create a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 5.3. Build your project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 5.4. See console output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Appendix A: Debugprobe. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Building OpenOCD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Install OpenOCD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Debug Probe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Debug Probe wiring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Debug with a second Pico or Pico 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Install debugprobe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 debugprobe wiring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Debug Probe interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Use the UART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Linux. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Debug with OpenOCD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Debug with SWD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Appendix B: Picotool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Getting picotool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Building picotool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Using picotool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Display information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Save the program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Binary Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Basic information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Full Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Appendix C: Manual toolchain setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Configure your environment via Script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Manually Configure your Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Get the SDK and examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Install the Toolchain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Enable UART serial communications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Update the SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Use the CLI to Blink an LED in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Building "Blink" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Load and run "Blink" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Manually Create your own Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Table of contents 2 Getting started with Raspberry Pi Pico-series Debugging your project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Appendix D: Use other Integrated Development Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Use Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Setting up Eclipse for Pico on a Linux machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Use CLion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Setting up CLion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Other Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Appendix H: Documentation Release History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 15 October 2024 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 6 September 2024 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 9 August 2024. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 8 August 2024. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 02 May 2024 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 02 Feb 2024 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 14 Jun 2023 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 03 Mar 2023 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 01 Dec 2022 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 30 Jun 2022 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 17 Jun 2022 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 04 Nov 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 03 Nov 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 30 Sep 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 23 Jun 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 07 Jun 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 13 Apr 2021. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 07 Apr 2021. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 05 Mar 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 23 Feb 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 01 Feb 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 26 Jan 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 21 Jan 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Table of contents 3 Getting started with Raspberry Pi Pico-series Chapter 1. Introduction To follow this guide you will need the following: • Raspberry Pi Pico-series device • a Micro USB cable The following are required for some of the later steps: • Raspberry Pi Debug Probe, or a second Raspberry Pi Pico-series device The following instructions assume that you are using a Pico-series device; some details may differ if you use a different Raspberry Pi microcontroller-based board. Pico-series devices are built around microcontrollers designed by Raspberry Pi. Development on the boards is fully supported with both a C/C++ SDK, and an official MicroPython port. This book talks about how to get started with the SDK, and walks you through how to build, install, and work with the SDK toolchain.  TIP The main method covered in this book uses a VS Code extension to make your life easy. If you would like to set up your development environment manually, see Manually Configure your Environment. For more information on the official MicroPython port, see: • the documentation for the Raspberry Pi Pico-series Python SDK • the Raspberry Pi Press book Get Started with MicroPython on Raspberry Pi Pico - 2nd Edition For more information on the C/C++ SDK, see the documentation for the Raspberry Pi Pico-series C/C++ SDK. Chapter 1. Introduction 4 Getting started with Raspberry Pi Pico-series Chapter 2. Install Visual Studio Code Visual Studio Code (VS Code) is a popular open source editor developed by Microsoft. The Raspberry Pi Pico VS Code Extension makes it easy to install dependencies and build software for Pico-series devices.  TIP If you don’t want to use VS Code, you can either use VSCodium (the community-driven libre alternative) or configure your environment manually. To install Visual Studio Code (VS Code) on Raspberry Pi OS or Linux, run the following commands: $ sudo apt update $ sudo apt install code On macOS and Windows, you can install VS Code from https://code.visualstudio.com/Download. On macOS, you can also install VS Code with brew using the following command: $ brew install --cask visual-studio-code Chapter 2. Install Visual Studio Code 5 Getting started with Raspberry Pi Pico-series Chapter 3. Install the Raspberry Pi Pico VS Code Extension The Raspberry Pi Pico VS Code extension helps you create, develop, run, and debug projects in Visual Studio Code. It includes a project generator with many templating options, automatic toolchain management, one click project compilation, and offline documentation of the Pico SDK. The VS Code extension supports all Raspberry Pi Pico-series devices. 3.1. Install Dependencies 3.1.1. Raspberry Pi OS and Windows No dependencies needed. 3.1.2. Linux Most Linux distributions come preconfigured with all of the dependencies needed to run the extension. However, some distributions may require additional dependencies. The extension requires the following: • Python 3.9 or later • Git • Tar • a native C and C++ compiler (the extension supports GCC) You can install these with: $ sudo apt install python3 git tar build-essential 3.1.3. macOS To install all requirements for the extension on macOS, run the following command: $ xcode-select --install This installs the following dependencies: • Git • Tar • A native C and C++ compiler (the extension supports GCC and Clang) 3.1. Install Dependencies 6 Getting started with Raspberry Pi Pico-series 3.2. Install the Extension You can find the extension in the VS Code Extensions Marketplace. Search for the Raspberry Pi Pico extension, published by Raspberry Pi. Click the Install button to add it to VS Code. Figure 1. Debugging in VS Code. You can find the store entry at https://marketplace.visualstudio.com/items?itemName=raspberry-pi.raspberry-pi-pico. You can find the extension source code and release downloads at https://github.com/raspberrypi/pico-vscode. When installation completes, check the Activity sidebar (by default, on the left side of VS Code). If installation was successful, a new sidebar section appears with a Raspberry Pi Pico icon, labelled "Raspberry Pi Pico Project". 3.2. Install the Extension 7 Getting started with Raspberry Pi Pico-series Chapter 4. Load and debug a project The VS Code extension can create projects based on the examples provided by Pico Examples. For an example, we’ll walk you through how to create a project that blinks the LED on your Pico-series device: 1. In the VS Code left sidebar, select the Raspberry Pi Pico icon, labelled "Raspberry Pi Pico Project". 2. Select New Project from Examples. 3. In the Name field, select the blink example. 4. Choose the board type that matches your device. 5. Specify a folder where the extension can generate files. VS Code will create the new project in a sub-folder of the selected folder. 6. Click Create to create the project. The extension will now download the SDK and the toolchain, install them locally, and generate the new project. The first project may take 5-10 minutes to install the toolchain. VS Code will ask you whether you trust the authors because we’ve automatically generated the .vscode directory for you. Select yes. Figure 2. Creating a project in VS Code.  NOTE The CMake Tools extension may display some notifications at this point. Ignore and close them. On the left Explorer sidebar in VS Code, you should now see a list of files. Open blink.c to view the blink example source code in the main window. The Raspberry Pi Pico extension adds some capabilities to the status bar at the bottom right of the screen. Compile Compiles the sources and builds the target UF2 file. You can copy this binary onto your device to program it. Run Finds a connected device, flashes the code into it, and runs that code. Chapter 4. Load and debug a project 8 Getting started with Raspberry Pi Pico-series The extension sidebar also contains some quick access functions. Click on the Pico icon in the side menu and you’ll see Compile Project. Hit Compile Project and a terminal tab will open at the bottom of the screen displaying the compilation progress. 4.1. Compile and Run blink To run the blink example: 1. Hold down the BOOTSEL button on your Pico-series device while plugging it into your development device using a micro USB cable to force it into USB Mass Storage Mode. 2. Press the Run button in the status bar or the Run project button in the sidebar. You should see the terminal tab at the bottom of the window open. It will display information concerning the upload of the code. Once the code uploads, the device will reboot, and you should see the following output: The device was rebooted to start the application. Your blink code is now running. If you look at your device, the LED should blink twice every second. 4.2. Make a Code Change and Re-run To check that everything is working correctly, click on the blink.c file in VS Code. Navigate to the definition of LED_DELAY_MS at the top of the code: #ifndef LED_DELAY_MS #define LED_DELAY_MS 250 #endif LED_DELAY_MS 1. Change the 250ms (a quarter of a second) to 100 (a tenth of a second): #ifndef LED_DELAY_MS #define LED_DELAY_MS 100 #endif LED_DELAY_MS 2. Disconnect your device, then reconnect while holding the BOOTSEL button. 3. Press the Run button in the status bar or the Run project button in the sidebar. You should see the terminal tab at the bottom of the window open. It will display information concerning the upload of the code. Once the code uploads, the device will reboot, and you should see the following output: The device was rebooted to start the application. Your blink code is now running. If you look at your device, the LED should flash faster, five times every second. 4.1. Compile and Run blink 9 Getting started with Raspberry Pi Pico-series 4.3. Debug The Raspberry Pi Debug Probe is a debug solution for any Arm-based computer. You can use other debug hardware with Pico-series devices, but we recommend the Debug Probe to make configuration as simple as possible. If you’d like to use a Pico-series device as a Debug Probe, see Debug with a second Pico or Pico 2. First, connect the Debug Probe to your Pico-series device through the debug connector on the board. Depending on which Pico device you have, different connectors will be required. For Pico, Pico W, and Pico 2, use a soldering iron to solder the Debug Probe connectors onto the board. For Pico H, Pico WH, and Pico with headers, the debug header is already added. Just connect the Debug Probe with the supplied cable. Figure 3. Debug Probe wiring For more information, see the Debug Probe documentation. Now, plug the Debug Probe USB into your computer. The Debug Probe does not power the Pico device, it must be powered separately. To start the debugger: 1. Open the extension sidebar by clicking on the Pico icon. 2. Select Debug Project or press F5. 3. If prompted to select a debugger, choose Pico Debug (Cortex-Debug) The debugger will automatically download the code to the device, insert a breakpoint at the beginning of your main 4.3. Debug 10 Getting started with Raspberry Pi Pico-series function, and run until that breakpoint is hit. Figure 4. Debugging in VS Code. Once in debugging mode, the sidebar has a number of windows displaying useful information about the current state of the device. At the top, a small control bar contains buttons that control code execution. Hover over the buttons to identify them. To continue code execution click Continue (F5). Your blink code is now running. If you look at your device, the LED should be blinking as before. Now press Restart (Ctrl+Shift+F5) to go back to the beginning of main. Press Step-over (F10) once. The highlighted line, which indicates the next line to be executed, will advance to the pico_led_init function call. To step into this function, press Step-into (F11). The source window will update to indicate execution is now at the beginning of the function. You can either continue to step over code until the function returns to main, or select Step-out (Shift+F11) to finish executing the function. After returning to the main function, check the Local Variables window to see that the value of rc is 0 (PICO_OK). Press Restart (Ctrl+Shift+F5) again to go back to the beginning of main. Then move the cursor down to the pico_set_led line and press F9. When you create the breakpoint, you’ll see a red dot indicating the breakpoint location: 4.3. Debug 11 Getting started with Raspberry Pi Pico-series Figure 5. Debugging in VS Code. You can add and remove a breakpoint by clicking on the red dot. Press Continue (F5); execution should halt on the breakpoint. Next, press Step-over (F10) and you should see the LED light up. 4.3. Debug 12 Getting started with Raspberry Pi Pico-series Chapter 5. Say "Hello World" in C After blinking an LED on and off, the next thing that most developers will want to do is create and use a serial port, and say "Hello World." 5.1. Serial input and output on Pico-series devices Serial input (stdin) and output (stdout) can be directed to serial UART and/or to USB CDC (USB serial). With a serial UART console, the input and output are sent over the UART pins on the device - by default it will use Pin 1 (GP0) for sending output (UART0_TX) and Pin 2 (GP1) for receiving input (UART0_RX). You will then need to connect the UART pins on the Pico-series device to a UART to USB converter, such as the Debug Probe, as shown in the Debug Probe Wiring diagram. With a USB CDC console, the input and ouput are sent directly over the USB cable connected to your computer, so no additional wiring will be needed. However you may miss some of the printout when your code starts running, as your computer may take a second or two to connect to the Pico-series device after it restarts. You can select either or both consoles when using the extension, depending on your preference. 5.2. Create a project  NOTE The SDK makes use of CMake to control its build system, see Manually Create your own Project if you don’t want to use the VS Code extension 1. In the VS Code left sidebar, select the Raspberry Pi Pico icon, labelled "Raspberry Pi Pico Project". 2. Select New Project. 3. In the Name field, name your project. For example "hello_world". 4. Choose the board type that matches your device. 5. Specify a folder where the extension can generate files. VS Code will create the new project in a sub-folder of the selected folder. 6. Under "STDIO support", select which consoles you would like 7. Click Create to create the project. The extension will now generate the new project. VS Code will ask you whether you trust the authors because we’ve automatically generated the .vscode directory for you. Select yes. 5.3. Build your project To run the "Hello world" example: 1. Hold down the BOOTSEL button on your Pico-series device while plugging it into your development device using a micro USB cable to force it into USB Mass Storage Mode. 2. Press the Run button in the status bar or the Run project button in the sidebar. 5.1. Serial input and output on Pico-series devices 13 Getting started with Raspberry Pi Pico-series You should see the terminal tab at the bottom of the window open. It will display information concerning the upload of the code. Once the code uploads, the device will reboot, and you should see the following output: The device was rebooted to start the application. Your "Hello world" code is now running. Although the "Hello World" example is now running, we cannot yet see the text. 5.4. See console output If using STDIO UART make sure you have wired it up first. STDIO USB does not need any wiring other than being connected to your computer. In VS Code. Go to the view menu, and select "Terminal" to open the bottom pane. In this pane, you will find the "Serial Monitor" tab. Select the serial port. There may be more than one. The baud rate should be 115200. Select "Start Monitoring" to see the output. Figure 6. VS Code serial monitor 5.4. See console output 14 Getting started with Raspberry Pi Pico-series Appendix A: Debugprobe Raspberry Pi provides two ways to debug Pico-series devices: • the Raspberry Pi Debug Probe • debugprobe firmware running on a second Pico or Pico 2 Both methods provide a way to debug Pico-series devices on platforms that lack GPIOs to connect directly to UART or SWD, such as Windows, macOS, and Linux. The debugging device connects to your usual computer using USB, and to the Pico using SWD and UART. Building OpenOCD Shortly after RP2350 launch you will likely need to build openocd from source if not using the VS Code extension. You can get a binary release from https://github.com/raspberrypi/pico-sdk-tools. $ git clone https://github.com/raspberrypi/openocd.git $ cd openocd $ ./bootstrap $ ./configure --disable-werror $ make -j4 To start openocd from the build directory, you can use: For RP2350: sudo src/openocd -s tcl -f interface/cmsis-dap.cfg -f target/rp2350.cfg -c "adapter speed 5000" For RP2040: sudo src/openocd -s tcl -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000" Install OpenOCD To get started, you’ll need OpenOCD. To install OpenOCD, run the following command in a terminal: $ sudo apt install openocd To install OpenOCD on macOS, run the following command: $ brew install openocd Building OpenOCD 15 Getting started with Raspberry Pi Pico-series To run OpenOCD, use the openocd command in your terminal. Debug Probe The simplest way to debug a Pico-series device is the Raspberry Pi Debug Probe. The Raspberry Pi Debug Probe provides Serial Wire Debug (SWD), and a generic USB-to-Serial bridge.  NOTE For more information about the Debug Probe, see the documentation site. Debug Probe wiring Figure 7. Wires included with the Debug Probe. Debug Probe 16 Getting started with Raspberry Pi Pico-series Figure 8. Wiring between the Debug Probe (left) and Pico (right). To connect Debug Probe to Pico H, connect the following: • Debug Probe "D" port to Pico H "DEBUG" SWD JST-SH connector • Debug Probe "U" port, with the three-pin JST-SH connector to 0.1-inch header (male): ◦ Debug Probe RX connected to Pico H TX pin ◦ Debug Probe TX connected to Pico H RX pin ◦ Debug Probe GND connected to Pico H GND pin Then, connect two USB cables: one from your computer to the microUSB port on Debug Probe and another from your computer to the microUSB port on Pico.  NOTE If you have a non-H Pico, Pico 2 or Pico W (without a JST-SH connector) you can still connect it to a Debug Probe. Solder a male connector to the SWCLK, GND, and SWDIO header pins on the board. Using the alternate 3-pin JST-SH connector to 0.1-inch header (female) cable included with the Debug Probe, connect to the Debug Probe "D" port. Connect SWCLK, GND, and SWDIO on the Pico or Pico W to the SC, GND, and SD pins on the Debug Probe, respectively. The wiring loom between Pico and the Debug Probe is shown in Figure 8. Debug with a second Pico or Pico 2 One Pico or Pico 2 can reprogram and debug another using the debugprobe firmware, which transforms the Pico or Pico 2 into a USB → SWD and UART bridge. Debug with a second Pico or Pico 2 17 Getting started with Raspberry Pi Pico-series Figure 9. Wiring between Pico A (left) and Pico B (right) with Pico A acting as a debugger and Pico B as a system under test. You must connect at least the ground and the two SWD wires. Connect the UART serial port to provide access to the UART serial output of Pico B. You can also bridge the power supply to power both boards with one USB cable. For more information, see debugprobe wiring. Install debugprobe You can download a UF2 binary of debugprobe from the Pico-series documentation. Boot the debugger Pico or Pico 2 with the BOOTSEL button pressed. Copy debugprobe_on_pico.uf2 onto the device to begin debugging.  NOTE Use debugprobe_on_pico.uf2 to use a Pico for debugging. Use debugprobe.uf2 for the Debug Probe accessory hardware. Build debugprobe Alternatively, you can build debugprobe using the following instructions: These build instructions assume you are running on Linux, and have installed the SDK.  NOTE These instructions are for Pico; replace the -DPICO_BOARD=pico with -DPICO_BOARD=pico2 for Pico 2 $ cd ~/pico $ git clone https://github.com/raspberrypi/debugprobe.git $ cd debugprobe $ git submodule update --init $ mkdir build $ cd build $ export PICO_SDK_PATH=../../pico-sdk $ cmake -DDEBUG_ON_PICO=ON -DPICO_BOARD=pico .. $ make -j4 Boot the debugger Pico or Pico 2 with the BOOTSEL button pressed. Copy debugprobe.uf2 onto the device to begin debugging. debugprobe wiring debugprobe wiring 18 Getting started with Raspberry Pi Pico-series Figure 10. Wiring between Pico A (left) and Pico B (right), configuring Pico A as a debugger. The wiring loom between the two Pico boards is shown in Figure 10. Pico A GND -> Pico B GND Pico A GP2 -> Pico B SWCLK Pico A GP3 -> Pico B SWDIO Pico A GP4/UART1 TX -> Pico B GP1/UART0 RX Pico A GP5/UART1 RX -> Pico B GP0/UART0 TX The minimum set of connections required to load and run code via OpenOCD is GND, SWCLK and SWDIO. Connect the UART wires to communicate with Pico B’s UART serial port through Pico A’s USB connection. You can also use the UART wires to talk to any other UART serial device, such as the boot console on a Raspberry Pi. To power Pico A with Pico B, connect the following pins: • When using USB in device mode, or not at all, connect VSYS to VSYS • When acting as a USB Host, connect VBUS to VBUS to provide 5V on the USB connector. Debug Probe interfaces Both the Debug Probe and any Pico-serires device running debugprobe are composite devices with two USB interfaces: 1. A class-compliant CDC UART (serial port), so it works on Windows out of the box. 2. A vendor-specific interface for SWD probe data conforming to CMSIS-DAP v2. Use the UART Linux To use the UART connection on Linux, run the following command: Debug Probe interfaces 19 Getting started with Raspberry Pi Pico-series $ sudo minicom -D /dev/ttyACM0 -b 115200 Windows Download and install PuTTY. Open Device Manager and locate the COM port number of the device running debugprobe. In this example it is COM7. Open PuTTY. Select Serial under connection type. Then type the name of your COM port along with 115200 as the speed. Use the UART 20 Getting started with Raspberry Pi Pico-series Select Open to start the serial console. You are now ready to run your application. macOS First, install minicom using Homebrew: $ brew install minicom Then, run the following command to use the UART connection: Use the UART 21 Getting started with Raspberry Pi Pico-series $ minicom -D /dev/tty.usbmodem1234561 -b 115200 Debug with OpenOCD With Debug Probe, you can load binaries via the SWD port and OpenOCD. First, build a binary. The