Troubleshooting

Installation Issues

Add-on Not Appearing

  • Refresh your browser cache
  • Re-add the repository using the button on the Installation page
  • Check add-on store logs for repository errors

Container Issues

  • Check if port 8267 is already in use
  • Verify volume mount permissions
  • Review container logs using docker logs espresense-companion
  • Check firewall settings
  • Verify container network mode

MQTT Issues

Connection Problems

  • Verify MQTT broker is running
  • Check credentials in config.yaml match your MQTT setup
  • Ensure port 1883 is not blocked
  • Test MQTT connection using MQTT Explorer
  • Check broker logs

Discovery Not Working

  • Verify “Discovery” is enabled in MQTT configuration
  • Check MQTT logs for discovery messages
  • Try manually configuring MQTT in the Companion’s MQTT tab

Configuration Issues

Room Layout Problems

  • Verify floor ID matches between rooms and floor sections
  • Check points format: [[x,y], [x,y]]
  • Ensure coordinates are within floor bounds
  • Confirm measurements use consistent units
  • Verify origin point (0,0) is at bottom-left
  • Check room points are in clockwise/counter-clockwise order
  • Look for overlapping room definitions

Node Configuration

  • Confirm room ID matches between nodes and rooms sections
  • Verify coords are within room boundaries
  • Check that each node has a unique name
  • Ensure node maximum distance is set to 0
  • Verify node firmware version

Device Tracking Issues

Device Not Appearing

  • Check devices tab for MQTT messages
  • Verify device ID format matches wildcards
  • Ensure BLE device is broadcasting
  • Check number of node fixes (aim for 5+)

Inaccurate Location

  • Hover over device to see distance circles
  • Verify node placement follows recommended guidelines
  • Check for interference sources
  • Review node optimization status
  • Verify RSSI@1m calibration

Log Files

Check these logs for troubleshooting:

Companion Logs

  • Home Assistant add-on: Check add-on logs
  • Docker: Use docker logs espresense-companion
  • Look for error messages and connection issues

MQTT Topics to Monitor

espresense/rooms/+/max_distance  # Node distance settings
espresense/devices/+             # Device updates
espresense/rooms/+/telemetry     # Node status

Quick Fixes

Poor Accuracy

  1. Check Node Coverage:
    • Verify 5+ nodes can see device
    • Check node placement matches guidelines
    • Look for dead zones in coverage
  2. Check Settings:
    • Verify node maximum distance is 0
    • Review device RSSI@1m values
    • Check node optimization results

System Reset Steps

  1. Soft Reset:
    • Restart the companion service
    • Clear browser cache
    • Re-subscribe to MQTT topics
  2. Hard Reset:
    • Backup config.yaml
    • Remove and reinstall add-on
    • Restore configuration
    • Reconfigure nodes

Getting Help

If you’re still having issues:

  1. Join our Discord Community - The fastest way to get help and discuss ESPresense
  2. Check GitHub Issues
  3. Create a new issue with:
    • Your config.yaml (redact sensitive info)
    • Error messages/logs
    • Steps to reproduce
    • Expected vs actual behavior

Help write this documentation! Click the edit this page below.