ESP32 Firmware Platform

Overview

This repo implements an ESP-IDF firmware platform for a fault-monitored sensor node on the Seeed Studio XIAO ESP32S3. It supports a FreeRTOS backend and a cooperative backend behind a shared application/HAL boundary.

The firmware samples an ADC input, classifies range faults, reports UART telemetry, handles button-driven recovery, services watchdog paths, and exposes the same portable app behavior through host-native tests and ESP-IDF builds.

Hardware Target

• Board: Seeed Studio XIAO ESP32S3
• Primary firmware stack: ESP-IDF v5.2.5
• Compatibility/test stack: PlatformIO native tests, Wokwi runtime check, and legacy Arduino-compatible firmware environments
• Sensor input: potentiometer-driven ADC input
• User I/O: button input, status LED output, USB serial telemetry

Architecture

main/app_main.cpp
  -> components/app_backends/
      -> components/app_core/
          -> components/app_core/include/platform_hal.h
              -> components/platform_esp32s3/

Layer	Location	Responsibility
ESP-IDF entry point	main/app_main.cpp	Selects one execution backend from Kconfig
Execution backends	components/app_backends/	Own scheduler policy, RTOS integration, queues, timers, and watchdog service points
Portable app core	components/app_core/	Owns sampling cadence, fault handling, telemetry emission, trace toggles, and HAL-driven behavior
Platform HAL contract	components/app_core/include/platform_hal.h	Defines the app-core boundary for ADC, UART, GPIO, button, time, trace, reset reason, and watchdog operations
ESP32S3 platform implementation	components/platform_esp32s3/	Implements the HAL using ESP-IDF facilities
Shared portable modules	src/*.c, include/*.h	Provide state machine, sensor math, telemetry formatting, and time helpers

The app-core boundary is enforced by scripts/check_app_core_includes.sh, which blocks Arduino, FreeRTOS, ESP-IDF driver, timer, watchdog, log, and error headers from the portable app-core paths.

hal_schema.yml is the source for the generated HAL header and API reference. The generator lives in tools/hal_codegen/, and CI verifies generated artifacts stay in sync with the schema.

Build

# RTOS backend
idf.py -B build-rtos -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.ci.rtos" set-target esp32s3 build

# Cooperative backend
idf.py -B build-cooperative -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.ci.cooperative" set-target esp32s3 build

# XIAO ESP32S3 PlatformIO build
platformio run -e seeed_xiao_esp32s3

ESP-IDF is the primary firmware path. PlatformIO remains for host-native Unity tests, the Wokwi runtime check, XIAO ESP32S3 PlatformIO builds, and legacy Arduino compatibility paths. See docs/toolchain.md.

Test

# Host-native behavioral tests
platformio test -e native

# App-core include boundary
scripts/check_app_core_includes.sh

# Wokwi runtime gate, requires WOKWI_CLI_TOKEN
scripts/wokwi_runtime_check.sh

# HAL schema/codegen checks
cargo test --manifest-path tools/hal_codegen/Cargo.toml
cargo build --release --manifest-path tools/hal_codegen/Cargo.toml

Current CI covers ESP-IDF backend builds, PlatformIO firmware build, native tests, Wokwi runtime telemetry validation, HAL code generation, and timing analysis. See docs/ci_evidence_map.md for the claim-to-validation map.

Runtime Behavior

The firmware reports CSV-like UART telemetry for sample state, ADC raw value, converted millivolts, and active fault code. The app core latches ADC range faults, clears recoverable faults through the button path, toggles trace points, and services watchdog bookkeeping through the platform HAL.

The RTOS backend uses FreeRTOS tasks, queues, timers, and watchdog service points. The cooperative backend runs the shared app behavior through explicit app_core_tick() calls without moving scheduler-specific headers into the app core.

Timing Evidence

Timing and runtime evidence is documented outside the README:

• docs/timing_model.md
• docs/timing_profile.md
• docs/runtime_profile.md
• docs/hardware_timing_trace.md
• docs/hardware_oscilloscope_trace.md

Those documents define how timing was measured or how future evidence should be collected. Exact measured values should be treated as bounded evidence tied to the committed artifacts they reference.

Repository Layout

hal_schema.yml                HAL interface definition for codegen
tools/hal_codegen/            Rust CLI that generates the C HAL header and API docs
tools/factory_test/           Serial factory test runner
components/app_core/          Portable app core and HAL contract
components/app_backends/      RTOS and cooperative execution backends
components/platform_esp32s3/  ESP-IDF platform HAL implementation
main/                         ESP-IDF application entry point
src/                          Portable C modules and legacy compatibility path
include/                      Shared public headers
test/                         Host-native Unity tests and fake HAL
docs/                         Architecture, validation, timing, and evidence notes
scripts/                      CI and local validation helpers
artifacts/                    Historical captures, timing samples, and debug artifacts
.github/workflows/            CI workflow definitions
platformio.ini                PlatformIO firmware, simulation, and native-test environments
CMakeLists.txt                ESP-IDF project definition

Key docs:

• docs/architecture.md
• docs/hal_api_reference.md
• docs/rtos_task_design.md
• docs/fault_injection_matrix.md
• docs/ci_evidence_map.md
• docs/evidence_map.md
• docs/toolchain.md
• docs/bare_metal_porting_notes.md

Evidence and Limitations

This project uses ESP-IDF on ESP32S3. It is not pure from-reset bare-metal firmware, not automotive-certified firmware, not a safety-critical system, and not production manufacturing validation. The repo is intended to demonstrate embedded architecture, RTOS/cooperative execution tradeoffs, HAL isolation, testing, and measured timing behavior on a constrained microcontroller platform.

Existing ESP32S3 bring-up logs and captures are retained as bounded historical evidence. They do not prove physical ADC accuracy, electrical safety, sensor calibration, board-level correctness, field reliability, or product qualification.

For a restrained job-alignment note, see docs/tesla_firmware_platforms_alignment.md.