owagner / hue2mqtt

Gateway between a Philips Hue bridge and MQTT

hue2mqtt

Written and (C) 2015-16 Oliver Wagner [email protected]

Provided under the terms of the MIT license.

Overview

Gateway between a Philips Hue bridge and MQTT, using the official Philips Java API library.

It is intended as a building block in heterogenous smart home environments where an MQTT message broker is used as the centralized message bus. See https://github.com/mqtt-smarthome for a rationale and architectural overview.

Topic structure

hue2mqtt follows the mqtt-smarthome topic structure with a top-level prefix and a function like status and set. Lamp, group and scene names are read from the Hue bridge.

Status reports are sent to the topic

hue/status/lights/<lampname>

The payload is a JSON encoded object with the following fields:

• val - either 0 if the lamp is off, or the current brightness (1..254)
• hue_state - A JSON object which has the complete lamp state as returned from the Hue API:
  • on: boolean, whether the lamp is on
  • bri: current brightness 1..254
  • hue: hue from 0..65535
  • sat: saturation from 0..254
  • xy: an array of floats containing the coordinates (0..1) in CIE colorspace
  • ct: Mired color temperature (153..500)
  • alert: alert effect, textual
  • effect: color effect, textual
  • colormode: current color mode, textual (ct, hs, or xy)
  • reachable: boolean, whether the light is reachable

Setting state is possible in one of three ways:

Method 1: Publishing a simple integer value to

hue/set/lights/<lampname>

will for value=0 turn off the lamp and for values > 0 turn the lamp on and set the brightness to the given value.

Method 2: Publishing a JSON encoded object to

hue/set/lights/<lampname>

will set multiple parameters of the given lamp. The field names are the same as the ones used in the hue_state state object. Additionally, a field "transitiontime" can be specified which defines the transitiontime to the new state in multiple of 100ms.

Method 3: Publishing a simple value to

hue/set/lights/<lampname>/<datapoint>

will distinctly set a single datapoint (equal to the field names in the composite JSON state object) to the simple value.

The fields "bri", "hue", "sat", "x", "y" and "ct" have variants with a "_inc" suffix which accept a relative value. For example, setting "bri_inc" to "5" will increase the brightness by 5, setting "bri_inc" to "-5" will decrease the brightness by 5. The values will clip properly within their allowed range.

The same is possible with groups:

hue/set/groups/<groupname>

The special group name 0 is also recognized and refers to the default group which contains all lights connected to a bridge.

Authentication

Like all applications connecting to a Hue bridge, hue2mqtt needs to be authenticated using push link at least once. The bridge will then assign a whitelist username (in fact a token) which is automatically used on subsequent connections. The token is stored using Java Preferences.

When authentication is required, a one-shot not retained message is published to topic

hue/status/authrequired

Available options:

• bridge.id

  ID of the Hue bridge to connect to. Required if there is more than one bridge on the network.

• bridge.ip

  Like ID, but using the IP address. Not recommended.

• mqtt.server

  ServerURI of the MQTT broker to connect to. Defaults to "tcp://localhost:1883".

• mqtt.clientid

  ClientID to use in the MQTT connection. Defaults to "hue".

• mqtt.topic

  The topic prefix used for publishing and subscribing. Defaults to "knx/".

Dependencies

• Java 1.7 SE Runtime Environment: https://www.java.com/
• Eclipse Paho: https://www.eclipse.org/paho/clients/java/ (used for MQTT communication)
• Minimal-JSON: https://github.com/ralfstx/minimal-json (used for JSON creation and parsing)
• Philips HUE Java API Library: https://github.com/PhilipsHue/PhilipsHueSDK-Java-MultiPlatform-Android

Automatically built jars can be downloaded from the release page on GitHub at https://github.com/owagner/hue2mqtt/releases

History

• 0.13 - 2016/07/5 - owagner

  • actually deal with error 1157 ("No bridges found") in onError handler and exit

• 0.12 - 2016/06/11 - owagner

  • will now always go through bridge discovery. Bridges can be specified using either their ID (preferred) or IP. Username is stored per ID.
  • will now publish a non-retained message to topic/status/authrequired if authentication is required.

• 0.11 - 2016/05/28 - owagner/hobbyquaker

  • adapted to new 1.8.1+ API scheme of whitelist usernames being assigned by the bridge. The assigned username is stored using Java Preferences. The scheme should be compatible with already authorized hue2mqtt instances, which used a hardcoded username of "hue2mqttuser".
  • Hue API libraries updated to 0.11.2.

• 0.10 - 2016/02/23 - owagner

  • attempt to reconnect every 10s if bridge connection errors out

• 0.9 - 2015/10/01 - owagner

  • truncate float numbers to integer when setting integer-only datapoints. Fixes #6
  • update Philip Hue lib to 1.8.3

• 0.8 - 2015/09/28 - hobbyquaker

  • fixed set alert
  • fixed set effect

• 0.7 - 2015/07/25 - owagner

  • fixed direct datapoint set variant of _inc fields
  • updated eclipse-paho to 1.0.2 and minimal-json to 0.9.4

• 0.6 - 2015/07/15 - owagner

  • updated SDK libs to 1.8
  • added support for the "_inc" variants of fields. Implements #3

• 0.5 - 2015/06/25 - owagner

  • fix syslog logging to ignore intermediate IO errors
  • minimal-json updated to 0.9.2

• 0.4 - 2015/03/09 - owagner

  • better output of available groups and scenes after initial connect

hue2mqtt's Issues

Mqtt server on permanent local is address

Ups. Heading should be
Hue bridge on permanent local IP address.
In my router I made sure that my hue bridge is always on 192.168.0.199. Can hue2mqtt performance benefit from this? If yes where do I define the permanent IP address? And can I do this if I use your .jar to install hue2mqtt on my raspberry pi running full Jessie. Thanks. And sorry if this is a very simple question. Thanks in advance.

Clip Increment Feature (new increment* attributes in PHLightState)

The Hue Java SDK supports the new attributes bri_inc, sat_inc, hue_inc and ct_inc since V1.8. Can you add support for them in the set-topic?

Problem: Parsing error probably caused by Hue Motion Sensor?

After the latest round of FW updates on the Hue Bridge and lamps and introducing the new Hue Motion Sensor to my setup, I now get an ongoing stream of

hue2mqtt[650]: SEVERE: Internal API error [com.philips.lighting.model.PHHueParsingError@e52776, com.philips.lighting.model.PHHueParsingError@1b90a01, com.philips.lighting.model.PHHueParsingError@978117, com.philips.lighting.model.PHHueParsingError@5d042e, com.philips.lighting.model.PHHueParsingError@1fc5c04]

So I guess this is caused by the messages the motion sensor sends to the bridge.

Solution: I first need to find out the exact problem. Is there a way to run hue2mqtt with a higher debug level so I can start collecting data on the root cause? I am happy to help with adding support for the motion sensor to hue2mqtt even with my very basic understanding of Java :-)

The motion sensor announces itself with an ID of "ZLLPresence" according to 1.3 at http://www.developers.meethue.com/documentation/supported-sensors

It shouldn't be too hard to add its specifics to hue2mqtt but that is definitely not for me to decide :-)

set command fails on float values

WARNING: Exception when processing published message to set/lights/Bad/hue: 30000.12356
java.lang.NumberFormatException: For input string: "30000.12356"

Problem with Hue-Connection

Hi,

after a while I get the following Exception:
Nov 16, 2016 9:24:29 PM com.tellerulam.hue2mqtt.HueHandler onError WARNUNG: Error in bridge connection. Code 22: No connection; will reconnect in 10s Nov 16, 2016 9:24:29 PM com.tellerulam.hue2mqtt.HueHandler onConnectionLost WARNUNG: Connection to bridge 192.168.2.126 lost Exception in thread "Timer-0" com.philips.lighting.hue.sdk.exception.PHHueException: You are already connected. at com.philips.lighting.hue.sdk.PHHueSDK.connect(PHHueSDK.java:286) at com.tellerulam.hue2mqtt.HueHandler.connect(HueHandler.java:66) at com.tellerulam.hue2mqtt.HueHandler.reconnect(HueHandler.java:71) at com.tellerulam.hue2mqtt.HueHandler$1.run(HueHandler.java:208) at java.util.TimerThread.mainLoop(Timer.java:555) at java.util.TimerThread.run(Timer.java:505) Nov 16, 2016 9:28:47 PM com.tellerulam.hue2mqtt.HueHandler onError WARNUNG: Error in bridge connection. Code 22: No connection; will reconnect in 10s Exception in thread "Timer-1" java.lang.IllegalStateException: Timer already cancelled. at java.util.Timer.sched(Timer.java:397) at java.util.Timer.schedule(Timer.java:193) at com.tellerulam.hue2mqtt.HueHandler.onError(HueHandler.java:204) at com.philips.lighting.hue.sdk.notification.impl.PHNotificationManagerImpl$1.onReceived(PHNotificationManagerImpl.java:140) at com.philips.lighting.hue.sdk.notification.impl.PHHueResultReceiver.execute(PHHueResultReceiver.java:24) at com.philips.lighting.hue.sdk.notification.impl.PHNotificationManagerImpl.notifySDKError(PHNotificationManagerImpl.java:146) at com.philips.lighting.hue.sdk.heartbeat.PHHeartbeatProcessor.run(PHHeartbeatProcessor.java:168) at java.util.TimerThread.mainLoop(Timer.java:555) at java.util.TimerThread.run(Timer.java:505)

After this point no more updates arrived in mqtt - I have to restart hue2mqtt. Do u have an idea?

publish subtopics

Could you add a command line option to activate publishing of all datapoints status (e.g. hue/status/lights/lamp1/sat)?

Create tag for version 0.4

Could you please create a tag for version 0.4?

Detailed download, installation and auto start instructions for Raspberry Pi

Would it be possible to add some help on what linux commands I need to move the .jar file to my Rpi? Also to ensure I have the needed programs updated and running. And how I make sure hue2mqtt starts automatically after each boot. If too trivial, then please just refer to where I can find out. Thanks a million from a newbie in Copenhagen.

Hi

Could you give a procedure to have hue2mqtt installed and running on Raspberry pi 3.
I have installed node.js version 8.x.x and when I run the command

sudo npm install -g hue2mqtt

I get and error:
npm ERR! code MODULE_NOT_FOUND
npm ERR! Cannot find module 'internal/util/types'

npm ERR! A complete log of this run can be found in:
npm ERR! /root/.npm/_logs/2018-06-07T12_45_04_668Z-debug.log

Your help will be appreciated
Thanks

alert datapoint

mosquitto_pub -t 'hue/set/lights/Hobbyraum/alert' -m 'select'

leads to...

com.tellerulam.hue2mqtt.MQTTHandler processMessage
WARNING: Exception when processing published message to set/lights/Hobbyraum/alert: select
java.lang.IllegalArgumentException: Attempting to set unknown datapoint alert to value select
         at com.tellerulam.hue2mqtt.MQTTHandler.addDatapointToLightState(MQTTHandler.java:210)