# Algorithms

Wi-Fi signals pass through walls and reflect off surfaces, so presence from neighboring rooms can leak into a
zone. For some setups that's exactly what you want. For others it's a constant source of false triggers.
TOMMY Zero ships with algorithms that either lean into that sensitivity or try to contain it, with the default
sitting somewhere in the middle.

## Contained

Reduces false positives from outside the zone as long as the zone is separated by walls. May miss stationary presence.

## Standard

Reliable detection within the zone with minimal leakage. The default choice for most zones.

## Radar

Captures all presence detectable by the devices. May detect presence outside the intended zone.


# Discord Community

import { TrackedDiscordLink } from '@/components/docs/TrackedDiscordLink';

<TrackedDiscordLink />

## What You'll Find on Discord

* **Announcements**: Major release notifications and important updates
* **Roadmap**: Feature voting and development priority discussions
* **Development Updates**: Progress reports and behind-the-scenes insights
* **Feature Requests**: Submit feature requests and provide community input
* **Support**: Real-time help from experienced users and developers for installation, configuration, and troubleshooting
* **Discussions**: Real-time discussions with developers and power users

## What We Look For

* **Active participation** in community discussions
* **Constructive feedback** on features and improvements
* **Bug reporting** and testing assistance
* **Feature suggestions** and use case sharing
* **Help with documentation** and community support

## Community Influence

Your input shapes TOMMY's development:

* **Feature prioritization** based on community votes
* **Implementation feedback** on new features and updates
* **Use case validation** for new capabilities
* **Documentation improvements** from user feedback

## Open Development Process

* **Public roadmap** with clear timelines
* **Transparent decision-making** process
* **Community-driven priorities** and features

## Community Guidelines

* **Be respectful** and constructive in all interactions
* **Stay on topic** in designated channels
* **Search before asking** to avoid duplicate questions
* **Share knowledge** and help other community members
* **Provide detailed feedback** when testing features


# Contact

import { CompanyInformation } from '@/components/docs/CompanyInformation';

## General Inquiries

For any general questions, email [info@tommysense.com](mailto:info@tommysense.com).

## Support

For technical support, installation help, troubleshooting, and community discussions, please join our [Discord Community](/docs/community). Our community is active 24/7 and provides real-time help from experienced users and developers.

<CompanyInformation />


# Detection Mode

## Motion Detection

Motion detection captures bigger movements such as walking, waving hands, sitting down, getting up, etc. All devices support this mode.

### Requirements

This mode is supported by all devices and configurations.

## Presence Detection

Presence detection enables TOMMY Zero to detect breathing and micromovements, meaning it can detect when someone is present in a zone even when they're not moving around.

### Requirements

| Requirement          | Capable            | Optimal                         |
| -------------------- | ------------------ | ------------------------------- |
| **Devices**          | ESP32-C6           | ESP32-C5                        |
| **Band**             | 2.4 GHz            | 5 GHz                           |
| **Device Count**     | 2 or more          | 4 or more                       |
| **Topology**         | Star               | Mesh                            |
| **Performance Mode** | Conservative       | Performance or High Performance |
| **Algorithm**        | Contained          | Standard or Radar               |
| **Hold Time**        | 10 seconds or more | 10 seconds or more              |

#### Optimal Configuration

Will detect stationary presence, as long as you are not holding your breath.

#### Capable Configuration

Will detect stationary presence, as long as you are not holding your breath, but might struggle with shallow breathing.


# Device Placement

Where you put devices matters more than how many you add. The dashboard has a detailed, interactive guide for optimal placement, with diagrams you can follow as you set up a zone. It covers how [topology](/docs/topology) changes coverage, what [motion vs presence](/docs/detection-mode) asks of placement, and how two devices differ from three or more.

## How to open the guide

Open **Devices → Device placement** in the sidebar. You can also open it from a [zone](/docs/creating-zones/zone): under **Devices**, click **How to place your devices**.


# How It Works

import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';

TOMMY Zero turns Wi-Fi devices into 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

<Steps>
  <Step>
    ### Install TOMMY Zero

    TOMMY Zero runs as a server on your local network. You can install it as a [Home Assistant App](/docs/installation/homeassistant) or run it as a [Docker container](/docs/installation/docker). Either way, the install gives you:

    * **The TOMMY Zero server**. Handles device coordination, configuration, OTA updates, sensing algorithms, and integrations.
    * **The TOMMY Zero dashboard**. A web UI for managing zones, devices, and settings for optimizing sensing.
  </Step>

  <Step>
    ### 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 [Zone](/docs/creating-zones/zone) for the full guide. A [group](/docs/creating-zones/group) is the option that shares one transmitter across several zones.
  </Step>

  <Step>
    ### Flash at least 2 devices

    TOMMY Zero 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](/docs/flashing-devices/tommy-flasher). Plug the board in over USB and flash it from the UI.
    * **Through [ESPHome](/docs/flashing-devices/esphome)**. If you already run ESPHome, add the TOMMY Zero 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.
  </Step>

  <Step>
    ### Devices form a sensing network

    Once powered and assigned to a zone, the devices pair up and continuously exchange small Wi-Fi packets. The zone's [topology](/docs/topology) determines which devices transmit: in star topology a single device broadcasts while the rest listen, in mesh all but one device transmit. This traffic has two purposes:

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

    Each transmitting device broadcasts between 30 and 100 packets per second depending on your chosen [performance mode](/docs/performance-mode), a rate high enough to capture presence in real time.
  </Step>

  <Step>
    ### 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 Zero 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](/docs/detection-mode) for details.

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

  <Step>
    ### Connect to Home Assistant or Matter

    Each zone surfaces as an entity in your smart home:

    * **Home Assistant**: through the [Home Assistant integration](/docs/integration/homeassistant), each zone appears as a `binary_sensor` with live updates.
    * **Matter**: through the [Matter integration](/docs/integration/matter), 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.
  </Step>
</Steps>

## Limitations and Considerations

### Current Limitations

* **All presence detected**: No distinction between humans, pets, or objects (planned, see [roadmap](/docs/roadmap)).

### Environmental Factors

The environment affects sensing accuracy and range. Several factors can enhance or limit TOMMY Zero's presence 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 Zero devices affects both network reliability and sensing range. Devices placed too far apart may have reduced presence detection abilities.

* **Interference**: Other Wi-Fi networks, Bluetooth devices, and electronic equipment operating on similar frequencies can introduce noise that affects CSI data quality.


# Introduction

## Key Features

* **Through-wall sensing**: Occupancy is sensed through walls and obstacles, allowing devices to be hidden in closets, cupboards, or anywhere out of sight
* **Flexible zone coverage**: Create zones that span your entire house with a few devices, or divide areas like "upstairs" and "downstairs" regardless of room boundaries
* **Direction-free setup**: Unlike traditional sensors that need to "look" at specific areas, Wi-Fi sensing monitors the entire area within a zone without requiring careful positioning or aiming
* **No hub required**: TOMMY Zero runs as a Home Assistant App or on a Linux host (Docker) and uses supporting devices to create a sensing network
* **Privacy-focused**: TOMMY Zero runs on your own hardware and all sensing data stays on your local network. It needs an internet connection for license verification and the optional Online Coordination service. We run a [Network Bounty Program](/docs/network-bounty-program) that rewards anyone who finds an undocumented external connection.

## Quick Start

1. Read the [system requirements](/docs/system-requirements) to ensure your setup is compatible
2. Install TOMMY Zero on [Home Assistant](/docs/installation/homeassistant) or [Docker](/docs/installation/docker)
3. Flash your ESP32 devices using the [TOMMY Flasher](/docs/flashing-devices/tommy-flasher) or [ESPHome](/docs/flashing-devices/esphome)
4. [Create zones](/docs/creating-zones/zone) and configure presence detection
5. Integrate with [Home Assistant](/docs/integration/homeassistant) or [Matter ecosystems](/docs/integration/matter)


# License Activation

import { Callout } from 'fumadocs-ui/components/callout';

## Activation Steps

1. Open the TOMMY Zero dashboard
2. Open **Settings → License** in the sidebar
3. Enter your license key (from your purchase email) in the **Activate license** field
4. Click **Activate**

<Callout title="Privacy Information" type="info">
  The TOMMY Zero server communicates with `https://activation.tommysense.com` to activate and validate your license. Only non-personal data (such as your license key and a machine identifier) is transmitted. For details on exactly what is transmitted, see the [Network Communication section of the Privacy Policy](/docs/privacy-policy#network-communication).
</Callout>

## Troubleshooting

**Activation fails:**

* Check your internet connection
* Verify your license key is correct
* Ensure `https://activation.tommysense.com` is accessible from your network
* Check firewall settings that might block HTTPS connections

**License not recognized after activation:**

* Wait a few seconds and refresh the dashboard
* Restart the TOMMY Zero application
* Check application logs for error messages

**Need help?** Contact [info@tommysense.com](mailto:info@tommysense.com) with your license key (first/last 4 chars) and any error messages.


# Network Bounty Program

TOMMY Zero's core is closed source, so the way to verify our local data claims is to sandbox it and inspect its connections yourself. A privacy conscious user would need to do that on every release, which is tedious. That's why we run this bounty program, incentivizing the community to do this check by rewarding anyone who finds undocumented network connections in current releases. Findings are fixed and published.

## The claim we're asking you to test

All sensing data stays on your local network. The only external connections TOMMY Zero makes are license activation and validation, and the optional Online Coordination service, exactly as documented under [Network Communication](/docs/privacy-policy#network-communication) in our privacy policy.

## What qualifies

A valid finding is a **connection leaving your device** (the TOMMY Zero server or a flashed device) to any external destination, or transmitting any data, that is not documented in the privacy policy's Network Communication section. This includes:

* Connections to undocumented hosts or endpoints
* Documented connections transmitting undocumented fields or data
* Any external transmission of sensing data, in any form

## What does not qualify

* Local network traffic (peer-to-peer CSI packets, MQTT, mDNS, dashboard access)
* Traffic generated by your own configuration or third-party software not part of TOMMY Zero.
* If you run the firmware via the ESPHome component, the connection must originate from TOMMY Zero's component, not from other components in your ESPHome configuration
* Connections initiated by your browser when using the dashboard, such as fetching the changelog from TOMMY's GitHub repository, unless those connections transmit sensing data
* DNS lookups for documented hosts
* A renamed field or a different encoding of the same documented data. Fields are documented by their meaning, not their exact wire format. What matters is whether undocumented information leaves your device
* Standard HTTP protocol headers on the documented requests. Requests also carry standard HTTP protocol headers such as Content-Type and a User-Agent identifying the HTTP library. These carry no sensing or user data
* Findings on beta, pre-release, or modified builds
* General security vulnerabilities. This program covers undocumented network communication only. Security issues should be reported to [info@tommysense.com](mailto:info@tommysense.com), but are outside this bounty's scope.

## The bounty

**€250 per release.** The bounty applies to the latest released version of TOMMY Zero. One bounty is paid per release regardless of how many undocumented connections are found in it, and the first valid submission received claims it. A submission must be received while the version it targets is the latest release, unless the undocumented connection is still present in the newer release. Ordering between submissions, and between submissions and releases, is decided by submission timestamps and release timestamps in the changelog.

## Submitting a finding

Email **[bounty@tommysense.com](mailto:bounty@tommysense.com)** with:

* The TOMMY Zero version (server and firmware)
* A packet capture or equivalent evidence showing the connection
* Enough detail about your setup for us to reproduce it

We confirm receipt, verify the finding against the current release, and respond with our conclusion. Valid findings are paid, fixed, and published on this page with credit to the finder (or anonymously, your choice).

## Payment

Payouts are made by bank transfer. To pay you, we need a name and payment details, and we may need basic identity information where required for our accounting or legal obligations. We can't pay anonymous submissions, but we can publish your finding anonymously.

We aim to verify submissions within 14 days, and pay valid findings within 30 days of verification.

## Findings to date

<span style={{ color: "var(--color-fd-muted-foreground)", fontSize: "0.875rem" }}>
  Program started June 12, 2026, covering TOMMY Zero 5.4.0 and later.
</span>

None so far.


# Network Impact

import { Callout } from 'fumadocs-ui/components/callout';

TOMMY Zero shares the Wi-Fi channel with everything else on your network, so it is built to take as little of it as possible. This page explains what it actually sends, what that adds up to in practice, and which settings control it.

## What TOMMY Zero sends

TOMMY Zero's airtime falls into two classes:

* **Sensing broadcasts**. The transmitting devices in a zone broadcast on the channel. The [topology](/docs/topology) controls how many devices transmit: one in star, all but one in mesh. [Performance mode](/docs/performance-mode) sets how often.
* **CSI backhaul**. Every listening device forwards its channel measurements to the TOMMY Zero server through the access point, once for each broadcast it hears.

## Example figures

Star topology, conservative mode, on a 5 GHz HE20 channel. The 2-device zone is one broadcast and one backhaul. The 4-device zone is one broadcast and three backhauls.

| Zone                                   | Channel utilization |
| -------------------------------------- | ------------------- |
| 2 devices (1 transmitter, 1 listener)  | 0.77%               |
| 4 devices (1 transmitter, 3 listeners) | 1.62%               |

<Callout title="Live estimate in the dashboard" type="info">
  Open **Network impact** under **Stats** in the sidebar to see the estimated airtime your zones use per band and channel, with a per-zone breakdown.
</Callout>

## Tips to reduce impact

* **[Topology](/docs/topology)** sets how many devices transmit. Star keeps it to a single transmitter per zone regardless of zone size, while mesh scales with the number of devices in the zone.
* **[Performance Mode](/docs/performance-mode)** sets the broadcast rate. Conservative is recommended for most users. Higher modes increase Wi-Fi traffic.
* **Band** matters: zones on 5 GHz (ESP32-C5) run at higher data rates, so the same traffic takes less airtime, and the band is typically far less congested than 2.4 GHz.
* **Channels** are separate airtime domains. Zones on different bands or access point channels do not compete. On mesh Wi-Fi networks, pin each zone's devices to a different access point than other zones where possible (see the BSSID notes in [system requirements](/docs/system-requirements)). Devices within a zone must share an access point, but spreading zones across access points offloads the traffic. The effect is biggest when the access points run on different channels.

## About the estimates

Airtime is how long TOMMY Zero holds the channel, modelled for the negotiated PHY mode on a strong link between the devices and the access point. Retransmissions on weak links, router settings, and neighboring networks can shift the real numbers, which is why the dashboard's live estimate is the best reference for your setup.


# Performance Mode

## Conservative Mode

Minimizes network interference. May miss fast movements like quick entries into a room. Recommended for most users.

## Performance Mode

Increased transmission rate. Captures fast movements and micro-movements like running, breathing and keyboard typing.

## High Performance Mode

Highest transmission rate. Maximum sensitivity.


# Privacy Policy

import { Callout } from 'fumadocs-ui/components/callout';

## Data Collection Practices

TOMMY does not require marketing opt-ins or operate analytics or behavioral-usage databases. The only marketing list we keep is the optional TOMMY One email list, which you join only by signing up and confirming your email address (described under TOMMY One Email Updates below). The only data we store on our license servers is the minimal information required to enforce your license, such as your license key, a machine identifier, the number of active zones, and the timestamps of license checks. This data is used solely for license activation and validation, never for marketing or profiling. The optional Online Coordination service for device discovery (described under Network Communication below) stores nothing to disk; it holds only your server's local address (e.g. 192.168.1.100:8547) briefly in memory. Additional data may be collected by our third-party service providers, Paddle, Keygen, Resend, and Cloudflare, as described below.

## TOMMY One Email Updates

You can leave your email address on the [TOMMY One page](/one) to get updates and early access. We use it only to email you about TOMMY One, and never share or sell it.

**Confirmation.** After you sign up, we send you an email with a confirmation link. Your address is added to the list only when you open that link. Until then we store nothing beyond the confirmation email itself, which is kept in Resend's sending logs. The link expires after 7 days.

**Country.** When you confirm, we store the country you are in, worked out from your IP address by our hosting provider. We use it only to see where interest in TOMMY One comes from and plan where it ships first. We store the country only, never your IP address or a more precise location.

**Spam protection.** The sign-up form uses Cloudflare Turnstile to tell people from bots. Turnstile runs a check in your browser and receives your IP address and basic browser information, which Cloudflare uses only to detect bots. Our server also keeps your IP address in memory for up to 10 minutes to limit repeated sign-ups. It is not written to disk.

**Unsubscribing.** Every update email has an unsubscribe link. You can also ask us to delete your address by emailing [info@tommysense.com](mailto:info@tommysense.com).

## Third-Party Service Providers

### Paddle Inc.

Purchase transactions are processed by Paddle Inc., our Merchant of Record. Paddle collects information necessary to process and manage transactions in accordance with the terms accepted at the time of purchase. For full details on Paddle's data collection and privacy practices, see [Paddle's Privacy Policy](https://www.paddle.com/legal/privacy).

### Keygen LLC

License management and activation services are provided by Keygen LLC. Keygen stores only your email address as personally identifiable information. All data transmitted to Keygen is sent over HTTPS. For information on how Keygen stores and secures your data, see their privacy policy at [keygen.sh/privacy](https://keygen.sh/privacy/).

### Resend, Inc.

Emails for the TOMMY One list are sent by Resend, Inc., which also stores the list. Resend holds your email address, your country, whether you have unsubscribed, and delivery logs for the emails we send you. For details, see [Resend's Privacy Policy](https://resend.com/legal/privacy-policy).

### Cloudflare, Inc.

The TOMMY One sign-up form is protected by Cloudflare Turnstile. Cloudflare processes the data described under TOMMY One Email Updates above only to check whether a visitor is a person. For details, see [Cloudflare's Turnstile Privacy Addendum](https://www.cloudflare.com/turnstile-privacy-policy/).

## Network Communication

TOMMY Zero runs on your own hardware, and all sensing data flows peer to peer on your local network. TOMMY Zero needs an active internet connection for two things.

**License verification.** TOMMY Zero verifies your license when it starts and periodically while running.

**Online Coordination (optional).** Your TOMMY Zero server registers its local network address (e.g. 192.168.1.100:8547) with our coordination service so your devices can find it using a pairing code and establish a direct local connection. This helps in setups where mDNS doesn't reach across the network, or where the server and devices don't have fixed addresses for manual setup. It is enabled by default and can be disabled in the dashboard under Settings > Discovery methods.

The fields transmitted in each case are listed below.

<Callout title="License activation and validation" type="info">
  The server communicates with `https://activation.tommysense.com`. Only the fields listed below are transmitted. We never collect or transmit any sensing data. These fields are used solely for license enforcement.

  **During activation** (when you activate or add a license key):

  * **License key**: The license key you are activating
  * **Existing license key**: The license key already on this device, if any (used for consolidation)
  * **Machine fingerprint**: A non-personal per-machine identifier
  * **App version**: The version of TOMMY Zero you are running

  **On application start** (when TOMMY Zero starts up, and again if it reconnects to the license server):

  * **Previous machine ID**: The machine ID previously assigned on a prior run. Used to request that the activation server releases the old claim on the license if it is stale
  * **Machine fingerprint**: A non-personal per-machine identifier
  * **License key**: Your license key
  * **App version**: The version of TOMMY Zero you are running
  * **Active zones**: The number of zones currently in use
  * **Session nonces**: A list of randomly generated, non-personal, per-session identifiers for each active device. Sent so the server can issue a signed per-device session credential that ties your devices' operation to a valid, current license

  **Heartbeat** (periodically while the application is running, and also briefly when a device joins or reboots and when the licensing session starts or restarts):

  * **Machine ID**: The per-machine identifier assigned by the activation server when your device was registered
  * **License key**: As on application start (see above)
  * **App version**: As on application start (see above)
  * **Active zones**: As on application start (see above)
  * **Device identifiers and session nonces**: As on application start (see above)

  **On license session stop** (when TOMMY Zero shuts down, and when the licensing session restarts while TOMMY Zero keeps running, such as when you save configuration changes in the dashboard, switch or detach a license, or complete an activation):

  * **Machine ID**: The per-machine identifier assigned by the activation server when your device was registered. Sent so the server releases this device's claim on the license
</Callout>

<Callout title="Online Coordination (optional)" type="info">
  Your TOMMY Zero server and devices use our coordination service at `https://coordination.tommysense.com`. The server registers its local network address (e.g. 192.168.1.100:8547) so your devices can find it using a pairing code and establish a direct local connection. This helps in setups where mDNS doesn't reach across the network, or where the server and devices don't have fixed addresses for manual setup. It is enabled by default and can be disabled in the dashboard under Settings > Discovery methods. Only the metadata listed below is transmitted.

  **From the TOMMY Zero server** (registers so devices can find it):

  * **Pairing code**: The code that links your devices to your server
  * **Role**: `server`
  * **Local addresses**: The server's local network IP address(es) and port, used to establish a direct connection

  **From each device**:

  * As of version 5.3.0, devices look up the server using the pairing code only. No device identifier, MAC address, or device IP is transmitted to the coordination service.
  * On versions before 5.3.0, devices still transmit a MAC-derived identifier (e.g. `esp32-<mac>`) and their local IP address. The coordination server now ignores and never stores device registrations. Updating to 5.3.0 stops the device sending it entirely.

  The server's entry is held in memory on the coordination server only while registered; it expires about 90 seconds after the server stops heartbeating, and is lost if the coordination service restarts. The coordination server does not store device entries.
</Callout>

All other operations occur locally on your network without external data transmission. We run a [Network Bounty Program](/docs/network-bounty-program) that rewards anyone who finds an undocumented external connection. Findings are fixed and published.

## Data Retention

License data is retained for as long as your license remains active. If you deactivate your license or it is otherwise terminated, we retain the associated data for a reasonable period as required for legal and dispute resolution purposes, after which it is deleted.

Your TOMMY One email address and country are kept until you unsubscribe or ask us to delete them. If you unsubscribe, Resend keeps your address marked as unsubscribed so we do not email you again. If you ask us to delete your data, we remove it completely.

## Contact

For questions or concerns about this privacy policy, contact us at [info@tommysense.com](mailto:info@tommysense.com).


# Refund Policy

## Evaluation Period

TOMMY Zero provides a free Trial Mode so you can test detection in your home before buying a license. We recommend using Trial Mode first.

## 30-day money-back guarantee

Pro licenses include a 30-day money-back guarantee. If you request a refund within 30 days of purchase, we refund the license in full.

To request a refund, email [info@tommysense.com](mailto:info@tommysense.com). Include the first 4 and last 4 characters of your license key, and the email address you used to purchase.

## After 30 days

After 30 days, purchases are final, except where technical problems prevent license delivery or activation. Eligible cases include failure to receive a license number, activation system failures, or duplicate billing. Refunds in these cases are provided when the issue cannot be resolved through support.

We cannot guarantee compatibility with every hardware or software setup. Trial Mode and the 30-day money-back guarantee are there so you can check your setup before the purchase is final. After 30 days, refunds are not issued for compatibility issues.

## Questions

If you have questions about this policy, email [info@tommysense.com](mailto:info@tommysense.com).


# Release Notes

## Detailed Changelog

For release notes including version history, bug fixes, and detailed feature descriptions:

**[View Full Changelog on GitHub](https://github.com/tommy-sense/homeassistant-addon/blob/main/tommy/CHANGELOG.md)**

## What's Included in Releases

**Feature Updates:**

* New capabilities and functionality
* Performance improvements and optimizations
* User interface enhancements

**Bug Fixes:**

* Stability improvements and crash fixes
* Network connectivity issue resolutions
* Dashboard and UI bug corrections

**Security Updates:**

* Vulnerability patches and security improvements
* Dependency updates for security compliance
* Privacy protection improvements


# TOMMY Zero Roadmap

import { TrackedDiscordLink } from '@/components/docs/TrackedDiscordLink';

## 2026 Roadmap

#### Stationary Presence Detection (Implemented)

Detect when someone is present in a zone even when they're not moving, supporting room occupancy detection for sleeping, reading, or other stationary activities.

#### Passive Devices as Sensors

Allow devices that are not flashed with TOMMY Zero firmware to be used as passive sensors (e.g., Smart TVs, computers, gaming consoles). This feature will reduce the number of dedicated sensors needed.

#### Filtering Non-Human Presence

Distinguish between human presence and other sources like pets, fans, robot vacuum cleaners, and environmental factors.

## Future Features (Timeline TBD)

*The following features are planned for future development but do not have confirmed timelines as they depend on ongoing research and potential hardware improvements.*

### Fall Detection

Detect when a person falls within the monitored environment, supporting safety monitoring for elderly care applications, emergency response automation, and health and wellness monitoring without requiring wearable devices.

### Room-Level Localization

Detect approximate location of people within a space, supporting room-level positioning and automation based on where people are located within zones.

### Human Identification

Identify specific individuals present in the environment, supporting personalized automations such as "set lights to scene ID when person X enters the room" or "play person Y's preferred music when they arrive."

### Activity Recognition

Identify specific activities being performed, such as:

* Walking patterns and direction
* Gestures like clapping or waving
* Sitting, standing, or lying down
* Exercise or movement routines

## Development Priorities

Our roadmap is shaped by:

* **Community Feedback** - Features most requested by users
* **Technical Feasibility** - Current hardware and software capabilities
* **Research Progress** - Advances in Wi-Fi sensing algorithms
* **Hardware Evolution** - New devices and capabilities

***

*This roadmap is subject to change based on technical discoveries, community feedback, and development priorities. Timeline estimates are goals, not guarantees.*

**Want to influence the roadmap?**

<TrackedDiscordLink />


# Getting Support

import { Callout } from 'fumadocs-ui/components/callout';
import { TrackedDiscordLink } from '@/components/docs/TrackedDiscordLink';

## Community Support

The Discord community provides:

* **Real-time help** from experienced users
* **Developer presence** for technical questions
* **Dedicated support channels** for different types of issues

<TrackedDiscordLink />

## Getting Effective Help

### Before Asking for Help

1. **Check the documentation** - Many questions are already answered
2. **Search Discord history** - Your question might have been asked before
3. **Try basic troubleshooting** - Restart devices, check connections
4. **Gather information** - Prepare logs, error messages, and configuration details

<Callout title="Check Docs First" type="tip">
  Many common questions are answered in our documentation and FAQ. Checking there first often gets you answers faster than waiting for Discord responses.
</Callout>

### When Asking for Help

**Provide Context:**

* Describe your setup (hardware, network, installation method)
* Explain what you expected vs. what actually happened
* Share exact error messages or screenshots
* Include relevant logs (dashboard, device, Home Assistant, Docker)

**Be Specific:**

* Avoid "it doesn't work" - describe specific symptoms
* Include steps to reproduce the problem
* Mention what you've already tried
* Specify your environment (OS, browser, network setup)


# System Requirements

import { Callout } from 'fumadocs-ui/components/callout';

## Requirements

* **Home Assistant Operating System (HA OS)** or **Docker (Linux host only)** for running the TOMMY Zero server
* **Minimum 2 devices per zone** (same Wi-Fi band - either 2.4GHz or 5GHz)
* **Network access** - The TOMMY Zero server and all devices must be on the same network and able to communicate with each other. The server also requires internet access to communicate with the license server.

## Supported Devices

* **ESP32** (2.4GHz)
* **ESP32-C3** (2.4GHz)
* **ESP32-C5** (2.4GHz & 5GHz)
* **ESP32-C6** (2.4GHz)
* **ESP32-S2** (2.4GHz)
* **ESP32-S3** (2.4GHz)

<Callout title="Special Note for Mesh Networks" type="info">
  If using mesh networks, devices in each zone must be on the same access point. Different zones can use different access points.

  To ensure devices connect to the correct access point, you must provide the router BSSID (MAC address) during flashing. See the [TOMMY Flasher](/docs/flashing-devices/tommy-flasher) or [ESPHome](/docs/flashing-devices/esphome) documentation for instructions on how to configure BSSID.
</Callout>


# Terms and Conditions

## License Types

TOMMY Zero is available in both Trial Mode and Pro Edition. **Both are for non-commercial use only** unless you have a separate commercial license or other written agreement with us that expressly permits commercial use.

**Trial Mode (non-commercial).** For qualifying non-commercial use, we grant you a limited, non-exclusive, non-transferable right to run TOMMY Zero in Trial Mode **on one (1) machine or in one (1) deployment** at any time. Trial Mode is feature-complete for evaluation but automatically pauses detection for a short window on a recurring basis. This does not extend to multiple concurrent installations or environments under the same gratis entitlement. If you wish to run TOMMY Zero on additional machines or in additional deployments, you must obtain a separate Pro license (or another license we authorize in writing), unless we expressly agree otherwise.

**Pro Edition (non-commercial).** Pro Edition features require the purchase of a valid Pro license. A standard Pro license is **non-commercial**: it authorizes the same kind of personal or home use as Trial Mode, without the periodic detection pauses and with the additional Pro features described when you purchase. Each Pro license is valid for **a single machine only** (one licensed installation at a time). Running Pro Edition on additional machines requires a separate license for each machine.

## Commercial Use

Commercial use (including use by organizations, for business purposes, revenue-generating activities, or in any context outside personal or home non-commercial use) **is not covered** by the gratis Trial Mode entitlement or by a standard Pro license. Organizations and others requiring commercial use must obtain a **commercial license** (or other agreement) from us, regardless of whether they would otherwise use Trial Mode or Pro Edition features.

## License Activation and Transfer

Licenses are activated online and remain flexible: you can transfer your license to another machine by deactivating on the current device and reactivating on the new one. License transfer is permitted for the same licensee only and does not constitute a transfer of ownership or rights to another person.

## Software Updates

We will do our best to provide software updates and improvements, but we do not guarantee any future versions, bug fixes, or feature additions. Updates are provided at our sole discretion.

## Internet Connectivity

TOMMY Zero requires an active internet connection to communicate with the license server for activation and periodic license verification. No sensing data ever leaves your local network. For details on when and how TOMMY Zero communicates externally, see [Network Communication](/docs/privacy-policy#network-communication). We are not liable for any interruption of service caused by loss of internet access or by temporary unavailability of the license server.

## Online Coordination Service

TOMMY Zero optionally provides an online coordination service that helps devices discover your TOMMY Zero server on your local network. This service is provided as a convenience feature only and carries no uptime guarantee or service-level commitment. We may suspend, modify, or permanently discontinue the coordination service at any time without notice or liability.

If the coordination service becomes unavailable, your TOMMY Zero installation will continue to function normally. You can switch to [Automatic (mDNS)](/docs/device-discovery/automatic-mdns) or [Manual](/docs/device-discovery/manual) device discovery at any time without affecting your license or local detection capabilities.

## System Compatibility

TOMMY Zero operates across diverse hardware and software environments. Given the wide range of system configurations, we cannot guarantee compatibility with every setup. We strongly advise testing Trial Mode to verify compatibility with your specific environment before purchasing a license.

## Support Services

Our team provides community support through our Discord channel on a best-effort basis. Support is voluntary and community-driven. Purchasing a Pro license does not entitle you to personalized technical support.

Bug fixes and issue resolutions are prioritized but not guaranteed. Pro licenses do not include dedicated support time, and no service-level agreement (SLA) exists for personal licenses.

For assistance, we recommend checking our Discord community channel, where other users may have encountered similar issues.

## Payment Processing

All purchases are processed through Paddle Inc., which acts as our **Merchant of Record** and authorized reseller. As Merchant of Record, Paddle is the seller of record on all transactions and assumes responsibility for billing, invoicing, VAT and tax collection, and payment processing. Refunds are handled by us, as described in our [Refund Policy](/docs/refund-policy). Prices are listed and charged in **EUR**.

## Tax Obligations

Tax rates (Sales Tax or VAT) are determined by your purchase location. Our payment processor automatically suggests applicable taxes based on your IP address, though you may adjust these during checkout. You are responsible for ensuring your location and tax information are accurate according to applicable regulations. Any discrepancies resulting from currency conversion, exchange rates, or tax adjustments are your responsibility.

## Restrictions

You may not, and may not permit others to:

* Reverse engineer, decompile, disassemble, or otherwise attempt to derive the source code or underlying algorithms of TOMMY Zero;
* Modify, adapt, translate, or create derivative works based on TOMMY Zero;
* Remove, alter, or obscure any copyright, trademark, or other proprietary notices contained in or on TOMMY Zero;
* Sublicense, sell, resell, or otherwise distribute TOMMY Zero or any rights to it;
* Use TOMMY Zero to develop a competing product or service;
* Circumvent or attempt to circumvent any license enforcement or technical protection mechanisms;
* Use TOMMY Zero in any manner that violates applicable law or these terms.

## Intellectual Property

TOMMY Zero, including all software, code, algorithms, documentation, branding, and related materials, is and remains the exclusive property of TOMMY and its licensors. These terms grant you a limited license to use TOMMY Zero as described herein; no ownership is transferred. All rights not expressly granted are reserved.

TOMMY Zero may include third-party open source components, each of which is subject to its own license terms. These terms do not alter or override any open source license that applies to those components.

## Perpetual License

A purchased Pro license is perpetual: once validly issued, it authorizes you to download and use the version of TOMMY Zero available at the time of purchase, for as long as you comply with these terms. Perpetual licenses are subject to the single-machine limitation described under License Types.

You are not entitled to any future versions of TOMMY Zero under a perpetual license. While we may offer updates, receiving them is not guaranteed and does not form part of your license entitlement.

We do not guarantee the continued availability of any specific version for download. We will make reasonable efforts to keep a download available, but we cannot promise that the exact version you purchased will remain accessible indefinitely. **It is your responsibility to retain a copy of the installer or build you downloaded.** We are not liable for any loss arising from your failure to do so.

**Governing terms for your licensed version.** The terms, privacy policy, and refund policy in effect at the time of your purchase govern your use of the version you purchased. If you choose to install a newer version of TOMMY Zero, the terms published on our website at the time of that installation will apply to your use of the updated version. Installing or activating an update constitutes your acceptance of those terms.

## Termination

We may terminate or suspend your license immediately and without notice if you breach any provision of these terms. Upon termination, you must immediately cease all use of TOMMY Zero and delete all copies in your possession. Termination does not entitle you to a refund. Sections that by their nature should survive termination (including Restrictions, Intellectual Property, Limitation of Liability, and Governing Law) will continue to apply.

## Disclaimer of Warranties

TOMMY Zero is provided **"as is"** and **"as available"** without warranty of any kind. To the fullest extent permitted by applicable law, we disclaim all warranties, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, non-infringement, and accuracy. We do not warrant that TOMMY Zero will be error-free, uninterrupted, or free of harmful components. Your use of TOMMY Zero is at your sole risk.

## Limitation of Liability

To the fullest extent permitted by law, TOMMY shall not be liable for any damages arising from the use or inability to use the software. This limitation includes, but is not limited to, direct, indirect, incidental, special, consequential, or punitive damages; loss of data, profits, revenue, or business opportunities; or device malfunction or damage. You assume all risk associated with the use of TOMMY Zero.

In any event, our total aggregate liability to you for any claim arising out of or relating to these terms or your use of TOMMY Zero shall not exceed the amount you paid for your license in the twelve (12) months preceding the claim, or EUR 50, whichever is greater.

## Refund Policy

Pro licenses include a 30-day money-back guarantee. Email [info@tommysense.com](mailto:info@tommysense.com) within 30 days of purchase with the first 4 and last 4 characters of your license key and the email address you purchased with, and the license is refunded in full. We cannot guarantee compatibility with every setup. Trial Mode and the money-back period are there so you can check yours. After 30 days, purchases are final, and refunds are not issued for compatibility issues. Limited exceptions may apply for verified technical issues that prevent license delivery or activation and cannot be resolved through support. For full details, see our [Refund Policy](/docs/refund-policy).

## Geographic Restrictions

TOMMY Zero is not available in the United States. By using or purchasing TOMMY Zero, you confirm that you are not located in, and are not accessing TOMMY Zero from, the United States. You are responsible for ensuring that your use of TOMMY Zero complies with all laws applicable in your jurisdiction.

## Changes to These Terms

We reserve the right to update or modify these terms at any time. Updated terms will be published on our website and will apply to any new version of TOMMY Zero installed after that date. If you continue using your currently installed version without updating, the terms in effect at the time of your purchase (or your last update, as applicable) continue to govern that use. Installing or activating any new version of TOMMY Zero after a terms update constitutes your acceptance of the revised terms. If you do not agree to updated terms, do not install the new version.

## Assignment

You may not assign or transfer your license or any rights or obligations under these terms without our prior written consent. Any purported assignment in violation of this section is void. We may assign or transfer our rights and obligations under these terms without restriction.

## No Waiver

Failure by us to enforce any provision of these terms does not constitute a waiver of our right to enforce that provision or any other provision in the future. No waiver is effective unless made in writing.

## Severability

If any provision of these terms is found to be invalid, unlawful, or unenforceable under applicable law, that provision will be modified to the minimum extent necessary to make it enforceable, or severed if modification is not possible. The remaining provisions will continue in full force and effect.

## Entire Agreement

These terms, together with our [Privacy Policy](/docs/privacy-policy) and [Refund Policy](/docs/refund-policy), constitute the entire agreement between you and TOMMY regarding your use of the software and supersede all prior agreements, representations, or understandings relating to the same subject matter.

## Governing Law and Jurisdiction

These terms are governed by and construed in accordance with the laws of Denmark, without regard to its conflict of law principles. Any disputes arising out of or in connection with these terms shall be subject to the exclusive jurisdiction of the courts of Denmark. Nothing in these terms limits any mandatory consumer protection rights you may have under the laws of your country of residence.

## Contact

For legal notices or questions about these terms, contact us at [info@tommysense.com](mailto:info@tommysense.com). For technical support, visit our [Discord community](/docs/discord-community).


# Topology

More sensing paths improve presence detection, but each path adds airtime and network bandwidth. Choose based on how much traffic your network can handle.

## Star

A single device is designated as the transmitter. This provides fewer sensing paths than mesh, but uses the least airtime and network bandwidth. If the transmitter goes offline, another device takes over automatically, and the role returns to the selected transmitter when it comes back online.

You can select the transmitter for the zone. Aim for the sensing lines between the transmitter and each receiver to fan out through the room: a centered transmitter is the easiest way, but a corner transmitter also works when receivers spread out around it.

## Mesh

All but one device transmit, each covering a single direction. This covers every sensing path once, but not bidirectionally.


# TOMMY Zero vs ESPectre

## Overview

ESPectre and TOMMY Zero both detect motion by analyzing Wi-Fi Channel State Information (CSI) on ESP32 devices, but they take very different approaches. ESPectre is an open-source (GPL-3.0) project where a single ESP32 "listens" to the Wi-Fi link between itself and your router, making the router the fixed transmitter. TOMMY Zero is a closed-source system where multiple ESP32 devices measure signals between each other, which lets you define arbitrary zones by placing devices.

If you prefer an open-source solution and single-device-per-area sensing is enough for your use case, ESPectre is a solid option. If you want multi-device zones, richer integration, and an easier install, TOMMY Zero is a better fit.

<style>
  {`
    table {
      table-layout: fixed;
      width: 100%;
    }
    table th:first-child,
    table td:first-child {
      width: 25%;
    }
    table th:nth-child(2),
    table td:nth-child(2) {
      width: 37.5%;
    }
    table th:nth-child(3),
    table td:nth-child(3) {
      width: 37.5%;
    }
    `}
</style>

## Technology Comparison

| Aspect              | TOMMY Zero                                                                                                                   | ESPectre                                                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Released**        | 17 August 2025                                                                                                               | 2 November 2025                                                                                                           |
| **Technology**      | Wi-Fi sensing (Channel State Information)                                                                                    | Wi-Fi sensing (Channel State Information)                                                                                 |
| **Protocol**        | Wi-Fi (802.11)                                                                                                               | Wi-Fi (802.11)                                                                                                            |
| **Signal Analysis** | Measures fluctuations in Wi-Fi signals                                                                                       | Measures fluctuations in Wi-Fi signals                                                                                    |
| **Sensing paths**   | Device-to-device - ESP32 devices measure the links between each other, in a star or mesh [topology](/docs/topology) per zone | Router-to-device - the ESP32 measures the link between itself and the router, so the router acts as the fixed transmitter |

## Comparison

### Device Requirements

| Aspect                   | TOMMY Zero                                              | ESPectre                                                |
| ------------------------ | ------------------------------------------------------- | ------------------------------------------------------- |
| **Device count**         | 2 or more devices                                       | 1 or more devices                                       |
| **Device compatibility** | ESP32, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-S2, ESP32-S3 | ESP32, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-S2, ESP32-S3 |

### Sensing Capabilities

| Aspect                          | TOMMY Zero                                                                                                                                        | ESPectre                                                                                                                                                          |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Zones**                       | Freely defined by placing devices. A zone is the sensing area spanned by the devices you assign to it                                             | Limited to the router-to-device path. Each ESP32 senses motion along its link to the router, so arbitrary zones aren't possible unless you move the router itself |
| **Detection area**              | Motion is detected in the area spanned by the ESP32 devices in a zone                                                                             | Motion is detected along the path between your router and the ESP32                                                                                               |
| **Obstacle penetration**        | Can detect motion through obstacles and walls                                                                                                     | Can detect motion through obstacles and walls                                                                                                                     |
| **Motion filtering**            | Cannot differentiate between human movement and other moving objects (pets, curtains, fans, etc.). Human vs. non-human filtering planned for 2026 | Cannot differentiate between human movement and other moving objects (pets, curtains, fans, etc.)                                                                 |
| **Stationary presence sensing** | Supported with compatible hardware (see [Detection Mode](/docs/detection-mode))                                                                   | Not supported                                                                                                                                                     |

### Setup and Integration

| Aspect                         | TOMMY Zero                                                                                    | ESPectre                                                               |
| ------------------------------ | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Installation**               | Home Assistant App or Docker container (\~2 mins setup)                                       | CLI tool (\~10-15 mins setup, as stated in the docs)                   |
| **Home Assistant integration** | Native Home Assistant integration with automatic entity creation, or integrate through Matter | Integrates with Home Assistant through MQTT and manual entity creation |
| **ESPHome support**            | Supported                                                                                     | Supported                                                              |

### Privacy and Cost

| Aspect          | TOMMY Zero                                                                          | ESPectre                        |
| --------------- | ----------------------------------------------------------------------------------- | ------------------------------- |
| **Privacy**     | Runs locally, no cloud required, except for communication with the licensing server | Runs locally, no cloud required |
| **System type** | Closed-source, proprietary system                                                   | Open source (GPL-3.0)           |
| **Price**       | Free Trial Mode. Pro Edition available as one-time purchase                         | Free                            |

## Use Cases

### When to choose TOMMY Zero

* You want stationary presence sensing
* You want to define arbitrary zones by placing devices rather than being tied to the router-to-device path
* You want a one-click install through the Home Assistant App Store or Docker
* You want native Home Assistant integration or Matter integration out of the box

### When to choose ESPectre

* You want a fully open-source solution and are comfortable with GPL-3.0
* Single-device, single-area motion detection is enough for your use case
* You're fine with a CLI-based setup and wiring things up through MQTT manually
* You want to get started with zero software cost and only hardware to buy


# Comparisons

## Overview

A few projects today tackle motion and presence detection using Wi-Fi or other RF signals. Each takes a different approach, with different trade-offs around hardware, accuracy, ecosystem, and openness. The table below summarizes the landscape. Follow the links for a deeper comparison against TOMMY Zero.

| Project                                                             | Released         | Technology                | Sensing Paths    | Stationary Presence | Source              | Pricing                        |
| ------------------------------------------------------------------- | ---------------- | ------------------------- | ---------------- | ------------------- | ------------------- | ------------------------------ |
| TOMMY Zero                                                          | 17 August 2025   | Wi-Fi CSI (ESP32)         | Device-to-device | Yes\*               | Closed source       | Free Trial / one-time purchase |
| [Philips Hue MotionAware](/docs/comparisons/motionaware-comparison) | 4 September 2025 | Zigbee signal fluctuation | Light-to-light   | No                  | Closed source       | Included with Hue Bridge Pro   |
| [ESPectre](/docs/comparisons/espectre-comparison)                   | 2 November 2025  | Wi-Fi CSI (ESP32)         | Router-to-device | No                  | Open source (GPLv3) | Free                           |

\* Stationary presence detection with TOMMY Zero requires compatible hardware. See [Detection Mode](/docs/detection-mode) for configuration requirements and optimal setup.

The *Sensing Paths* column describes which signals the system measures. **Device-to-device** systems measure signals between their own sensing devices, so you can place them to define the exact zones you want to monitor. **Router-to-device** systems measure the signal between a single sensor and your router, so the detection zone is fixed to that path; the only way to reshape it is to move the router.

## Individual Comparisons

* [TOMMY Zero vs Philips Hue MotionAware](/docs/comparisons/motionaware-comparison)
* [TOMMY Zero vs ESPectre](/docs/comparisons/espectre-comparison)

For how Wi-Fi sensing compares to mmWave sensors in general, see [mmWave vs Wi-Fi sensing](/learn/mmwave-vs-wifi-sensing).


# TOMMY Zero vs Philips Hue MotionAware

## Overview

Philips Hue MotionAware and TOMMY Zero both detect motion using Radio Frequency (RF) sensing, though they rely on different wireless technologies and target different smart home ecosystems.

MotionAware works within the Philips Hue ecosystem, analyzing how motion affects Zigbee signals between Hue lights. TOMMY Zero uses ESP32 devices to monitor Wi-Fi Channel State Information (CSI) and integrates with Home Assistant or any Matter-compatible ecosystem.

<style>
  {`
    table {
      table-layout: fixed;
      width: 100%;
    }
    table th:first-child,
    table td:first-child {
      width: 25%;
    }
    table th:nth-child(2),
    table td:nth-child(2) {
      width: 37.5%;
    }
    table th:nth-child(3),
    table td:nth-child(3) {
      width: 37.5%;
    }
    `}
</style>

## Technology Comparison

| Aspect              | TOMMY Zero                                                                                                                   | Philips Hue MotionAware                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Released**        | 17 August 2025                                                                                                               | 4 September 2025                                                                         |
| **Technology**      | Wi-Fi sensing (Channel State Information)                                                                                    | Zigbee signal fluctuation analysis                                                       |
| **Devices**         | ESP32-based devices (2 or more per zone)                                                                                     | Philips Hue lights (3-4 per motion area)                                                 |
| **Protocol**        | Wi-Fi (802.11)                                                                                                               | Zigbee                                                                                   |
| **Signal Analysis** | Measures fluctuations in Wi-Fi signals                                                                                       | Measures fluctuations in Zigbee signals                                                  |
| **Sensing paths**   | Device-to-device - ESP32 devices measure the links between each other, in a star or mesh [topology](/docs/topology) per zone | Light-to-light - Hue lights measure the Zigbee links between each other in a motion area |

## Comparison

### Device Requirements

| Aspect                   | TOMMY Zero                                                                                   | Philips Hue MotionAware                            |
| ------------------------ | -------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| **Device count**         | Requires 2 or more ESP32 devices per zone                                                    | Requires 3-4 Philips Hue lights per zone           |
| **Device compatibility** | Works with a wide range of ESP32-based devices                                               | Works with compatible Hue lights                   |
| **Device reuse**         | Can add sensing to existing ESP32 devices through ESPHome without losing prior functionality | Lights serve dual purpose (illumination + sensing) |

### Setup and Integration

| Aspect              | TOMMY Zero                                                                             | Philips Hue MotionAware                                                                                 |
| ------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Hub requirement** | No hub required, but needs to be installed as a Home Assistant App or Docker container | Requires Hue Bridge Pro (exclusive to this feature)                                                     |
| **Ecosystem**       | Integrates with Home Assistant and Matter ecosystems                                   | Integrates with Philips Hue ecosystem                                                                   |
| **Privacy**         | Runs locally, except for license verification                                          | Processes locally on the Bridge Pro. A Hue account and cloud connection are required for some features. |

### Sensing Capabilities

| Aspect                          | TOMMY Zero                                                                                                                                        | Philips Hue MotionAware                                                                           |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| **Detection area**              | Sensing within the area covered by the ESP32 devices                                                                                              | Sensing within the area covered by the lights                                                     |
| **Obstacle penetration**        | Can detect motion through obstacles and walls                                                                                                     | Can detect motion through obstacles and walls                                                     |
| **Motion filtering**            | Cannot differentiate between human movement and other moving objects (pets, curtains, fans, etc.). Human vs. non-human filtering planned for 2026 | Cannot differentiate between human movement and other moving objects (pets, curtains, fans, etc.) |
| **Stationary presence sensing** | Supported                                                                                                                                         | Not supported                                                                                     |

### Cost and Flexibility

| Aspect            | TOMMY Zero                                                  | Philips Hue MotionAware                                                                                 |
| ----------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Upfront cost**  | At least two ESP32 devices per zone, available at low cost  | Requires Hue Bridge Pro purchase + 3-4 Hue lights per zone                                              |
| **License model** | Free Trial Mode. Pro Edition available as one-time purchase | Included with Hue Bridge Pro (no subscription). Security alerts and event timeline require subscription |
| **System type**   | Closed-source, proprietary system                           | Closed-source, proprietary system                                                                       |
| **Support**       | Community support through Discord channel                   | Support through Philips ecosystem                                                                       |

## Use Cases

### When to choose TOMMY Zero

* You want stationary presence sensing
* You want flexibility in how you define motion zones
* You have ESP32 devices lying around or want to start with cost-effective hardware
* You prefer local control through Home Assistant or need Matter ecosystem integration
* You don't have Philips Hue lights or the Hue Bridge Pro

### When to choose Philips Hue MotionAware

* You already own Philips Hue lights and the Hue Bridge Pro
* Sensing is needed in areas where you're installing lights anyway
* You prefer managing motion zones through the Philips Hue app


# Group

import { Step, Steps } from 'fumadocs-ui/components/steps';

## What is a group?

A group is a set of zones that sense through one shared transmitter. The transmitter sits on the border between those zones. Each zone covers the space between that transmitter and the devices assigned to the zone.

A group does not detect presence by itself. The zones inside it do. For a zone with its own devices and no shared transmitter, see [Zone](/docs/creating-zones/zone).

## Group requirements

* **One shared transmitter** for the whole group
* **At least one other device in each zone**
* **Star topology only.** Mesh is not available for a group
* **Same Wi-Fi band** for every device in the group (2.4 GHz or 5 GHz)
* **Same access point** when the devices are on a mesh network. See [mesh networks](/docs/system-requirements)

## Drawback

Presence near the shared transmitter shows up as presence in every zone that shares it. Put the transmitter where people do not linger if those zones need to stay independent.

## Creating a group

<Steps>
  <Step>
    ### Create the group

    1. **Open the TOMMY Zero dashboard.**
    2. **Go to Zones.**
    3. **Click Create** (or the **+** next to **Zones** in the sidebar).
    4. **Choose Group**, enter a unique name, and confirm.
  </Step>

  <Step>
    ### Assign the shared transmitter

    1. **Open the group.**
    2. **Assign one device as the transmitter** under Group settings. That device transmits for every zone in the group.
  </Step>

  <Step>
    ### Add a zone for each area

    1. **Create a zone inside the group** and give it a unique name.
    2. **Assign at least one device** to that zone, besides the shared transmitter.
    3. **Repeat** for each area the group should cover.
  </Step>
</Steps>


# Zone

import { Step, Steps } from 'fumadocs-ui/components/steps';

## What is a zone?

A zone defines a specific area for presence detection. Each zone:

* **Detects presence** in the space between the devices you assign to it
* **Spans the entire area** between those devices, regardless of walls or rooms
* **Creates a motion sensor entity** for integration with Home Assistant or Matter

To share one transmitter across several zones, see [Group](/docs/creating-zones/group).

## Zone requirements

* **At least 2 devices per zone** (same Wi-Fi band, 2.4 GHz or 5 GHz)
* **Minimum 1 meter apart** between devices
* **Same access point.** Devices must be on the same access point when using mesh networks. See [mesh networks](/docs/system-requirements) in system requirements

## Creating a zone

<Steps>
  <Step>
    ### Access zone management

    1. **Open the TOMMY Zero dashboard** in your web browser.
    2. **Go to Zones.**
    3. **Click Create** (or the **+** next to **Zones** in the sidebar).
    4. **Choose Zone** when the dialog asks for a type.
  </Step>

  <Step>
    ### Name your zone

    1. **Enter a descriptive name** for your zone (for example "Living Room", "Kitchen", or "Upstairs")
    2. **Choose a unique name.** Zone names must be unique within your TOMMY Zero instance
    3. **Click "Create zone"** to confirm
  </Step>

  <Step>
    ### Add devices to your zone

    1. **Ensure devices are connected.** They show up on the **Devices** page and, inside the zone, under **Available to add**
    2. **Open the zone**, then click **Assign** on a device
    3. **Verify Wi-Fi band compatibility.** All devices must use the same band (2.4 GHz or 5 GHz)
  </Step>
</Steps>

## Understanding zone coverage

Your zone covers the entire space between devices:

* **Through walls.** Wi-Fi signals penetrate walls, so presence detection can cross rooms
* **Behind obstacles.** Presence can be detected behind furniture and other obstacles
* **Multi-room areas.** A single zone can span multiple rooms


# Automatic (Online Coordination)

import { Callout } from 'fumadocs-ui/components/callout';

<Callout title="Requires Internet on Devices" type="warn">
  Online Coordination requires your devices to have an active internet connection. If your devices don't have internet access, use [Automatic (mDNS)](/docs/device-discovery/automatic-mdns) or [Manual](/docs/device-discovery/manual) instead.
</Callout>

<Callout title="Privacy Information" type="info">
  When Online Coordination is enabled, your TOMMY Zero server registers its local address (e.g. 192.168.1.100:8547) with `https://coordination.tommysense.com`. Devices look up the server using the pairing code only. No device identifier or device IP is transmitted. See the [Network Communication section of the Privacy Policy](/docs/privacy-policy#network-communication) for the full details.
</Callout>

## How It Works

The TOMMY Zero server publishes its local address (e.g. 192.168.1.100:8547) to the coordination service. Your devices look up the server's local address by pairing code and establish a direct local connection. All data flows directly between the device and your server after that.

## Configuring Devices

### TOMMY Flasher

During provisioning, select **Automatic (Online Coordination)** as the discovery mode. No additional configuration is needed.

See the [TOMMY Flasher guide](/docs/flashing-devices/tommy-flasher) for complete instructions.

### ESPHome

Online Coordination is not supported on ESPHome devices. Use [Automatic (mDNS)](/docs/device-discovery/automatic-mdns) or [Manual](/docs/device-discovery/manual) instead.


# Automatic (mDNS)

## How It Works

When the TOMMY Zero server starts:

1. It advertises itself as `_tommy._tcp.local` via mDNS
2. Broadcasts its IP address and required ports
3. Includes metadata like version, startup time, and process ID

When a device starts:

1. The device listens for `_tommy._tcp.local` broadcasts
2. When it detects the advertisement, it extracts the server IP, ports, and service availability
3. The device connects automatically
4. It appears on the **Devices** page within seconds

## Requirements

* TOMMY Zero server and devices must be on the same network
* Network infrastructure must allow multicast traffic

## Configuring Devices

### TOMMY Flasher

During provisioning, select **Automatic (mDNS)** as the discovery mode. No additional configuration is needed.

See the [TOMMY Flasher guide](/docs/flashing-devices/tommy-flasher) for complete instructions.

### ESPHome

Add the following to your `sensor_tommy` config:

```yaml
sensor_tommy:
  discovery: mdns
```

See the [ESPHome flashing guide](/docs/flashing-devices/esphome) for complete instructions.


# Manual

## How It Works

The device connects directly to your TOMMY Zero server using the IP address and port you specify during flashing. This requires stable IP addresses on both the server and the device.

## Configuring Devices

### TOMMY Flasher

During provisioning, select **Manual** as the discovery mode and enter:

* **Instance IP**: The IP address where your TOMMY Zero server is running (e.g., `192.168.1.100`)
* **UDP Relay Port**: Default is `8547` unless you changed it

See the [TOMMY Flasher guide](/docs/flashing-devices/tommy-flasher) for complete instructions.

### ESPHome

Add the following to your `sensor_tommy` config:

```yaml
sensor_tommy:
  discovery: manual
  instance_ip: "192.168.1.100"
  udp_relay_port: 8547
```

See the [ESPHome flashing guide](/docs/flashing-devices/esphome) for complete instructions.


# ESPHome Component

import { Callout } from 'fumadocs-ui/components/callout';

## Requirements

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

<Callout title="Shelly devices" type="warn">
  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.
</Callout>

<Callout title="Bluetooth Proxy Compatibility" type="info">
  If you're using Bluetooth Proxy alongside TOMMY Zero, 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](https://esphome.io/components/psram/) for details on how to enable it.
</Callout>

## Configuration

Add the following to your ESPHome device YAML.

```yaml
esphome:
  # ... your existing configuration
  min_version: 2026.9.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
```

<Callout title="External Component Source" type="info">
  ESPHome downloads the `sensor_tommy` component from your TOMMY Zero 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 Zero runs as a Home Assistant App. Otherwise, replace it with the hostname or IP address of the machine running the server. The port is the file server HTTP port (default `8090`).
</Callout>

## Automatic configuration changes

TOMMY Zero automatically changes parts of your ESPHome configuration that are required for it 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 -> 6.1
  esp32.framework.source: (unset) -> https://github.com/espressif/esp-idf/releases/download/v6.1/esp-idf-v6.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
  esp32.framework.sdkconfig_options.CONFIG_FREERTOS_IN_IRAM: (unset) -> y
  esp32.framework.sdkconfig_options.CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY: (unset) -> y
  wifi.power_save_mode: LIGHT -> NONE
```

## Discovery

The `sensor_tommy` component supports two discovery modes on ESPHome. [Online Coordination](/docs/device-discovery/automatic-coordination-service) is not available on ESPHome devices.

### Automatic (mDNS)

The device discovers the TOMMY Zero server via mDNS on your local network. Requires that multicast traffic reaches the device. See [Automatic (mDNS)](/docs/device-discovery/automatic-mdns) for details.

```yaml
sensor_tommy:
  discovery: mdns
```

### Manual

Connects the device directly to the TOMMY Zero server using the IP address and port. This requires stable IP addresses on both the server and the device. See [Manual Discovery](/docs/device-discovery/manual) for details.

```yaml
sensor_tommy:
  discovery: manual
  instance_ip: "192.168.x.x"   # required, IP of your TOMMY Zero 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 Zero 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.

```yaml
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](/docs/system-requirements) 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.

```yaml
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

```yaml
sensor_tommy:
  discovery: mdns
  xiao_esp32c6_antenna: internal
```

### External UFL antenna

```yaml
sensor_tommy:
  discovery: mdns
  xiao_esp32c6_antenna: external
```

## Integration with Existing Components

TOMMY Zero works alongside your existing ESPHome components:

```yaml
# 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:

1. **Compile and upload** using your normal ESPHome workflow
2. **Monitor logs** to verify TOMMY Zero component initialization
3. **Check Devices** in the TOMMY Zero 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 Zero server is reachable
* Monitor ESPHome logs for error messages

### Discovery Problems

* For mDNS: verify the device and TOMMY Zero 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](https://esphome.io/components/external_components.html) for detailed instructions.


# TOMMY Flasher

import { Callout } from 'fumadocs-ui/components/callout';

## Requirements

* Chrome or Edge (WebSerial API support required)
* Device connected via USB or UART
* TOMMY Zero dashboard running (Home Assistant App or Docker)

## Flashing Process

### 1. Access the Flasher

1. Open the TOMMY Zero dashboard in your browser
2. Open **Devices** in the sidebar, then click **Flash new device** (or the **+** next to **Devices**)
3. Select **TOMMY Flasher** as the flash method
4. Select your device from the available options

### 2. Connect Your Device

1. Connect your device to your computer via USB or UART
2. Click **"Connect device"** in the flasher interface
3. Select the appropriate serial port from the browser dialog
4. The flasher will automatically detect your device and display:
   * **Variant**: Device model
   * **Board ID**: Unique chip identifier
   * **MAC Address**: Device network identifier

### 3. Flash the Firmware

1. Once connected, click **"Flash device"**
2. The flashing process will begin automatically
3. Monitor the progress bar as the firmware is written

## After Flashing

Once flashing is complete, your device will:

1. **Restart** with TOMMY Zero firmware
   * Some devices don't restart automatically and require a manual reset by pressing the reset button or unplugging and reconnecting the USB cable
2. **Enter serial provisioning mode** - waiting for configuration over the USB connection

### Serial Provisioning

Configuration is sent to the device over the same USB/serial connection used for flashing:

1. In the TOMMY Flasher, disconnect the USB cable from the device, then reconnect it
2. Click **"Connect device"** and select the serial port
3. Enter your configuration in the dialog (see field descriptions below)
4. Click **"Configure Device"** to send the configuration
5. The device stores the configuration, restarts, and connects to your network - initial boot may take a few minutes

#### Wi-Fi Credentials

* **SSID** (required): Your Wi-Fi network name
* **Password** (required): Your Wi-Fi password
* **BSSID** (optional): Router MAC address (e.g., `AA:BB:CC:DD:EE:FF`) - required for mesh networks

#### Discovery

How the device finds your TOMMY Zero instance. Choose one:

* **Automatic (Online Coordination)**: Uses TOMMY Zero's coordination service for the device to look up the server's local address (e.g. 192.168.1.100:8547) by pairing code and establish a direct local connection. All data flows directly between the device and your server after that. Requires an internet connection on the device.
* **Automatic (mDNS)**: The device discovers the TOMMY Zero server via mDNS on your local network. Requires that multicast traffic reaches the device.
* **Manual**: Specify the IP of your TOMMY Zero server directly. When selected, enter **Instance IP** and **UDP Relay Port** (default: 8547). Useful when automatic discovery is unavailable.

#### Max TX Power

* **Auto** (default): Use the board default. Recommended for most boards.
* **Manual**: Set Wi-Fi TX power in dBm (2–20), rounds to nearest 0.25 dBm. Some boards work better with reduced power.

<Callout type="warn">
  Make sure to use the correct Wi-Fi band (2.4GHz or 5GHz) that your device supports.
</Callout>

<Callout type="info">
  Router BSSID is optional but required for TOMMY Zero to work on mesh networks. Please refer to the [information about mesh networks](/docs/system-requirements) in system requirements.
</Callout>

<Callout type="info">
  For more details on each discovery method, see [Automatic (Online Coordination)](/docs/device-discovery/automatic-coordination-service), [Automatic (mDNS)](/docs/device-discovery/automatic-mdns), and [Manual](/docs/device-discovery/manual).
</Callout>

### Troubleshooting Connection Issues

If you can't connect to your device:

1. Ensure USB cable supports data transfer (not power-only)
2. Try different USB ports
3. Install USB-to-serial drivers if required
4. Unplug and reconnect the USB cable
5. Ensure you're using a supported browser (Chrome or Edge)

## Security Notes

* All flashing happens locally in your browser
* Firmware files are served from your local TOMMY Zero instance
* Your browser communicates with the device


# Home Assistant Integration

## Prerequisites

* **Valid zone configuration** (at least 2 devices on the same Wi-Fi band)
* **Home Assistant** with access to install custom integrations

## Installation

### Installation using Home Assistant Community Store (HACS)

1. Follow the [HACS guide for custom repositories](https://hacs.xyz/docs/faq/custom_repositories)
2. When prompted for the repository, enter: `https://github.com/tommy-sense/homeassistant-integration`
3. Select **Integration** as the category
4. Click **Add**
5. Search for **tommy** in the store
6. Click on it and press **Download**
7. Restart Home Assistant
8. Configure the TOMMY integration (see Configuration below)

### Manual Installation

1. [Download the latest release](https://github.com/tommy-sense/homeassistant-integration/releases/latest)
2. Unpack the release and copy the `custom_components/tommy` directory into the `config/custom_components` directory of your Home Assistant installation
   * The directory structure should be `config/custom_components/tommy`
3. Restart Home Assistant
4. Configure the TOMMY integration (see Configuration below)

## Enabling the Integration

The Home Assistant integration is enabled per zone and is disabled by default:

1. Open your TOMMY Zero dashboard
2. Open the zone you want to expose to Home Assistant (from **Zones** in the sidebar, or the Zones page)
3. Under **Network Configuration**, toggle the **Home Assistant** switch in **Integrations**. The switch only affects the selected zone, so repeat this for every zone you want to expose.

Only zones with the switch enabled show up in Home Assistant. Turning the switch off removes the zone's motion sensor entity again.

## Configuration

1. Go to **Settings → Devices & Services**
2. Click **"Add Integration"**
3. Search for **"TOMMY"**
4. Fill out the details when prompted:
   * Enter the IP address of your Home Assistant instance (for App) or the Docker container running TOMMY Zero (for Docker)
   * Enter the MQTT Port assigned in your TOMMY Zero configuration (App configuration) or environment variables (Docker installation) (default: 1886)

## Zones

Once a zone has the Home Assistant integration enabled, no further configuration is needed for it to show up. Home Assistant will automatically stay in sync with zones in the dashboard when adding, removing, or renaming zones. For each enabled zone, a motion sensor entity is exposed in Home Assistant.

## Troubleshooting

**Integration Not Found:**

* Ensure the `custom_components/tommy` directory is in the correct location
* Restart Home Assistant after installation
* Check Home Assistant logs for installation errors

**Connection Issues:**

* Verify the IP address and MQTT port are correct
* Ensure TOMMY Zero is running and accessible
* Check firewall settings if using Docker installation
* Review Home Assistant logs for connection errors

**Zones Not Appearing:**

* Make sure the Home Assistant switch is enabled for the zone under **Network Configuration → Integrations**
* Verify presence detection is working in the TOMMY Zero dashboard
* Confirm the integration is active in Home Assistant
* Check entity state in Developer Tools → States
* Restart the TOMMY integration if needed


# Matter Integration

import { Callout } from 'fumadocs-ui/components/callout';

## Prerequisites

* **TOMMY Zero instance running** (Home Assistant App or Docker)
* **Valid zone configuration** (at least 2 devices on the same Wi-Fi band)
* **Matter-compatible platform** with Matter support enabled
* **Network connectivity** between TOMMY Zero and your Matter controller

<Callout title="Certification Warning" type="info">
  You may encounter a certification warning stating "This device has not been certified" with a safety prompt. This is normal for software devices, and you can safely continue with the pairing process.
</Callout>

## Setting Up Matter Integration

### Enable Matter and Generate Pairing Codes

1. Open your TOMMY Zero dashboard
2. Open the zone you want to integrate (from **Zones** in the sidebar, or the Zones page)
3. Under **Network Configuration**, toggle the **Matter** switch in **Integrations**. TOMMY Zero will restart the zone's services to bring up the Matter device. The switch only affects the selected zone, so repeat this for every zone you want to expose over Matter.
4. Once enabled, click **"Show pairing code"** below the switch to reveal the QR code and setup code for pairing

### Platform-Specific Setup

#### Home Assistant

1. Install and configure the Matter integration in Home Assistant. See the [Home Assistant Matter Integration guide](https://www.home-assistant.io/integrations/matter/#adding-a-matter-device-to-home-assistant) for detailed setup instructions
2. Navigate to **Settings → Devices & Services**
3. Click **"Matter"** in the "Configured" list
4. Click **"Add device"**
5. For first-time pairing: Select **"No. It's new."** and scan the QR code from the TOMMY Zero dashboard
6. For subsequent pairings: Select **"Yes. It's already in use."** and enter the setup code from the TOMMY Zero dashboard
7. Follow the Home Assistant pairing wizard to complete setup

#### Apple HomeKit

1. Launch the Home app on your iPhone, iPad, or Mac
2. Tap the **"+"** icon and select **"Add Accessory"**
3. Use **"Scan QR Code"** or select **"More Options"** for manual code entry
4. Scan the QR code or enter the setup code from the TOMMY Zero dashboard if QR scanning fails
5. Follow the Home app prompts to finish pairing
6. Assign the sensor to a room

#### Google Home

1. Launch the Google Home app
2. Tap **"+"** and select **"Set up device"**
3. Select **"Works with Google"** and then **"Matter"**
4. Scan the QR code or enter the setup code from the TOMMY Zero dashboard if QR scanning fails
5. Follow Google Home prompts to finish pairing
6. Assign the sensor to a room

#### Samsung SmartThings

1. Launch the SmartThings app
2. Tap **"+"** and select **"Add device"**
3. Use **"Scan QR code"** option
4. Scan the QR code or enter the setup code from the TOMMY Zero dashboard if QR scanning fails
5. Follow SmartThings prompts to finish pairing
6. Assign the sensor to a room

#### Generic Matter Setup

For other Matter-compatible platforms:

1. Launch your Matter-compatible application
2. Find **"Add Device"** or **"Add Accessory"** option
3. Choose Matter/Thread device type if prompted
4. Scan the QR code or enter the setup code from the TOMMY Zero dashboard if QR scanning fails
5. Follow your platform's prompts to finish pairing
6. Assign the sensor to a room

## Pairing Code Information

**QR Code:**

* First-time pairing only (cannot be reused after successful pairing)
* Quick setup with camera-enabled devices

**Setup Code (Manual Pairing Code):**

* Can be used for initial pairing and subsequent re-pairings
* Manual entry when QR scanning isn't available
* Always available as fallback method


# Docker Installation

import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';

## Requirements

* **Linux host** (Windows/macOS Docker not supported)
* **AMD64 or ARM64** architecture
* **Host networking**
* **Docker** installed and running

<Callout title="Linux Host Required" type="warn">
  TOMMY Zero Docker container requires a Linux host. Docker on Windows (including WSL2) and macOS are not supported.
</Callout>

## Installation

### Docker Compose (Recommended)

Docker Compose provides an easier way to manage TOMMY Zero with a configuration file.

**Quick Start:**

1. Create a `docker-compose.yml` file with the following content:

```yaml
services:
  tommy:
    image: tommysense/virtual-bridge:latest
    container_name: tommy
    network_mode: host
    restart: unless-stopped
    environment:
      DASHBOARD_PORT: 8089          # Web Dashboard
      FILE_SERVER_HTTP_PORT: 8090   # Configuration file and OTA
      FILE_SERVER_HTTPS_PORT: 8091  # Configuration file and OTA
      MQTT_PORT: 1886               # Built-in MQTT broker
      UDP_RELAY_PORT: 8547          # Device communication
    volumes:
      - ~/.tommy:/data
```

2. Start the container:

```bash
docker compose up -d
```

3. Stop the container:

```bash
docker compose down
```

4. Update TOMMY Zero:

```bash
docker compose down && docker compose pull && docker compose up -d
```

### Docker Run

Alternatively, you can run TOMMY Zero directly with Docker:

```bash
docker run -d --name tommy \
  --network host \
  -v $HOME/.tommy:/data \
  -e DASHBOARD_PORT=8089 \
  -e FILE_SERVER_HTTP_PORT=8090 \
  -e FILE_SERVER_HTTPS_PORT=8091 \
  -e MQTT_PORT=1886 \
  -e UDP_RELAY_PORT=8547 \
  --restart unless-stopped \
  tommysense/virtual-bridge:latest
```

### Configuration Options

You can customize TOMMY Zero's behavior using environment variables:

| Environment Variable     | Default | Description                |
| ------------------------ | ------- | -------------------------- |
| `DASHBOARD_PORT`         | 8089    | Web dashboard              |
| `FILE_SERVER_HTTP_PORT`  | 8090    | Configuration file and OTA |
| `FILE_SERVER_HTTPS_PORT` | 8091    | Configuration file and OTA |
| `MQTT_PORT`              | 1886    | Built-in MQTT broker       |
| `UDP_RELAY_PORT`         | 8547    | Device communication       |

### Release Channels

The `latest` tag follows stable releases. To try pre-release versions, use the `beta` tag instead:

```yaml
    image: tommysense/virtual-bridge:beta
```

The `beta` tag receives every pre-release and also every stable release, so beta users automatically converge onto stable when it ships. To control updates manually, pin an exact version instead (for example `tommysense/virtual-bridge:6.0.0`).

## Important Notes

### Host Networking Requirement

TOMMY Zero requires host networking (`--network host` or `network_mode: host` in docker-compose.yml) because devices use mDNS for auto-discovery, which requires host networking.

### Data Persistence

The volume mount (`-v $HOME/.tommy:/data` or `~/.tommy:/data` in docker-compose.yml) ensures configuration, zone settings, firmware files, and logs persist across container restarts.

## Accessing the Dashboard

After starting the container, access the TOMMY Zero dashboard at:

```
http://localhost:8089
```

Or replace `localhost` with your server's IP address if accessing remotely.

## Managing the Container

### View Logs

```bash
docker logs tommy
```

### Stop the Container

```bash
docker stop tommy
```

### Start the Container

```bash
docker start tommy
```

### Update TOMMY Zero

**Using Docker Compose:**

```bash
docker compose down && docker compose pull && docker compose up -d
```

**Using Docker Run:**

```bash
# Stop and remove the old container
docker stop tommy
docker rm tommy

# Pull the latest image
docker pull tommysense/virtual-bridge:latest

# Start with the same configuration
docker run -d --name tommy \
  --network host \
  -v $HOME/.tommy:/data \
  -e DASHBOARD_PORT=8089 \
  -e FILE_SERVER_HTTP_PORT=8090 \
  -e FILE_SERVER_HTTPS_PORT=8091 \
  -e MQTT_PORT=1886 \
  -e UDP_RELAY_PORT=8547 \
  --restart unless-stopped \
  tommysense/virtual-bridge:latest
```

## Troubleshooting

* Ensure you're running on a Linux host (not Windows/macOS Docker Desktop)
* Check that `--network host` (or `network_mode: host` in docker-compose.yml) is specified
* Verify no port conflicts with other services
* Check container logs with `docker logs tommy`


# Home Assistant Installation

import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { TrackedHomeAssistantLink } from '@/components/docs/TrackedHomeAssistantLink';

## Requirements

* Home Assistant OS
* AMD64 or ARM64 architecture

## Installation Steps

<Steps>
  <Step>
    ### Add the TOMMY Repository

    Click the button below to add the TOMMY repository to your Home Assistant instance:

    <TrackedHomeAssistantLink />

    **Or manually add the repository:**

    1. Navigate to **Settings** → **Apps** → **App Store**
    2. Click the three dots menu (⋮) in the top right
    3. Select **Repositories**
    4. Add this URL: `https://github.com/tommy-sense/homeassistant-addon`
  </Step>

  <Step>
    ### Install the TOMMY Zero App

    1. Refresh the App Store page
    2. Find "TOMMY Zero" in the list of available apps
    3. Click on the TOMMY Zero app
    4. Click **Install**

    <Callout title="Stable or Beta" type="info">
      The repository contains two apps: **TOMMY Zero** and **TOMMY Zero (beta)**. TOMMY Zero (beta) receives pre-release versions for early testing and is also updated to every stable release. Install one or the other, not both: they use the same ports by default and would conflict.
    </Callout>
  </Step>

  <Step>
    ### Configure the App

    After installation, configure ports if needed:

    1. Go to the **Configuration** tab
    2. Adjust ports if they conflict with your setup:

    | Port                | Default | Purpose                    |
    | ------------------- | ------- | -------------------------- |
    | `dashboard`         | 8089    | Web dashboard              |
    | `file_server_http`  | 8090    | Configuration file and OTA |
    | `file_server_https` | 8091    | Configuration file and OTA |
    | `mqtt`              | 1886    | Built-in MQTT broker       |
    | `udp_relay`         | 8547    | Device communication       |
  </Step>

  <Step>
    ### Start the App

    1. Click **Start** to launch the TOMMY Zero app
    2. Enable **Start on boot** for automatic startup
    3. Enable **Add to sidebar** for easy access
  </Step>
</Steps>

## Accessing the Dashboard

Once the app is running, you can access the TOMMY Zero dashboard within Home Assistant.

## Troubleshooting

* Check app logs in **Settings** → **Apps** → **TOMMY Zero** → **Log**
* Ensure no port conflicts with other services
* Verify Home Assistant has network access to discover ESP32 devices