Homebridge-mqtt is a Plugin for Homebridge.
Switch branches/tags
Nothing to show
Clone or download
Latest commit 0595ff6 May 17, 2018
Failed to load latest commit information.
lib fix removeService May 1, 2018
.gitignore initial commit Aug 2, 2016
LICENSE add LICENSE Oct 12, 2016
README.md Added qos option Jan 13, 2018
index.js add multiple instances May 17, 2018
package.json add multiple instances May 17, 2018



NPM version

Homebridge-mqtt is a Plugin for Homebridge. The design is based on MVC pattern, have a look at homebridge-mvc. Homebridge-mqtt is a dynamic Plugin that allows you to add and control accessories from a "Bridge" or "Device" with a mqtt API. Node-RED is the perfect platform to use with homebridge-mqtt.

Note-RED is a visual tool for wiring together hardware devices, APIs and online services.


If you are new to Homebridge, please first read the Homebridge documentation. If you are running on a Raspberry, you will find a tutorial in the homebridge-punt Wiki.

Install homebridge:

sudo npm install -g homebridge

Install homebridge-mqtt:

sudo npm install -g homebridge-mqtt


Add the mqtt-platform in config.json in your home directory inside .homebridge.

  "platform": "mqtt",
  "name": "mqtt",
  "url": "mqtt://",
  "port": "1883",
  "topic_type": "multiple",
  "topic_prefix": "homebridge",
  "username": "foo",
  "password": "bar",
  "cert": "/path/to/certificate.pem",
  "key": "path/to/key.pem",
  "ca": "/path/to/ca_certificate.pem",
  "qos": 1

Replace with the ip-address of your mqtt broker.


topic_type multiple: the data is sent to all devices, e.g.

topic : homebridge/from/set

topic_type single: the data is sent to a single device, the accessory name is added to the topic, e.g.

topic : homebridge/from/set/flex_lamp

mqtt API

The data (payload) is sent/received in a JSON format using following topics:

  • homebridge/to/add
  • homebridge/to/add/service
  • homebridge/to/remove
  • homebridge/to/remove/service
  • homebridge/to/get
  • homebridge/to/set
  • homebridge/to/set/reachability
  • homebridge/to/set/accessoryinformation
  • homebridge/from/get
  • homebridge/from/set
  • homebridge/from/response
  • homebridge/from/identify

Version 0.3.0 and higher supports multiple services. To handle multiple services a new property service_name has been introduced.

Note: To add a service to an existing accessory (created prior version 0.3.0) please first remove the accessory and add it again.

Howto examples

add accessory

topic: homebridge/to/add
payload: {"name": "flex_lamp", "service_name": "light", "service": "Switch"}

or with the additional accessory informations

topic: homebridge/to/add
  "name": "flex_lamp",
  "service_name": "light",
  "service": "Switch",
  "manufacturer": "lamp_manu",
  "model": "flex_007",
  "serialnumber": "4711",
  "firmwarerevision": "1.0.0"


topic: homebridge/from/response
payload: {"ack": true, "message": "accessory 'flex_lamp' service_name 'light' is added."}

add service

Note: an accessory with the same name must be added before.

topic: homebridge/to/add/service
payload: {"name": "multi_sensor", "service_name": "humidity", "service": "HumiditySensor"}


topic: homebridge/from/response
payload: {"ack": true, "message": "service_name 'humidity', service 'HumiditySensor' is added."}

remove accessory

topic: homebridge/to/remove
payload: {"name": "flex_lamp"}


topic: homebridge/from/response
payload: {"ack": true, "message": "accessory 'flex_lamp' is removed."}

remove service

topic: homebridge/to/remove/service
payload: {"name": "multi_sensor", "service_name": "humidity"}


topic: homebridge/from/response
payload: {"ack": true, "message": "accessory 'multi_sensor' service_name 'humidity' is removed."}

get accessory/accessories

The purpose of this topic is to retrieve accessory configurations. Use homebridge/from/set to control your devices.

topic: homebridge/to/get
payload: {"name": "outdoor_temp"}

homebridge sends the accessory configuration:

topic: homebridge/from/response
  "outdoor_temp": {
    "services": {
      "Temperature": "TemperatureSensor"
    "characteristics": {
      "Temperature": {
        "CurrentTemperature": 13.4
topic: homebridge/to/get
payload: {"name": "*"}

homebridge sends all accessory configurations:

topic: homebridge/from/response
  "node_switch": {
    "services": {
      "light": "Switch"
    "characteristics": {
      "Light": {
        "On": true
  "office_lamp": {
    "services": {
      "office_light": "Lightbulb"
    "characteristics": {
      "office_light": {
        "On": "blank",
        "Brightness": 65
  "living_temp": {
    "services": {
      "living_temperature": "TemperatureSensor"
    "characteristics": {
      "living_temperature": {
        "CurrentTemperature": 19.6

set value (to homebridge)

topic: homebridge/to/set
payload: {"name": "flex_lamp", "service_name": "light", "characteristic": "On", "value": true}

get value (from homebridge)

topic: homebridge/from/get
payload: {"name": "flex_lamp", "service_name": "light", "characteristic": "On"}

Homebridge-mqtt will return the cached value to HomeKit. Optionally you can publish the actual value using homebridge/to/set.

set value (from homebridge)

topic: homebridge/from/set
payload: {"name": "flex_lamp", "service_name": "light", "characteristic": "On", "value": true}

set reachability

topic: homebridge/to/set/reachability
payload: {"name": "flex_lamp", "reachable": true}
payload: {"name": "flex_lamp", "reachable": false}

set accessory information

topic: homebridge/to/set/accessoryinformation
payload: {"name": "flex_lamp", "manufacturer": "espressif", "model": "esp8266-12", "serialnumber": "4711", "firmwarerevision": "1.1.0"}

identify accessory

topic: homebridge/from/identify
payload: {"name":"indoor_temp","manufacturer":"homebridge-mqtt","model":"v0.3.0","serialnumber":"2017-02-13T12:17"}

define characterstic

The required characteristics are added with the default properties. If you need to change the default, define the characteristic-name with the properties. e.g.:

topic: homebridge/to/add
    "name": "living_temp",
    "service_name": "temperature",
    "service": "TemperatureSensor",
    "CurrentTemperature": {"minValue": -20, "maxValue": 60, "minStep": 1}

To add an optional charachteristic define the characteristic-name with "default" or with the properties. e.g.:

topic: homebridge/to/add
    "name": "living_lamp",
    "service_name": "light",
    "service": "Lightbulb",
    "Brightness": "default"
topic: homebridge/to/add
    "name": "bathroom_blind",
    "service_name": "blind",
    "service": "WindowCovering",
    "CurrentPosition": {"minStep": 5},
    "TargetPosition": {"minStep": 5},
    "CurrentHorizontalTiltAngle": {"minValue": 0, "minStep": 5},
    "TargetHorizontalTiltAngle": {"minValue": 0, "minStep": 5}

HomeKitTypes.js describes all the predifined Services, Characteristcs, format and properties for the value e.g.:

 * Service "Contact Sensor"

Service.ContactSensor = function(displayName, subtype) {
  Service.call(this, displayName, '00000080-0000-1000-8000-0026BB765291', subtype);

  // Required Characteristics

  // Optional Characteristics

 * Characteristic "Contact Sensor State"

Characteristic.ContactSensorState = function() {
  Characteristic.call(this, 'Contact Sensor State', '0000006A-0000-1000-8000-0026BB765291');
    format: Characteristic.Formats.UINT8,
    perms: [Characteristic.Perms.READ, Characteristic.Perms.NOTIFY]
  this.value = this.getDefaultValue();

inherits(Characteristic.ContactSensorState, Characteristic);

Characteristic.ContactSensorState.UUID = '0000006A-0000-1000-8000-0026BB765291';

// The value property of ContactSensorState must be one of the following:
Characteristic.ContactSensorState.CONTACT_DETECTED = 0;
Characteristic.ContactSensorState.CONTACT_NOT_DETECTED = 1;

Derived from this:

service = ContactSensor
characteristic = ContactSensorState
format = UINT8
property = 0 or 1

Node-red example


For more examples take a look at the wiki