Homebridge Eqiva eQ-3 (EQ3) Bluetooth Thermostat Plugin

This plugin allows you to control Eqiva eQ-3 (EQ3) Bluetooth thermostats via Homebridge.

Prerequisites

Before installing this plugin, ensure you have the expect tool installed:

sudo apt install expect

Installation

Step 1: Install the Plugin

Install the plugin using:

sudo npm install -g homebridge-eq3hk

Step 2: Set Up MQTT

1. Install Mosquitto:

   sudo apt update
   sudo apt install mosquitto mosquitto-clients
   sudo systemctl start mosquitto
   sudo systemctl enable mosquitto

2. Verify Mosquitto is running:

   sudo systemctl status mosquitto

Step 3: Pair Your Thermostat

1. Enter Bluetooth control:

   sudo bluetoothctl

2. Turn on the agent and start scanning:

   agent on
   scan on

3. Pair with the thermostat using its MAC address:

   pair XX:XX:XX:XX:XX:XX

4. Enter the pairing code displayed on the thermostat.

Step 4: Grant Execution Permissions

Grant execution permissions to the eq3.exp file:

sudo chmod +x /path/to/homebridge-eq3hk/eq3.exp

Example:

sudo chmod +x /var/lib/homebridge/node_modules/homebridge-eq3hk/eq3.exp

Check the owner of the file and ensure the user running Homebridge has the appropriate permissions:

ls -l /var/lib/homebridge/node_modules/homebridge-eq3hk/eq3.exp

Step 5: Configuration via Homebridge UI

Configuration is done via the Homebridge UI, allowing you to add and configure multiple thermostats easily.

Example configuration via the Homebridge UI:

• Name: Living Room Thermostat
• MAC Address: XX:XX:XX:XX:XX:XX
• Cache: 10

To add multiple thermostats, simply repeat the process with different MAC addresses.

Step 6: Running mqtt_handler.js on Startup

To ensure the mqtt_handler.js script runs automatically on Raspberry Pi startup, create a systemd service:

1. Create a service file:

   sudo nano /etc/systemd/system/mqtt_handler.service

2. Add the following configuration:

   [Unit]
   Description=MQTT Handler
   After=network.target
   
   [Service]
   ExecStart=/usr/bin/node /path/to/homebridge-eq3hk/mqtt_handler.js
   WorkingDirectory=/path/to/homebridge-eq3hk
   StandardOutput=inherit
   StandardError=inherit
   Restart=always
   User=pi
   
   [Install]
   WantedBy=multi-user.target

   Replace /path/to/homebridge-eq3hk with the actual path to your plugin installation directory (typically /var/lib/homebridge/node_modules/homebridge-eq3hk).

3. Save and close the file, then reload systemd:

   sudo systemctl daemon-reload

4. Start and enable the service:

   sudo systemctl start mqtt_handler.service
   sudo systemctl enable mqtt_handler.service

5. Check the status of the service:

   sudo systemctl status mqtt_handler.service

Troubleshooting

Mosquitto installation issues (Raspberry Pi / Debian Bookworm)

Mosquitto 2.x is available directly from the default Debian Bookworm repositories — no PPA required. Just use:

sudo apt update && sudo apt install mosquitto mosquitto-clients

If you previously tried adding the Mosquitto PPA and encountered errors, you can safely ignore them and use the command above.

Bluetooth adapter DOWN / Connection failed after reboot

If the BT adapter is blocked by rfkill, eq3.exp will fail silently. Check:

hciconfig hci0

If it shows DOWN, unblock and bring it up:

sudo bash -c 'echo 0 > /sys/class/rfkill/rfkill0/soft'
sudo hciconfig hci0 up

To make this permanent across reboots, add to /etc/rc.local (before exit 0):

/bin/bash -c "echo 0 > /sys/class/rfkill/rfkill0/soft" 2>/dev/null
hciconfig hci0 up 2>/dev/null

mqtt_handler stops working after plugin update

After updating the plugin via Homebridge UI, restart the mqtt_handler service:

sudo systemctl restart mqtt_handler.service

eq3.exp permission denied

Run:

sudo chmod +x /var/lib/homebridge/node_modules/homebridge-eq3hk/eq3.exp

HomeKit shows wrong temperature

The plugin uses a cache (default: 10 seconds). If temperature seems stale, reduce the Cache Duration in plugin settings.

Acknowledgements

This plugin utilizes the eQ-3 radiator thermostat repository, specifically the eq3.exp file. Many thanks to the author, Heckie75, for their valuable contribution.