Pinscope on the ESP8266

Remote access, logs, metrics and firmware updates for the ESP8266 with the ESP8266 RTOS SDK: a component, a key in menuconfig, one call.

With an AI assistant. Copy the instructions and paste them into Claude, Cursor, Copilot or ChatGPT in your project: it adds Pinscope the way this page says, and asks you for the project key instead of writing it into your code. Or give it the link: esp8266.md.

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

This page is for ESP8266_RTOS_SDK 3.4. The Arduino core for the ESP8266 is not supported yet.

Try the sample first

With the ESP8266_RTOS_SDK 3.4 set up:

git clone https://github.com/pinscope-dev/pinscope-esp8266 && cd pinscope-esp8266
export IDF_PATH=~/esp/ESP8266_RTOS_SDK
PINSCOPE_KEY=psk_... WIFI_SSID=... WIFI_PASSWORD=... idf.py build flash monitor

1. Connect

Add the component

Get it from https://github.com/pinscope-dev/pinscope-esp8266 and put the pinscope folder in your project's components/ folder, or point EXTRA_COMPONENT_DIRS at it.

Enter your project key

In the dashboard, open your project and the tab Connect a device and copy the project key. Enter it in idf.py menuconfig under Pinscope.

Start it

#include "pinscope.h"

void app_main(void)
{
    /* your WiFi and web server setup */

    pinscope_start(NULL);
}

Call it once, after tcpip_adapter_init() and esp_event_loop_create_default(). It does not need WiFi to be connected yet and reconnects by itself. The device needs to reach connect.pinscope.dev on TCP port 443, outbound only.

2. Reach the device

Whatever listens on port 80 of the device is served at its own HTTPS address, as on ESP32. See Reach the device.

3. Logs and metrics

Pinscope's own lines reach the Logs tab, and anything you send with pinscope_log(). ESP_LOG output stays on the serial port.

Metric	Meaning
`heap_free`, `heap_min`	Free heap now, and the lowest it has been
`stack/pinscope`	Stack the Pinscope task has never used
`rssi`, `uptime_s`	WiFi signal, and time since boot

pinscope_metric("water_level_cm", 42.5);

4. Crashes

The SDK keeps no backtrace across a reset, so the dashboard shows that the device restarted after a crash (reset reason panic, or a watchdog), not where it crashed.

5. Firmware updates

The partition table needs two OTA slots: in menuconfig, Partition Table → Factory app, two OTA definitions (4 MB of flash). Upload build/<project>.bin under Firmware and press Update firmware on the device. The image is written to the spare slot and booted. The SDK has no rollback: a new image that cannot connect stays on the device until it is flashed again by cable, so try each build on a device at hand first.

Memory

About 7 KB of RAM: 4.2 KB of buffers, queue and state, and a 3 KB task stack. No TLS library, which on the ESP8266 would take a large share of the free heap.

If it does not work

What you see	What to check
`the project key is missing`	Enter the key in `idf.py menuconfig` under Pinscope
No `online at` line, no error	WiFi is not connected yet, or the network does not let the device reach `connect.pinscope.dev` on TCP port 443
There is no Update firmware button	The partition table has no second OTA slot