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