Installation

Home Assistant OS (HAOS)

Step 1: Add Repository

Click Add

Step 2: Install

Click Install, Start, then Show in Sidebar

Home Assistant Container

Example docker-compose configuration:

version: '3.7'
services:
  espresense:
    image: espresense/espresense-companion
    ports:
      - 8267:8267
    volumes:
      - ./data/espresense:/config/espresense

MQTT Setup

ESPresense and ESPresense Companion require MQTT to function. Here’s how to set it up:

Using Home Assistant’s MQTT Addon

Install the Mosquitto broker addon from the official add-on store
Start the addon
ESPresense Companion will automatically use these settings

Using External MQTT Broker

Install Mosquitto or your preferred MQTT broker
Note your configuration:
- Host
- Port (default 1883)
- Username
- Password
You’ll need these details for the configuration step

MQTT Discovery

Enable MQTT Discovery (“auto-discovered”) in your MQTT configuration
If disabled, you’ll need to manually configure MQTT settings in the Companion’s MQTT tab

Node Configuration

After installation, configure your ESPresense nodes by setting maximum distance to zero. To modify the maximum distance, send an MQTT message (in Home Assistant, Settings->MQtt->Configure, “Publish a packet”?) :

key: espresense/rooms/*/max_distance/set
value: 0

This ensures you get all distance readings without filtering.

Next Steps

Once installation is complete:

Move on to Configuration to set up your floorplan
Place your nodes according to the Node Placement Guide
Start tracking your devices!

Troubleshooting Installation

Common Issues:

Can’t see the add-on in Home Assistant:
- Refresh your browser
- Verify the repository was added successfully
- Check the add-on store logs
MQTT Connection Failed:
- Verify MQTT broker is running
- Check credentials are correct
- Ensure MQTT port (1883) is not blocked
Docker Container Won’t Start:
- Check port 8267 is not in use
- Verify volume mount permissions
- Review container logs