xiao-esphome - SKILL.md Agent Skill

name: xiao-esphome description: | ESPHome YAML configuration for SeeedStudio XIAO series microcontrollers. Use when writing ESPHome YAML configs for XIAO boards to integrate with Home Assistant. Supports ESP32C3, ESP32C6, ESP32S3, and RP2040 XIAO boards. Requires /xiao for pin definitions and board specifications.

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

Board	Platform	WiFi	Notes
ESP32C3	ESP32-C3	✅	Cost-effective, WiFi + BLE
ESP32C6	ESP32-C6	✅	WiFi 6, low power
ESP32S3	ESP32-C3	✅	Dual-core, AI, camera support
RP2040	RP2040	❌	No WiFi, use with external WiFi

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)

Board	SDA	SCL
ESP32C3	D4	D5
ESP32S3	D7	D6
RP2040	D6	D7

SPI

Board	MOSI	MISO	SCLK
ESP32C3	D10	D9	D8
ESP32S3	D11	D9	D10
RP2040	D10	D9	D8

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

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

WiFi Not Connecting

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

I2C/SPI Not Working

Check pin mappings for your board
Enable scan: true for I2C
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

Error	Solution
`Invalid YAML syntax`	Check indentation (use 2 spaces)
`esphome: command not found`	Run `pip install esphome`
`Board not found`	Verify board name (e.g., `esp32-c3-devkitm-1`)
`I2C bus not found`	Check I2C pins with `/xiao` skill

Common esphome CLI Commands

Command	Purpose
`esphome config <file>`	Validate YAML configuration
`esphome compile <file>`	Compile firmware
`esphome run <file>`	Compile and upload
`esphome logs <file>`	View device logs

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

Use substitutions for device names and common values
Enable OTA for wireless updates
Use secrets for sensitive data
Enable logging during development
Add status LED for visual feedback
Use packages for reusable configurations
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:

Arduino	ESPHome
C++ code	YAML config
Manual polling	Automated updates
No HA integration	Native HA integration
Complex OTA	Built-in OTA
Manual WiFi	ESPHome WiFi

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+