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
- Check Node Coverage:
- Verify 5+ nodes can see device
- Check node placement matches guidelines
- Look for dead zones in coverage
- Check Settings:
- Verify node maximum distance is 0
- Review device RSSI@1m values
- Check node optimization results
System Reset Steps
- Soft Reset:
- Restart the companion service
- Clear browser cache
- Re-subscribe to MQTT topics
- Hard Reset:
- Backup config.yaml
- Remove and reinstall add-on
- Restore configuration
- Reconfigure nodes
Getting Help
If you’re still having issues:
- Join our Discord Community - The fastest way to get help and discuss ESPresense
- Check GitHub Issues
- Create a new issue with:
- Your config.yaml (redact sensitive info)
- Error messages/logs
- Steps to reproduce
- Expected vs actual behavior