/testbench-integration

name: testbench-integration
description: >
  Integrates an ESP32 project with the Universal ESP32 Testbench. Adds firmware
  modules (UDP logging, WiFi provisioning, OTA, BLE command handling, strategic
  log messages), updates build config, then writes the Testbench operations,
  Testing, and Appendix chapters into the project's existing FSD.
  Triggers on "integrate testbench", "add testbench", "testbench integration",
  "set up project", "add testing", "add tester".

ESP32 Testbench Integration

This is a procedure. When triggered, read the project's existing FSD, integrate the firmware with the testbench infrastructure — each module **only when the FSD requires it** (UDP logging always; OTA, BLE command handling, provisioning per scope; strategic log messages always), then write the operational, testing, and appendix chapters into the FSD.

**Prerequisite:** The project must already have an FSD with at least a System Overview and Functional Requirements section. Use the `define` skill first to generate one from a rough description if needed.

The testbench provides the **test infrastructure**. This skill adds both the **firmware integration** (modules the testbench needs to interact with the device) and the **FSD documentation** (operational guide, test plan, troubleshooting).

FSD Document Structure

This skill operates on FSDs produced by the `define` skill, which uses the **layer-grouped "Parts" scheme** (see `define/references/canonical-fsd-structure.md`). Chapter *numbers* are dynamic, so **locate chapters by role/title, not by a fixed number**:

# <Project Name> — FSD
## System Overview              ← front matter, read-only
## System Architecture (§2.4 Component Layering) ← front matter, read-only
## Implementation Phases        ← front matter, read-only
## Risks, Assumptions & Dependencies ← front matter, read-only
# Part A — Application Logic (L2)   ← one chapter per feature; read-only
# Part B — Interfaces (L1)          ← one chapter per interface; read-only
# Part C — Foundation / Transport (L0)
# Part D — Cross-cutting Concerns
# Part E — Operations & Verification
##   Operational Procedures      ← REPLACED by this skill (testbench operations)
##   Verification & Validation   ← REPLACED by this skill (testbench test cases)
## Appendices                    ← testbench logging strategy + constants appended

There is **no global Functional Requirements or Interface Specifications section** — requirements live in each component chapter, and each interface is its own L1 chapter under Part B. This skill **reads** the front matter and component chapters (to extract features, phases, interfaces, constants) without modifying them, and **replaces** the Operational Procedures and Verification & Validation chapters under Part E (and appends to Appendices).

Steps 1–7 handle firmware integration. Steps 8–12 write the Operations / V&V / Appendix chapters.

Template Reference

All template code lives in `Embedded-AI-Harness/test-firmware/`. When adding modules, copy from these templates and customize project-specific values:

| Module | Template source | Customization | |--------|----------------|---------------| | `udp_log.c/.h` | `test-firmware/main/udp_log.c` | None (universal) | | `wifi_prov.c/.h` | `test-firmware/main/wifi_prov.c` | Change `AP_SSID`. | | `portal.html` | `test-firmware/main/portal.html` | Change `<title>` and `<h1>` | | `ota_update.c/.h` | `test-firmware/main/ota_update.c` | Change `OTA_DEFAULT_URL` | | `ble_nus.c/.h` | `test-firmware/main/ble_nus.c` | Change BLE device name | | `http_server.c/.h` | `test-firmware/main/http_server.c` | Add project-specific endpoints | | `nvs_store.c/.h` | `test-firmware/main/nvs_store.c` | Change `NVS_NAMESPACE` | | `dns_server/` | `test-firmware/components/dns_server/` | None (copy entire dir) | | `partitions.csv` | `test-firmware/partitions.csv` | None (dual OTA layout) | | `sdkconfig.defaults` | `test-firmware/sdkconfig.defaults` | Reference for required options | | `app_main.c` | `test-firmware/main/app_main.c` | Reference for init order only |

Testbench Compatibility Contract

The testbench actively drives the device through BLE commands, HTTP relay, captive portal automation, and serial/UDP log parsing. The firmware must conform to two contracts:

• **Contract 1: Required Log Messages** -- 17 exact format strings the testbench greps for (e.g. `"Init complete"`, `"STA got IP"`, `"OTA succeeded"`). Missing or reformatted strings break testbench detection.
• **Contract 2: Process Flows** -- only the flows the FSD puts in scope: WiFi provisioning (SoftAP captive portal), OTA (HTTP `/ota` endpoint), BLE commands and BLE-triggered WiFi reset (NimBLE NUS) **only when the product uses BLE**, and the canonical boot sequence (always). A flow the spec never asked for is silent pack adoption.

For the complete log pattern table, process flow sequences, and compatibility validation rules, read `references/compatibility-contract.md`.

Procedure

Step 1: Identify project

Find the project's FSD path and firmware root directory. Confirm:

• What chip is being used (ESP32, ESP32-S3, etc.)
• Where the firmware source lives (e.g. `main/` directory)
• The project name

Step 2: Parse FSD — extract features and build checklist

Read the entire FSD (produced by the `define` skill). Extract features from the **component chapters** (each chapter states the FR/NFR it owns — there is no global requirements section), phases from the **Implementation Phases** chapter, interfaces from the **Part B (L1 Interfaces)** chapters, and architecture details from **System Architecture (§2.4 Component Layering)**.

Build a feature checklist:

NEEDS_WIFI        → if project uses WiFi
NEEDS_BLE         → if project uses BLE
NEEDS_BLE_NUS     → if project uses Nordic UART Service
NEEDS_OTA         → if project supports firmware updates
NEEDS_MQTT        → if project uses MQTT
NEEDS_UDP_LOG     → always yes when NEEDS_WIFI=yes
N