Hardware plan and wiring
The hardware plan is the part of this platform that gets settled first and should change the least. The firmware is written against it and the wiring is done against it. This page covers where it comes from, how to read it, and what to check before you wire.
At a glance
| Frameworks supported | esp-idf and arduino, those two only |
|---|---|
| Hardware supported | esp-idf build targets: esp32 / s2 / s3 / c2 / c3 / c6 / h2. arduino dev boards: ESP32 and ESP8266 boards, Arduino Uno |
| What the plan holds | Framework, target, part list, pin connections, constraint entries, recorded requirements |
| What the plan does not hold | Electrical parameters of individual parts, PCB layout, enclosure, power supply design |
| Who decides | You. It proposes, and nothing takes effect until you confirm it |
| How reliable the pins are | Derived from documentation, not measured. Check them against the real parts before you wire |
How it picks for you
Once you have described what you want to build, it does three things: pick a main controller, pick the peripheral parts, and lay out the pins. In priority order, it goes on:
- What you already have. Name a part number and it builds around your part number instead of choosing another.
- What the device has to do. A display needs enough memory and the right interface; Bluetooth needs a chip that has Bluetooth.
- How well the platform supports it. It would rather hand you a plan that holds together than a novel one that breaks.
So item 1 is worth the most. Say what you have at the start and you avoid the whole round of "the board in the plan is one I do not own / the board I own is not used".
Proposed → confirmed → frozen
A plan goes through three stages, and the interface shows which one you are in:
| Proposed | It lays out a version of the plan in the chat. Nothing counts yet — have it changed as much as you like |
|---|---|
| Confirmed | Once you say confirm in the chat, it stops changing that version and gets ready to freeze. No snapshot is fixed at this stage |
| Frozen | The plan is fixed into a numbered snapshot. Firmware and builds from then on go by that snapshot. The top of the Main pane changes from Not frozen to Frozen #1, and only at this point does the top bar show Hardware plan confirmed |
After the freeze, a plan card appears in the chat with three counts of what was fixed: how many parts, how many connections, how many constraints.
Why freeze at all
Because firmware has to be written against one fixed set of facts. If the plan keeps changing while the code is being written, you hit the hardest class of problem there is: the code uses the old pin and the table shows the new one. Freezing means that from that moment on, the code and the wiring use the same facts.
A freeze is not permanent. Tell it when you need a change and it produces a new version that goes through confirmation again.
When the freeze is blocked
When you ask for a freeze in the chat, you sometimes get Freeze blocked, with a few items to confirm listed underneath. That is not a fault — it is saying: there are facts it is not sure of, and it will not decide them for you. An I²C address the schematic does not give, say, or a module whose power arrangement it cannot derive.
Two ways forward:
- Answer them one at a time (recommended). Reply to those items in the chat, for example
The touch chip's address is 0x5A, I measured it. With the information filled in, the freeze goes through. - Freeze anyway. There is a button for it under that list. Pressing it sends your decision to the assistant, which resubmits the freeze carrying those blockers. The price is that those items may genuinely turn out to be wrong.
The four support levels
The top bar always carries a Hardware support marker. What it answers is: how sure the platform is about the road you are on right now.
| Recommended | It can pick a build target for this hardware, and the hardware facts are complete. Go straight ahead |
|---|---|
| Can try | A build target can be picked, but a piece of the hardware facts is missing — usually the parts are listed and the pin connections are not settled. It can be done, with a higher chance of trouble |
| Needs more info | Not a no — it says what you have given is not enough to judge on. One full part number usually changes it |
| Unsupported | The framework was recognised, but this target is not in the capability catalogue, and retrying does nothing. It would rather say so now than pretend and blow up at build time |
Needs more info is the one most often misread. Do not swap the board when you see it — read out the whole part number printed on the board and it usually clears.
Reading the Modules list
The Modules block in the Main pane answers "what did it pick for me". It is a list; each row is one part, with the pins it takes up on the right.
Every row is marked with a type:
| MCU | The core chip itself, for example ESP32-S3 |
|---|---|
| Dev board | The finished board that chip is soldered onto, for example ESP32-S3-DevKitC-1. The pins listed on its right are the pins available on that board |
| Module | Peripheral parts: sensors, displays, PMUs and so on. What is listed on the right is that part's own pin names (SCL, SDA, RESET, for example) |
Buy from this list. The part numbers have to match — for the same function, pin order can differ completely between manufacturers.
Reading the Pin connections table
Below the Modules list is Pin connections, which answers "how do I wire this". Each row is one connection: a pin on a module → a pin on the dev board.
| Module | On the left, the peripheral part and its own pin name |
|---|---|
| → | Connects to |
| Board | On the right, the GPIO number on the dev board |
| Type | What this wire is for: Power / Ground / Signal, or the specific bus (I²C, QSPI and so on) |
⚠️ Already wired on the board vs. wired by you
This is the easiest thing here to get wrong, and the easiest way to destroy a part.
If a part is already soldered onto the dev board (an on-board display, an on-board power management chip), then those connections in the table are already made inside the board, and there is nothing for you to wire. Wire them again on the outside and, at best, it does not work; at worst you short something out.
Only the modules you plug in yourself (a sensor on a breadboard, an external display) need wiring from the table.
How to tell them apart: check whether that row in the Modules list is part of the dev board itself. When you cannot tell, ask it:
Check it over before you wire
The pins it gives are derived from documentation, not measured. When no online check has been run, the interface says as much: "Pins have not been checked online; verify against the real parts before wiring." Once one has been run, that line shows the time of the most recent online check instead.
What to check: the silkscreen printed on the board. Match the GPIO4 in the table against the 4 or D4 printed on your board. Two boards in the same family can have completely different pin layouts.
TRIG→GPIO2, ECHO→GPIO1, GND→GND, and VCC to whatever supply the module itself calls for.What else is in the Main pane
Keep scrolling and there are these:
| Wiring constraints (read this) | The places in the plan where things go wrong are listed here on their own. Read this block before you touch anything. Before wiring, also confirm whether the module you are holding is the 3.3V or the 5V version — its supply and signal levels have to match the board |
|---|---|
| Recorded requirements | It writes down each requirement you have stated and builds the firmware to match. Usable as an acceptance checklist |
| Firmware features | Which features the firmware actually implements so far. This table comes from the code, not from the plan — if it says a feature is there, it is there |
| Build output | The result of the most recent build, in four rows: Compile (the status), Framework, Build target, Size. On a failure it adds a Failed stage row |
If you come from software development
Think of a frozen hardware plan as a lockfile: what it pins is not dependency versions but physical facts — which chip, which pins, which bus. Firmware generation takes that lock as its input, and changing the lock means generating again.
Unlike a lockfile, it cannot be verified. npm ci fails when the lock and the registry disagree; here, you wire it wrong and the build still passes and the flash still succeeds — only those few lines in the Console tell you otherwise. So "check against the real parts before wiring" is not a politeness. It is the one check in this whole chain, and you are the only one who can carry it out.
Common questions
Can I choose which pins get used?
Yes, say so. Put the HC-SR04 TRIG on GPIO4, not GPIO2. It rearranges the plan.
Can the plan still change after I confirm it?
Yes. Say what you want changed and it produces a new version. The earlier versions stay.
Why can I not use GPIO6 through GPIO11?
On a classic ESP32 those pins are wired to the flash chip; take them and the board does not come up. It normally keeps clear of them, but you can run into it by assigning them yourself — so it is worth adding Do not use GPIO6 through GPIO11 to your description.
I cannot make sense of the plan it gave me — can I have it explained?
Yes, and this is the lowest-effort way to use it: Explain why you picked this chip, What is each of these QSPI lines for?, Which pins are still free?. You do not have to understand the generated code, but you can ask at any point.