As a hardware engineer, you’ve probably experienced this scenario: you hand off a board to the firmware team, and two days later they come back with a list of questions.
- “Is this pin active high or low?”
- “What’s the I²C address of that sensor?”
- “Which timer channel is connected to the PWM pin?”
Sound familiar?
The problem isn‘t your design – it’s the lack of a proper design document.
A well-written PCB design document is the bridge between hardware and software. It saves countless hours of back‑and‑forth, prevents integration bugs, and makes you the hero of the firmware team.
This article shows you exactly what to include and how to structure it.
1. Why Bother? The Cost of Bad Documentation
When your firmware engineer has to dig through schematics, guess pin functions, or reverse‑engineer I²C addresses, you‘re burning expensive time.
A good design document turns “what does this pin do?” into “here‘s the complete interface specification”.
2. The Essential Sections of a PCB Design Document
You don‘t need a 50‑page novel. Aim for 5‑10 pages that cover the following:
① Overview & Block Diagram
- One paragraph: what does this board do？
- A high‑level block diagram showing major components and interfaces (MCU, sensors, power, connectors).
② Power Architecture
- Voltage rails, expected current draw, sequencing requirements.
- Power‑on/reset timing if critical.
③ Pin Mapping Table (The Most Valuable Part)
Create a table that maps every pin from the MCU/FPGA to its function and connection.
This single table answers 90% of firmware questions.
④ Communication Interfaces
For each bus (I²C, SPI, UART, CAN, USB), specify:
- Bus speed
- Device addresses (I²C)
- CS/IRQ pin assignments
- Any required pull‑up/down resistors
⑤ Memory Map (If applicable)
For FPGAs or external memories, provide a detailed address map.
⑥ Configuration Straps / Boot Options
How is the board configured at power‑up？ BOOT pins, strapping resistors, configuration EEPROM, etc.
⑦ Clock Sources
List all clocks (crystal, oscillator, PLL) with frequencies and accuracy.
⑧ Test Points and Debug Interfaces
- JTAG/SWD pinout
- UART console pins
- Any test points for production
⑨ Known Errata / Workarounds
Be honest. If there‘s a silicon bug or a board‑level limitation, document it. It saves hours of false bug reports.
⑩ Revision History
A simple table tracking document versions and changes.
3. Practical Tips for Writing the Document
Start Early, Not at the End
Write the document while you design the schematic. The pin mapping table can be filled as you assign pins. Don‘t wait until the board is done.
Use a Shared Format
Keep the document in a format that everyone can access: Markdown in the Git repo, Google Docs, or a company wiki. Avoid sending Word files by email.
Keep It Under 10 Pages
Firmware engineers won‘t read a 200‑page user manual. Focus on what they need to write drivers and initialize hardware.
Include Schematics as Figures (Not Just Netlists)
Export relevant schematic pages as PNG/PDF and paste them into the document. A picture of a 4‑wire SPI connection is worth a thousand words.
Version‑Control the Document
If you use Git for hardware, check the design document into the same repository. Tag releases together.
4. A Simple Template (Copy This)
You can start from this Markdown skeleton:
PCB Design Document – [Project Name]
Revision: 1.0
Date: YYYY-MM-DD
Author: [Your Name]
Status: Draft / Released
1. Overview
[One paragraph describing what this board does, its application, and key features. Example: This board is the main control unit for a smart home gateway. It integrates Wi‑Fi/BLE, a temperature/humidity sensor, an OLED display, and push buttons.]
2. Block Diagram
Replace with an actual block diagram showing major components and their interconnections (MCU, sensors, power, interfaces, etc.).
3. Power Architecture
| Rail | Voltage | Max Current | Power‑up sequence | Notes |
|---|---|---|---|---|
| 3.3V | 3.3V | 500mA | 1 | Main logic, sensors, wireless module |
| 1.8V | 1.8V | 100mA | 2 | MCU core voltage |
| VBAT | 3.0‑4.2V | 1A | 0 | Battery input, converted to 3.3V via DCDC |
Power‑up sequence notes:
- VBAT always present (battery powered)
- 3.3V comes up first, then 1.8V after ~10ms delay.
4. Pin Mapping Table
| MCU Pin | Pin Name | Connected to | Function | Active level | Notes |
|---|---|---|---|---|---|
| PA0 | ADC_IN0 | Battery voltage divider | Battery monitoring | Analog | Divider 1:2, 0‑3.3V → 0‑8.4V |
| PA1 | USART2_TX | GPS module TX | GPS data receive | 3.3V | Baud 9600, 8N1 |
| PA2 | USART2_RX | GPS module RX | GPS command send | 3.3V | Same as above |
| PB4 | PWM_CH3 | LED driver (PWM dimming) | Backlight brightness | PWM | 1 kHz, 8‑bit resolution |
| PC13 | GPIO_IN | Limit switch (NO) | Stop signal | Active high | Internal pull‑down, pulled to 3.3V externally |
| PB6 | I2C1_SCL | Temperature sensor (SCL) | I2C clock | Open‑drain | External 4.7kΩ pull‑up |
| PB7 | I2C1_SDA | Temperature sensor (SDA) | I2C data | Open‑drain | External 4.7kΩ pull‑up |
This table is the most valuable part for firmware engineers – make it accurate and complete.
5. Communication Interfaces
5.1 I²C Bus
- Speed: 400 kHz
-
Device addresses:
- Temperature sensor (TMP117): 0x48
- RTC (DS3231): 0x68
- Pull‑up resistors: 4.7 kΩ on both SCL and SDA to 3.3V.
5.2 SPI Bus
- Clock frequency: 10 MHz
- CPOL/CPHA: 0 / 0
-
Devices: External Flash (W25Q64)
- CS: PB2 (active low)
- MOSI: PA7
- MISO: PA6
- SCK: PA5
5.3 UART
| UART | TX pin | RX pin | Baud rate | Purpose |
|---|---|---|---|---|
| USART2 | PA1 | PA2 | 9600 | GPS module communication |
| USART3 | PB10 | PB11 | 115200 | Debug console output |
6. Memory Map (if applicable)
| Address range | Device / purpose | Size | Notes |
|---|---|---|---|
| 0x0800 0000 | Internal Flash | 512 KB | Program storage |
| 0x2000 0000 | Internal SRAM | 128 KB | Variables / heap / stack |
| 0x9000 0000 | External SPI Flash | 8 MB | Accessed via SPI, file system |
7. Configuration Jumpers / Boot Options
| Jumper / pin | Configuration | Function |
|---|---|---|
| BOOT0 | 10kΩ pull‑down | 0 → boot from Flash |
| BOOT1 | 10kΩ pull‑down | Not used, reserved |
| J1 (2‑pin) | Short to enable | Enter ISP programming mode |
8. Clock Sources
| Clock | Frequency | Accuracy | Purpose |
|---|---|---|---|
| Main crystal | 25 MHz | ±30 ppm | MCU main clock (HSE) |
| RTC crystal | 32.768 kHz | ±20 ppm | Real‑time clock, low‑power timers |
9. Debug Interface (JTAG/SWD)
| Pin | Function |
|---|---|
| 1 | 3.3V |
| 2 | SWDIO |
| 3 | SWCLK |
| 4 | GND |
| 5 | RESET (optional) |
Use a 5‑pin 1.27mm header. Firmware team can connect J‑Link or ST‑Link.
10. Test Point List
| Test point | Net | Purpose | Location (X, Y) |
|---|---|---|---|
| TP1 | 3.3V | Main power monitor | (10, 20) |
| TP2 | GND | Ground reference | (15, 20) |
| TP3 | VBAT | Battery voltage monitor | (10, 25) |
| TP4 | SWDIO | Debug signal | (30, 40) |
11. Known Issues / Workarounds
| Issue description | Affected version | Workaround |
|---|---|---|
| I²C communication with temperature sensor occasionally NACKs | v1.0 | Add 10 ms delay before each read |
| Battery voltage ADC readings fluctuate | v1.0 | Software oversampling (average 16 samples) |
12. Revision History
| Version | Date | Author | Change description |
|---|---|---|---|
| 0.1 | 2026-05-01 | John | Initial draft |
| 0.2 | 2026-05-10 | John | Added pin mapping table, I²C addresses |
| 1.0 | 2026-05-20 | John | First release, added test points and known issues |
Appendix: Firmware Engineer Cheat Sheet
- ☑️ Pin mapping table (see Section 4)
- ☑️ I²C addresses: Temp sensor 0x48, RTC 0x68
- ☑️ SPI mode: Mode 0 (CPOL=0, CPHA=0)
- ☑️ Debug UART: USART3, 115200, 8N1
- ☑️ SWD pins: SWDIO/Pin2, SWCLK/Pin3
- ☑️ Boot config: BOOT0 pulled low → Flash boot
- ☑️ Known issues: see Section 11
End of document
5. What Firmware Engineers Really Want (A Cheat Sheet)
If you have only one page to give them, make it this:
- ✔️ Pin assignment table (MCU pin → function → active level)
- ✔️ I²C addresses of all devices
- ✔️ SPI mode and clock polarity
- ✔️ UART baud rate and configuration
- ✔️ JTAG/SWD pinout
- ✔️ Boot configuration
- ✔️ Known issues / workarounds
That‘s it. Give them that, and they‘ll never bother you again.
Conclusion
A good PCB design document is **not **a burden – it’s a force multiplier. It turns the handoff from a source of friction into a smooth, predictable process.
The firmware team will thank you. Your project manager will thank you. And future you, revisiting the design six months later, will thank you too.
So next time you start a board, open a blank document and write down the pin mapping table as you route. It takes an extra hour and saves a week of confusion.
This article is brought to you by AnyPCBA, a PCB manufacturer that believes great hardware starts with clear communication. We support hardware teams with small‑to‑medium volume production, transparent quotes, and free DFM checks.
