firmware: ESP8266 port — cross-compile clean, ~$2 MCU now reachable

ESP8266 has been EOL'd by Espressif in favour of the C3, but it's
still the dominant chip in the cheap-and-cheerful hobbyist stratum
(NodeMCU / Wemos D1 Mini boards routinely <$2 in bulk). Getting DCP
to run there is two changes:

1. Sketch-level PWM API. The reference lamp example used
   Arduino-ESP32 core 3.x v3 LEDC API (ledcAttach / ledcWrite),
   which doesn't exist on ESP8266. Replaced direct calls with thin
   lamp_pwm_setup() / lamp_pwm_write() inline helpers that pick
   the right backend at compile time (LEDC on ESP32, analogWrite
   with analogWriteFreq / analogWriteRange on ESP8266, digital
   fallback elsewhere). Zero protocol-layer impact.

2. library.properties: architectures=esp32,esp8266,*. The DCPBle.cpp
   was already guarded with #if __has_include(<NimBLEDevice.h>),
   so the BLE side compiles to nothing on ESP8266 (which has no
   BLE radio anyway).

Build matrix after this commit:

    ESP32-WROOM-32    Xtensa LX6              295 KB / 22.7 KB
    ESP32-C3          RV32IMC                 289 KB / 13.4 KB
    ESP32-C6          RV32IMAC + HW-crypto    266 KB / 14.0 KB
    ESP32-H2          RV32IMAC + 802.15.4     292 KB / 14.0 KB
    ESP32-P4          RV32IMAFC dual-core     326 KB / 22.0 KB
    ESP8266 NodeMCU   Xtensa LX106 (legacy)   242 KB / 28.9 KB   ← new

ESP8266 fit: 23% of flash, 36% of RAM, 93% of IRAM. Tight on IRAM
(legitimate concern on this MCU) but well within budget.

Helper-function refactor cost on ESP32: +88 bytes flash. No global
RAM change. So adding ESP8266 support did not regress the ESP32
target in any measurable way.

Side-effects:
- docs/paper/main.tex §validation paragraph generalised from "ESP32
  RISC-V family" to "ESP family" with ESP8266 row added
- README cross-compile table extended with the ESP8266 row and a
  reproduce command
- Roadmap bullet updated

Runtime UART validation on the ESP8266 itself is still TODO (need a
NodeMCU on the bench). Build artefacts are produced and verified by
arduino-cli.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: WaylandYang

README.md

@@ -90,12 +90,12 @@ measured / typical of the cited sources.*
 See [docs/RATIONALE.md §7](docs/RATIONALE.md) for what the hardware
 validation does and does not prove.
 
-### Cross-compile clean on the ESP32 RISC-V family
+### Cross-compile clean across the ESP family (Xtensa + RISC-V + ESP8266)
 
 The reference firmware is portable by design (Arduino `Stream` + a
-software SHA-256, no Xtensa-specific code paths). It cross-compiles
-unchanged for every RISC-V ESP32 variant, with end-to-end UART
-validation pending boards on the bench:
+software SHA-256, no SoC-specific code paths in `DCP.{h,cpp}`). It
+cross-compiles for every current ESP32 variant *and* for ESP8266,
+with end-to-end UART validation pending boards on the bench:
 
 | Target            | ISA                   | Flash (lamp+blink) | Globals  | Status        |
 |-------------------|-----------------------|--------------------|----------|---------------|
@@ -104,13 +104,19 @@ validation pending boards on the bench:
 | ESP32-C6          | RV32IMAC + HW-crypto  | 266 KB             | 14.0 KB  | builds ✓      |
 | ESP32-H2          | RV32IMAC + 802.15.4   | 292 KB             | 14.0 KB  | builds ✓      |
 | ESP32-P4          | RV32IMAFC dual-core   | 326 KB             | 22.0 KB  | builds ✓      |
+| ESP8266 NodeMCU   | Xtensa LX106 (legacy) | 242 KB             | 28.9 KB  | builds ✓      |
 
-All builds use Arduino-ESP32 core 3.3.8 + the same
-`firmware/esp32/` library, zero conditionals. Reproduce with:
+All builds use Arduino-ESP32 core 3.3.8 / Arduino-ESP8266 core 3.x
++ the same `firmware/esp32/` library. The sketch picks PWM API at
+compile time (`ledcAttach`/`ledcWrite` on ESP32, `analogWrite` on
+ESP8266); the protocol layer itself has no `#ifdef`. Reproduce
+with:
 
 ```bash
 arduino-cli compile --clean --fqbn esp32:esp32:esp32c3 \
     --library firmware/esp32 firmware/esp32/examples/lamp
+arduino-cli compile --clean --fqbn esp8266:esp8266:nodemcuv2 \
+    --library firmware/esp32 firmware/esp32/examples/lamp
 ```
 
 ## Manifest
@@ -288,7 +294,7 @@ MIT.
 - [x] Codegen `--stubs`: emits handler signatures + binding table
 - [x] Quickstart video script ([docs/QUICKSTART_VIDEO.md](docs/QUICKSTART_VIDEO.md))
 - [x] Real-hardware UART validation (ESP32-WROOM-32, 13/13 round-trips)
-- [x] Cross-compile clean on ESP32 RISC-V family (C3, C6, H2, P4)
+- [x] Cross-compile clean on ESP32 RISC-V family (C3, C6, H2, P4) and ESP8266
 - [x] Public repo at `device-context-protocol/dcp` (v0.3.0 released)
 - [x] PyPI release (`pip install pydcp`)
 - [ ] T-Panel S3 + CAN bus demo (firmware ready, awaiting hardware)

docs/paper/main.tex

@@ -468,15 +468,19 @@ \subsection{ESP32 reference firmware}
 the firmware-side CBOR float decode path. All thirteen cases pass against
 real hardware.
 
-\paragraph{Portability across the ESP32 RISC-V family.} The same
-\texttt{firmware/esp32/} library compiles unchanged for every RISC-V
-variant of the ESP32 family --- C3 (RV32IMC, 289\,KB / 13.4\,KB), C6
+\paragraph{Portability across the ESP family.} The same
+\texttt{firmware/esp32/} library compiles unchanged across the
+current ESP32 family --- C3 (RV32IMC, 289\,KB / 13.4\,KB), C6
 (RV32IMAC, 266\,KB / 14.0\,KB), H2 (RV32IMAC + 802.15.4, 292\,KB /
-14.0\,KB), and P4 (RV32IMAFC dual-core, 326\,KB / 22.0\,KB) ---
-demonstrating that the design's portability claim holds beyond the
-single Xtensa target on which it was measured. End-to-end UART
-validation on these targets is pending bench availability, but the
-build artefacts are byte-identical in structure.
+14.0\,KB), and P4 (RV32IMAFC dual-core, 326\,KB / 22.0\,KB) --- and
+additionally on the legacy ESP8266 NodeMCU (Xtensa LX106, 242\,KB /
+28.9\,KB), where the lamp example sketch picks the PWM API at
+compile time (\texttt{ledcAttach}/\texttt{ledcWrite} on ESP32,
+\texttt{analogWrite} on ESP8266) while the protocol layer itself
+remains \texttt{\#ifdef}-free. End-to-end UART validation on these
+non-Xtensa-LX6 targets is pending bench availability, but the build
+artefacts confirm the portability claim beyond the single target on
+which the runtime was measured.
 
 \subsection{Conformance suite}
 

firmware/esp32/examples/lamp/lamp.ino

@@ -5,19 +5,45 @@
 //     dcp serve examples/lamp_manifest.yaml --serial COM3   (Windows)
 //     dcp serve examples/lamp_manifest.yaml --serial /dev/ttyUSB0   (Linux)
 //
-// Hardware: any ESP32 dev board. The built-in LED is on GPIO 2 on most
-// WROOM-32 dev kits (DOIT, NodeMCU-32, etc.). If your board has it on a
-// different pin, change LED_PIN below.
+// Hardware: any ESP32 dev board or ESP8266 (NodeMCU / Wemos D1). The
+// built-in LED is on GPIO 2 on most WROOM-32 dev kits. On ESP8266 the
+// onboard LED is usually GPIO 2 as well but ACTIVE-LOW — flip the duty
+// inversion below if your board has a different scheme.
 //
-// Requires Arduino-ESP32 core 3.0 or newer (uses the v3 LEDC API). For
-// core 2.x replace the ledcAttach/ledcWrite calls with the old
-// ledcSetup + ledcAttachPin + ledcWrite(channel, duty) sequence.
+// PWM API:
+//   ESP32:   Arduino-ESP32 core 3.x v3 LEDC API (ledcAttach / ledcWrite)
+//   ESP8266: stock analogWrite() (range remapped to 0..255 to match)
+//
+// All other DCP code paths are platform-independent.
 
 #include "DCP.h"
 
 constexpr int LED_PIN     = 2;       // built-in LED on most WROOM-32 dev boards
 constexpr int PWM_FREQ_HZ = 5000;
 constexpr int PWM_BITS    = 8;
+constexpr int PWM_MAX     = (1 << PWM_BITS) - 1;     // 255
+
+static inline void lamp_pwm_setup() {
+#if defined(ESP32)
+    ledcAttach(LED_PIN, PWM_FREQ_HZ, PWM_BITS);      // core 3.x v3 API
+#elif defined(ESP8266)
+    analogWriteFreq(PWM_FREQ_HZ);
+    analogWriteRange(PWM_MAX);
+    pinMode(LED_PIN, OUTPUT);
+#else
+    pinMode(LED_PIN, OUTPUT);                        // fallback: digital only
+#endif
+}
+
+static inline void lamp_pwm_write(uint32_t duty) {
+#if defined(ESP32)
+    ledcWrite(LED_PIN, duty);
+#elif defined(ESP8266)
+    analogWrite(LED_PIN, duty);
+#else
+    digitalWrite(LED_PIN, duty > (PWM_MAX / 2) ? HIGH : LOW);
+#endif
+}
 
 static float g_brightness = 0.0f;
 static uint8_t g_r = 255, g_g = 255, g_b = 255;   // current target RGB (no real LED bound)
@@ -47,7 +73,7 @@ static dcp::Status handle_set_brightness(uint8_t kind,
 
     g_brightness = (float)level;
     uint32_t duty = (uint32_t)(g_brightness * 2.55f);
-    ledcWrite(LED_PIN, duty);     // v3 API: pin, not channel
+    lamp_pwm_write(duty);
     return dcp::STATUS_OK;
 }
 
@@ -86,9 +112,9 @@ static dcp::Status handle_set_color(uint8_t kind,
     // The default WROOM-32 dev board has no RGB LED. We acknowledge by giving
     // a visible 80ms flash on the built-in brightness LED, then restoring it.
     uint32_t saved = (uint32_t)(g_brightness * 2.55f);
-    ledcWrite(LED_PIN, 255); delay(80);
-    ledcWrite(LED_PIN, 0);   delay(80);
-    ledcWrite(LED_PIN, saved);
+    lamp_pwm_write(255); delay(80);
+    lamp_pwm_write(0);   delay(80);
+    lamp_pwm_write(saved);
     return dcp::STATUS_OK;
 }
 
@@ -123,10 +149,10 @@ static dcp::Status handle_blink(uint8_t kind,
     // Save current brightness so we can restore it after the blink.
     uint32_t saved = (uint32_t)(g_brightness * 2.55f);
     for (int64_t i = 0; i < times; ++i) {
-        ledcWrite(LED_PIN, 255);        delay(period);
-        ledcWrite(LED_PIN, 0);          delay(period);
+        lamp_pwm_write(255);        delay(period);
+        lamp_pwm_write(0);          delay(period);
     }
-    ledcWrite(LED_PIN, saved);
+    lamp_pwm_write(saved);
     return dcp::STATUS_OK;
 }
 
@@ -144,7 +170,7 @@ static dcp::DCP* dcp_instance = nullptr;
 void setup() {
     Serial.begin(115200);
 
-    ledcAttach(LED_PIN, PWM_FREQ_HZ, PWM_BITS);   // v3 API: pin + freq + resolution
+    lamp_pwm_setup();
 
     static dcp::DCP instance(Serial, bindings, sizeof(bindings) / sizeof(bindings[0]));
     dcp_instance = &instance;

firmware/esp32/library.properties

@@ -6,6 +6,6 @@ sentence=Device Context Protocol: bridge LLM agents to physical devices.
 paragraph=Reference firmware for the DCP wire protocol. Parses COBS-framed CRC-checked DCP frames over Serial OR BLE GATT (with NimBLE-Arduino), decodes a tiny CBOR subset, dispatches to user-registered intent handlers, and optionally verifies per-frame HMAC-SHA256 signatures.
 category=Communication
 url=https://github.com/device-context-protocol
-architectures=esp32,*
+architectures=esp32,esp8266,*
 depends=NimBLE-Arduino
 includes=DCP.h