gokul/fieldkit-usb

docs/firmware-contract.md

# Firmware pin assignment

The controller is an ESP32-S3-WROOM-1-N8R8.

| Function | ESP32-S3 pin | Electrical behavior |
| --- | --- | --- |
| OLED SDA | GPIO4 | I2C data, 4.7 kΩ pull-up to 3.3 V |
| OLED SCL | GPIO5 | I2C clock, 4.7 kΩ pull-up to 3.3 V |
| OLED reset | GPIO6 | Active low, 47 kΩ pull-up to 3.3 V |
| OLED panel power | GPIO7 | Active high; 47 kΩ pull-down keeps the 12 V load switch off during reset |
| USB D− | GPIO19 | Native USB through 22 Ω series resistor |
| USB D+ | GPIO20 | Native USB through 22 Ω series resistor |
| Up | GPIO1 | Active low; 10 kΩ pull-up and 100 nF debounce capacitor |
| Down | GPIO2 | Active low; 10 kΩ pull-up and 100 nF debounce capacitor |
| Left | GPIO38 | Active low; 10 kΩ pull-up and 100 nF debounce capacitor |
| Right | GPIO39 | Active low; 10 kΩ pull-up and 100 nF debounce capacitor |
| OK | GPIO40 | Active low; 10 kΩ pull-up and 100 nF debounce capacitor |
| Back | GPIO41 | Active low; 10 kΩ pull-up and 100 nF debounce capacitor |
| Status LED | GPIO42 | Active high through 1 kΩ |
| Boot button | GPIO0 | Active low |
| Reset button | EN | Active low |

GPIO35, GPIO36, and GPIO37 are deliberately unused because the N8R8 module reserves them for its octal PSRAM interface.

U9 is the SH1107-based C5123566 display in I2C mode. Its address-select pin is tied low. Keep GPIO7 low while 3.3 V stabilizes and while the display is held in reset, then drive GPIO7 high to apply the approximately 12 V panel rail. On shutdown, turn the panel rail off before removing logic power.