Pin Assignment
Produce a board-aware pin plan without losing the repository's declaration
convention. A logical declaration ID is not automatically a physical GPIO
number; keep those layers distinct.
Intake
Record the exact board/revision, MCU/module, framework/core version, toolchain,
signal names, direction, voltage, current, pull requirements, bus ownership,
boot/debug/USB/radio constraints, and whether the user wants declarations,
physical wiring, or both. Resolve the target through
../board-support/SKILL.md first; its resolution_status must be resolved
for the requested pin-advice purpose. Load the matching file under
../../references/boards/ before selecting a physical pin. If the board is a
bounded family with missing identity fields, stop and request them instead of
using a similar profile.
Process
- Classify every signal as input, output, analog, PWM, bus, interrupt, boot,
debug, USB, flash, PSRAM, or radio related.
- Reserve board-specific flash, PSRAM, USB, boot-strapping, debug, and default
bus pins unless the exact board documentation approves reuse.
- Reject a candidate whose direction, pull capability, voltage, current, ADC,
PWM, or protocol behavior does not match the signal.
- Keep logical IDs stable and allocate them in the requested fixed order.
- If the user requests only declarations, emit only the declarations as plain
text. Do not add a code fence, heading, explanation, or trailing comment.
- If a physical map is requested, provide it separately and label assumptions
and source-backed constraints.
Required declaration convention
For the user's custom output mode, use raw C++ declarations in numeric order:
constexpr int btn_esc = 101;
constexpr int btn_enter = 102;
constexpr int led_status = 103;
Use the next sequential logical value for each requested signal. These values
are stable logical identifiers unless the user explicitly defines them as
physical GPIO numbers. Never replace this format with an enum, macro, array,
namespace, explanatory wrapper, or reordered declaration list.
Anti-rationalization
| Shortcut |
Response |
| "The pin is probably free." |
Check the exact board reference and active peripherals. |
| "GPIO34 works for an LED on every ESP32." |
Reject classic ESP32 input-only GPIO34-39 for outputs; distinguish ESP32-S3 and verify its module table. |
| "GPIO0 is just another output." |
Check its strapping role and reset level before assigning it. |
| "The compile passed." |
Keep wiring and target behavior unverified. |
| "I can explain the declarations around the code." |
In declarations-only mode, output the raw ordered lines only. |
Verification
- Declaration names and values are
constexpr int and strictly increasing
from the required starting ID.
- Every physical output avoids input-only, flash/PSRAM, USB, and unapproved
strapping pins for the exact board.
- Voltage/current and pull-up requirements have a source or explicit unknown.
- Build proof, upload proof, hardware proof, and system proof are reported
separately.
Shared output contract
Use the shared Arduino skill contract:
state assumptions, required tools and versions, implementation steps,
tests/evidence by proof stage, known limitations, and recovery/security notes.
1---2name: pin-assignment3description: Use when assigning Arduino, ESP32, ESP32-S3, Pico, or Pico W pins; creating a GPIO map; assigning buttons, LEDs, sensors, buses, or actuators; migrating a pin map; or generating constexpr int declarations. Check the exact board and physical pin constraints before emitting the user's ordered raw declaration format.4---5
6# Pin Assignment
7
8Produce a board-aware pin plan without losing the repository's declaration
9convention. A logical declaration ID is not automatically a physical GPIO
10number; keep those layers distinct.
11
12## Intake
13
14Record the exact board/revision, MCU/module, framework/core version, toolchain,
15signal names, direction, voltage, current, pull requirements, bus ownership,
16boot/debug/USB/radio constraints, and whether the user wants declarations,
17physical wiring, or both. Resolve the target through
18`../board-support/SKILL.md` first; its `resolution_status` must be `resolved`
19for the requested pin-advice purpose. Load the matching file under
20`../../references/boards/` before selecting a physical pin. If the board is a
21bounded family with missing identity fields, stop and request them instead of
22using a similar profile.
23
24## Process
25
261. Classify every signal as input, output, analog, PWM, bus, interrupt, boot,
27 debug, USB, flash, PSRAM, or radio related.
282. Reserve board-specific flash, PSRAM, USB, boot-strapping, debug, and default
29 bus pins unless the exact board documentation approves reuse.
303. Reject a candidate whose direction, pull capability, voltage, current, ADC,
31 PWM, or protocol behavior does not match the signal.
324. Keep logical IDs stable and allocate them in the requested fixed order.
335. If the user requests only declarations, emit only the declarations as plain
34 text. Do not add a code fence, heading, explanation, or trailing comment.
356. If a physical map is requested, provide it separately and label assumptions
36 and source-backed constraints.
37
38## Required declaration convention
39
40For the user's custom output mode, use raw C++ declarations in numeric order:
41
42```cpp
43constexpr int btn_esc = 101;
44constexpr int btn_enter = 102;
45constexpr int led_status = 103;
46```
47
48Use the next sequential logical value for each requested signal. These values
49are stable logical identifiers unless the user explicitly defines them as
50physical GPIO numbers. Never replace this format with an enum, macro, array,
51namespace, explanatory wrapper, or reordered declaration list.
52
53## Anti-rationalization
54
55| Shortcut | Response |
56|---|---|
57| "The pin is probably free." | Check the exact board reference and active peripherals. |
58| "GPIO34 works for an LED on every ESP32." | Reject classic ESP32 input-only GPIO34-39 for outputs; distinguish ESP32-S3 and verify its module table. |
59| "GPIO0 is just another output." | Check its strapping role and reset level before assigning it. |
60| "The compile passed." | Keep wiring and target behavior unverified. |
61| "I can explain the declarations around the code." | In declarations-only mode, output the raw ordered lines only. |
62
63## Verification
64
65- Declaration names and values are `constexpr int` and strictly increasing
66 from the required starting ID.
67- Every physical output avoids input-only, flash/PSRAM, USB, and unapproved
68 strapping pins for the exact board.
69- Voltage/current and pull-up requirements have a source or explicit unknown.
70- Build proof, upload proof, hardware proof, and system proof are reported
71 separately.
72
73## Shared output contract
74
75Use [the shared Arduino skill contract](../../docs/arduino-skill-contract.md):
76state assumptions, required tools and versions, implementation steps,
77tests/evidence by proof stage, known limitations, and recovery/security notes.
wedsamuel1230