# TOMMY

> Wi-Fi sensing for Home Assistant. Turn ESP32 devices into motion and presence sensors that detect occupancy through walls - entirely on your local network.

TOMMY uses Channel State Information (CSI) extracted from Wi-Fi packets to detect motion and presence. 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 motion or presence for the zone as a whole.

Everything runs locally. No cloud. No subscription. An internet connection is only required for license activation and periodic verification. 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 device mesh, 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)
- [Boundary Mode](https://www.tommysense.com/docs/boundary-mode): Control how strictly detection is isolated to the zone - Precise, Balanced, Sensitive, or Custom
- [Device Placement](https://www.tommysense.com/docs/device-placement): Placement principles, zone design strategy, Signal Visualizer usage, troubleshooting

## Device Discovery

- [Automatic - Online Coordination](https://www.tommysense.com/docs/device-discovery/automatic-coordination-service): Devices find the TOMMY instance via TOMMY's coordination server (TOMMY Flasher only)
- [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 instance IP directly during flashing; use when mDNS is unavailable

## 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 (1 zone)** - One-time purchase. Uninterrupted detection, 1 zone, unlimited devices.
**Pro (Unlimited zones)** - 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 mesh 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 uses a mesh topology with arbitrary zones, ESPectre uses a star topology (router-to-device path); TOMMY is closed-source and paid, ESPectre is open-source and free

## Roadmap & Community

- [Roadmap](https://www.tommysense.com/docs/roadmap): Q2 2026 - human vs. non-human filtering; Q3 2026 - 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 (5 GHz, best for presence), 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
- **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 movement detected (filtering planned Q2 2026)
- **Privacy**: All sensing data stays on the local network; only license key + non-personal machine ID sent externally
- **Source**: Core is closed-source; Home Assistant integration and ESPHome component are open-source
- **Released**: 17 August 2025
- **Website**: https://www.tommysense.com
- **Full docs as plain text**: https://www.tommysense.com/llms-full.txt