embedded-brainstorming

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:

• AGENTS.md read
• Datasheet key parameters identified
• All hardware questions asked and answered
• Pin assignment table created
• Pin conflicts resolved
• Architecture proposed
• Design document written
• User explicitly approved

---

Key Principles

1. One question at a time — Hardware context is complex
2. Datasheet numbers trump assumptions — Verify timing parameters
3. Pin conflicts must be resolved BEFORE code — Hardware can't be refactored easily
4. Design document required — Future reference and debugging
5. 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