Wiring Guide
This section covers wiring each component to the ESP32. Every wiring doc in this section follows the same format.
What Each Wiring Doc Contains
- Overview — what the component does and why it is in the design
- Pin table — precise source → destination for every wire to run
- Wiring diagram — a visual aid (pre-rendered SVG from WireViz source)
- Verification — minimal firmware code to confirm the wiring before moving on
- Gotchas — common wiring mistakes specific to this component
How to Read a Pin Table
Every pin table has these columns:
| Column | Meaning |
|---|---|
| Component pin | The physical pin name on the breakout board |
| Wire colour | Suggested colour to use (consistency helps debugging) |
| ESP32 pin | The physical label on the DevKitC-1 header |
| GPIO # | The GPIO number used in firmware |
| Notes | Important warnings or clarifications |
Suggested wire colour convention used in this guide:
| Colour | Signal type |
|---|---|
| Red | VCC / power |
| Black | GND |
| Yellow | Clock signals (SCLK, SCL, BCLK) |
| Blue | Data signals (MOSI, MISO, SDA) |
| White | Chip select / control (CS, DC, RST) |
| Orange | Interrupt / status (BUSY, INT, SQW) |
| Green | General GPIO (buttons) |
Wiring Safety Checklist
Before powering on after adding a new component:
- VCC connected to the correct voltage (3.3 V or 5 V — check the component's datasheet)
- GND connected
- No bare wire ends touching adjacent pins
- USB cable is disconnected while inserting/removing wires
- Multimeter continuity check on each new wire
About the WireViz Diagrams
The wiring diagrams in each doc were generated from YAML source files stored in the
wireviz/ folder at the root of this repository. To regenerate them:
pip install wireviz
cd wireviz
wireviz rtc-ds3231.yml # generates rtc-ds3231.svg
The pre-rendered SVGs are already in static/img/wiring/ and do not need to be
regenerated unless you change the source YAML.