Ready to take your JavaScript development to the next level? Meet npm Enterprise - the ultimate in enterprise JavaScript. Learn more »


1.2.0 • Public • Published


mqtt-smarthome NPM version Dependency Status Build Status Coverage Status XO code style License

Gateway between a Philips Hue bridge and MQTT

Because hue2mqtt sadly isn't developed anymore and I don't like Java I decided to reimplement this on Node.js. hue2mqtt.js should work as an 1:1 drop-in-replacement for hue2mqtt. Differences to the original hue2mqtt are:

  • Option --publish-distinct. When activated hue2mqtt.js publishes every datapoint on it's own topic (like e.g hue/status/lights/Livingroom/bri)
  • --publish-distinct also publishes a rgb value that is useful to visualize a lamps color on e.g. a web ui.

Getting started


Prerequisites: Node.js >= 6.0

sudo npm install -g hue2mqtt


dersimn created a dockerized version of hue2mqtt.js.


Usage: hue2mqtt [options]

  -v, --verbosity         possible values: "error", "warn", "info", "debug"
                                                               [default: "info"]
  -n, --name              instance name. used as mqtt client id and as topic
                          prefix                                [default: "hue"]
  -m, --mqtt-url          mqtt broker url.          default: "mqtt://"]
  -b, --bridge            hue bridge address. if ommited bridge will be searched
  -p, --polling-interval  light status polling interval in seconds [default: 10]
  -d, --publish-distinct  publish distinct light states
  -h, --help              Show help                                    [boolean]
  --disable-names         use light ID instead of name when publishing changes
  --mqtt-retain           enable/disable retain flag for mqtt messages
                                                       [boolean] [default: true]
  --insecure              allow tls connections with invalid certificates
  --version               Show version number                          [boolean]

All config options can be set via environment variables also (uppercase, underscore).

I suggest to use pm2 to manage the hm2mqtt process (start on system boot, manage log files, ...)


You can add Username/Password for the connection to the MQTT broker to the MQTT URL param like e.g. mqtt://user:pass@broker. For a secure connection via TLS use mqtts:// as URL scheme.

Topics and Payloads

hue2mqtt.js 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


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)
    • 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" 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.


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 which is automatically used on subsequent connections.

When authentication is required, a one-shot not retained message is published to topic hue/status/authrequired.


MIT © Sebastian Raff


npm i hue2mqtt

Downloadsweekly downloads









last publish


  • avatar
Report a vulnerability