Table of Contents

HAmbiSync (Hue Ambilight Synchronization)

This project is a desktop/server version of the Ambilight+hue mobile app.

HAmbiSync periodically queries your Philips TV (2011+ models with ambilight are supported) for ambilight colors data on TV edges, calculates the average value of the user defined points and sends this color to the configured Hue Lamps.

The idea is to save the resources on the smartphone/tablet and run the synchronization service on your desktop or even a server. You can also control this app remotely using simple HTTP requests (via curl/wget or your own apps and scripts). See below for the XBMC automation example.

This app is intended for advanced users, or at least to the users who can read and understand the documentation below.

AFTER upgrading to the new firmware, jointSPACE NEEDS TO BE ACTIVATED by entering the following digits sequence while watching TV (WatchTV activity): "5646877223". You don't need to activate it if the original Ambilight+hue mobile app already works for you.

This sample is for 2 hue lamps, lamp 1 is located on the right of the TV, above the top edge and is mapped to the top led on the right edge and to the 2 most right leds of the top edge. Lamp 2 is mapped to the top-left side leds. If you specify multiple sides/leds, the average color of all these leds will be used.

To find out how many leds your TV API reports, open http://<tv.ip>:1925/1/ambilight/topology.

For this model top side has 9 leds, right/left sides have 4 leds. Note that index is zero based, so the right top edge led index is 8, not 9.
Lamp numbers can be found using the Hue app or Ambilight+hue app on your mobile device.

The above topology and lamps config corresponds to the following layout:

Layout for your TV may be different. On some TVs index on the sides starts from the bottom instead of the top (3-2-1-0 instead of 0-1-2-3).

You can add more lamps to the config if needed and map them to any leds or the average value of arbitrary leds combination.

Ensure JSON syntax is still valid after your modifications, don't forget the commas.

transition property specifies how smoothly the colors will change. 3 is the default value used in the original mobile app for all the lamps except those in the shadowed zone (behind the user), this zone lamps have transition time set to 5.

immersion property sets the level of the experience. Value 10 is the default, value 0 will give you white lamps.

brightness is self explanatory (0-10).

model allows to specify the model of the lamp. Normally the model should be detected automatically from the bridge, but it may not work for some lamps. Recognized models: LCT001, LCT002, LCT003, LLC001, LLC005, LLC006, LLC007, LLC011, LLC012, LLC013, LLC014, LLS001, LST001. Lightstrip is LST001, Bloom is LLC007, A19 is LCT001, BR30 is LCT002.

Lamps will be updated in the same order as in the config file. If you have multiple lamps on the same side, it makes sense to put them close in the config.

Start the app:

Windows: run bin\hambisync.exe

Mac/Linux: cd bin, run java -jar hambisync.jar or run bin/hambisync.sh

On the first start the app will search for bridges in your local network. If you have only one bridge, it will try to connect to this bridge automatically. Follow the console log messages and press the button on your bridge to authorize the connection.

If you have multiple bridges, either specify the bridge IP in conf/application.conf via bridge.ip property or use HTTP API to connect to the specific bridge IP: http://127.0.0.1:4567/bridge/connect/<IP>, open http://127.0.0.1:4567/bridge for the bridges list.

Ctrl+C to stop the app. You need to restart the app after making any changes to configuration. Lamps configuration can be applied on the fly using /sync-preset/load/<name> WEB API, see below.

Running as Windows Service

After you've configured the app and ensured that it works properly, it's a good idea to start it automatically as the system service.
Use the supplied scripts in the bin directory. Make sure to run them as Administrator.

install-service.bat to install the HAmbiSync service

start-service.bat to start the HAmbiSync service

If you want to access the service via HTTP API, change web.ip to IP address of your machine that can be accessed within the local network and ensure that web.port (4567 by default) is open on your firewall. You must add firewall exception for the service/app or add a rule for this specific port, otherwise firewall will block access and you will not be able to control the service remotely.

Linux/Mac users will have to use their system specific approach to run java -jar hambisync.jar or bin/hambisync.sh on system startup.

HTTP Control API

HAmbiSync starts a web server on the user specified web.ip:web.port (http://127.0.0.1:4567 by default). Use it to control the server remotely from other applications and scripts.

URL

Description

/

app version and synchronization status

/status

1 if sync is running, 0 otherwise

/start

start ambilight to hue sync

/stop

stop ambilight to hue sync

/toggle

toggle ambilight to hue sync

/sync-preset/load/<name>

load lamps synchronization config from conf/sync-presets/<name>.json

/on

turn all sync config lamps on

/off

turn all sync config lamps off

/preset/save/<name>

save current lamps state into the preset with provided <name>

/preset/load/<name>

load preset with provided name and applies it to lamps

/preset/load/<name>/<delay>

load preset after specified delay in milliseconds

/preset/list/

print the list of available presets

/bridge

list discovered bridges

/bridge/connect

connect to the first discovered bridge

/bridge/connect/<ip>

connect to the bridge with the specified <ip>

/cc/<trigger>

execute command and control preset with the specified <trigger>

/cc-ctrl/reload

reload command and control presets without restating the server

/cc-ctrl/list

list command preset triggers and the descriptions

Command & Control Presets

It's possible to define your own presets that will run applications/scripts on the machine where HAmbiSync is running via HTTP API calls.
This way you can control apps and automate different processes by simple HTTP GET requests that can be performed from other apps, mobile devices, Android widgets (via Tasker), etc.

Presets are .json files that are placed in conf/cc-presets folder, example of the preset:

trigger defines what URL will trigger the command, in this case it would be /cc/fb.

aliases can provide an optional array of triggers that will run the same preset

type defines what the preset does, use exec for execution of the process and http for HTTP request.

command is the path to the executable/script, if type is set to http, the command defines the URL to query

workdir is the working directory, if not set, executable's parent directory will be used

args defines an array of arguments to pass to the executable, each argument can be a fixed parameter or a placeholder ${param}, placeholders are substituted with the corresponding HTTP request parameters. To stop playing and pass /stop, the URL would be: /cc/fb?action=stop, to start playback again: /cc/fb?action=play