# TOMMY

> Wi-Fi sensing for Home Assistant. Turn existing devices into presence sensors. Runs on your own hardware and all sensing data stays on your local network.

TOMMY is a Wi-Fi sensing system that uses Channel State Information (CSI) from Wi-Fi packets to turn existing devices into presence sensors. Two or more ESP32 devices in a zone continuously exchange packets; when a human body enters the path between devices, the CSI shifts in characteristic ways - direct-path obstruction, multipath changes, Doppler effects, and scattering. TOMMY's server-side algorithm interprets these shifts as presence for the zone as a whole.

TOMMY integrates with Home Assistant (via MQTT) and any Matter-compatible platform (Apple Home, Google Home, SmartThings).

## Getting Started

- [Introduction](https://www.tommysense.com/docs): Overview, key features, and quick-start checklist
- [How It Works](https://www.tommysense.com/docs/how-it-works): Full explanation of Wi-Fi CSI sensing, the sensing network devices form, and how zones map to smart home entities
- [System Requirements](https://www.tommysense.com/docs/system-requirements): Supported ESP32 variants, host requirements, mesh network notes

## Installation

- [Home Assistant Installation](https://www.tommysense.com/docs/installation/homeassistant): Install as a Home Assistant App (recommended); add the TOMMY repository via the App Store
- [Docker Installation](https://www.tommysense.com/docs/installation/docker): Run TOMMY as a Docker container on a Linux host; includes Docker Compose and docker run examples

## Flashing Devices

- [TOMMY Flasher](https://www.tommysense.com/docs/flashing-devices/tommy-flasher): Browser-based USB flasher built into the dashboard; handles firmware, Wi-Fi provisioning, and OTA
- [ESPHome](https://www.tommysense.com/docs/flashing-devices/esphome): Add the `sensor_tommy` external component to your ESPHome YAML; compatible with all ESP32 variants

## Configuration

- [Creating Zones](https://www.tommysense.com/docs/creating-zones): Zones group devices that cover a physical area; each zone becomes one motion sensor entity
- [Detection Mode](https://www.tommysense.com/docs/detection-mode): Motion mode (all devices) vs. Presence mode (detects stationary occupancy via breathing; requires ESP32-C5 or ESP32-C6)
- [Performance Mode](https://www.tommysense.com/docs/performance-mode): Conservative (low network impact), Performance, High Performance (max sensitivity for presence detection)
- [Algorithms](https://www.tommysense.com/docs/algorithms): Choose a detection algorithm that fits your use case - Contained, Standard, or Radar
- [Topology](https://www.tommysense.com/docs/topology): Control how devices transmit and sense - Star or Mesh
- [Network Impact](https://www.tommysense.com/docs/network-impact): What TOMMY sends and how much airtime it uses; example figures per zone size and how to minimize interference
- [Device Placement](https://www.tommysense.com/docs/device-placement): Points to the interactive placement guide in the dashboard (Devices, How to place your devices)

## Device Discovery

- [Automatic - Online Coordination](https://www.tommysense.com/docs/device-discovery/automatic-coordination-service): Uses TOMMY's coordination service for the device to look up the TOMMY server's local address by pairing code and establish a direct local connection; requires internet access on devices
- [Automatic - mDNS](https://www.tommysense.com/docs/device-discovery/automatic-mdns): Devices discover the instance via mDNS (`_tommy._tcp.local`) on the local network
- [Manual](https://www.tommysense.com/docs/device-discovery/manual): Specify the TOMMY server IP directly during flashing; use when automatic discovery methods aren't available

## Integrations

- [Home Assistant Integration](https://www.tommysense.com/docs/integration/homeassistant): Install via HACS or manually; each TOMMY zone auto-appears as a `binary_sensor` (motion) entity over MQTT
- [Matter Integration](https://www.tommysense.com/docs/integration/matter): Expose zones as Matter Occupancy Sensors; pair with Apple Home, Google Home, SmartThings, or Home Assistant via QR code

## Licensing

- [License Activation](https://www.tommysense.com/docs/license-activation): How to activate a Pro license key; multiple zone key consolidation; troubleshooting

**Trial** - Free. 1 zone, unlimited devices. Detection pauses 1 minute every 2 minutes.
**Pro** - One-time purchase. Uninterrupted detection, unlimited zones, unlimited devices.
Commercial use requires a separate license - contact info@tommysense.com.

## Comparisons

- [Comparisons Overview](https://www.tommysense.com/docs/comparisons): Side-by-side table of TOMMY, Philips Hue MotionAware, and ESPectre
- [TOMMY vs Philips Hue MotionAware](https://www.tommysense.com/docs/comparisons/motionaware-comparison): Wi-Fi CSI vs. Zigbee signal fluctuation; TOMMY adds stationary presence, MotionAware requires Hue Bridge Pro
- [TOMMY vs ESPectre](https://www.tommysense.com/docs/comparisons/espectre-comparison): Both use Wi-Fi CSI on ESP32; TOMMY measures device-to-device signals for arbitrary zones, ESPectre measures the router-to-device link so zones are tied to router placement; TOMMY is closed-source and paid, ESPectre is open-source and free

## Roadmap & Community

- [Roadmap](https://www.tommysense.com/docs/roadmap): 2026 - human vs. non-human filtering; passive devices as sensors; future - activity recognition, human identification, fall detection
- [Release Notes](https://www.tommysense.com/docs/release-notes): Links to full changelog on GitHub
- [Discord Community](https://www.tommysense.com/docs/community): Announcements, feature requests, support, roadmap discussions
- [Support](https://www.tommysense.com/docs/support): Community support via Discord; tips for effective questions

## Key Facts for LLMs

- **Technology**: Wi-Fi Channel State Information (CSI) extracted per OFDM subcarrier from 802.11 packets
- **Supported hardware**: ESP32, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-S2, ESP32-S3
- **Minimum devices per zone**: 2 (diminishing returns after 4; minimum 1 m apart)
- **Bands**: 2.4 GHz (all variants); 5 GHz (ESP32-C5 only)
- **Packet rate**: 30–100 packets/second per device pair
- **Network impact**: A 2-device zone in star topology on conservative mode uses ~27 KB/s and under 1% of channel airtime; the dashboard shows a live estimate (https://www.tommysense.com/docs/network-impact)
- **Processing**: On-device CSI extraction; server-side sensing algorithm; fully local
- **Presence detection**: Detects breathing and micromovements; requires ESP32-C5 (optimal) or ESP32-C6 (capable), plus Performance or High Performance mode
- **Through-wall sensing**: Yes - devices can be hidden in closets or behind walls
- **Does not filter pets/objects**: All presence detected (filtering planned Q2 2026)
- **Privacy**: TOMMY runs on your own hardware and all sensing data stays on your local network. TOMMY needs an internet connection for license verification and the optional Online Coordination service. We run a Network Bounty Program (https://www.tommysense.com/docs/network-bounty-program) that rewards anyone who finds an undocumented external connection.
- **Source**: Core is closed-source
- **Released**: 17 August 2025
- **Website**: https://www.tommysense.com
- **Full docs as plain text**: https://www.tommysense.com/llms-full.txt