| name | embedded-brainstorming |
| description | Use BEFORE any embedded firmware development - clarifies hardware requirements, pin assignments, interface timing, and architecture through structured questions and design approval gate |
Embedded Brainstorming
Overview
Hardware development requires explicit clarification BEFORE writing firmware code. Different from software brainstorming because hardware decisions have physical constraints that cannot be easily changed later.
Core principle: Understand hardware constraints BEFORE implementation.
Do NOT write any firmware code, generate any driver, or take any implementation action until hardware requirements are approved and architecture documented.
This is not optional. This is not "when convenient." This is a HARD GATE.
Announce at start: "I'm using the embedded-brainstorming skill to clarify hardware requirements before implementation."
Anti-Pattern: "This Driver Is Too Simple"
Every embedded component needs design clarification:
| Component | Hidden Complexity |
|---|
| Single GPIO | Pull-up/down, drive strength, interrupt config, debounce |
| Simple I2C sensor | Address, clock speed, pull-up resistor values, timeout |
| Basic SPI LCD | DMA buffer size, timing constraints, pin conflicts |
| UART debug | Baud rate tolerance, DMA needed, buffer overflow handling |
"Simple" drivers are where hardware assumptions cause hours of wasted work.
Red Flags:
- "This sensor only needs 3 lines of code"
- "I'll figure out the pin assignments later"
- "The datasheet is straightforward"
- "Let me just write a quick prototype first"
The Process
Step 1: Explore Project Context
read AGENTS.md
read references/chips.md
glob **/*.h
Check:
- Existing drivers and patterns
- Pin assignments in use
- Hardware already configured
Step 2: Identify Hardware Constraints
Read datasheet/specification:
- Electrical characteristics (voltage, current, timing)
- Communication protocol details
- Pin requirements and conflicts
- Memory/peripheral constraints
Step 3: Ask Clarifying Questions (One at a Time)
Hardware-specific questions must be asked individually. Don't batch them.
Good question format:
What is the LCD controller model?
Options:
A) ST7789 (240x240, SPI interface)
B) ILI9341 (320x240, SPI/Parallel)
C) GC9A01 (240x240, circular display)
D) Other (specify model and interface)
Bad question format:
What LCD controller, resolution, and interface do you need?
(Batching loses context and creates confusion.)
Step 4: Hardware-Specific Questions
| Component Type | Key Questions |
|---|
| LCD/Display | Controller model? Interface (SPI/I2C/Parallel)? Resolution? Color depth? DMA buffer size? Refresh rate? |
| Sensor (IMU) | Model? I2C address? Sample rate? Interrupt needed? Calibration requirement? |
| Communication | Protocol? Baud rate? DMA needed? Timeout handling? Error recovery? |
| GPIO Control | Pull-up/down? Drive strength? Interrupt trigger type? Debounce time? |
| Power | Voltage levels? LDO needed? Battery monitoring? Sleep mode? |
Step 5: Check Pin Conflicts
After identifying required pins:
Verify pin assignments:
SPI LCD requires: MOSI, MISO, SCK, CS, DC, RESET
IMU requires: SDA, SCL, INT
Available pins: GPIO1-48
Conflicts detected:
- GPIO10: SPI CS vs IMU INT
- GPIO8: LCD DC vs I2C SDA
Resolution options:
A) Move LCD CS to GPIO9
B) Move IMU INT to GPIO11
C) Use different SPI bus for LCD
Step 6: Propose Architecture
Three-layer design:
- Application Layer: Business logic (sensor data processing, UI rendering)
- HAL/Driver Layer: Hardware abstraction (LCD HAL, IMU HAL)
- Platform Layer: Chip SDK (ESP-IDF, STM32 HAL)
Proposed architecture:
src/
├── app/
│ ├── sensor_handler.c # Application: IMU data processing
│ └── ui_renderer.c # Application: LCD rendering
├── hal/
│ ├── lcd_hal.c # HAL: LCD hardware abstraction
│ ├── imu_hal.c # HAL: IMU hardware abstraction
│ └── lcd_hal.h
│ └── imu_hal.h
└── platform/
│ ├── spi_platform.c # Platform: ESP32 SPI driver wrapper
│ └── i2c_platform.c # Platform: ESP32 I2C driver wrapper
Step 7: Present Design for Approval
Show:
- Hardware timing diagram (if applicable)
- Pin assignment table
- Architecture diagram
- Testing strategy (HAL Mock + Hardware verification)
Step 8: Write Design Document
Save to docs/embedded/specs/:
## LCD Driver Specification
**Controller**: ST7789
**Interface**: SPI (Mode 0)
**Resolution**: 240x240
**DMA**: Single transfer max 4092 bytes
**Refresh**: 60Hz
## Pin Assignments
| Function | GPIO | Notes |
|----------|------|-------|
| SPI_MOSI | 11 | DMA channel 1 |
| SPI_SCK | 12 | 40MHz max |
| LCD_CS | 10 | Active low |
| LCD_DC | 9 | Data/Command |
| LCD_RST | 8 | Reset |
## Architecture
- LCD HAL: Abstracts SPI commands
- Platform: ESP-IDF SPI driver
- Application: UI rendering
## Testing Strategy
1. HAL Mock: Test command sequences without hardware
2. Hardware: Verify actual LCD response
Step 9: Get Explicit Approval
Hardware design ready for review.
Design document: docs/embedded/specs/lcd-driver-spec.md
Pin assignments: [table above]
Do you approve this hardware design?
- If YES: I'll invoke embedded-tdd to write HAL Mock tests
- If NO: What needs clarification?
WAIT for user response. Do not proceed until approved.
Step 10: Invoke embedded-tdd
After approval:
"Hardware design approved. I'm invoking the embedded-tdd skill to write HAL Mock tests first."
Process Flow Diagram
digraph embedded_brainstorming {
"Start" [shape=doublecircle];
"Read AGENTS.md" [shape=box];
"Read datasheet" [shape=box];
"Hardware question?" [shape=diamond];
"Ask one question" [shape=box];
"All questions answered?" [shape=diamond];
"Check pin conflicts" [shape=box];
"Conflicts found?" [shape=diamond];
"Resolve conflicts" [shape=box];
"Propose architecture" [shape=box];
"Write design doc" [shape=box];
"User approves?" [shape=diamond];
"STOP: No code without approval" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
"Invoke embedded-tdd" [shape=doublecircle];
"Start" -> "Read AGENTS.md";
"Read AGENTS.md" -> "Read datasheet";
"Read datasheet" -> "Hardware question?";
"Hardware question?" -> "Ask one question" [label="yes"];
"Hardware question?" -> "Check pin conflicts" [label="no"];
"Ask one question" -> "All questions answered?";
"All questions answered?" -> "Ask one question" [label="no"];
"All questions answered?" -> "Check pin conflicts" [label="yes"];
"Check pin conflicts" -> "Conflicts found?";
"Conflicts found?" -> "Resolve conflicts" [label="yes"];
"Conflicts found?" -> "Propose architecture" [label="no"];
"Resolve conflicts" -> "Propose architecture";
"Propose architecture" -> "Write design doc";
"Write design doc" -> "User approves?";
"User approves?" -> "STOP: No code without approval" [label="no"];
"User approves?" -> "Invoke embedded-tdd" [label="yes"];
}
Hardware Timing Verification
For timing-sensitive components (SPI LCD, high-speed sensors):
SPI Timing Checklist
SPI Configuration:
- Mode: 0/1/2/3 (check datasheet)
- Clock speed: Within datasheet range
- CS handling: Active low/high, automatic/manual
- DMA: Size limit (ESP32-S3: 4092 bytes)
Timing Margins:
- Setup time: min X ns
- Hold time: min Y ns
- CS to clock: min Z ns
I2C Timing Checklist
I2C Configuration:
- Clock speed: 100kHz/400kHz/1MHz
- Pull-up resistors: Calculate based on bus capacitance
- Address: 7-bit or 10-bit
- Timeout: ACK timeout handling
Common Mistakes
| Mistake | Fix |
|---|
| Batch multiple hardware questions | Ask one at a time, wait for answer |
| Skip datasheet check | Read electrical characteristics section |
| Ignore pin conflicts | Create pin assignment table, check overlaps |
| No timing verification | Calculate timing margins, verify with datasheet |
| Skip design document | Write spec before coding |
| Proceed without approval | Wait for explicit "approved" response |
Checklist (Create TodoWrite)
Before proceeding to embedded-tdd:
Key Principles
- One question at a time — Hardware context is complex
- Datasheet numbers trump assumptions — Verify timing parameters
- Pin conflicts must be resolved BEFORE code — Hardware can't be refactored easily
- Design document required — Future reference and debugging
- Explicit approval required — No assumption of approval
Integration
Required next skill: embedded-tdd
After approval: "Hardware design approved. I'm invoking the embedded-tdd skill."
Do NOT:
- Start coding before approval
- Skip the design document
- Assume user approved without confirmation
