1# Raspberry Pi Pico SDK
2
3The Raspberry Pi Pico SDK (henceforth the SDK) provides the headers, libraries and build system
4necessary to write programs for the RP-series microcontroller-based devices such as the Raspberry Pi Pico or Raspberry Pi Pico 2
5in C, C++ or assembly language.
6
7The SDK is designed to provide an API and programming environment that is familiar both to non-embedded C developers and embedded C developers alike.
8A single program runs on the device at a time and starts with a conventional `main()` method. Standard C/C++ libraries are supported along with
9C-level libraries/APIs for accessing all of the RP-series microcontroller's hardware including PIO (Programmable IO).
10
11Additionally, the SDK provides higher level libraries for dealing with timers, synchronization, Wi-Fi and Bluetooth networking, USB and multicore programming. These libraries should be comprehensive enough that your application code rarely, if at all, needs to access hardware registers directly. However, if you do need or prefer to access the raw hardware registers, you will also find complete and fully-commented register definition headers in the SDK. There's no need to look up addresses in the datasheet.
12
13The SDK can be used to build anything from simple applications, fully-fledged runtime environments such as MicroPython, to low level software
14such as the RP-series microcontroller's on-chip bootrom itself.
15
16The design goal for entire SDK is to be simple but powerful.
17
18Additional libraries/APIs that are not yet ready for inclusion in the SDK can be found in [pico-extras](https://github.com/raspberrypi/pico-extras).
19
20# Documentation
21
22See [Getting Started with the Raspberry Pi Pico-Series](https://rptl.io/pico-get-started) for information on how to setup your
23hardware, IDE/environment and how to build and debug software for the Raspberry Pi Pico and other RP-series microcontroller based devices.
24
25See [Connecting to the Internet with Raspberry Pi Pico W](https://rptl.io/picow-connect) to learn more about writing
26applications for your Raspberry Pi Pico W that connect to the internet.
27
28See [Raspberry Pi Pico-Series C/C++ SDK](https://rptl.io/pico-c-sdk) to learn more about programming using the
29SDK, to explore more advanced features, and for complete PDF-based API documentation.
30
31See [Online Raspberry Pi Pico SDK API docs](https://rptl.io/pico-doxygen) for HTML-based API documentation.
32
33# Example code
34
35See [pico-examples](https://github.com/raspberrypi/pico-examples) for example code you can build.
36
37# Getting the latest SDK code
38
39The [master](https://github.com/raspberrypi/pico-sdk/tree/master/) branch of `pico-sdk` on GitHub contains the
40_latest stable release_ of the SDK. If you need or want to test upcoming features, you can try the
41[develop](https://github.com/raspberrypi/pico-sdk/tree/develop/) branch instead.
42
43# Quick-start your own project
44
45## Using Visual Studio Code
46
47You can install the [Raspberry Pi Pico Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=raspberry-pi.raspberry-pi-pico) in VS Code.
48
49## Unix command line
50
51These instructions are extremely terse, and Linux-based only. For detailed steps,
52instructions for other platforms, and just in general, we recommend you see [Raspberry Pi Pico-Series C/C++ SDK](https://rptl.io/pico-c-sdk)
53
541. Install CMake (at least version 3.13), and a GCC cross compiler
55   ```
56   sudo apt install cmake gcc-arm-none-eabi libnewlib-arm-none-eabi libstdc++-arm-none-eabi-newlib
57   ```
581. Set up your project to point to use the Raspberry Pi Pico SDK
59
60   * Either by cloning the SDK locally (most common) :
61      1. `git clone` this Raspberry Pi Pico SDK repository
62      1. Copy [pico_sdk_import.cmake](https://github.com/raspberrypi/pico-sdk/blob/master/external/pico_sdk_import.cmake)
63         from the SDK into your project directory
64      2. Set `PICO_SDK_PATH` to the SDK location in your environment, or pass it (`-DPICO_SDK_PATH=`) to cmake later.
65      3. Setup a `CMakeLists.txt` like:
66
67          ```cmake
68          cmake_minimum_required(VERSION 3.13...3.27)
69
70          # initialize the SDK based on PICO_SDK_PATH
71          # note: this must happen before project()
72          include(pico_sdk_import.cmake)
73
74          project(my_project)
75
76          # initialize the Raspberry Pi Pico SDK
77          pico_sdk_init()
78
79          # rest of your project
80
81          ```
82
83   * Or with the Raspberry Pi Pico SDK as a submodule :
84      1. Clone the SDK as a submodule called `pico-sdk`
85      1. Setup a `CMakeLists.txt` like:
86
87          ```cmake
88          cmake_minimum_required(VERSION 3.13...3.27)
89
90          # initialize pico-sdk from submodule
91          # note: this must happen before project()
92          include(pico-sdk/pico_sdk_init.cmake)
93
94          project(my_project)
95
96          # initialize the Raspberry Pi Pico SDK
97          pico_sdk_init()
98
99          # rest of your project
100
101          ```
102
103   * Or with automatic download from GitHub :
104      1. Copy [pico_sdk_import.cmake](https://github.com/raspberrypi/pico-sdk/blob/master/external/pico_sdk_import.cmake)
105         from the SDK into your project directory
106      1. Setup a `CMakeLists.txt` like:
107
108          ```cmake
109          cmake_minimum_required(VERSION 3.13)
110
111          # initialize pico-sdk from GIT
112          # (note this can come from environment, CMake cache etc)
113          set(PICO_SDK_FETCH_FROM_GIT on)
114
115          # pico_sdk_import.cmake is a single file copied from this SDK
116          # note: this must happen before project()
117          include(pico_sdk_import.cmake)
118
119          project(my_project)
120
121          # initialize the Raspberry Pi Pico SDK
122          pico_sdk_init()
123
124          # rest of your project
125
126          ```
127
128   * Or by cloning the SDK locally, but without copying `pico_sdk_import.cmake`:
129       1. `git clone` this Raspberry Pi Pico SDK repository
130       2. Setup a `CMakeLists.txt` like:
131
132           ```cmake
133           cmake_minimum_required(VERSION 3.13)
134
135           # initialize the SDK directly
136           include(/path/to/pico-sdk/pico_sdk_init.cmake)
137
138           project(my_project)
139
140           # initialize the Raspberry Pi Pico SDK
141           pico_sdk_init()
142
143           # rest of your project
144
145           ```
1461. Write your code (see [pico-examples](https://github.com/raspberrypi/pico-examples) or the [Raspberry Pi Pico-Series C/C++ SDK](https://rptl.io/pico-c-sdk) documentation for more information)
147
148   About the simplest you can do is a single source file (e.g. hello_world.c)
149
150   ```c
151   #include <stdio.h>
152   #include "pico/stdlib.h"
153
154   int main() {
155       stdio_init_all();
156       printf("Hello, world!\n");
157       return 0;
158   }
159   ```
160   And add the following to your `CMakeLists.txt`:
161
162   ```cmake
163   add_executable(hello_world
164       hello_world.c
165   )
166
167   # Add pico_stdlib library which aggregates commonly used features
168   target_link_libraries(hello_world pico_stdlib)
169
170   # create map/bin/hex/uf2 file in addition to ELF.
171   pico_add_extra_outputs(hello_world)
172   ```
173
174   Note this example uses the default UART for _stdout_;
175   if you want to use the default USB see the [hello-usb](https://github.com/raspberrypi/pico-examples/tree/master/hello_world/usb) example.
176
1771. Setup a CMake build directory.
178      For example, if not using an IDE:
179      ```
180      $ mkdir build
181      $ cd build
182      $ cmake ..
183      ```
184
185   When building for a board other than the Raspberry Pi Pico, you should pass `-DPICO_BOARD=board_name` to the `cmake` command above, e.g. `cmake -DPICO_BOARD=pico2 ..` or `cmake -DPICO_BOARD=pico_w ..` to configure the SDK and build options accordingly for that particular board.
186
187   Specifying `PICO_BOARD=<booardname>` sets up various compiler defines (e.g. default pin numbers for UART and other hardware) and in certain
188   cases also enables the use of additional libraries (e.g. wireless support when building for `PICO_BOARD=pico_w`) which cannot
189   be built without a board which provides the requisite hardware functionality.
190
191   For a list of boards defined in the SDK itself, look in [this directory](src/boards/include/boards) which has a
192   header for each named board.
193
1941. Make your target from the build directory you created.
195      ```sh
196      $ make hello_world
197      ```
198
1991. You now have `hello_world.elf` to load via a debugger, or `hello_world.uf2` that can be installed and run on your Raspberry Pi Pico-series device via drag and drop.
200
201# RISC-V support on RP2350
202
203See [Raspberry Pi Pico-series C/C++ SDK](https://rptl.io/pico-c-sdk) for information on setting up a build environment for RISC-V on RP2350.