This Home Assistant add-on connects directly to your WaterFurnace Aurora-based heat pump system via RS-485 and publishes all sensor data to MQTT using the Homie convention. Home Assistant automatically discovers all entities through MQTT.
✅ Direct RS-485 Connection - No cloud dependency
✅ Auto-Discovery - Entities appear automatically in Home Assistant
✅ Serial & Network Support - USB adapters or Waveshare network adapters
✅ Comprehensive Sensors - Temperatures, power usage, system status, and more
✅ Web Debug Interface - Built-in web tool for diagnostics
✅ Debug Logging - Packet-level RS-485 communication debugging
New to this add-on? Follow these guides in order:
- Prerequisites - Check compatibility and requirements
- Hardware Setup - Create cable and connect to heat pump
- MQTT Setup - Install and configure Mosquitto broker
- Installation - Install and configure the add-on
Already set up? See Quick Start Guide for a condensed reference.
- Prerequisites - Hardware/software requirements and compatibility
- Hardware Setup - Cable creation, wiring diagram, physical connections
- MQTT Setup - Mosquitto broker installation and user creation
- Installation Guide - Add-on installation, configuration, verification
- Basic Configuration - Connection types, MQTT settings, log levels
- Network Adapters - Complete Waveshare setup guide (900+ lines)
- MQTT Configuration - Detailed MQTT broker setup and troubleshooting
- Troubleshooting Guide - Common issues and solutions
- Connection Issues - Heat pump connection problems
- Debug RS-485 - Packet-level communication debugging
- Logging Guide - Understanding and troubleshooting logs
- MQTT Issues - MQTT broker and entity discovery problems
- Releasing Guide - Automated release process and versioning
You need:
- WaterFurnace heat pump with Aurora control system (AID Tool port)
- RS-485 adapter - Choose one:
- USB RS-485 adapter (e.g., FTDI adapter) - Direct connection to Home Assistant
- Network adapter (e.g., Waveshare RS232/485_TO_WIFI_ETH) - Connect over Ethernet/WiFi
- Custom cable - RJ45 to bare wires (see Hardware Setup)
- MQTT broker - Mosquitto broker add-on (see MQTT Setup)
See Prerequisites Guide for detailed compatibility and requirements.
- In Home Assistant: Settings → Add-ons → Add-on Store
- Click ⋮ (top right) → Repositories
- Add:
https://github.com/atheismann/home-assistant-aurora-ruby-addon - Find Aurora MQTT Gateway and click Install
- Configure (see below) and click Start
Need help? See the Installation Guide for detailed instructions.
connection_type: serial
serial_port: /dev/ttyUSB0
mqtt_host: core-mosquitto
mqtt_port: 1883
mqtt_username: homeassistant
mqtt_password: your_secure_password
log_level: infoconnection_type: network
network_host: 192.168.1.100
network_port: 8899
network_protocol: tcp
mqtt_host: core-mosquitto
mqtt_port: 1883
mqtt_username: homeassistant
mqtt_password: your_secure_password
log_level: infoFor detailed configuration:
- Basic Configuration - All configuration options explained
- Network Adapters - Waveshare serial parameters (19200 8E1)
- MQTT Configuration - MQTT broker setup
Once running, Home Assistant automatically discovers:
Climate & Temperatures:
- Entering/leaving water temperature
- Outdoor temperature
- Lockout temperature
- Zone temperatures
System Status:
- Operating mode (heating, cooling, idle)
- Active zones
- Compressor speed & power
- Pump & fan speeds
Power & Energy:
- Compressor power & amperage
- Total system power
- Daily/monthly energy usage
And 40+ more sensors depending on your equipment configuration.
Tested and working with:
- WaterFurnace 7 Series with IntelliZone 2
- WaterFurnace 5 Series
- GeoSmart systems
- Various configurations with DHW, ECM blowers, VS drives, VS pumps
Requirements:
- Aurora control system with AID Tool port (RJ45 diagnostic port)
- Compatible with most WaterFurnace heat pumps manufactured after 2008
Having issues? Check these guides:
- Connection Issues - Can't connect to heat pump? Start here
- MQTT Issues - No entities appearing in Home Assistant?
- Debug RS-485 - ModBus timeout errors?
- Logging Guide - Understanding log output
Common Problems:
| Problem | Quick Solution | Guide |
|---|---|---|
| ModBus timeout | Try reversing A+/B- connections | Connection Issues |
| No entities | Check MQTT broker is running | MQTT Issues |
| Device not found | Check /dev/ttyUSB* exists |
Connection Issues |
| Wrong values | Enable debug logging | Debug RS-485 |
Enable detailed RS-485 communication logging:
log_level: debugThis enables:
- Network mode: tcpdump packet capture of all RS-485 communication
- Serial mode: strace system call tracing
- ModBus protocol: Request/response byte-level logging
See Debug RS-485 Guide for interpreting debug output.
This add-on follows semantic versioning with automated releases.
When a PR is merged to main, a new version is automatically:
- Calculated based on PR labels (
major,minor, orpatch) - Tagged and released on GitHub
- Built and published to GitHub Container Registry
See Releasing Guide for details.
See CHANGELOG.md for version history and changes.
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
- Label your PR:
major,minor, orpatchfor semantic versioning
See Releasing Guide for release process details.
- Documentation: Browse the docs/ folder for comprehensive guides
- Issues: Report bugs or request features
- Discussions: Ask questions or share your setup
- Community: Home Assistant Community Forum
This add-on packages the excellent waterfurnace_aurora Ruby gem by @ccutrer.
Built with:
- waterfurnace_aurora - Ruby library for Aurora protocol
- Alpine Linux - Lightweight container base
- Home Assistant - Home automation platform
This add-on is licensed under the MIT License. The underlying waterfurnace_aurora library is also MIT licensed.
Made with ❤️ for WaterFurnace heat pump owners