Emulates Philips Hue API to other home automation gateways such as an Amazon Echo/Dot or other systems that support Philips Hue local network discovery. The ha-bridge is not part of meethue.philips.com so the cloud sign in does not apply to this system. The Bridge handles basic commands such as "On", "Off", "Brightness" and "Color" commands of the hue protocol. This bridge can control most devices that have a distinct API.
Here are some diagrams to put this software in perspective.
The Echo path looks like this:
+------------------------+ +------------------------+
+-------------+ | H A +------------------| | A +------------------+ |
| Amazon Echo |----->| U P | ha-bridge core |--->| P | Device to control| |
+-------------+ | E I +------------------| | I +------------------+ |
+------------------------+ +------------------------+
THe Harmony Hub path looks like this:
+------------------------+ +------------------------+
+-------------+ | H A +------------------| | A +------------------+ |
| Harmony Hub |----->| U P | ha-bridge core |--->| P | Device to control| |
+-------------+ | E I +------------------| | I +------------------+ |
+------------------------+ +------------------------+
A Custom implementation path looks like this:
+------------------------+ +------------------------+
+-------------+ | H A +------------------| | A +------------------+ |
| HA System |----->| U P | ha-bridge core |--->| P | Device to control| |
+-------------+ | E I +------------------| | I +------------------+ |
+------------------------+ +------------------------+
SECURITY RISK: If you are unsure on how this software operates and what it exposes to your network, please make sure you understand that it can allow root access to your system. It is best practice to not open this to the Internet through your router as there are no security protocols in place to protect the system. The License agreement states specifically that you use this at your own risk.
ATTENTION: This requires a physical Amazon Echo, Echo Plus, Spot, Tap or Show and does not work with prototype devices built using the Alexa Voice Service e.g. Amazon's Alexa AVS Sample App and Sam Machin's AlexaPi. The AVS version does not have any capability for Hue Bridge discovery!
NOTE: This software does require the user to have knowledge on how processes run on Linux or Windows with java. Also, an understanding of networking basics will help as well. This system receives upnp udp multicast packets from devices to be found, so that is something to understand. Please make sure you have all your devices use static IP addresses from your router. Most all questions have been answered already. PLEASE USE GOOGLE TO FIND YOUR ANSWERS!
NOTE: This software does not control Philips Hue devices directly. A physical Philips Hue Hub is required for that, by which the ha-bridge can then proxy all of your real Hue bridges behind this bridge.
ISSUE: Google Home does NOT support local connection to Philips Hue Hubs and requires that it connect to meethue.com. Since the ha-bridge only emulates the local API, and is not associated with Philips, this method will not work.
FAQ: Please look here for the current FAQs! https://github.com/bwssytems/ha-bridge/wiki/HA-Bridge-FAQs
In the cases of systems that require authorization and/or have APIs that cannot be handled in the current method, a module may need to be built. The Harmony Hub is such a module and so is the Nest module. The Bridge has helpers to build devices for the gateway for the Logitech Harmony Hub, Vera, Vera Lite or Vera Edge, Nest, Somfy Tahoma, Home Assistant, Domoticz, MQTT, HAL, Fibaro, HomeWizard, LIFX, OpenHAB, FHEM, Broadlink, Mozilla IOT, HomeGenie and the ability to proxy all of your real Hue bridges behind this bridge.
Alternatively the Bridge supports custom calls and executing programs/scripts as well using http/https/udp and tcp such as the LimitlessLED/MiLight bulbs using the UDP protocol. Binary data is supported with UDP/TCP.
This bridge was built to help put the Internet of Things together.
To customize and build it yourself, build a new jar with maven:
mvn install
Otherwise, downloads are available at https://github.com/bwssytems/ha-bridge/releases.
Then locate the jar and start the server with:
ATTENTION: Due to port 80 being the default, Linux restricts this to super user. Use the instructions below.
java -jar ha-bridge-5.4.1.jar
Next gen Linux systems (this includes the Raspberry Pi), use systemd to run and manage services. Here is a link on how to use systemd: https://www.digitalocean.com/community/tutorials/how-to-use-systemctl-to-manage-systemd-services-and-units
Create the directory and make sure that ha-bridge-5.4.1.jar is in your /home/pi/ha-bridge directory.
pi@raspberrypi:~ $ mkdir ha-bridge
pi@raspberrypi:~ $ cd ha-bridge
pi@raspberrypi:~/ha-bridge $ wget https://github.com/bwssytems/ha-bridge/releases/download/v5.4.1/ha-bridge-5.4.1.jar
Create the ha-bridge.service unit file:
pi@raspberrypi:~ $ cd /etc/systemd/system
pi@raspberrypi:~ $ sudo nano ha-bridge.service
Copy the text below into the editor nano.
[Unit]
Description=HA Bridge
Wants=network.target
After=network.target
[Service]
Type=simple
WorkingDirectory=/home/pi/ha-bridge
ExecStart=/usr/bin/java -jar -Dconfig.file=/home/pi/ha-bridge/data/habridge.config /home/pi/ha-bridge/ha-bridge-5.4.1.jar
[Install]
WantedBy=multi-user.target
Save the file in the editor by hitting CTL-X and then saying Y to update and save.
Reload the system control config:
pi@raspberrypi:~ $ sudo systemctl daemon-reload
To start the bridge:
pi@raspberrypi:~ $ sudo systemctl start ha-bridge.service
To start the service at boot, use the enable command:
pi@raspberrypi:~ $ sudo systemctl enable ha-bridge.service
To look at the log, the output goes into the system log at `/var/log/syslog':
pi@raspberrypi:~ $ tail -f /var/log/syslog
Docker start offering official support for Raspbian operating system since autumn 2016. Running services inside containers became to be a good alternative to normal installation method described before.
Install Docker Community Edition (CE) on Raspberry Pi
pi@raspberrypi:~ $ curl -fsSL get.docker.com -o get-docker.sh
pi@raspberrypi:~ $ sudo sh get-docker.sh
For every architecture there is a specialized ha-bridge Docker image available. Please use the suitable image from the following list.
The following example explains how to run the latest version of ha-bridge Docker container on Raspberry Pi 3.
pi@raspberrypi:~ $ docker pull habridge/ha-bridge-raspberrypi3
pi@raspberrypi:~ $ docker run \
--name ha-bridge \
--rm \
--init \
--detach \
--net=host \
--volume=$PWD:/ha-bridge/data \
--volume=/etc/localtime:/etc/localtime:ro \
--volume=/etc/timezone:/etc/timezone:ro \
habridge/ha-bridge-raspberrypi3
To set additional arguments for ha-bridge just write them as arguments for docker run command.
pi@raspberrypi:~ $ docker run \
--name ha-bridge \
--rm \
--init \
--detach \
--net=host \
--volume=$PWD:/ha-bridge/data \
--volume=/etc/localtime:/etc/localtime:ro \
--volume=/etc/timezone:/etc/timezone:ro \
habridge/ha-bridge-raspberrypi3 \
-Dserver.port=8080 \
-Dsecurity.key=secret
To halt the ha-bridge Docker container use the stop command:
pi@raspberrypi:~ $ docker stop ha-bridge
If you like to automate the deployment just use the Ansible role on https://github.com/escalate/ansible-ha-bridge-docker.
These examples will help you proxy your current webserver requests to the ha-bridge running on a different port, such as 8080.
Reverse proxy with Apache on Ubuntu linux:
Enable the required Apache modules:
a2enmod proxy proxy_http headers
Added the following lines to my Apache config file “000-default”
<VirtualHost *:80>
ProxyPass /api http://localhost:8080/api nocanon
ProxyPassReverse /api http://localhost:8080/api
ProxyRequests Off
AllowEncodedSlashes NoDecode
# Local reverse proxy authorization override
# Most unix distribution deny proxy by default (ie /etc/apache2/mods-enabled/proxy.conf in Ubuntu)
<Proxy http://localhost:8080/api*>
Order deny,allow
Allow from all
</Proxy>
….. (the rest of the VirtualHost config section) …..
</VirtualHost>
Restart apache for the changes to take effect.
service apache2 restart
server.modules += ( "mod_proxy" )
proxy.server = (
"/api" =>
(
( "host" => "127.0.0.1",
"port" => "8080"
)
)
)
location /api {
proxy_pass http://127.0.0.1:8080/api;
}
Arguments are now deprecated. The ha-bridge will use the old -D arguments and populate the configuration screen, Bridge Control Tab, which can now be saved to a file and will not be needed. There is only one optional argument that overrides and that is the location of the configuration file. The default is the relative path "data/habridge.config".
This will guarantee that the ha-bridge will not use an IPV6 address. This cannot be automatically set inside the code.
java -jar -Djava.net.preferIPv4Stack=true ha-bridge-W.X.Y.jar
<filepath>The default location for the configuration file to contain the settings for the bridge is the relative path from where the bridge is started in "data/habridge.config". If you would like a different filename or directory, specify -Dconfig.file=<directory>/<filename> explicitly. The command line example:
java -jar -Dconfig.file=/home/me/data/myhabridge.config ha-bridge-W.X.Y.jar
<port number>The default port number for the bridge is 80. To override what the default or what is in the configuration file for this parameter, specify -Dserver.port=<port number> explicitly. This is especially helpful if you are running the ha-bridge for the first time and have another application on port 80. The command line example:
java -jar -Dserver.port=80 ha-bridge-W.X.Y.jar
Note: if using with a Google Home device, port 80 must be used.
<ip address>The default ip address for the bridge to listen on is all interfaces (0.0.0.0). To override what the default or what is in the configuration file for this parameter, specify -Dserver.ip=<ip address> explicitly. This is especially helpful if you are running the ha-bridge for the first time and have another application on that utilizes the default interface. The command line example:
java -jar -Dserver.ip=192.168.1.1 ha-bridge-W.X.Y.jar
<Your Key To Encrypt Security Data>This option is very important to set if you will be using username/passwords to secure the ha-bridge. The ha-bridge needs to encrypt the settings in the config file and to make sure they are secured specifically to you is to provide this key. Otherwise a default key is used and it is available in the code on github for the ha-bridge here, so not very secure in that sense. It is very important provide this if you are using username/password. To override the default, specify -Dsecurity.key=<Your Key To Encrypt Security Data> explicitly on the command line. This is will prevent any issues if your config file gets hacked. The command line example:
java -jar -Dsecurity.key=Xfawer354WertSdf321234asd ha-bridge-W.X.Y.jar
<The path to your scripts and program directory>This sets a directory of your choosing to have a walled area for what can be executed by the Exec Command type. This is a good feature to use if you use the capabilities of executing a script or program from the ha-bridge. The default is not set which allows any program or script to be called and anyone with access to the your system could create an exec command call and execute it from the API. This is will prevent any issues if your system gets hacked. To override the default, specify -Dexec.garden=<The path to your scripts and program directory> explicitly on the command line. The command line example:
java -jar -Dexec.garden=C:\Users\John\bin
This section will cover the basics of configuration and where this configuration can be done. This requires that you have started your bridge process and then have pointed your
favorite web interface by going to the http://<my ip address>:<port> or http://localhost:<port> with port you have assigned. The default quick link is http://localhost for your reference.
This screen allows you to see your devices you have configured for the ha-bridge to present to a controller, such as an Amazon Echo/Dot. You can test each device from this page as this calls the ha-bridge just as a controller would, i.e. the Echo. This is useful to make sure your configuration for each device is correct a
$ claude mcp add ha-bridge \
-- python -m otcore.mcp_server <graph>