README.md

# Raspberry Pi Pico

This repo shows how to use the Raspberry Pi Pico SDK.

## Init submodules 

You will need the **pico-sdk** to compile the code in this repo. Use the following command to clone it with all its submodules:

```bash
git submodule update --recursive --init pico-sdk
```

## Raspberry Pi Documentation

- [Raspberry Pi Pico C/C++ SDK][1]
- [Raspberry Pi Pico Quick Start][2]
- [Raspberry Pi Pico W (WiFi) Quick start][3]

## Projects

- [SHT30 sensor](sht30/README.md): Application that acquires Humidity and Temperature values from a SHT30 sensor.
- [Blinky](blinky/README.md): Application to blink a led
- [PWM](pwm/README.md): Application to generate a PWM signal.

### Build 

A utility script allows to build and deploy the projects. Usage:

```bash
Build Raspberry Pi Pico projects

Syntax: ./build.sh [-b|c|d|f|h|p] <args>
[ -b ]        Build project.
[ -c ]        Clean
[ -d ]        Launch debugger
[ -f ]        Flash board
[ -h ]        Help
[ -p PATH ]   Set project path
```

Example:

```bash
./build.sh -bf -p blinky/
```

Will build and flash the blinky application on the Raspberry Pi Pico.
If you want to manually build your project checkout this [chapter](#tools).

## Add new project

If you want to add a project you will need to create a new project folder containing the following basic files.

```
new_project
|
|---.config
|---CMakeLists.txt
|---pico_sdk_import.cmake
|---main.cpp
|---...
```

The *pico_sdk_import.cmake* just need to be copied to your project folder no modification required.

### Config file

This files contains two values:
- BOARD_TYPE: Defines the type of board to which the code will be compiled for.
- SRC_PATH: Relative path to the source code

Example:

```bash
BOARD_TYPE=grove_pico_w
SRC_PATH=src
```

A list of supported boards is available [here](pico-sdk/src/boards/include/). You can also define your own
like I did for the *SHT30* app. Checkout this [file](sht30/src/grove_pico_w.h)

### Cmakelists

Here is a basic example for the Pico without WiFi:

```bash
cmake_minimum_required(VERSION 3.13)

include(pico_sdk_import.cmake)

project(blinky C CXX ASM)

set(CMAKE_C_STANDARD 11)
set(CMAKE_CXX_STANDARD 17)

list(APPEND PICO_BOARD_HEADER_DIRS ${CMAKE_CURRENT_LIST_DIR})

pico_sdk_init()

file(GLOB SRC *.cpp)
add_executable(${PROJECT_NAME} ${SRC})

pico_enable_stdio_usb(${PROJECT_NAME} 0)
pico_enable_stdio_uart(${PROJECT_NAME} 1)

target_include_directories(${PROJECT_NAME} PRIVATE ${CMAKE_CURRENT_LIST_DIR})
target_link_libraries(${PROJECT_NAME} pico_stdlib)

pico_add_extra_outputs(${PROJECT_NAME})
```

## Tools

**This guide as been tested for Ubuntu 22.04**

### Toolchain

A docker image containing all the tools is available. You can build it with the following command.

```bash
docker build -t pico-dev .
```

Alternatively you can pull the image from GitLab.

TODO: push image to gitlab

To run the image you can use the run script:

```bash
./run
```

or 

```bash
docker run --rm -it --name pico-env -v $PWD:/mnt/ pico-dev
```

### Flash and debug

You can use the Raspberry Pi Debug probe to flash and debug applications. To use it you must first install OpenOCD.
Download and install the OpenOCD dependencies:

```bash
sudo apt install automake autoconf build-essential texinfo libtool libftdi-dev libusb-1.0-0-dev
```

Clone, build and install OpenOCD:

```bash
cd ~
git clone https://github.com/raspberrypi/openocd.git --branch rp2040-v0.12.0 --depth=1 --no-single-branch
cd openocd
./bootstrap
./configure
make -j4
sudo make install
```

Check OpenOCD version:

```bash
openocd --version
```

Output: 

```bash
Open On-Chip Debugger 0.12.0-g4d87f6d (2024-01-08-14:31)
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html

```

Create a file with any name (ex. pico_openocd.rules) under /etc/udev/rules.d and put this line inside.

```bash
ATTRS{idVendor}=="2e8a", ATTRS{idProduct}=="000c", MODE="660", GROUP="plugdev", TAG+="uaccess"
```

## Compile Pico W code

Run the docker container and navigate to the *sht30/pico_w* folder. Create a *build* folder and navigate to it:

```bash
mkdir build && cd build
```

Inside the *build* folder you will setup the **CMake** environnement.

```bash
cmake -DPICO_BOARD=grove_pico_w ..
```

This will initialize **CMake** and generate a Makefile. To build the project simply run:

```bash
make
```

Alternatively you can run the *build.sh* script from the top folder. 

1. Setup project folder and board type (run only once)

```bash
./build.sh -p sht30/pico_w/ -t grove_pico_w
```

2. Compile

```bash
./build.sh -b
```

## Deploy application on the Raspberry Pi Pico

### Flash using UF2 (USB Flashing Format)

You can flash the Pico via USB using the *.uf2* file.

1. Power up the Pico while pressing the **BOOTSEL** button
2. You Pico should show up as a drive.
3. Copy the *pico_w/build/sht30.uf2* onto the Pico.
    1. Linux:   
        ```bash
        cp pico_w/build/sht30.uf2 /media/$USER/RPI-RP2
        ```
    2. Windows: Drag and drop the file

### Flash using debug probe and OpenOCD

Run the build script with the *-f* option:

```bash
./build.sh -f
```

> :warning: This command must be performed on your host machine not in a running docker container


[1]:https://datasheets.raspberrypi.com/pico/raspberry-pi-pico-c-sdk.pdf?_gl=1*155jvvo*_ga*MTk5NjQ0ODQwNy4xNzAyNjI5NzEx*_ga_22FD70LWDS*MTcwNDI5MDg1OS4zLjEuMTcwNDI5MTA0Ny4wLjAuMA..
[2]:https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf?_gl=1*i8b34r*_ga*MTk5NjQ0ODQwNy4xNzAyNjI5NzEx*_ga_22FD70LWDS*MTcwNDI5MDg1OS4zLjEuMTcwNDI5MTEzNy4wLjAuMA..
[3]:https://datasheets.raspberrypi.com/picow/connecting-to-the-internet-with-pico-w.pdf?_gl=1*19f24rw*_ga*MTk5NjQ0ODQwNy4xNzAyNjI5NzEx*_ga_22FD70LWDS*MTcwNDI5MDg1OS4zLjEuMTcwNDI5MTA0OS4wLjAuMA..