How It Works

How TOMMY goes from install to entities in your smart home, and the Wi-Fi sensing technology behind it.

TOMMY turns Wi-Fi devices into motion and presence sensors that detect occupancy through walls and obstacles. This page walks through the full setup and then goes deeper into the technology behind it.

Overview

Install TOMMY

TOMMY runs as a self-hosted server on your local network. You can install it as a Home Assistant App or run it as a Docker container. Either way, the install gives you:

The TOMMY server. Handles device coordination, configuration, OTA updates, sensing algorithms, and smart home integrations.
The TOMMY dashboard. A web UI for managing zones, devices, and settings for optimizing sensing.

Everything runs on your own network. All sensing and processing happen locally. No sensing data ever leaves your network. An internet connection is required for license activation and verification.

Create a zone

A zone is a logical group of devices that cover the same physical area. Each zone maps to a single entity in your smart home.

Zones can span multiple rooms. Wi-Fi signals pass through walls, so a zone's coverage is defined by where the devices are placed, not by room boundaries.
Every device must belong to a zone to contribute to detection.
Devices in the same zone must use the same Wi-Fi band (2.4 GHz or 5 GHz).

See Creating Zones for the full guide.

Flash at least 2 devices

TOMMY runs on ESP32 microcontrollers. Supported variants:

ESP32
ESP32-C3
ESP32-C5
ESP32-C6
ESP32-S2
ESP32-S3

You can flash devices in two ways:

From the dashboard using the TOMMY flasher. Plug the board in over USB and flash it from the UI.
Through ESPHome. If you already run ESPHome, add the TOMMY component to your YAML config.

A zone needs at least two devices so packets can flow between them and the receiving side can measure how the Wi-Fi signal changes along the way.

Devices form a mesh

Once powered and assigned to a zone, the devices pair up and continuously exchange small Wi-Fi packets with each other. This traffic has two purposes:

Coordination. Keep the devices in sync within the zone.
Sensing. Each packet carries reference signals (pilot tones) that the receiving device uses to measure the state of the Wi-Fi channel.

The exchange runs at a rate high enough to capture real-time motion, typically between 30 and 100 packets per second per device pair depending on your chosen performance mode.

Your body disrupts the signal

Every received packet is analysed by the firmware to extract Channel State Information (CSI): a per-subcarrier description of how the Wi-Fi signal was affected on its way from transmitter to receiver.

CSI captures:

Signal amplitude across each OFDM subcarrier.
Phase shifts at different frequencies.
Frequency response of the channel.
Multipath characteristics, meaning how the signal reflected, scattered, and diffracted on the way.

When a human body enters the space between two devices, CSI changes in characteristic ways:

Direct-path obstruction: the line-of-sight component weakens.
Multipath changes: reflections off walls and furniture shift as the body adds and removes reflection paths.
Doppler effects: moving body parts introduce small frequency shifts in reflected signal components.
Scattering: the human body scatters Wi-Fi signals differently than static objects.

Even small movements show up in CSI. The chest rising and falling during breathing is enough to perturb the signal at 2.4 GHz and 5 GHz wavelengths. That is why TOMMY can report presence (a person in the zone, even standing still) in addition to motion (a person actively moving). Presence detection has specific hardware and configuration requirements; see Detection Mode for details.

Server-side, TOMMY continuously analyses the CSI stream coming in from each device pair in a zone using a proprietary algorithm to interpret the signal as motion or presence for the zone as a whole.

Connect to Home Assistant or Matter

Each zone surfaces as an entity in your smart home:

Home Assistant: through the Home Assistant integration, each zone appears as a binary_sensor with live updates.
Matter: through the Matter integration, each zone is exposed as a Matter occupancy sensor to any Matter-compatible controller.

Use these entities in your automations for lights, HVAC, alarms, or routines.

Limitations and Considerations

Current Limitations

All motion detected: No distinction between humans, pets, or objects (planned, see roadmap).

Environmental Factors

The environment affects sensing accuracy and range. Several factors can enhance or limit TOMMY's motion detection capabilities:

Walls and building materials: Different materials affect signal penetration differently. Drywall allows signals to pass through, while concrete and brick can significantly reduce range. Thicker walls require devices to be placed closer together.
Room size and layout: Larger spaces may require more devices to maintain adequate coverage. Open floor plans generally provide better signal propagation than spaces with many small rooms.
Furniture placement: Dense furniture arrangements can create signal shadows or dead zones. Device placement can help overcome these obstacles.
Reflective surfaces: Mirrors, large windows, and metal surfaces can cause signal reflections that create multipath effects. While multipath effects are used for detection, excessive reflections can sometimes cause false positives outside the detection area.
Large metal objects: Appliances, filing cabinets, and other large metal objects can block or redirect Wi-Fi signals, potentially creating blind spots or false positives.
Device spacing: The distance between TOMMY devices affects both network reliability and sensing range. Devices placed too far apart may have reduced motion detection abilities.
Interference: Other Wi-Fi networks, Bluetooth devices, and electronic equipment operating on similar frequencies can introduce noise that affects CSI data quality.

How It Works

On this page