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:

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
NEEDS_CMD_HANDLER → if NEEDS_BLE_NUS=yes
OTA_TRIGGER       → ble / http / both

Record project-specific values:

• WiFi AP SSID for captive portal (e.g. "KB-Setup")
• BLE device name (e.g. "iOS-KB")
• OTA URL (e.g. "$TESTBENCH_URL/firmware/<project>/<project>.bin")
• NVS namespace
• Any project-specific command opcodes

Step 3: Audit firmware code

Inventory the project's source files. For each module in the template reference table, check:

• Does the file exist?
• Does it contain the required log patterns?
• Does it match the template's API signatures?

Also check:

• CMakeLists.txt — are all sources listed in SRCS? Are all PRIV_REQUIRES present?
• sdkconfig.defaults — are required options set?
• partitions.csv — does it have OTA slots (if NEEDS_OTA)?
• app_main.c — what's the init order? Is "Init complete" the last log?
• components/dns_server/ — does it exist (if NEEDS_WIFI)?

Step 4: Add missing modules (Enforce Contract 2)

Follow this decision tree. For each missing module, copy from test-firmware/main/ and customize. These templates implement the exact process flows required by the Testbench Compatibility Contract (Contract 2) — WiFi captive portal, BLE NUS command protocol, OTA via HTTP endpoint, and the canonical boot sequence:

Does the project use WiFi? --NO--> Skip WiFi, UDP, OTA
  |YES
  v
Has udp_log.c? --YES--> Check log message exists
  |NO --> Copy from test-firmware
  v
Has wifi_prov.c? --YES--> Check AP_SSID, check wifi_prov_reset()
  |NO --> Copy from test-firmware, customize AP_SSID
  v
Needs OTA? --NO--> Skip
  |YES
  v
Has ota.c? --YES--> Check OTA_DEFAULT_URL, check log messages
  |NO --> Copy from test-firmware, customize URL
         Ensure partitions.csv has OTA slots
  v
Uses BLE? --NO--> Skip BLE modules
  |YES
  v
Has ble_nus.c? --YES--> Check device name
  |NO --> Copy from test-firmware, customize name
  v
Has cmd_handler.c? --YES--> Check CMD_OTA + CMD_WIFI_RESET exist
  |NO --> Copy from test-firmware, add project-specific opcodes
  v
Has heartbeat task? --YES--> Check "alive" pattern
  |NO --> Add to app_main.c
  v
Has "Init complete"? --YES--> Done
  |NO --> Add to end of app_main()

When copying files:

• Read the template source from test-firmware
• Customize project-specific values (AP_SSID, BLE name, OTA URL, NVS namespace)
• Add or remove project-specific opcodes in cmd_handler
• Write the customized file to the project

Step 5: Enforce Contract 1 — Required Log Messages

Check every required log pattern from the Testbench Compatibility Contract (Contract 1) table. For each missing pattern:

• Add the exact log statement at the correct location
• Use the exact format string — the testbench skills grep for these patterns
• Do not paraphrase, reformat, or localize the strings
• These are infrastructure, not debug aids — they must survive any "clean up logging" refactors

Step 6: Update build config

Update the project's build configuration:

CMakeLists.txt — add new source files to SRCS, add any missing PRIV_REQUIRES:

• nvs_flash, esp_wifi, esp_netif, esp_event (WiFi)
• esp_http_server, esp_http_client, esp_https_ota (OTA)
• bt (BLE)
• dns_server, lwip (captive portal)
• esp_app_format, app_update (OTA + status endpoint)
• json (OTA HTTP endpoint)
• Add EMBED_FILES "portal.html" if wifi_prov uses captive portal

partitions.csv — copy from test-firmware/ (partitions-4mb.csv for 4MB flash, partitions.csv for 8MB+). See esp-idf-handling skill for flash size and partition table rules.

sdkconfig.defaults — verify required options are set (NimBLE, partition table, flash size, etc.). See esp-idf-handling skill for flash size defaults.

dns_server component — copy test-firmware/components/dns_server/ if project needs captive portal but doesn't have it

Step 7: Update app_main.c

Ensure the canonical init order:

1. NVS init (with erase-on-corrupt fallback)
2. Boot count increment
3. esp_netif_init() + esp_event_loop_create_default()
4. udp_log_init(CONFIG_TESTBENCH_IP, 5555) — a dotted-quad, not a name: ESP-IDF 6 does not bundle mDNS, so the DUT cannot resolve .local
5. Register IP event handler for HTTP server
6. wifi_prov_init()
7. ble_nus_init(cmd_handler_on_rx)
8. Heartbeat task (alive_task)
9. ESP_LOGI(TAG, "Init complete, running event-driven")

The exact implementation can vary, but the order must be: NVS → netif → UDP → WiFi → BLE → cmd handler → heartbeat → "Init complete".

Step 8: Write "7. Operational Procedures" (Testbench Operations)

Replace the Operational Procedures chapter (under Part E) with testbench-specific operational content covering: hardware setup, flashing, WiFi provisioning, BLE commands, OTA updates, HTTP endpoints, and log monitoring. This chapter becomes a standalone operations guide with no test cases.

Step 9: Write "8. Verification & Validation" (Testing)

Replace the Verification & Validation chapter (under Part E) with testbench test cases. Write phase verification tables where every FSD feature appears in exactly one table, test procedures reference the Operational Procedures chapter (not duplicate), and every step has concrete success criteria.

Step 10: Write "9. Troubleshooting Guide" and "10. Appendix"

Replace with testbench-specific diagnostics (logging strategy, failure-to-fix mapping table).

For detailed templates, markdown examples, and rules for Steps 8-10, read references/fsd-writing-guide.md.

Step 11: Build verification

cd <project-root> && idf.py build

Fix any compilation errors. Common issues:

• Missing PRIV_REQUIRES in CMakeLists.txt
• Missing #include directives
• Function signature mismatches between header and implementation

Step 12: Summary report

List what was added/changed:

• New files copied from test-firmware (with customizations noted)
• Modified files (what changed)
• Build result
• Any issues found and fixed

Completeness Checklist

After completing all steps, verify:

Firmware integration (Steps 1–7):

• Every module needed by the feature checklist exists
• Every required log pattern is present
• CMakeLists.txt has all sources and dependencies
• app_main.c follows the canonical init order
• "Init complete" is the last log message in app_main()

Operational Procedures chapter (Step 8):

• Hardware table documents all slots (including dual-USB if applicable)
• All project-specific values are filled in (no <placeholder> the AI must guess)
• WiFi provisioning includes all three values: portal_ssid, ssid, password
• WiFi provisioning documents both phases (ensure AP mode + provision via portal)
• BLE command reference table covers every opcode
• OTA workflow covers upload + both trigger methods (BLE and HTTP)
• HTTP endpoints documented with relay examples
• The chapter works as a standalone operations guide

Verification & Validation chapter (Step 9):

• Every FSD feature appears in a phase verification table
• Every implementation phase has a verification table
• Test procedures reference (not duplicate) the Operational Procedures chapter
• Every test step has concrete success criteria

Troubleshooting & Appendix (Step 10):

• Logging strategy explains when to use serial monitor vs UDP logs
• Troubleshooting covers likely failure modes

Build (Step 11):

• Project builds cleanly with idf.py build

Testbench Skills Reference

Every endpoint these skills drive is specified in FSD Appendix D.