ESPHome for XIAO

ESPHome is a YAML-based firmware framework for creating custom firmware for ESP devices, with native Home Assistant integration.

Supported XIAO Boards

Not supported: nRF52840, SAMD21, nRF54L15 (ESPHome doesn't support these platforms)

Quick Start

1. Installation

Choose your ESPHome installation method:

• CLI (Recommended): See setup/cli.md
• Docker: See setup/docker.md
• Home Assistant Add-on: See setup/add-on.md

Quick install (CLI):

pip install esphome

2. Create New Configuration

esphome create config.yaml

3. Select Your Board Template

Choose the appropriate board configuration from references/boards/:

• ESP32C3: esp32c3.md
• ESP32C6: esp32c6.md
• ESP32S3: esp32s3.md
• RP2040: rp2040.md

4. Upload to Board

# Via USB
esphome run config.yaml

# Via OTA (after initial upload)
esphome upload config.yaml

Board Base Configurations

Copy the base configuration for your XIAO board and customize:

# Example: XIAO ESP32C3 base config
substitutions:
  device_name: "xiao-sensor"
  friendly_name: "XIAO Sensor"

esphome:
  name: ${device_name}
  platform: ESP32
  board: esp32-c3-devkitm-1

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

# See references/boards/esp32c3.md for complete config

Common Components

Add components as needed:

Sensors

• BME280: Temperature, humidity, pressure (I2C)
• DHT: Temperature, humidity (digital)
• AHT20: Temperature, humidity (I2C)
• See references/components/sensors.md

Displays

• SSD1306: OLED display (I2C/SPI)
• ST7789: TFT display (SPI)
• See references/components/displays.md

Communication

• I2C Bus: references/components/i2c.md
• SPI Bus: references/components/spi.md
• UART: references/components/uart.md

Connectivity

• WiFi: references/components/wifi.md - ESP32 only
• MQTT: references/components/mqtt.md
• API: references/components/api.md - Home Assistant integration

Complete Examples

Ready-to-use configurations:

• Weather Station: references/examples/weather-station.md - BME280 + display + OTA
• Smart Switch: references/examples/smart-switch.md - Relay + button + LED
• Sensor Node: references/examples/sensor-node.md - Multi-sensor + MQTT
• BLE Proxy: references/examples/ble-proxy.md - BLE to WiFi bridge (ESP32)

XIAO Pin Mappings

I2C (Most boards)

SPI

See board-specific files for complete pin mappings.

Special Features

Deep Sleep (ESP32)

# Enable deep sleep
deep_sleep:
  run_duration: 60s
  sleep_duration: 300s

# Wake on button
deep_sleep:
  wakeup_pin: D13
  wakeup_pin_mode: KEEP_AWAKE

See references/advanced/deep-sleep.md

OTA Updates

# OTA enabled by default in base configs
ota:
  - platform: esphome
    password: !secret ota_password

Camera (ESP32S3 Sense)

esp32_camera:
  # See references/boards/esp32s3.md for camera config

Home Assistant Integration

Automatic Discovery

ESPHome automatically discovers devices in Home Assistant when using the api: component.

Secrets

Use Home Assistant secrets:

# In ESPHome config
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
  password: !secret api_password

Dashboard

Access ESPHome dashboard: http://esphome.local:6052

Troubleshooting

Upload Fails

1. Check board selection in esphome: platform
2. Enter boot mode: Hold BOOT button, press RESET
3. Try different USB cable
4. Check port: esphome config.yaml show-ports

WiFi Not Connecting

1. Verify credentials
2. Enable fast_connect: for quicker connection
3. Check 2.4GHz only (5GHz not supported)

I2C/SPI Not Working

1. Check pin mappings for your board
2. Enable scan: true for I2C
3. Verify pull-up resistors for I2C

See /xiao for authoritative pin definitions.

Code Verification

After generating ESPHome YAML, validate it using esphome CLI.

Quick Verification (If ESPHome CLI is Already Set Up)

# Validate and compile
esphome config your_device.yaml
esphome compile your_device.yaml

# Upload to device
esphome run your_device.yaml

Full Verification (First-Time Setup)

Step 1: Install ESPHome CLI (if not installed)

pip install esphome

# Verify installation
esphome version

Step 2: Create Secrets File (if not exists)

# Create secrets.yaml in same directory as config
cat > secrets.yaml <<'EOF'
wifi_ssid: "YourWiFiSSID"
wifi_password: "YourWiFiPassword"
api_password: "YourAPIPassword"
ota_password: "YourOTAPassword"
EOF

Step 3: Validate Configuration

# Check configuration validity
esphome config your_device.yaml

# Expected output:
# ✔ Config valid
# ➜ Platform: ESP32
# ➜ Board: esp32-c3-devkitm-1

Step 4: Compile and Upload

# Compile firmware
esphome compile your_device.yaml

# Upload to device (first time via USB)
esphome run your_device.yaml

# Or via OTA (after first upload)
esphome upload your_device.yaml

Common Errors and Solutions

Common esphome CLI Commands

Example: Complete Verification

# xiao_sensor.yaml - XIAO ESP32C3

substitutions:
  device_name: "xiao-sensor"

esphome:
  name: ${device_name}
  platform: ESP32
  board: esp32-c3-devkitm-1

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

Verification command:

esphome config xiao_sensor.yaml && esphome compile xiao_sensor.yaml

Best Practices

1. Use substitutions for device names and common values
2. Enable OTA for wireless updates
3. Use secrets for sensitive data
4. Enable logging during development
5. Add status LED for visual feedback
6. Use packages for reusable configurations
7. Test components individually before combining

Advanced Topics

• Packages: references/advanced/packages.md - Reusable config snippets
• Automations: references/advanced/automation.md - ESPHome scripting
• Web Server: references/advanced/web-server.md - Web interface
• Custom Sensor: references/advanced/custom-sensor.md - Custom C++ sensors

Migration from Arduino

Key differences:

Resources

setup/

ESPHome environment installation:

• setup/cli.md - ESPHome CLI installation via pip

• setup/docker.md - ESPHome in Docker container

• setup/add-on.md - Home Assistant ESPHome add-on

• setup/troubleshooting.md - Common ESPHome issues and solutions

• ESPHome Documentation: https://esphome.io/

• ESPHome Components: https://esphome.io/components/

• Home Assistant: https://www.home-assistant.io/

• XIAO Documentation: SeeedStudio Wiki

Requires: /xiao skill for pin definitions Compatible with: Home Assistant 2021.12+ Platform: ESPHome 2021.12+