homebridge-easy-mqtt

homebridge-easy-mqtt

Homebridge plugin to integrate simple MQTT devices into Apple HomeKit

Disclaimer

Any issues or damage resulting from use of this plugin are not the fault of the developer. Use at your own risk.

What does this plugin do?

This plugin is designed to be a simple replacement for the fantastic homebridge-mqttthing plugin which appears as though it's no longer being actively developed.

HomebridgeEasyMQTT currently supports Lightbulb, LockMechanism, Outlet, SecuitySystem,Switch, and TemperatureSensor, but will be expanded over time as more use cases are discovered. If there is an accessory type you'd like to see supported, please feel free to create an issue in GitHub.

Configuration

Using the Homebridge Config UI is the easiest way to set up this plugin. However, if you wish to do things manually then you will need to add the following to your Homebridge config.json:

{
  "name": "Easy MQTT",
  "accessories": [
    {
      "info": {
        "id": "string",
        "name": "string",
        "type": "string",
        "manufacturer": "string",
        "model": "string",
        "serialNumber": "string",
        "version": "string"
      },
      "mqtt": {
        "broker": "string",
        "username": "string",
        "password": "string",
        "options": "string"
      },
      "topicGetStatusActive": "string",
      "topicGetCurrentLockState": "string",
      "topicGetTargetLockState": "string",
      "topicSetTargetLockState": "string",
      "topicGetOn": "string",
      "topicSetOn": "string",
      "valueStatusActive": "string",
      "valueLockStateSecured": "string",
      "valueLockStateUnsecured": "string",
      "valueLockStateJammed": "string",
      "valueOn": "string",
      "valueOff": "string",
      "disableLogging": false
    }
    ...
  ],
  "verbose": false,
  "platform": "HomebridgeEasyMQTT"
}

All fields are required unless noted as "(Optional)"

Info:

• id - A unique ID to identify this accessory. Changing this value will result in a new accessory.
• name - The display name for the accessory in HomeKit
• type - The type of accessory, currently Lightbulb, LockMechanism, Outlet, SecuitySystem, Switch, and Temperature Sensor are supported
• manufacturer - (Optional) The accessory manufacturer which will display in HomeKit device details
• model - (Optional) The accessory model which will display in HomeKit device details
• serialNumber - (Optional) The accessory serial number which will display in HomeKit device details
• version - (Optional) The accessory software version which will display in HomeKit device details

MQTT:

• broker - The URL and port to use for communicating with your MQTT device
• username - (Optional) Username
• password - (Optional) Password
• options - (Optional) See MQTT Options below

Topics:

You will need to make sure to populate the appropriate topics based on the type.

You may define topics using a JSONPath dot notation to assist the parser in finding the right value within the message. See JSONPaths below for more details.

• General Purpose

  • topicGetStatusActive - (Optional) Whether or not the accessory is connected/reachable

• Lightbulb

  • topicGetBrightness - (Optional) The current brightness as a percent
  • topicSetBrightness - (Optional) For setting the brightness
  • topicGetHue - (Optional) The lightbulb's current hue
  • topicSetHue - (Optional) For setting the lightbulb's current hue
  • topicGetColorTemperature - (Optional) The current color temperature of the lightbulb
  • topicSetColorTemperature - (Optional) For setting the color temperature of the lightbulb
  • topicGetSaturation - (Optional) The current saturation setting of the lightbulb
  • topicSetSaturation - (Optional) For setting the saturation setting of the lightbulb

• LockMechanism

  • topicGetCurrentLockState - The current state of the lock, i.e. locked/unlocked
  • topicGetTargetLockState - The target (i.e. desired) state of the lock
  • topicSetTargetLockState - For setting the target (i.e. desired) state of the lock

• Outlet

  • topicGetOn - The current state of the outlet, i.e. on/off
  • topicSetOn - For setting the state of the outlet
  • topicGetOutletInUse - (Optional) Whether or not the outlet is currently being used

• SecuitySystem

  • topicGetCurrentSecurityState — The current state of the system
  • topicGetTargetSecurityState — The target state of the system
  • topicSetTargetSecurityState — For setting the target state of the system
  • topicGetStatusTampered — For getting whether the system has been tampered with
  • topicGetStatusFault — For getting whether there is a system error

• Switch

  • topicGetOn - The current state of the switch, i.e. on/off
  • topicSetOn - For setting the state of the switch

• TemperatureSensor

  • topicGetCurrentTemperature - The current temperature of the sensor
  • temperatureUnits - (Optional) The temperature units of the incoming value supplied by the sensor, C for Celsius (default) F for Fahrenheit

Values:

As with Topics, you will need to populate the appropriate values based on the type. Note that while they are defined as strings, they will be auto-converted to the appropriate primitives (e.g. boolean or number) where appropriate.

• General Purpose

  • valueStatusActive - Accessory is connected/reachable, e.g. "true", "1", or "Alive"

• Lightbulb

  • valueOn - Turned on, e.g. "true", or "1", or "On"
  • valueOff - Turned off, e.g. "false", or "0", or "Off"

• LockMechanism

  • valueLockStateSecured - Locked state, e.g. "true", "255", or "Locked"
  • valueLockStateUnsecured - Unlocked state, e.g. "false", "0", or "Unlocked"
  • valueLockStateJammed - (Optional) Lock is jammed, e.g. "254" or "Jammed"

• Outlet

  • valueOn - Turned on, e.g. "true", or "1", or "On"
  • valueOff - Turned off, e.g. "false", or "0", or "Off"
  • valueOutletInUse - Currently being used, e.g. "true", or "1", or "On"

• SecuritySystem

  • valueArmStay — (Optional) system armed in stay mode, e.g. "SA" or "stay"
  • valueArmAway — (Optional) system armed in away mode, e.g. "AA" or "away"
  • valueArmNight — (Optional) system armed in night mode, e.g. "NA" or "night"
  • valueDisarm — (Optional) system armed in away mode, e.g. "D" or "disarmed"
  • valueAlarmTriggered — (Optional) when the alarm has been triggered, e.g. "true" or "1" or "triggered"
  • valueTampered — (Optional) when the system has been tampered with, e.g. "true" or "1" or "tampered"
  • valueFault — (Optional) when the system has a general fault, e.g. "true" or "1" or "fault"

• Switch

  • valueOn - Turned on, e.g. "true", or "1", or "On"
  • valueOff - Turned off, e.g. "false", or "0", or "Off"

Logging/Debugging:

By default, devices will log activity, for example when a Switch is turned on or a LockMechanism is unlocked.

To disable, add the following to the accessories you'd like to silence.

• "disableLogging": true

You may also turn on additional logging if you'd like to see the MQTT messages passed back and forth. You can do this by adding the following at the top level of the config.

• "verbose": true

MQTT Options

You are able to pass in any arbitrary MQTT options via mqtt.options in the config. This can include, for example, such as clientId, protocolVersion, etc. Just make sure the value provided is valid JSON. For example:

"options": "{ \"protocolVersion\": \"4\", \"clientId\": \"my-client-id\", \"rejectUnauthorized\": true }"

JSONPaths

For some devices, the desired values in the MQTT messages can get embedded within a JSON object. For example, here is the MQTT message for my door lock that is received when the door is locked:

{ "time": 1750870005853, "state": 255 }

Since the value (255) that I need is embedded within JSON, I can use JSONPath syntax to tell the parser how to find the value.

So, in this example I would define my topic as:

zwave/1/door_lock/currentMode$.state

The $.state at the end tells the parser to grab the value using the key "state".

This can be arbitrarily complicated and several layers deep. For example,

{
  "time":1750870005853,
  "state": {
    "number": {
      "value": 255
    }
  }
}

would use the topic

zwave/1/door_lock/currentMode$.state.number.value

Credits

@arachnetech for the fantastic homebridge-mqttthing plugin which serves as the main inspiration for this project

And to the amazing creators/contributors of Homebridge who made this plugin possible!

Changelog

1.2.0 (2025-09-02)

Added

• Security System accessory type
• Support for battery and status

Fixed

• Allow raw strings in MQTT messages
• Changing accessory type cleans up old Homebridge accessories

Changed

• Updated dev dependencies
• Significant under-the-hood refactoring to speed future development
• Removed in-use setter topic for outlet since it is not user-modifiable
• Condensed and cleaned up config UI
  • Removed optional accessory info fields as they were messy and provided little value
• Deprecated inconsistent LockMechanism topic names
  • topicGetLockCurrentState -> topicGetCurrentLockState
  • topicGetLockTargetState -> topicGetTargetLockState
  • topicSetTargetState -> topicSetTargetLockState