magnus919_agent-skills/esp32-development/references/hardware-and-electrical-safety.md

Hardware and electrical safety

Read this before assigning pins, attaching a module, or driving a load. The exact board schematic, module datasheet, SoC datasheet, and attached-device datasheet override generic examples.

Power first

Record these values before connecting anything:

• board input path: USB, 5V/VIN, regulated 3V3, battery input, or another rail;
• logic voltage and absolute maximum pin voltage;
• regulator continuous and transient current, including radio bursts;
• attached-device voltage, idle current, peak current, startup/inrush, and sleep current;
• whether two separately powered circuits share ground or require isolation;
• required decoupling, bulk capacitance, and power sequencing.

ESP32 GPIO is generally 3.3 V logic and must not be treated as 5 V tolerant. A 5V board pin is usually a supply rail, not a 5 V GPIO permission. Use a suitable level shifter, divider, buffer, transistor, MOSFET, or isolated interface based on signal direction, speed, topology, and voltage.

A stable USB idle state does not prove the supply can handle Wi-Fi transmission, a display backlight, a radio PA, or an actuator startup. Brownout resets are power evidence. Fix the supply path instead of disabling the detector.

Pin-selection gate

For every selected pin, check all of the following against the exact target:

1. Exposed on this board and not consumed by flash, PSRAM, antenna switching, Ethernet, camera, display, USB, or onboard peripherals.
2. Input/output capability matches the use. Some classic ESP32 GPIOs are input-only.
3. Not a boot-strapping pin, or its external pull/network preserves the required reset level.
4. Does not conflict with UART logging, USB Serial/JTAG, JTAG, or the intended recovery path.
5. Supports the requested analog, RTC, touch, wake, or peripheral function on this SoC.
6. Reset-time state is safe for the attached circuit. A pin can float or pulse before application initialization.
7. External pull-ups/pull-downs do not fight onboard components or exceed current limits.

Classic ESP32 examples such as GPIO0/2/5/12/15 strapping behavior, GPIO6–11 flash use, GPIO34–39 input-only behavior, and ADC2/Wi-Fi contention are not universal family rules. Treat them as prompts to inspect the matching family documentation, not as a portable pin table.

Two family-specific traps illustrate why that lookup matters:

• On classic ESP32, the GPIO12/MTDI reset level selects the VDD_SDIO flash-supply voltage. An external pull that selects the wrong voltage can prevent flash boot. Follow the exact module schematic and datasheet rather than copying a generic pull network.
• On ESP32-C3, only GPIO0–GPIO5 are RTC GPIOs available for Deep-sleep wake; other GPIOs can wake only from Light-sleep. Recheck the matching GPIO and sleep documentation for every other family.

Do not disable CONFIG_ESP_BROWNOUT_DET to make resets disappear. A brownout during a flash write or security-provisioning operation can corrupt persistent state. Measure and repair the supply path.

Inputs

• Never leave a safety-relevant digital input floating. Use an internal or external pull as supported by the exact pin and required impedance.
• Debounce mechanical contacts in hardware, software, or both. Record the chosen interval instead of burying it in a magic number.
• Protect long wires and exposed connectors against ESD, transients, and induced noise.
• Scale analog inputs so the maximum possible voltage remains within the documented ADC range, including fault conditions.
• ADC readings vary with attenuation, calibration data, reference behavior, source impedance, noise, and radio activity. Average only after fixing wiring and range problems.

Outputs and loads

A GPIO is a control signal, not a power supply.

Load	Minimum external stage
Indicator LED	Series resistor sized for LED voltage and safe GPIO current
Logic input at another voltage	Appropriate unidirectional or bidirectional level translation
Relay/solenoid	Transistor or MOSFET driver, rated supply, flyback protection for DC coils
DC motor/pump	Motor driver or MOSFET stage, flyback/current handling, separate power budget
Servo	External supply sized for stall current; common reference when not isolated
High-current LED/strip	Constant-current or rated switching driver; power injection as required
AC/mains load	Certified isolated interface and qualified electrical design; do not prototype directly from GPIO

Check whether a module marketed as a "relay board" or "motor driver" accepts 3.3 V logic. Optocouplers and input LEDs can still require more current or voltage than an ESP32 pin safely supplies.

Bus electrical checks

• I2C needs pull-ups to the correct logic rail. Count onboard pull-ups in parallel and calculate the effective resistance.
• SPI needs a shared reference, correct voltage, dedicated chip selects, and signal integrity appropriate to wire length and clock rate.
• UART requires crossed TX/RX, common reference unless isolated, matching voltage levels, baud, data bits, parity, stop bits, and flow control.
• RS-232 is not TTL UART. RS-485 and CAN/TWAI need transceivers and topology-appropriate termination/biasing.
• I2S, camera, LCD, SD, Ethernet, and high-speed SPI wiring become board-layout problems quickly. Reduce speed only as a diagnostic, not as proof the physical design is sound.

Hardware bring-up

1. Inspect for shorts and confirm supply polarity with power removed.
2. Power the ESP32 alone; measure rails and capture boot current/serial output.
3. Add the attached device's power only; verify rail stability and temperature.
4. Add ground/reference and one signal group at a time.
5. Verify idle voltage with a meter or oscilloscope before enabling outputs.
6. Use a bus scanner or loopback at conservative speed.
7. Read a stable identity/status register before trusting measurements.
8. Add the real load last and test worst-case startup, radio transmit, reset, and actuator conditions.

Use templates/hardware-bringup.md to keep these decisions reviewable.