Thursday, 6 October 2016

Installing ha-bridge on your Raspberry Pi

EDIT: Updated 14th June 2017 to reflect version 4.5.5. Default port is now 80 to keep Google Home happy and service now supports MQTT! Advice on backups also added 7th Feb. Version 4x also supports adding a Home Assistant instance which is great!

Want to control your Vera, Harmony hub or Home Assistant entities with your Amazon echo or Google Home? ha-bridge is the best way to achieve that and installation is actually quite easy and takes less than 5 minutes. Here are the steps.

  1. On your Raspberry Pi, make sure you are in the Pi home folder:
    cd /home/pi/
  2. Then make a habridge folder:
    mkdir habridge
  3. Now change to the folder and download the latest ha-bridge jar file:
    cd habridge
  4. Create a ‘data’ holder inside the habridge folder:
    mkdir data
  5. Now you have to create the systemd service file:
    nano habridge.service
  6. Then copy and paste the following:

    Description=HA Bridge

    ExecStart=/usr/bin/java -jar -Dconfig.file=/home/pi/habridge/data/habridge.config /home/pi/habridge/ha-bridge-4.5.5.jar


  7. Now, to save the file, hit CTRL-X, then hit Y and RETURN
  8. You need Java 8 JDK to be able to run ha-bridge
    sudo apt-get update && sudo apt-get install oracle-java8-jdk
  9. Then run:
    sudo update-alternatives --config java and select the JDK 8 version (/usr/lib/jvm/jdk-8-oracle-arm32-vfp-hflt/jre/bin/java) if asked.
  10. Then run the following to confirm you have the right Java version:
    java -version
  11. Next you need to enable the systemd service so it will automatically start every time you reboot your Raspberry Pi (ignore the Shell script instructions on the ha-bridge ReadMe as newer Debian builds [Jessie] work best with systemd):
    sudo systemctl enable /home/pi/habridge/habridge.service
  12. Now that it is enabled, you have to start it. Since it is enabled, you don’t need the full path to run it:
    sudo systemctl start habridge
  13. The default port for HA Bridge is 80, so open your browser and go to your RPI address, port 80:
N.B If the ha-bridge version is updated, simply edit the WGET line in step 3 to download the correct version and edit the code used in step 6 (habridge.service) to reflect the correct version. If you want, you can have multiple versions downloaded in the habridge folder and simply switch between them by modifying the code in the habridge.service file (the ExecStart line).

  1. Stop ha-bridge either via the GUI or using sudo systemctl stop habridge.service
  2. Change into the ha-bridge directory cd /home/pi/habridge
  3. Edit the service file nano habridge.service
  4. Save the change then run sudo systemctl daemon-reload
  5. Start the service using sudo systemctl start habridge.service
  6. Check the status after a few seconds with sudo systemctl status habridge.service
If you want to control your Home Assistant entities with ha-bridge, there is a great guide here and here on Pete Scargill's blog There is also one on controlling the MiLight bridge here

Immediately after configuring the bridge and all of you devices, I would run a backup at the bottom of the "Bridge Devices" tab and the "Bridge Control" tab. If you do not choose a name, ha-bridge will automatically create one for you.

Bridge Devices is all of the individual actions you've created and if the defaults are left, the backup file will be located in /data and look something like device.db-2017-02-07-20-28-06.bk.

Bridge Control contains the actual bridge configuration like your Harmony Hubs IP, Vera, MQTT etc. The backup is located in /home/pi/habridge/data and looks something likes habridge.config-2017-02-07-20-28-19.cfgbk.

I strongly encourage you to remote in to your Pi using WinSCP and save these backup files locally just in case your Pi's SD card goes duff as mine has on three occasions now. Popping these backups into the appropriate folders after a rebuild certainly makes getting ha-bridge live again much simpler.


  1. Hi
    Found you via Pete Scargill's site. followed your instructions which worked perfectly. But i ran it at port 80 where the Apache page was then ran "sudo java -jar -Dserver.port=82 ha-bridge-3.2.2.jar" to put it on port 82 which works, but it is also on port 80. How do i get port 80 back to where it was ?
    Thanks Chris.

    1. You can configure the port in the ha-bridge GUI. Did you do that?

  2. Thanks to your guide I am able to see the Bridge. I have a Mi-light Dimmable Led Bulb E26 with remote, plus an echo dot. What now? Do I need to purchase a controller?

    Thank you!!

  3. I have done every thing you have said but at the end when I try access the bridge from browser it says this site cannot be reached.
    I enter in browser and it says cannot be reached. I've also tried 88. I have no idea why nothing is happening. Do you have any ideas?

    1. What happens when you type 'sudo systemctl status habridge' (without the quotes). Is the service running? N.B You do not need to append the port if it is 80. Just use the IP.

  4. Hi you need to edit a line in the Service file as it still points to /ha-bridge-3.2.2.jar instead of /ha-bridge-3.5.1.jar

    Caused me a slight problem but excellent write up.


  5. Thank you!

    This was the missing step for me to finish off setting up a link between openhab and echo.