ESPHome Component

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

Requirements

ESPHome installed and configured
ESP-IDF framework (required for Wi-Fi CSI support)
Existing ESPHome configuration (TOMMY integrates with your current setup)
Running TOMMY server (ESPHome downloads the sensor_tommy component from it at compile time, see External Component Source)

Shelly devices

Before flashing ESPHome on a Shelly, it is highly recommended to take a full backup of the device as one full-chip read. A raw dump containing the bootloader, partition table, OTA slots, NVS, and the factory NVS. Without it, you may have issues regaining factory calibrations, Matter provisioning keys, and similar data.

Bluetooth Proxy Compatibility

If you're using Bluetooth Proxy alongside TOMMY, be aware that the BLE software stack on the ESP32 consumes a significant amount of RAM. If you experience crashes, you might need to either use devices with more RAM or PSRAM, or use dedicated devices for the Bluetooth proxy.

If your ESP32 module has PSRAM available, enable it to help with memory constraints. See the ESPHome PSRAM documentation for details on how to enable it.

Configuration

Add the following to your ESPHome device YAML.

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

external_components:
  - source:
      type: git
      url: http://homeassistant.local:8090/tommy-esphome
      ref: main
    components: [ sensor_tommy ]
    refresh: 2min

sensor_tommy:
  # Option 1: Automatic (mDNS)
  discovery: mdns

  # Option 2: Manual Discovery
  # discovery: manual
  # instance_ip: "192.168.x.x"
  # udp_relay_port: 8547

  # Mesh networks only
  # mesh_network_pin_bssid: "AA:BB:CC:DD:EE:FF"

  # ESP32-C3 Super Mini only
  # esp32c3_supermini_optimizations: true
  
  # Seeed Studio XIAO ESP32C6 only
  # xiao_esp32c6_antenna: internal  # or: external

External Component Source

ESPHome downloads the sensor_tommy component from your TOMMY server. The firmware is bundled into the server so that firmware and server always stay in sync.

The server must be running when you compile, and the url in external_components must point to it. homeassistant.local works when TOMMY runs as a Home Assistant add-on. Otherwise, replace it with the hostname or IP address of the machine running TOMMY. The port is TOMMY's file server HTTP port (default 8090).

Automatic configuration changes

TOMMY automatically changes parts of your ESPHome configuration that are required for TOMMY to function. You do not need to set those yourself. All changes are logged during compilation, for example:

WARNING TOMMY edited some of your ESPHome config for compatibility:
  esp32.framework.version: 5.5.5 -> 5.5.1
  esp32.framework.source: (unset) -> https://github.com/espressif/esp-idf/releases/download/v5.5.1/esp-idf-v5.5.1.zip
  esp32.toolchain: (unset) -> esp-idf
  esp32.framework.sdkconfig_options.CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM: (unset) -> 128
  esp32.framework.sdkconfig_options.CONFIG_ESP_WIFI_DYNAMIC_TX_BUFFER_NUM: (unset) -> 128
  esp32.framework.sdkconfig_options.CONFIG_ESP_WIFI_CSI_ENABLED: (unset) -> y
  esp32.framework.sdkconfig_options.CONFIG_ESP_WIFI_AMPDU_TX_ENABLED: (unset) -> n
  esp32.framework.sdkconfig_options.CONFIG_ESP_WIFI_AMPDU_RX_ENABLED: (unset) -> n
  esp32.framework.sdkconfig_options.CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE: (unset) -> n
  esp32.framework.sdkconfig_options.CONFIG_PM_ENABLE: (unset) -> n
  esp32.framework.sdkconfig_options.CONFIG_ESP_TASK_WDT_TIMEOUT_S: (unset) -> 30
  wifi.power_save_mode: LIGHT -> NONE

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

On mesh networks, pin all devices in a zone to the same access point with mesh_network_pin_bssid. TOMMY adds that BSSID to your existing Wi-Fi config. If you already use a networks list, it is added to the first entry. If you use top-level ssid and password, they are converted to a networks list with the BSSID.

sensor_tommy:
  discovery: mdns
  mesh_network_pin_bssid: "AA:BB:CC:DD:EE:FF"  # Router MAC address (must be uppercase)

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 esp32c3_supermini_optimizations: true to lower Wi-Fi TX power to 8.5 dBm.

Leave it out for any other ESP32-C3 board.

sensor_tommy:
  discovery: mdns
  esp32c3_supermini_optimizations: true

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

Integration with Existing Components

TOMMY works alongside your existing ESPHome components:

# Your existing components continue to work
binary_sensor:
  - platform: gpio
    pin: GPIO0
    name: "Button"

# TOMMY component runs in parallel
sensor_tommy:
  discovery: mdns

Flashing Your Device

After updating your ESPHome configuration:

Compile and upload using your normal ESPHome workflow
Monitor logs to verify TOMMY component initialization
Check Devices in the TOMMY dashboard to confirm the device appears

Some boards need to be put into Firmware Download Mode before ESPHome can flash them over USB or UART. Connect the device, then hold the Boot button, press Reset, and release both. If the device still fails to connect, check your board's documentation for how to enter Firmware Download Mode.

Troubleshooting

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.

ESPHome Component

On this page