ESPresense is an AGPL-3.0 licensed ESP32 firmware project that turns low-cost ESP32 boards into indoor positioning nodes which report presence data over MQTT to Home Assistant or to the ESPresense-companion application.

What it is

ESPresense is an open-source firmware and companion toolchain for the ESP32 microcontroller platform, written in C and distributed under the AGPL-3.0 licence. Each node runs on an ESP32 board, gathers indoor positioning information, and transmits that data to an MQTT broker so that other software can determine where tracked devices are located within a building. The project sits inside the Home Assistant and broader home-automation ecosystem, where MQTT acts as the common message bus between sensors and consumers.

The concrete problem it solves is room-level presence awareness for automation. Home Assistant exposes a mqtt_room component for this purpose, and ESPresense provides the hardware-side implementation that feeds it. Without a node like this, a Home Assistant installation knows only that a device exists on the network, not which room it occupies. ESPresense fills that gap by placing inexpensive ESP32 hardware around a home or building and publishing position estimates that automations can consume directly. For users who want more than the stock mqtt_room integration, the separate ESPresense-companion project consumes the same node output to provide fuller indoor positioning.

Key capabilities

• Runs on ESP32 hardware and is built with the esp32-arduino framework, so nodes are assembled from commodity microcontroller boards.
• Publishes presence and position data over MQTT for consumption by Home Assistant's mqtt_room component.
• Works with ESPresense-companion for indoor positioning beyond what the stock Home Assistant component provides.
• Supports several compact board targets, with named topics for m5atom, m5atom-lite, m5atom-matrix, and m5stickc-plus devices.
• Documents its build process in BUILDING.md and tracks changes in CHANGELOG.md, so contributors can compile firmware from source.
• Carries a continuous-integration build via GitHub Actions, giving each commit a verifiable build status.
• Ships under AGPL-3.0, keeping the firmware and any modified distributions open.

Who uses it and how

• Home Assistant users who want room-level automations, feeding positions into the mqtt_room sensor component over an existing MQTT broker.
• Households running several nodes at once, since indoor positioning improves as more ESP32 boards cover different rooms.
• Makers using small M5Stack form-factor hardware, including m5atom, m5atom-lite, m5atom-matrix, and m5stickc-plus boards, for discreet room-mounted nodes.
• Users who outgrow the basic Home Assistant path and deploy ESPresense-companion alongside the nodes for dedicated indoor positioning.
• Contributors and self-builders who follow BUILDING.md to compile and flash firmware rather than relying on prebuilt binaries.

Getting started

Build the firmware from source following the instructions in BUILDING.md, then flash it to a supported ESP32 board, including the M5Stack variants named in the project topics. Full documentation is hosted at espresense.com, and changes between versions are listed in CHANGELOG.md.

How it compares

Within the tools named in the project's own documentation, ESPresense is the node-side firmware, while Home Assistant's mqtt_room component is the consumer and ESPresense-companion is the richer positioning front end that reads the same node output. It therefore complements rather than competes with those projects: the component and companion are useless for indoor positioning without hardware publishing to MQTT, and ESPresense is that hardware layer.

When to use it — and when not to

A self-hoster must run an MQTT broker and, for the fuller positioning experience, the separate ESPresense-companion service, plus the hardware and flashing workflow needed to build and deploy firmware to each node. Anyone unwilling to operate a broker, compile firmware, or maintain multiple physical boards should look elsewhere. The README itself is thin, offering badges, a documentation link, and pointers to BUILDING.md and CHANGELOG.md rather than step-by-step setup, and the repository carries 121 open issues, so expect to rely on the external documentation site when problems arise.