# Add Pinscope to a Zephyr application

Pinscope gives the device's web server a secure address, sends LOG_* output, metrics and fatal errors to the Pinscope dashboard, and updates the firmware through MCUboot. You are adding it to an existing Zephyr 4.x application on a board with a network (WiFi, Ethernet or cellular). Full docs: https://pinscope.dev/docs/zephyr

## First, look at the project

- Find the west manifest (`west.yml`) and the application's `prj.conf`.
- Note how the network comes up (WiFi connect code, Ethernet, DHCP or a static address) and whether the app serves HTTP, and on which port.
- Note whether it builds with sysbuild and MCUboot.

## Steps

1. Add the module to `west.yml`, under `projects`, then run `west update`:
   ```yaml
   - name: pinscope
     url: https://github.com/pinscope-dev/pinscope-zephyr
     revision: v0.2.5
     path: modules/lib/pinscope
   ```
2. Switch it on in `prj.conf`:
   ```
   CONFIG_PINSCOPE=y
   ```
3. The project key. The user copies it from the dashboard: their project, tab **Connect a device**. It goes into `CONFIG_PINSCOPE_PROJECT_KEY`. Keep it out of the committed `prj.conf`: put it in a local file that is not committed, for example `key.conf` next to `prj.conf` with `CONFIG_PINSCOPE_PROJECT_KEY="psk_..."`, add `key.conf` to `.gitignore`, and build with `-- -D<app>_EXTRA_CONF_FILE=key.conf` under sysbuild, where `<app>` is the application folder's name (`-- -DEXTRA_CONF_FILE=key.conf` without sysbuild).
4. No code is needed: Pinscope starts by itself once the system is up, switches on what it uses (IPv4, TCP, sockets, DNS, DHCP, settings, the random generator) and starts DHCP if the interface has no address. The application keeps bringing the network up as it does now.
5. If the app's HTTP server is not on port 80, set `CONFIG_PINSCOPE_LOCAL_PORT`.
6. Settings: Pinscope keeps the device's credential in Zephyr settings, on the flash partition labelled `storage_partition`. Some boards (the ST Nucleo boards among them) define none, and the build then stops with a message that shows the overlay to add: put it in `boards/<board>.overlay`, in free flash that no image slot or MCUboot uses. For the NUCLEO-F429ZI with MCUboot that is `partition@8000`, 32 KB.
7. Firmware updates use MCUboot. If the app does not use it yet, add to `sysbuild.conf`:
   ```
   SB_CONFIG_BOOTLOADER_MCUBOOT=y
   SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y
   ```
   and build with `--sysbuild`. ECDSA P-256 keeps MCUboot small enough for the 32 KB many boards give it (with the default RSA it overflows on the Nucleo boards). The board needs `boot_partition`, `slot0_partition` and `slot1_partition`. Tell the user to sign with their own key in production (`SB_CONFIG_BOOT_SIGNATURE_KEY_FILE`): the default key is public.
8. The network: Pinscope starts DHCP only when the interface has no address, and leaves a fixed address alone. If the app sets one (`CONFIG_NET_CONFIG_MY_IPV4_ADDR`), check it is real: the addresses in Zephyr's samples (192.0.2.x, 10.0.0.x without a gateway) cannot reach the internet, and the device would never connect. Ask the user whether to switch to DHCP (remove the fixed address settings) or give a real address, netmask and gateway (`CONFIG_NET_CONFIG_MY_IPV4_GW`).
9. RP2040 boards (Pico W, W55RP20) have no random generator Zephyr knows: build with `-S pinscope-rp2040`. Elsewhere Pinscope's keys come from the board's hardware generator; a sample's `CONFIG_TEST_RANDOM_GENERATOR` affects only Zephyr's non-cryptographic random numbers, but tell the user it is not meant for products.

10. Optional, for the EU Cyber Resilience Act: if the user wants vulnerability tracking, an SBOM of each build comes from `west spdx --init -d build` before the build, building with `-DCONFIG_BUILD_OUTPUT_META=y`, then `west spdx -d build` (writes `build/spdx/*.spdx`); the user attaches it to the uploaded firmware in the dashboard's Security tab, or from CI with `ci.sh ... --sbom`. Do not add it to the build unasked.

## Check

- `west build -b <board> --sysbuild` succeeds.
- After flashing, the log shows `pinscope: online at https://...` and the device appears in the dashboard. For updates the user uploads `build/<app>/zephyr/zephyr.signed.bin`, and `zephyr.elf` for decoded fatal errors.

## 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).