ESPHome Integration

TOMMY works alongside other ESPHome components, allowing you to add motion sensing to your existing ESPHome devices without replacing your current configuration.

Requirements

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

Supported ESP32 Variants

Variant	Frequency	ESP-IDF Version	Platform Version
ESP32	2.4GHz	5.4.2	Default
ESP32-C3	2.4GHz	5.4.2	Default
ESP32-C5	2.4GHz & 5GHz	5.5.1	55.03.31
ESP32-C6	2.4GHz	5.4.2	Default
ESP32-S2	2.4GHz	5.4.2	Default
ESP32-S3	2.4GHz	5.4.2	Default

Configuration

Select your ESP32 variant to see the appropriate configuration:

esphome:
  # ... your existing configuration

esp32:
  variant: ESP32
  framework:
    type: esp-idf
    version: 5.4.2
    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:
  power_save_mode: NONE

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

sensor_tommy:
  # Optional: Configure instance details
  # instance_ip: "192.168.x.x"
  # file_server_http_port: 8090
  # file_server_https_port: 8091

esphome:
  # ... your existing configuration

esp32:
  variant: ESP32C3
  framework:
    type: esp-idf
    version: 5.4.2
    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:
  power_save_mode: NONE

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

sensor_tommy:
  # Optional: Configure instance details
  # instance_ip: "192.168.x.x"
  # file_server_http_port: 8090
  # file_server_https_port: 8091

esphome:
  # ... your existing configuration

esp32:
  variant: ESP32C5
  framework:
    type: esp-idf
    version: 5.5.1
    platform_version: 55.03.31
    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:
  power_save_mode: NONE

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

sensor_tommy:
  # Optional: Configure instance details
  # instance_ip: "192.168.x.x"
  # file_server_http_port: 8090
  # file_server_https_port: 8091

esphome:
  # ... your existing configuration

esp32:
  variant: ESP32C6
  framework:
    type: esp-idf
    version: 5.4.2
    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:
  power_save_mode: NONE

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

sensor_tommy:
  # Optional: Configure instance details
  # instance_ip: "192.168.x.x"
  # file_server_http_port: 8090
  # file_server_https_port: 8091

esphome:
  # ... your existing configuration

esp32:
  variant: ESP32S2
  framework:
    type: esp-idf
    version: 5.4.2
    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:
  power_save_mode: NONE

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

sensor_tommy:
  # Optional: Configure instance details
  # instance_ip: "192.168.x.x"
  # file_server_http_port: 8090
  # file_server_https_port: 8091

esphome:
  # ... your existing configuration

esp32:
  variant: ESP32S3
  framework:
    type: esp-idf
    version: 5.4.2
    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:
  power_save_mode: NONE

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

sensor_tommy:
  # Optional: Configure instance details
  # instance_ip: "192.168.x.x"
  # file_server_http_port: 8090
  # file_server_https_port: 8091

Configuration Options

Optional Settings

The sensor_tommy component supports optional configuration for network discovery:

sensor_tommy:
  instance_ip: "192.168.x.x"        # IP of your TOMMY instance
  file_server_http_port: 8090         # HTTP port (default: 8090)
  file_server_https_port: 8091        # HTTPS port (default: 8091)

These settings provide a fallback when mDNS auto-discovery fails.

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 instance 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:
  # TOMMY configuration

Flashing Your Device

After updating your ESPHome configuration:

Compile and upload using your normal ESPHome workflow
Monitor logs to verify TOMMY component initialization
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 instance is reachable
Monitor ESPHome logs for error messages

Discovery Problems

Add manual instance configuration as fallback
Check network connectivity between device and TOMMY instance
Verify mDNS is working on your network

External Components Guide

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

ESPHome Integration

On this page