# Add Pinscope to an ESP8266 RTOS SDK project

Pinscope gives the device's web server a secure address, sends its logs, metrics and exceptions to the Pinscope dashboard, and updates its firmware from there. You are adding it to an existing ESP8266_RTOS_SDK 3.4 project. Full docs: https://pinscope.dev/docs/esp8266

## First, look at the project

- Find `app_main()` and where networking starts: `tcpip_adapter_init()` and `esp_event_loop_create_default()`, then WiFi.

## Steps

1. Get the component from https://github.com/pinscope-dev/pinscope-esp8266 and put its `pinscope` folder in the project's `components/` folder (or point `EXTRA_COMPONENT_DIRS` at it).
2. The project key. The user copies it from the dashboard: their project, tab **Connect a device**, and enters it with `idf.py menuconfig` → Pinscope (it goes into `sdkconfig`). If `sdkconfig` is committed in this repository, tell the user the key would be committed with it, and suggest adding `sdkconfig` to `.gitignore`. Do not put the key in a committed `sdkconfig.defaults`.
3. Start it once, after `tcpip_adapter_init()` and `esp_event_loop_create_default()`; it does not need WiFi to be connected yet:
   ```c
   #include "pinscope.h"
   ...
   pinscope_start(NULL);
   ```
4. If the HTTP server is not on port 80, set `CONFIG_PINSCOPE_LOCAL_PORT`.
5. Updates need two OTA slots (menuconfig → Partition Table → Factory app, two OTA definitions, 4 MB of flash). Tell the user plainly: the SDK has no rollback, so a new image that cannot connect stays until it is flashed again by cable; try each build on a device at hand first.

## Check

- `idf.py build` (or `make`) succeeds; after flashing, the device appears in the dashboard.

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