Project 9: ESP32-S3 + Cardputer Board Reverse-Engineering Lab

Build a board-validation lab that verifies Cardputer pin mapping, memory behavior, signal timing, and electrical limits with repeatable measurements.

Quick Reference

Attribute Value
Difficulty Expert
Time Estimate 2-3 weeks
Main Programming Language C (ESP-IDF)
Alternative Programming Languages C++, Rust
Coolness Level Level 4
Business Potential Level 3
Prerequisites ESP-IDF workflow, basic electronics, logic analyzer basics
Key Topics ESP32-S3 memory map, DMA constraints, pin mux, power/thermal profiling

1. Learning Objectives

  1. Validate real board behavior against official pin maps and docs.
  2. Measure peripheral timing, jitter, and bus contention empirically.
  3. Build pass/fail diagnostics for electrical and firmware assumptions.
  4. Produce a reusable board bring-up checklist for future projects.

2. All Theory Needed (Per-Concept Breakdown)

2.1 ESP32-S3 Memory and Peripheral Reality

Fundamentals ESP32-S3 behavior is determined by memory region properties, DMA eligibility, cache interactions, and peripheral bus ownership. IRAM/DRAM/PSRAM are not equivalent, and timing-sensitive paths break when buffers are placed in the wrong region.

Deep Dive into the concept A board-level reverse-engineering workflow starts from immutable constraints: chip architecture, board routing, and power rails. You then validate each claim by direct measurement. For Cardputer, that means proving keyboard scan matrix behavior, TFT throughput, audio path quality, IR precision, and SD stability under concurrent workloads. The critical skill is distinguishing software bugs from physical limits. You need repeatable test vectors, deterministic logging, and thresholds that separate “acceptable variance” from real fault. Use isolated tests first (single bus, single peripheral), then mixed stress scenarios.

2.2 Signal Integrity and Practical Failure Modes

  • Debouncing must be treated as both electrical and software filtering.
  • SPI contention appears as frame tearing, delayed writes, and random stalls.
  • ADC noise floor depends on gain staging and board activity.
  • Thermal drift changes timing and analog quality over long runs.

3. Project Specification

3.1 What You Will Build

A diagnostics firmware and report pack with:

  • Pin map validator for keyboard, TFT, mic, speaker, IR, microSD, Grove.
  • Memory map and DMA-safe buffer report.
  • Current draw and thermal profile capture.
  • Signal timing validation for key peripherals.

3.2 Functional Requirements

  1. Detect and report all target peripherals with pass/fail status.
  2. Run timing tests and output jitter/latency summaries.
  3. Record current and temperature trends over stress intervals.
  4. Export deterministic markdown and CSV reports.

3.3 Non-Functional Requirements

  • Performance: diagnostics pass under 3 minutes.
  • Reliability: repeatable results across 5 consecutive runs.
  • Usability: clear failure signatures and next-step hints.

3.4 Example Usage / Output

$ idf.py flash monitor
I hwlab: board_scan start
I hwlab: keyboard matrix PASS
I hwlab: tft spi throughput PASS
I hwlab: audio floor -31.8 dBFS
I hwlab: ir jitter 2us max
I hwlab: current idle=92mA peak=318mA
I hwlab: thermal steady=48.2C
I hwlab: overall PASS

4. Solution Architecture

4.1 High-Level Design

[Boot] -> [Board Map Loader] -> [Peripheral Test Runner]
                               -> [Signal/Power Profiler]
                               -> [Report Generator]

4.2 Key Components

Component Responsibility Key Decision
Board Registry Source of truth for pins/buses Keep immutable constants in one file
Test Runner Executes deterministic diagnostics Isolate each peripheral first
Profiler Captures timing/power/thermal metrics Fixed sample windows
Reporter Produces markdown + CSV Include pass/fail thresholds

5. Implementation Guide

5.1 Development Environment Setup

  • ESP-IDF stable branch for ESP32-S3.
  • Serial monitor + logic analyzer capture setup.
  • Optional current probe for rail measurements.

5.2 The Core Question You’re Answering

“Can I prove the board behaves as documented, with measurable evidence?”

5.3 Concepts You Must Understand First

  1. DMA-capable memory placement and buffer ownership.
  2. Peripheral bus arbitration and timing side effects.
  3. Thermal and power profiling methodology.
  4. GPIO constraints and boot pin safety.

5.4 Questions to Guide Your Design

  1. What makes a test deterministic in embedded hardware?
  2. What threshold defines a timing failure vs variance?
  3. How do you make failure logs actionable?

6. Testing Strategy

  • Unit tests: parser and threshold logic.
  • Integration tests: each peripheral in isolation.
  • HIL tests: mixed-load stress with capture logs.
  • Soak test: 10-minute thermal/power run.

7. Common Pitfalls & Debugging

  • Misclassified failures due to missing baselines.
  • Hidden SPI contention during concurrent UI+SD updates.
  • False positives from unstable power source.

8. Extensions & Challenges

  • Add automated oscilloscope waveform snapshot comparison.
  • Add noise profile classifier for audio capture path.
  • Create board-revision compatibility matrix.

9. Self-Assessment Checklist

  • I can explain each board subsystem and its failure signature.
  • I can reproduce diagnostics results on demand.
  • I have a report that another engineer can review independently.

10. Completion Criteria

Minimum: all core peripherals validated with evidence. Full: includes timing, power, thermal, and error taxonomy. Excellence: supports board revision diff reports.