Philips HDMI Sync API

superfladdy · December 28, 2020, 9:31am

Hi there,

quick question: Anyone maybe working on adding a binding for the Philips (Hue) HDMI sync box using their new API: https://hueblog.com/2020/03/04/hue-developers-can-now-access-api-for-the-hdmi-sync-box/

I would love to automate when (and when not) the box should synchronize the Hue lamps with the TV.

Before even considering looking into what it would take to do implement it myself, I wanted to check if someone more capable might already be working on this (or has it on the roadmap)

Thanks!

nYce · February 23, 2021, 1:05pm

I’m also very interested in Integrating my SyncBox into Openhab.

I’ve added a Feature Request: [hue] Add Hue Sync Box · Issue #10218 · openhab/openhab-addons · GitHub

superfladdy · February 23, 2021, 3:12pm

Great - thanks. I of course didn’t have any time yet to look into this further. As such, it might be better to make this an official feature request and let this be covered by people who know what they are doing.

Marlow · February 26, 2021, 8:57pm

Interested, too. This would be a great addition to OpenHAB.

/M

JessHerbst · April 8, 2021, 4:15am

Also would like to see this.

HomeyGER · April 13, 2021, 9:37pm

I will have a look at it and will try to create my first oh-addon.
Reading states from the sync-box and send some control-commands via API should be an easy one.

API is an easy one, does not offer so much, basicly everything that can be done in the hue-sync mobile app.

Basic stuff for the beginning:

network discovery for hue-sync boxes to add hue-sync-boxes as a thing
authentication process for openhab to get access to api by using that pairing-mode of the box
reading and updating states in openhab by polling the API every x seconds
some switch and dimmer items to control sync-mode, intensity, brightness etc.

What I am not interested in:

all the settings and hardware configuration like pairing with hue-bridge, select entertainment zone, wifi settings etc. I will leave that to the mobile-app because I don’t change this often.

Would this be enough for you guys, or is there something interesting that you have in mind?

Give me a few days

HomeyGER · April 22, 2021, 9:45am

Made it!

I have a first version of an addon ready and testing it right now.

Thing Discovery works, API Authentication (Pairing with Device) works, states are updated and I can do basic controls of the HueSync Box already, like changing mode, intensity, brightness, hdmi-input etc.

Looks good so far!
I would need some beta-testers that can test the addon before I finally push the sources to GIT and get it into the openhab-addons repository. Please drop a line here if you are interested!

Some screenshots:

nYce · April 22, 2021, 6:26pm

Oh… perfect!! I already love you!

I would love to participate and support you in any way!

I’m still using a home-made IR-Sender to control this device with OH… and this is a pain in the ass, since there is no feedback and sometimes signals get lost

Greetings, Jay

HomeyGER · April 22, 2021, 10:26pm

Okay, let’s give it a try.

You can find the download link to the JAR file of the bundle at the end of this post. It’s made for openhab 3.x and I am using it on my “openhab 3.0.1 - release build”, released and installed a few weeks ago. I want to support 2.5 too and it might work already, but I have not tested it yet. As already mentioned, very first version for testing only! It’s my first openhab-addon ever and its also been some years ago when I coded something in JAVA.

Installation:

After placing the *.jar file in your /addons folder, openhab should install it and start auto-discovery of the hue-sync-box and hopefully find it in your network and place it as a “Thing” in the InBox in your PaperUI.
If auto-discovery does not work for whatever reason, you can also add it manually in PaperUI, all you need is the IP Address or Hostname then.
When you added the thing it should go into “pairing” mode (Thing is offline with a Configuration-Warning about missing API Key) and finally start to spam the logfile of openhab that you have to press the Hardware-Button on your Sync-Box for at least 3 seconds until the LED blinks green one time.
When pairing was successfull, the thing should go online and poll the API of the box every 60 seconds for state-updates. This interval can also get changed in the advanced-settings of that thing in PaperUI.

Configuration:
Under “thing → channels” you should see a list of channels that are already implemented, most of them as read-only, but some settings also can get changed by this bundle already:

CHANNEL_POWER (supported options: on, off)
CHANNEL_MODE (supported options: powersave, passthrough, video, game, music, ambient)
CHANNEL_BRIGHTNESS (a value of 0-100)
CHANNEL_INTENSITY (supported options: subtle, moderate, high, intense)
CHANNEL_INPUT (supported options: input1, input2, input3, input4)
CHANNEL_SYNCSTATUS (supported options: on, off)

Enable Debug Mode:
Might be a good idea to enable debug mode for this bundle to get more information in the logs, in case you have any trouble adding or pairing with that device, please enable debug mode and share the logs with me here, so I can better understand what does not work for you.

To enable debug, just type this into the openhab-cli console:
log:set DEBUG org.openhab.binding.huesync

Sample .items- and .sitemap-file
huesync.items

Switch huesync_power        {channel="huesync:box:XXXXXXXXXXXXX:general#power"}
String huesync_mode         {channel="huesync:box:XXXXXXXXXXXXX:general#mode"}
String huesync_intensity    {channel="huesync:box:XXXXXXXXXXXXX:general#intensity"}
Dimmer huesync_brightness   {channel="huesync:box:XXXXXXXXXXXXX:general#brightness"}
String huesync_input        {channel="huesync:box:XXXXXXXXXXXXX:general#input"}
Switch huesync_sync_status  {channel="huesync:box:XXXXXXXXXXXXX:general#syncStatus"}

huesync.sitemap

sitemap huesync label="Hue Sync"
{
    Frame label="Mode" {
      Switch item=huesync_power label="Power"
      Selection item=huesync_mode label="Mode" icon="settings" mappings=[powersave="Powersave", passthrough="Passthrough", video="Video", music="Music", game="Game"]
      Selection item=huesync_intensity label="Itensity" icon="line" mappings=[subtle="Subtle", moderate="Moderate", high="High", intense="Intense"]
      Slider item=huesync_brightness label="Brightness" icon="pressure" minValue=0 maxValue=100 step=5
    }
    
    Frame label="Input" {
      Selection item=huesync_input label="Input" icon="receiver" mappings=[input1="Input 1", input2="Input 2", input3="Input 3", input4="Input 4"]
      Switch item=huesync_sync_status label="Sync Status"
    }
}

Good luck and happy testing!

Download Link JAR FILE for OpenHab 3.1 + 3.2 (last updated on 24/04/2021):
https://www.homeys-bunker.de/openhab-addons/org.openhab.binding.huesync-3.1.0-SNAPSHOT.jar

Download Link JAR FILE for OpenHab 3.3 + 3.4 (last updated on 02/01/2023):
https://www.homeys-bunker.de/openhab-addons/org.openhab.binding.huesync-3.4.0-SNAPSHOT.jar

Download Link JAR FILE for OpenHab 3.4.2 (last updated on 22/02/2023):
https://www.homeys-bunker.de/openhab-addons/org.openhab.binding.huesync-3.4.2.jar

Download Link JAR FILE for OpenHab 4.0.2 (last updated on 16/08/2023):
https://www.homeys-bunker.de/openhab-addons/org.openhab.binding.huesync-4.0.2.jar

Download Link JAR FILE for OpenHab 4.0.4 (last updated on 25/11/2023):
https://www.homeys-bunker.de/openhab-addons/org.openhab.binding.huesync-4.0.4.jar

Source Code on my GitHub:

nYce · April 23, 2021, 12:16pm

Alright.
I’m on the
3.1.0-SNAPSHOT Build #2331

Installing the version worked without problems.
Sync-Box thing also immediately found (Auto-Discovery)
I could not get the pairing to work first try:

Getting this message in the Log (as intented):
[DEBUG] [l.connector.http.HueSyncHttpConnector] - Sending registration command '{"appName":"openhab","instanceName":"huesync-1f60740a-1b8f-4774-b71a-71006de8466d"}' to 'https://192.168.1.156/api/v1/registrations'

Pressing the button on the box until it blinks green ONCE doesn’t seem to have any effect.
I then pressed the button much longer until it started slow blinking blue (Reset?^^) and pairing worked. So pairing is blinking blue and not green?


13:41:22.777 [DEBUG] [l.connector.http.HueSyncHttpConnector] - Sending registration command '{"appName":"openhab","instanceName":"huesync-1f60740a-1b8f-4774-b71a-71006de8466d"}' to 'https://192.168.1.156/api/v1/registrations'
13:41:22.805 [INFO ] [l.connector.http.HueSyncHttpConnector] - Pairing with Hue Sync Box successfully finished
13:41:22.888 [DEBUG] [esync.internal.handler.HueSyncHandler] - Received state powersave for channelID general#mode
13:41:22.893 [INFO ] [hab.event.ThingStatusInfoChangedEvent] - Thing 'huesync:box:SyncBox' changed from OFFLINE (CONFIGURATION_ERROR): Cannot connect to Hue Sync Box. API Access Token is not available in configuration. to ONLINE
13:41:22.895 [INFO ] [esync.internal.handler.HueSyncHandler] - Hue Sync Box: API Token changed! Updating Thing Configuration ...

Now the thing is online!

Adding Items to the channels:
Just added an equipment (used receiver) with the general control channels. Advanced input and output channels could probably be used later for switching devices on/off based on input status.

Items for Power and HDMI Status and Sync Status don’t work:

Trying to switch the Box On/Off gives me an unsupported command:
2021-04-23 13:54:00.454 [DEBUG] [sync.internal.handler.HueSyncHandler] - Unsupported command ON for channel general#power


2021-04-23 13:59:45.806 [DEBUG] [sync.internal.handler.HueSyncHandler] - Unsupported command OFF for channel general#syncStatus

Sync Mode:
Stood on “passthough”. That is no command i could give it (just Powersave,Music,Video,Game)
Powersave switched HDMI Status off.

What is the hdmiStatus-Channel? Does it enable processing or pass through of the hdmi-signal at all?

Input Source works.
Intensity works.
Brightness works.

Overall i’m very pleased with this first version.
Another suggestions:

Add Input and Output Channels to the “Show advanced”-Channels
fix all switches (HDMI Status, Power, Sync Status)

LG Jay

HomeyGER · April 24, 2021, 2:38pm

Hey,
thanks for your feedback!

That sounds a bit strange with the the pairing-process. It’s definitely a green light that should blink to finish the registration of openhab on the device. That’s also what the API-Documentation from Philips says:

Client tells users to press the button for 3 seconds until the LED blinks green to authorize this client to control Sync Box device.

I have done that lot’s of times already. Never seen a blue led …
What confuses me is the IP-Address in the debug-logs you have posted. From my point of view auto-discovery should discover the hostname (like “huesyncbox-cxxxxxxxxx”) and not the ip-address. Is it possible that you have changed this manually in the thing configuration because it was not working for you at the beginning?

In that case auto-discovery has not fully worked and added it to your inbox, but not with the correct hostname. Entering IP-Address manually in the thing-configuration could have fixed your issue then and the box went into pairing mode. Just a guess, not really sure! I would need a full log from the beginning of auto-discovery until it added that thing into your inbox.

We might debug this again and/or see what other users report here later

About input / output channels:
They do exist already, have a look at the PaperUI.
There are 4 input-channels and 1 output-channel, for each of them you can read the following states:

name: Friendly name, configured in HueSync App
type: Friendly type: generic, video, game, music, xbox, playstation, nintendoswitch, phone, desktop, laptop, appletv, roku, shield, chromecast, firetv, diskplayer, settopbox, satellite, avreceiver, soundbar, hdmiswitch
status: unplugged, plugged, linked, unknown
lastSyncMode: video, game, music

I think that’s all what the box offers in the API, it’s used by the mobile app where you select the “input” where it tells you on which HDMI Port something is plugged, unplugged or linked.

About the sync mode:
The command “passthrough” (containing the letter “R”, typo in your post?) works fine for me. Maybe it depends on the mode and if something is connected to the input and output channels!? Needs more testing

New Version:

I have updated the JAR file and sample items- and sitemap code in the previous posting with a newer version with some changes:

Sending “Power On/Off” command is working now
Sending “SyncStatus On/Off” command is working now
Removed the channel “HDMI Status”, this is basicly the “power” switch.
Improved error-handling when the device is offline or not reachable over network (Thing goes “offline”, try again in 30s)

To update it: Just remove the old *.jar file from your /addons folder and wait up to 30s until OpenHab uninstalled it and your Thing is “offline”. Then just upload the new *.jar file and wait until thing goes online again.

From my point of view we can do everything now that you can do in the hue-sync smartphone apps on the sync-screen.

If you still miss anything, let me know!

HomeyGER · April 24, 2021, 2:53pm

Here is a full API Sample response (from the documentation) with all options that are available.
So you guys can have a look yourself what information we can get (and modify) from there:

Most of these options are “read-only”. Only the stuff in the section “execution” and “behavior” can be changed (with some exceptions). “execution” is what I am currently working in that openhab-binding. “behavior” contains the “settings” configuration of the huesync-box. I have to do that in the app one time and I don’t need anything from there for now …

{
    "device": {
        "name": "My Sync Box",
        "deviceType": "HSB1",
        "uniqueId": "C42996000000",
        "ipAddress": "192.168.1.12",
        "apiLevel": 4,
        "firmwareVersion": "1.3.3",
        "buildNumber": 643518682,
        "lastCheckedUpdate": "2020-02-16T11:17:13Z",
        "updatableBuildNumber": null,
        "updatableFirmwareVersion": null,
        "update": {
            "autoUpdateEnabled": true,
            "autoUpdateTime": 11
        },
        "ledMode": 1,
        "wifiState": "wan",
        "action": "none",
        "capabilities": {
            "maxIrCodes": 16,
            "maxPresets": 16
        }
    },
    "hue": {
        "bridgeUniqueId": "001788FFFE000000",
        "bridgeIpAddress": "192.168.1.8",
        "groups": {
            "3": {
                "name": "TV Area",
                "numLights": 5,
                "active": false
            },
            "4": {
                "name": "PC Area",
                "numLights": 4,
                "active": false
            }
        },
        "connectionState": "connected"
    },
    "execution": {
        "mode": "powersave",
        "syncActive": false,
        "hdmiActive": false,
        "hdmiSource": "input1",
        "hueTarget": "groups/3",
        "brightness": 122,
        "lastSyncMode": "video",
        "video": {
            "intensity": "moderate",
            "backgroundLighting": true
        },
        "game": {
            "intensity": "high",
            "backgroundLighting": false
        },
        "music": {
            "intensity": "high",
            "palette": "melancholicEnergetic"
        },
        "preset": null
    },
    "hdmi": {
        "input1": {
            "name": "HDMI 1",
            "type": "generic",
            "status": "plugged",
            "lastSyncMode": "video"
        },
        "input2": {
            "name": "Gaming",
            "type": "xbox",
            "status": "plugged",
            "lastSyncMode": "game"
        },
        "input3": {
            "name": "HDMI 3",
            "type": "generic",
            "status": "unplugged",
            "lastSyncMode": "music"
        },
        "input4": {
            "name": "Shield",
            "type": "shield",
            "status": "plugged",
            "lastSyncMode": "video"
        },
        "output": {
            "name": "HDMI Out",
            "type": "generic",
            "status": "plugged",
            "lastSyncMode": "video"
        },
        "contentSpecs": "3840 x 2160 @ 60000 - SDR",
        "videoSyncSupported": true,
        "audioSyncSupported": true
    },
    "behavior": {
        "inactivePowersave": 20,
        "cecPowersave": 1,
        "usbPowersave": 1,
        "hpdInputSwitch": 1,
        "arcBypassMode": 0,
        "forceDoviNative": 0,
        "input1": {
            "cecInputSwitch": 1,
            "linkAutoSync": 0
        },
        "input2": {
            "cecInputSwitch": 1,
            "linkAutoSync": 0
        },
        "input3": {
            "cecInputSwitch": 1,
            "linkAutoSync": 0
        },
        "input4": {
            "cecInputSwitch": 1,
            "linkAutoSync": 0
        }
    },
    "ir": {
        "scan": {
            "scanning": false,
            "code": null
        },
        "codes": {}
    },
    "registrations": {
        "1": {
            "appName": "Hue Sync iOS",
            "instanceName": "iPhone X",
            "role": "user",
            "lastUsed": "2020-02-08T02:21:49Z",
            "created": "2020-01-21T02:26:24Z"
        },
        "0": {
            "appName": "Hue Sync Android",
            "instanceName": "Pixel",
            "role": "admin",
            "lastUsed": "2020-02-16T05:45:20Z",
            "created": "2020-01-11T05:45:20Z"
        }
    },
    "presets": {}
}

nYce · April 25, 2021, 4:45pm

Hey

You are right about the IP. First in autodiscovery i got the right hostname. When pairing didnt work changed it to the ip, but i guess that DNS worked before (i also checked if the hostname was right) and i think that wasn’t the issue… pairing did also not function with the ip in the config and just after pressing the button longer it worked.

One question, if you did this a lot of times: Does the green light flash once or many times in pairing mode? For me if i press the button 3s it just flashes green once.

About input and output channels, yes they already exist, that is nice… my suggestion was, to pack them to the “advanced tab” in the mainui thing configuration. That is nothing i need in any way, but maybe it’s nice for more casual users of OH3

How it is:

How Hue binding displays the channels:

About passthrough:

It probably also works fine for me, i have to test it a lil bit more when Switches work now

I guess i’m also using it just to Power/Sync On/Off and switch input devices… so its totally fine!
Thank you again!

If you have anything i should check or thest, i’m always up to it. Just send me a message here or as PM (german is also okay for me )

Greetings,
Jay

superfladdy · May 6, 2021, 12:00pm

Just adding - installed the file and works like a charm for now. Thank You, great work!

MightyMo · June 10, 2021, 11:21pm

First let me say that I installed originally on a Rasperry and the app was awesome; excellent job! But then I installed OH in a Docker and when I reinstalled the Sync Box Binding it would not receive the API Key. Nothing I did would work. I see at the top: API Error: java.net.UnknownHostException: huesyncbox-c42996057924. I should add that I copied and pasted the API Key from the Raspberry to the Docker Binding.

I’m guessing that mean my java in the container is not up to snuff; true?? How do I upgrade it if that is indeed the problem?? Thanks

xdanik · September 27, 2021, 6:29pm

Hi @HomeyGER,

would you mind open sourcing the source code? Or even better - could you create PR to the upstream?

I was already in middle of creating my own binding for this little black box and then I stumbled upon your solution

I was not able to get the box paired automatically with your binding - “Cannot connect to huesync-box. API Access Token is not available in configuration.” was in the logs even if I did the press button, wait for green light ritual
So I hand crafted the HTTP request and then just configured the Thing to use my own api key - that worked.

Also, would be please possible to add channel for the string hdmi.contentSpecs? My TV does not display the current source frequency, so this is kind of important information for me.

Thanks

Mario084 · December 9, 2021, 6:51pm

Hello guys,

I guess this won´t work with the Philips Hue Spotify Sync right?
Is there also a possibility to have a binding for this feature aswell?

I really would love to have some scenarios like “christmas” or “happy birthday” which starts to play music synced with my Hue lights all over the place.

Thx!

dewaard · January 30, 2022, 6:58pm

Works great! Except… there is no way to set the “Sync Mode” back to “passthrough”. Which is kind of essential in daily operation. @HomeyGER could you please add this?

Please consider opensourcing your code, so that more people can work on it.

Thanks!

magicofit · July 2, 2022, 12:54pm

I used this snapshot for some time …but now this jar doesnt work for me anymore.
Is there somewhere the latest source code for this binding to fix some issues?

DivineJimmi · December 27, 2022, 6:09pm

HERE TO HELP

The API authorization process seems broken with the newest update. You can use this link for API instructions or just follow my steps underneath. Hue Sync Box support? · Issue #552 · ebaauw/homebridge-hue · GitHub

How to fix this:
First, install the addon, autodiscover your syncbox and maybe change its Thing-Configuration to its real numeric IP (e.g. 192.x.x.x) and then follow these steps:

Get your SyncBox IP
download Postman (www.postman.com) (This is an easy API Tool)
open Postman an do a POST API request to this URL: https://syncboxIP/api/v1/registrations
You should get this response: { "code": 10, "message": "No payload" }
Click on raw and on the most right site choose JSON
Enter this into the body: { "appName": "openHAB", "appSecret": "MDAwMTExMDAwMTExMDAwMTExMDAwMTExMDAwMTExMDA=", "instanceName": "openhabian" }
Press SEND
You should get this responce: { "code": 16, "message": "Invalid State" }
Press the Button on the SyncBox (3 seconds) until the light flashes green once
Redo STEP 7
You should get a response containing your Hue Sync Access API Token

Paste this new token without the “” into your Thing Configuration. You might need to click Show advanced first.

Your openHAB should now connect flawless to your syncbox and will stay ONLINE.