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

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

Using External MQTT Broker

1. Install Mosquitto or your preferred MQTT broker
2. Note your configuration:
   • Host
   • Port (default 1883)
   • Username
   • Password
3. 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:

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

This ensures you get all distance readings without filtering.

Next Steps

Once installation is complete:

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

Troubleshooting Installation

Common Issues:

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