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 RP2040-based devices such as the Raspberry Pi Pico
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 RP2040's hardware include PIO (Programmable IO).
10
11Additionally the SDK provides higher level libraries for dealing with timers, synchronization, USB (TinyUSB) and multi-core programming
12along with various utilities.
13
14The SDK can be used to build anything from simple applications, to fully fledged runtime environments such as MicroPython, to low level software
15such as RP2040's on-chip bootrom itself.
16
17Additional libraries/APIs that are not yet ready for inclusion in the SDK can be found in [pico-extras](https://github.com/raspberrypi/pico-extras).
18
19# Documentation
20
21See [Getting Started with the Raspberry Pi Pico](https://rptl.io/pico-get-started) for information on how to setup your
22hardware, IDE/environment and for how to build and debug software for the Raspberry Pi Pico
23and other RP2040-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 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
45These instructions are extremely terse, and Linux-based only. For detailed steps,
46instructions for other platforms, and just in general, we recommend you see [Raspberry Pi Pico C/C++ SDK](https://rptl.io/pico-c-sdk)
47
481. Install CMake (at least version 3.13), and GCC cross compiler
49   ```
50   sudo apt install cmake gcc-arm-none-eabi libnewlib-arm-none-eabi libstdc++-arm-none-eabi-newlib
51   ```
521. Set up your project to point to use the Raspberry Pi Pico SDK
53
54   * Either by cloning the SDK locally (most common) :
55      1. `git clone` this Raspberry Pi Pico SDK repository
56      1. Copy [pico_sdk_import.cmake](https://github.com/raspberrypi/pico-sdk/blob/master/external/pico_sdk_import.cmake)
57         from the SDK into your project directory
58      2. Set `PICO_SDK_PATH` to the SDK location in your environment, or pass it (`-DPICO_SDK_PATH=`) to cmake later.
59      3. Setup a `CMakeLists.txt` like:
60
61          ```cmake
62          cmake_minimum_required(VERSION 3.13)
63
64          # initialize the SDK based on PICO_SDK_PATH
65          # note: this must happen before project()
66          include(pico_sdk_import.cmake)
67
68          project(my_project)
69
70          # initialize the Raspberry Pi Pico SDK
71          pico_sdk_init()
72
73          # rest of your project
74
75          ```
76
77   * Or with the Raspberry Pi Pico SDK as a submodule :
78      1. Clone the SDK as a submodule called `pico-sdk`
79      1. Setup a `CMakeLists.txt` like:
80
81          ```cmake
82          cmake_minimum_required(VERSION 3.13)
83
84          # initialize pico-sdk from submodule
85          # note: this must happen before project()
86          include(pico-sdk/pico_sdk_init.cmake)
87
88          project(my_project)
89
90          # initialize the Raspberry Pi Pico SDK
91          pico_sdk_init()
92
93          # rest of your project
94
95          ```
96
97   * Or with automatic download from GitHub :
98      1. Copy [pico_sdk_import.cmake](https://github.com/raspberrypi/pico-sdk/blob/master/external/pico_sdk_import.cmake)
99         from the SDK into your project directory
100      1. Setup a `CMakeLists.txt` like:
101
102          ```cmake
103          cmake_minimum_required(VERSION 3.13)
104
105          # initialize pico-sdk from GIT
106          # (note this can come from environment, CMake cache etc)
107          set(PICO_SDK_FETCH_FROM_GIT on)
108
109          # pico_sdk_import.cmake is a single file copied from this SDK
110          # note: this must happen before project()
111          include(pico_sdk_import.cmake)
112
113          project(my_project)
114
115          # initialize the Raspberry Pi Pico SDK
116          pico_sdk_init()
117
118          # rest of your project
119
120          ```
121
122   * Or by cloning the SDK locally, but without copying `pico_sdk_import.cmake`:
123       1. `git clone` this Raspberry Pi Pico SDK repository
124       2. Setup a `CMakeLists.txt` like:
125
126           ```cmake
127           cmake_minimum_required(VERSION 3.13)
128
129           # initialize the SDK directly
130           include(/path/to/pico-sdk/pico_sdk_init.cmake)
131
132           project(my_project)
133
134           # initialize the Raspberry Pi Pico SDK
135           pico_sdk_init()
136
137           # rest of your project
138
139           ```
1401. Write your code (see [pico-examples](https://github.com/raspberrypi/pico-examples) or the [Raspberry Pi Pico C/C++ SDK](https://rptl.io/pico-c-sdk) documentation for more information)
141
142   About the simplest you can do is a single source file (e.g. hello_world.c)
143
144   ```c
145   #include <stdio.h>
146   #include "pico/stdlib.h"
147
148   int main() {
149       setup_default_uart();
150       printf("Hello, world!\n");
151       return 0;
152   }
153   ```
154   And add the following to your `CMakeLists.txt`:
155
156   ```cmake
157   add_executable(hello_world
158       hello_world.c
159   )
160
161   # Add pico_stdlib library which aggregates commonly used features
162   target_link_libraries(hello_world pico_stdlib)
163
164   # create map/bin/hex/uf2 file in addition to ELF.
165   pico_add_extra_outputs(hello_world)
166   ```
167
168   Note this example uses the default UART for _stdout_;
169   if you want to use the default USB see the [hello-usb](https://github.com/raspberrypi/pico-examples/tree/master/hello_world/usb) example.
170
1711. Setup a CMake build directory.
172      For example, if not using an IDE:
173      ```
174      $ mkdir build
175      $ cd build
176      $ cmake ..
177      ```
178
179   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=pico_w ..`
180   to configure the SDK and build options accordingly for that particular board.
181
182   Doing so sets up various compiler defines (e.g. default pin numbers for UART and other hardware) and in certain
183   cases also enables the use of additional libraries (e.g. wireless support when building for `PICO_BOARD=pico_w`) which cannot
184   be built without a board which provides the requisite functionality.
185
186   For a list of boards defined in the SDK itself, look in [this directory](src/boards/include/boards) which has a
187   header for each named board.
188
1891. Make your target from the build directory you created.
190      ```sh
191      $ make hello_world
192      ```
193
1941. 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 via drag and drop.
195