# Add Pinscope to a Raspberry Pi Pico 2 W project

Pinscope gives the device's web server a secure address, sends printf output, metrics and HardFaults to the Pinscope dashboard, and updates the firmware with the RP2350's A/B partitions. You are adding it to an existing Pico SDK 2.x project for the Pico 2 W that uses FreeRTOS and lwIP. Full docs: https://pinscope.dev/docs/pico

## First, look at the project

- Find `CMakeLists.txt`, `lwipopts.h` and where WiFi connects (`cyw43_arch_wifi_connect_*`).
- Pinscope runs in a FreeRTOS task and uses lwIP sockets, so the project must use `pico_cyw43_arch_lwip_sys_freertos`. If it uses `NO_SYS=1` (no FreeRTOS), stop and tell the user: moving to FreeRTOS is a bigger change they should decide on.

## Steps

1. Get the library next to the project: `git clone https://github.com/pinscope-dev/pinscope-pico` (or as a git submodule).
2. In `CMakeLists.txt`, after `pico_sdk_init()`:
   ```cmake
   include(pinscope-pico/pinscope.cmake)
   target_link_libraries(app
       pinscope
       pico_cyw43_arch_lwip_sys_freertos
       FreeRTOS-Kernel-Heap4
       pico_stdlib)
   ```
   using the project's own target name instead of `app`, and keeping the libraries it already links.
3. In `lwipopts.h`, make sure these are set (the build stops with the setting to change if one is missing):
   ```c
   #define NO_SYS                  0
   #define LWIP_SOCKET             1
   #define LWIP_NETIF_LOOPBACK     1
   #define MEMP_NUM_NETCONN        12
   ```
4. The project key. The user copies it from the dashboard: their project, tab **Connect a device**. Put it in a header that is not committed, for example `secrets.h` added to `.gitignore`: `#define PINSCOPE_KEY "psk_..."`.
5. Once WiFi is connected, start it once; it reconnects by itself:
   ```c
   #include "pinscope.h"
   #include "secrets.h"
   ...
   pinscope_start(&(pinscope_config_t){
       .project_key = PINSCOPE_KEY,
       .firmware_version = "1.0.0",   // shown in the dashboard
   });
   ```
6. For updates, each board needs a partition table with two application partitions, loaded once: `picotool partition create partitions.json pt.uf2`, then `picotool load pt.uf2 && picotool reboot -u`, with a `partitions.json` like the one in `pinscope-pico/sample`. Tell the user this is a one-time step per board.

## Check

- The project builds and produces a `.uf2`.
- After flashing, the device appears in the dashboard under Devices.

## Rules

- Never invent a project key and never write the user's key into a file that is committed. Ask the user for it, and keep it where the steps below say. A key is `psk_` followed by 24 letters, digits, `-` or `_`, 28 characters in all; if the one you are given is not, ask again.
- Change as little as you can: add Pinscope, do not restructure the project, rename files or touch unrelated code.
- Do not add a TLS library, certificates or port forwarding. Pinscope makes one outbound connection to `connect.pinscope.dev` on TCP port 443 and encrypts it itself.
- Do not edit Pinscope's own source; configure it.
- When you are done, tell the user exactly what you changed and what they still have to do (enter the key, flash, upload the firmware for updates).