PROJECT MEMORY — esp32_sensor_module / pcb-designer-ai-agent

Auto-generated by opencode agent. Append on each change. Never delete — only append or replace Current State.

Project Overview

Carputer subsystem: an ESP32-WROOM-32 PCB that taps Toyota 5S-FE ECU signals (sensors + DTC diagnostics) and drives body relays (door locks, windows, HVAC, etc.) via 2× ULN2003A. Also houses a Python-based "PCB Designer AI Agent" (pcbai) for automated KiCad footprint generation.

File Manifest

File	Lines	Purpose
`src/main.cpp`	570	ESP32 firmware: sensor reads, UDP comms, DTC state machine
`build_plan.md`	139	Active PCB build plan: THT axial, DevKit V1, 160×120mm
`PCB_PLAN.md`	373	Superseded — original SMD-based PCB design doc
`voltage_divider_circuit.txt`	202	Circuit description: dividers, senders, doors, DTC, test proc
`5SFE_ECU_Pinout.txt`	131	Toyota 5S-FE ECU connector pinout + signal mapping
`ESP32_Pinout.txt`	182	ESP32 DevKit pin reference + sensor/body module assignments
`esp32_sensor_module_build_notes.md`	121	Build instructions, WROOM-32 module pinout
`esp32_sensor_module_bom.csv`	41	Bill of materials (41 line-items, SMD — superseded by build_plan.md)
`pyproject.toml`	43	Python package config for `pcbai` CLI
`carputermodule.kicad_pcb`	2387	KiCad PCB layout (7 THT footprints, REF** unassigned, clean backup restored)
`carputermodule.kicad_pro`	—	KiCad project file
`carputermodule.kicad_prl`	—	KiCad project local settings
`generate_pcb.py`	295	Deprecated — string-concatenation approach, fragile. Don't re-run.
`_extract_originals.py`	—	One-time script to restore clean file from corrupted backup
`_dedup_pcb.py`	—	Abandoned dedup attempts (superseded by backup restore)
`carputermodule.kicad_pcb.corrupted`	—	Corrupted backup (kept for reference)
`carputermodule.kicad_pcb.bak`	—	Recent backup
`tests/test_footprint_generator.py`	23	Tests for SMD R/C + SOIC footprint generators
`tests/test_qfn_qfp.py`	13	Tests for QFN + QFP footprint generators
`PROJECT_MEMORY.md`	—	This file — project state + decision log
`.opencode/agents/esp32-sensor-module.md`	—	opencode agent definition

Current State

✅ Working / Complete

Firmware (src/main.cpp): Fully implemented and compiles via PlatformIO.
- Analog sensor reads (MAP, coolant, throttle, fuel, oil)
- Digital pulse counting (speed via SPD, RPM via IGf)
- Door/GND-switch reads (driver, passenger, trunk, hood)
- 8-sample moving average smoothing
- DTC state machine (IDLE → WAIT_START → READ_BLINK → SEND_RESULT → CLEANUP)
- UDP packet send/receive (JSON)
- WiFi STA with reconnect logic
- Brown-out detector disabled
Circuit design (electrical): All 6 voltage dividers, 2 sender pullups, 4 door inputs, DTC transistor base resistors, power supply — unchanged, applicable to both PCB versions
build_plan.md: Active PCB build plan documented — THT axial resistors, DevKit V1 ESP32s, WAGO connectors, external DC-DC module, 160×120mm board

🏗️ In Progress — KiCad PCB (`carputermodule.kicad_pcb`)

7 footprints placed (per build_plan.md coordinates):
- U2 + U3 (ULN2003A DIL16), 3× WAGO 8-way, J5 + J6 (DevKit V1)
Not yet placed: resistors, caps, fuse, J4/J8/DC_IN/DC_OUT, mounting holes, board outline
No nets assigned yet (only net 0), no traces, no copper pour
File is being used for the THT build plan (not the old SMD design)
⚠️ File was corrupted by iterative script runs, restored from backup — clean 2387-line base with 7 REF** footprints ready for one-shot generation

📚 Lessons Learned — KiCad s-expression Generation

ALWAYS parse then manipulate then serialize — never generate .kicad_pcb files via string concatenation. Use sexp_parser.py from kicad-happy (/home/devkid/Downloads/kicad-happy-main/skills/kicad/scripts/sexp_parser.py) to build a parse tree, edit it, then write a serializer.
ALL strings must be quoted in canonical KiCad output — "F.Cu", "U2", "*.Cu", "through_hole". Unquoted atoms are parser-dependent and should never be written.
One-shot write() over iterative script — appending to the file corrupts it on re-runs. Write the complete file in one call.
Idempotency via sentinel — if a script must modify an existing file, check for a sentinel string to detect prior runs and skip changes.

🚧 Scaffolded / Not Yet Implemented

pcbai Python package: pyproject.toml exists, tests exist, but src/pcbai/ source directory does not exist.
- Missing: src/pcbai/__init__.py, core/config.py, core/logger.py, llm/provider.py, steps/footprint_generator.py, steps/footprint_qfn_qfp.py, pipeline/cli.py, etc.
- Tests import from pcbai.steps.footprint_generator and pcbai.steps.footprint_qfn_qfp — these modules must be created to pass tests
Body controller firmware: Referenced (esp32_body_controller) — separate repo

⏸️ Superseded / Deprecated

PCB_PLAN.md: Original SMD-based PCB design (0805 resistors, bare WROOM-32 modules, RPM3.3-3.0 DC-DC) — superseded by build_plan.md. Retained for reference (circuit concepts still valid).
esp32_sensor_module_bom.csv: SMD BOM, superseded by the THT parts list in build_plan.md.
carputermodule.kicad_pcb: Original KiCad PCB (130×80mm SMD layout) — not compatible with new 160×120mm THT build plan.

Decision Log

Date	Decision	Rationale
2026-06-03	Agent memory file created as `PROJECT_MEMORY.md` in esp32_sensor_module dir	Keeps state co-located with the code it describes; task-level granularity for log entries
2026-06-03	GPIO 39 (VN) pulled to GND via 10K	Fixes ADC crosstalk per ESP32 errata — input-only pin floats otherwise
2026-06-03	Door logic: LOW = open (switch closed to GND)	GND-switch with INPUT_PULLUP; natural when switch = closed circuit
2026-06-03	RPM = IGf pulses × 60 / 2	4-cylinder: 2 sparks per revolution (wasted spark), so divide by 2
2026-06-03	DTC blink decoder uses LOW period durations	Toyota MIL signal: HIGH = LED on, LOW duration distinguishes digit gap vs code gap vs repeat
2026-06-03	Dual ESP32 vs single	Separate firmwares avoid pin conflicts; no firmware rewrite needed; dedicated modules for sensor vs body
2026-06-03	New PCB build plan: THT axial resistors, DevKit V1 sockets, WAGO connectors, external Teyleten Robot DC-DC module, 160×120mm board	Simpler hand-assembly, easier troubleshooting, modular DC-DC can be replaced independently, DevKit V1 is cheaper/more available than bare modules
2026-06-03	Repurposing existing `carputermodule.kicad_pcb` for THT build plan instead of creating new file	Already has 7 THT footprints placed; avoids losing work; file name stays the same

Change Log

Date	Entry	Files Touched
2026-06-03	Initial project memory created	`PROJECT_MEMORY.md` (created)
2026-06-03	Agent file created with full project context	`.opencode/agents/esp32-sensor-module.md` (created)
2026-06-03	Memory system rules added to agent file	`.opencode/agents/esp32-sensor-module.md` (updated)
2026-06-03	New build plan `build_plan.md` added — THT/DevKit/WAGO/external DC-DC, 160×120mm. Supersedes `PCB_PLAN.md`	`build_plan.md` (created), `PROJECT_MEMORY.md` (updated)
2026-06-03	PCB state audited: 7 THT footprints placed in `carputermodule.kicad_pcb` (U2, U3, 3× WAGO, J5, J6). Board outline, resistors, caps, nets all still missing — file is being repurposed from old SMD design to new THT build plan	`PROJECT_MEMORY.md` (updated)
2026-06-03	`generate_pcb.py` written to programmatically add remaining components — multiple bugs discovered: `q()` quoting too permissive, `stanza()` doesn't handle multi-line children, `kv()` doesn't quote string values. File corrupted by iterative runs, restored from `.corrupted` backup 3×	`generate_pcb.py` (created), `carputermodule.kicad_pcb` (corrupted/restored)
2026-06-03	Read `kicad-happy` source (`/home/devkid/Downloads/kicad-happy-main/`) — discovered proper s-expression approach: `sexp_parser.py` tokenizer + recursive descent parser, tree manipulation, serializer. All all-string-quoted convention confirmed. Added lessons to agent file and memory log.	`.opencode/agents/esp32-sensor-module.md` (updated), `PROJECT_MEMORY.md` (updated)

Known Issues

Issue	Severity	Status
`pcbai` Python package source (`src/pcbai/`) does not exist — tests will fail	High	Open
GPIOs 34/35/36/39 are input-only — no internal pullups	Info	Documented
Strapping pins GPIO 0/2/5/12/15 on body module may interfere with boot	Medium	Open
ADC2 pins blocked when WiFi active — avoid on J6 body module	Info	Documented
R19/R20 (DTC 1K base R) have no transistor footprints in build_plan.md	Medium	Open — DTC functionality may be partially disabled
`carputermodule.kicad_pcb` is being repurposed for THT build plan but has no board outline, nets, or traces yet	Medium	In progress — 7 of ~30 components placed
`PCB_PLAN.md` and `esp32_sensor_module_bom.csv` are now out of date	Low	Documented — kept for circuit reference
No Edge.Cuts board outline exists — board dimensions not defined in KiCad	High	Open — need to add 160×120mm outline
String-concatenated s-expression generation is fragile and error-prone — use `sexp_parser.py` tree approach or KiCad GUI instead	High	Open — lessons learned, not yet applied

Next Steps / TODOs

Priority: High

Priority: Medium

Create src/pcbai/__init__.py, src/pcbai/steps/footprint_generator.py, src/pcbai/steps/footprint_qfn_qfp.py to satisfy existing tests
Create src/pcbai/pipeline/cli.py with click CLI for pcbai footprint command
Create src/pcbai/core/config.py and src/pcbai/core/logger.py
Run pytest tests/ and get green
Add GND copper pour on B.Cu
DRC check

Priority: Low

Create generate_pcb.py for KiCad PCB automation (if redo needed)
Add QFN/QFP support to footprint generator (tests already defined)
Implement LLM provider interface (src/pcbai/llm/provider.py)
Body controller firmware (esp32_body_controller)
Full pipeline (requirements → BOM → schematic → routing → Gerbers)

Critical Reference

Pin Map (Sensor ESP32 — J5)

GPIO	Signal	ADC	Type	Circuit
32	PIM (MAP)	ADC1_CH4	Analog	5.6K+10K divider
33	THW (ECT)	ADC1_CH5	Analog	5.6K+10K divider + NTC
34	VTA (TPS)	ADC1_CH6	Analog	5.6K+10K divider
25	SPD	—	Digital FALLING int	5.6K+10K divider
26	IGf (RPM)	—	Digital RISING int	5.6K+10K divider
19	T/VF	—	Digital in	5.6K+10K divider
35	Fuel	ADC1_CH7	Analog	120Ω to 3.3V
36	Oil pressure	ADC1_CH0	Analog	120Ω to 3.3V
13	Driver door	—	INPUT_PULLUP	10K series
14	Passenger door	—	INPUT_PULLUP	10K series
27	Trunk	—	INPUT_PULLUP	10K series
21	Hood	—	INPUT_PULLUP	10K series
22	TE1	—	Output (2N2222)	1K base
23	TE2	—	Output (2N2222)	1K base
39	VN pulldown	ADC1_CH3	Input (10K→GND)	ADC fix

Network

Sensor ESP32 IP: 192.168.4.20
Carputer IP (server): 192.168.4.3
AP SSID: Carputer_ECU / 12345678
UDP ports: Sensor→5001, Commands←5002, DTC→5003

Voltage Divider

Ratio: 10K / (5.6K + 10K) = 0.641
5V × 0.641 = 3.21V (safe for ESP32)

Sender Formula

V_ADC = ADC / 4095 × 3.3
R_sender = 120 × V_ADC / (3.3 − V_ADC)
Fuel: 3Ω (full) ↔ 110Ω (empty), inverted percentage
Oil: 3Ω (0 psi) ↔ 100Ω (100 psi), direct percentage

Build Plan — Already Placed Coordinates (do not move)

Ref	Footprint	Position (mm)
U2	ULN2003A DIP-16	(91.44, 63.5)
U3	ULN2003A DIP-16	(38.1, 63.5)
WAGO-1	WAGO 8-way	(96.52, 134.62)
WAGO-2	WAGO 8-way	(144.78, 134.62)
WAGO-3	WAGO 8-way	(193.04, 134.62)
J5	ESP32 DevKit V1	(66.04, 66.04)
J6	ESP32 DevKit V1	(231.14, 68.58)

Build Plan — Mounting Holes

Ref	Drill	Position (mm)
H1	3.2mm (M3)	(5, 5)
H2	3.2mm (M3)	(155, 5)
H3	3.2mm (M3)	(5, 115)
H4	3.2mm (M3)	(155, 115)

Build Plan — KiCad Footprint Library Paths

Component	Library Path
Resistors THT	`Resistor_THT:R_Axial_DIN0207_L6.3mm_D2.5mm_P10.16mm_Horizontal`
Ceramic cap THT	`Capacitor_THT:C_Disc_D5.0mm_W2.5mm_P5.00mm`
Electrolytic cap THT	`Capacitor_THT:CP_Radial_D6.3mm_P2.50mm`
Blade fuse holder	`Fuse:Fuseholder_Blade_Littelfuse_154_5.08mm`
WAGO 2-way	`TerminalBlock_WAGO:TerminalBlock_WAGO_236-102_1x02_P5.00mm_45Degree`
Pin header 1×6	`Connector_PinHeader_2.54mm:PinHeader_1x06_P2.54mm_Vertical`
M3 hole	`MountingHole:MountingHole_3.2mm`

Build Plan — DC-DC Module

Module: Teyleten Robot 100W 6A Buck Converter (70×31mm)
PCB reserved area: 75×35mm silkscreen box
DC_IN WAGO at one end, DC_OUT WAGO at other end

FilesExpand file tree

PROJECT_MEMORY.md

Latest commit

History