• Refined this starter for ESPHome instead of Arduino/PlatformIO.
• Added the recommended Apple HomeKit integration path via Home Assistant HomeKit Bridge.
• Kept the GPIO mapping grounded in the schematic: relay control is on GPIO4, native USB is GPIO19/GPIO20, BOOT is GPIO0, RESET is EN.

• MCU/module: ESP32-S3-WROOM-1-N16R8
• Firmware framework: ESPHome
• Build/install path: ESPHome Dashboard or ESPHome CLI
• HomeKit path: ESPHome → Home Assistant → HomeKit Bridge → Apple Home app
• USB: Native ESP32-S3 USB Serial/JTAG via GPIO19/GPIO20
• Power note: This board is 12V-powered. USB-C is for data/programming/debug only; do not rely on USB-C to power the board.

1. Flash ESPHome to the ESP32-S3.
2. Add the ESPHome device to Home Assistant.
3. Enable Home Assistant's HomeKit Bridge integration.
4. Expose the relay/switch entity to Apple Home.
5. Pair the HomeKit Bridge QR/code in the Apple Home app.

Yaml
esphome:
  name: esp32-s3-relay-controller
  friendly_name: ESP32-S3 Relay Controller
  comment: 12V powered dry-contact relay controller for Home Assistant and Apple HomeKit via HomeKit Bridge

esp32:
  board: esp32-s3-devkitc-1
  variant: esp32s3
  framework:
    type: esp-idf

# USB serial logging over native ESP32-S3 USB Serial/JTAG.
logger:
  level: INFO

# Home Assistant native API. This is what Home Assistant uses to discover/control the device.
api:
  encryption:
    key: "REPLACE_WITH_ESPHOME_API_ENCRYPTION_KEY"

# OTA updates after the first USB flash.
ota:
  - platform: esphome
    password: "REPLACE_WITH_OTA_PASSWORD"

wifi:
  ssid: "REPLACE_WITH_WIFI_SSID"
  password: "REPLACE_WITH_WIFI_PASSWORD"
  ap:
    ssid: "ESP32 Relay Fallback"
    password: "REPLACE_WITH_FALLBACK_AP_PASSWORD"

captive_portal:

# Optional web UI on the local network for quick testing outside Home Assistant.
web_server:
  port: 80

# Relay driver: schematic net RELAY_CTRL, ESP32-S3 GPIO4.
# Hardware behavior: HIGH -> MOSFET on -> relay coil energized -> NO closes to COM.
output:
  - platform: gpio
    id: relay_output
    pin:
      number: GPIO4
      mode: OUTPUT
    inverted: false

switch:
  - platform: output
    name: "Relay"
    id: relay
    output: relay_output
    restore_mode: ALWAYS_OFF
    icon: "mdi:electric-switch"
    device_class: switch

# Useful diagnostics visible in Home Assistant.
sensor:
  - platform: wifi_signal
    name: "WiFi Signal"
    update_interval: 60s
  - platform: uptime
    name: "Uptime"
    update_interval: 60s

text_sensor:
  - platform: wifi_info
    ip_address:
      name: "IP Address"
    ssid:
      name: "Connected SSID"
    mac_address:
      name: "MAC Address"
  - platform: version
    name: "ESPHome Version"

button:
  - platform: restart
    name: "Restart"

Yaml
switch:
  - platform: output
    name: "Gate Trigger"
    id: relay
    output: relay_output
    restore_mode: ALWAYS_OFF
    icon: "mdi:gate"

Yaml
output:
  - platform: gpio
    id: relay_output
    pin:
      number: GPIO4
      mode: OUTPUT
    inverted: false

switch:
  - platform: template
    name: "Relay Pulse"
    id: relay_pulse
    icon: "mdi:electric-switch"
    optimistic: true
    turn_on_action:
      - output.turn_on: relay_output
      - delay: 500ms
      - output.turn_off: relay_output
      - switch.template.publish:
          id: relay_pulse
          state: OFF
    turn_off_action:
      - output.turn_off: relay_output

1. Apply 12V input power to the board.
2. Connect USB-C to the computer for data/programming.
3. If upload does not auto-enter bootloader:
   • Hold BOOT.
   • Tap RESET.
   • Release BOOT.
   • Start the ESPHome install/upload again.
4. After first flash, future updates can usually be done OTA.

Bash
pip install esphome
esphome wizard esp32-s3-relay-controller.yaml
esphome run esp32-s3-relay-controller.yaml

1. In Home Assistant, go to Settings → Devices & services.
2. Add the ESPHome integration if it is not already present.
3. Adopt or add esp32-s3-relay-controller.
4. Confirm the switch.relay entity toggles the physical relay.
5. Rename the entity to the final user-facing name before exposing it to HomeKit.

1. In Home Assistant, go to Settings → Devices & services → Add Integration.
2. Add HomeKit Bridge.
3. Choose the domain/entity to expose, usually the relay switch entity only.
4. Home Assistant will show a pairing code/QR code.
5. Open the Apple Home app and add the bridge accessory.
6. The relay will appear in Apple Home as a controllable switch.

• Relay is OFF after boot because restore_mode: ALWAYS_OFF is set.
• Toggling the ESPHome switch energizes the relay: J3 NO closes to COM, NC opens from COM.
• Relay drops out after reboot, Wi-Fi reconnect, or firmware update unless intentionally commanded on again.
• Home Assistant can toggle the relay before it is exposed to Apple Home.
• Apple Home controls the Home Assistant HomeKit Bridge entity, not a separate direct ESPHome pairing.

• GPIO0 is reserved for BOOT mode and should not be used as a user button in this firmware.
• GPIO19/GPIO20 are reserved for native USB and should not be repurposed.
• restore_mode: ALWAYS_OFF is intentional for a relay dry-contact controller; it avoids unexpected activation after power loss.
• If the load needs a maintained state after power loss, change restore behavior only after confirming that is safe for the connected equipment.