ESPHome Component

Requirements

• ESPHome installed and configured
• ESP-IDF framework (required for Wi-Fi CSI support)
• Existing ESPHome configuration (TOMMY integrates with your current setup)

Configuration

Add the following to your ESPHome device YAML. Replace the variant value with the one matching your chip from the table below.

esphome:
  # ... your existing configuration
  min_version: 2026.2.4

esp32:
  # ... your existing configuration
  variant: ESP32  # see variant table below
  framework:
    type: esp-idf
    version: 5.5.1
    sdkconfig_options:
      CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM: '128'
      CONFIG_ESP_WIFI_DYNAMIC_TX_BUFFER_NUM: '128'
      CONFIG_ESP_WIFI_CSI_ENABLED: y
      CONFIG_ESP_WIFI_AMPDU_TX_ENABLED: n
      CONFIG_ESP_WIFI_AMPDU_RX_ENABLED: n
      CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE: n
      CONFIG_PM_ENABLE: n
      CONFIG_ESP_TASK_WDT_TIMEOUT_S: '30'

wifi:
  # ... your existing configuration
  power_save_mode: NONE
  # ESP32-C3 Super Mini only: reduce TX power to avoid connectivity issues.
  # output_power: 8.5
  # For mesh networks, you must specify the BSSID (requires using the networks list):
  # networks:
  # - ssid: "YourNetworkName"
  #   bssid: "AA:BB:CC:DD:EE:FF"  # Router MAC address (must be uppercase)
  #   password: "yourpassword"

external_components:
  - source: github://tommy-sense/esphome
    components: [ sensor_tommy ]
    refresh: 5min

sensor_tommy:
  discovery: mdns  # see Discovery section below for all options
  # xiao_esp32c6_antenna: internal  # Seeed Studio XIAO ESP32C6 only, see section below

Discovery

The sensor_tommy component supports two discovery modes on ESPHome. Online Coordination is not available on ESPHome devices.

Automatic (mDNS)

The device discovers the TOMMY server via mDNS on your local network. Requires that multicast traffic reaches the device. See Automatic (mDNS) for details.

sensor_tommy:
  discovery: mdns

Manual

Connects the device directly to the TOMMY server using the IP address and port. This requires stable IP addresses on both the server and the device. See Manual Discovery for details.

sensor_tommy:
  discovery: manual
  instance_ip: "192.168.x.x"   # required, IP of your TOMMY server
  udp_relay_port: 8547         # optional, default: 8547

BSSID for Mesh Networks

For mesh networks, you must specify the BSSID using the networks list format:

wifi:
  power_save_mode: NONE
  networks:
  - ssid: "YourNetworkName"
    bssid: "AA:BB:CC:DD:EE:FF"  # Router MAC address (must be uppercase)
    password: "yourpassword"

Please refer to the information about mesh networks in system requirements.

ESP32-C3 Super Mini

The ESP32-C3 Super Mini has a compact antenna that can cause connectivity issues at full TX power. Set output_power: 8.5 in your wifi: block to reduce it.

Leave it out for any other ESP32-C3 board.

wifi:
  power_save_mode: NONE
  output_power: 8.5

Seeed Studio XIAO ESP32C6 Antenna

The Seeed Studio XIAO ESP32C6 has an RF switch for selecting between the built-in ceramic antenna and an external antenna via the UFL connector. Set xiao_esp32c6_antenna in your sensor_tommy block to control it.

Leave it out for any other ESP32C6 board.

Built-in ceramic antenna

sensor_tommy:
  discovery: mdns
  xiao_esp32c6_antenna: internal

External UFL antenna

sensor_tommy:
  discovery: mdns
  xiao_esp32c6_antenna: external

SDK Configuration Options Explained

Each sdkconfig_options setting is configured for TOMMY's performance and reliability:

• CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM: '128' Sets the number of dynamic receive buffers to 128. This increases Wi-Fi receive buffer capacity, improving performance and reducing packet loss when handling high-frequency CSI data.

• CONFIG_ESP_WIFI_DYNAMIC_TX_BUFFER_NUM: '128' Sets the number of dynamic transmit buffers to 128. This increases Wi-Fi transmit buffer capacity, ensuring reliable data transmission to your TOMMY server without delays or dropped packets.

• CONFIG_ESP_WIFI_CSI_ENABLED: y Enables Wi-Fi Channel State Information (CSI) support. Required for TOMMY's motion detection capabilities, allowing the device to capture Wi-Fi signal characteristics used for motion sensing.

• CONFIG_ESP_WIFI_AMPDU_TX_ENABLED: n Disables Aggregated MAC Protocol Data Unit (AMPDU) transmission. AMPDU aggregation can interfere with CSI data collection, so disabling it improves CSI measurement accuracy.

• CONFIG_ESP_WIFI_AMPDU_RX_ENABLED: n Disables AMPDU reception. Similar to TX, disabling RX aggregation helps maintain consistent CSI data quality by preventing packet bundling that could affect signal analysis.

• CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE: n Disables power management when the Wi-Fi station is disconnected. TOMMY requires continuous communication between devices, and power saving modes can interrupt this communication, causing missed motion events.

• CONFIG_PM_ENABLE: n Disables overall power management. TOMMY devices need to maintain constant Wi-Fi connectivity and cannot enter sleep modes, as motion detection requires real-time signal monitoring.

• CONFIG_ESP_TASK_WDT_TIMEOUT_S: '30' Sets the task watchdog timeout to 30 seconds. During bootup and initialization, TOMMY components may take longer than the default timeout to initialize. This prevents premature reboots that could occur during the startup process.

Integration with Existing Components

TOMMY works alongside your existing ESPHome components:

# Your existing components continue to work
sensor:
  - platform: dht
    pin: GPIO4
    temperature:
      name: "Temperature"
    humidity:
      name: "Humidity"

switch:
  - platform: gpio
    pin: GPIO2
    name: "LED"

# TOMMY component runs in parallel
sensor_tommy:
  discovery: mdns

Flashing Your Device

After updating your ESPHome configuration:

1. Compile and upload using your normal ESPHome workflow
2. Monitor logs to verify TOMMY component initialization
3. Check the TOMMY dashboard to confirm the device appears

Troubleshooting

Compilation Issues

• Verify ESP-IDF framework configuration
• Check ESP32 variant matches your hardware
• Ensure all required sdkconfig options are set

Runtime Issues

• Check Wi-Fi connection stability
• Verify TOMMY server is reachable
• Monitor ESPHome logs for error messages

Discovery Problems

• For mDNS: verify the device and TOMMY server are on the same network segment
• For manual: verify the instance IP is correct and the device can reach it

External Components Guide

Need help with ESPHome external components? Follow the ESPHome External Components guide for detailed instructions.