Configure the plugin in your homebridge config.json file. Most configuration settings can now also be entered using
Homebridge Config UI X.
MQTT topics used fall into two categories:
- Control topics, of the form
setXXX, are published by MQTT-Thing in order to control device state (e.g. to turn on a light). - Status/notification topics, of the form
getXXX, are published by the device to notify MQTT-Thing that something has occurred (e.g. that a sensor has detected something or a control topic action has been performed).
All values shown below (often within <>) are comments/descriptions, and should not be copied into your configuration file. For an example of an actual configuration file, please see test/config.json.
- General Settings
- MQTT Settings
- MQTT Topics
- Topic Apply Functions
- Boolean Value Settings
- Accessory Information
- Publishing Values on Start-up
- History Service
- Confirmation
- Codecs
- JSONPath
- Validation
- Accessories
- Grouped Accessories
The following settings apply to all device types:
{
"accessory": "mqttthing",
"type": "lightbulb",
"name": "My lightbulb",
"url": "mqtt://192.168.1.235:1883",
"username": "MQTT_username",
"password": "MQTT_password",
"mqttOptions": { "keepalive": 30 },
"mqttPubOptions": { "retain": false },
"logMqtt": true,
"topics": {
"getName": "my/get/name/topic",
"getOnline": "my/get/online/topic",
"getBatteryLevel": "my/get/battery-level/topic",
"getChargingState": "my/get/battery-charging-state/topic",
"getStatusLowBattery": "my/get/status-low-battery/topic"
},
"integerValue": true,
"onlineValue": "Online",
"offlineValue": "Offline",
"chargingStateValues": [ "NotCharging", "Charging", "NotChargeable" ],
"startPub": [
{ "topic": "topic1", "message": "message1" },
{ "topic": "topic2", "message": "message2" }
],
"confirmationPeriodms": 1000,
"retryLimit": 5,
"debounceRecvms": 200,
"optimizePublishing": false,
"validate": true
}accessory - must always be set to the value mqttthing in order to use homebridge-mqttthing
type - one of the supported accessory types listed below
name - name of accessory, as displayed in HomeKit
caption - HomeKit caption/label (optional)
url - URL of MQTT server if not localhost port 1883 (optional). The URL can be one of the following protocols: 'mqtt', 'mqtts', 'tcp', 'tls', 'ws', 'wss'. The url is passed to mqtt.connect().
username - Username for MQTT server (optional)
password - Password for MQTT server (optional)
mqttOptions - Object containing all MQTT options passed to https://www.npmjs.com/package/mqtt#client, for MQTT configuration settings not supported above (optional). Any standard settings not specified in an mqttOptions option will be set by homebridge-mqttthing. Enable MQTT logging with logMqtt to check the options provided.
When MQTTS (MQTT over TLS) is used, the mqttOptions object is passed through to tls.connect() so the options described at https://nodejs.org/api/tls.html#tls_tls_connect_options_callback may be used. keyfile, certfile and cafile may be used to read key, cert and ca pem files respectively. Set insecure to true to disable all server identity checking (e.g. when using a self-signed certificate).
mqttPubOptions - Option containing any MQTT publishing options required. See https://www.npmjs.com/package/mqtt#publish for details.
logMqtt - Set to true to enable MQTT logging for this accessory (optional, defaults to false)
debounceRecvms - Whenever receiving a message on any configured topic, wait for the number of milliseconds specified before notifying Homekit. If a subsequent message is received during the debounce period, the debounce timer is restarted. This can be useful to filter extraneous notification messages from accessories.
optimizePublishing - Whenever publishing a message on any topic, don't republish the previously-published value.
In addition to setting the MQTT settings in config, you can also set them using environment variable overrides. Configured values in the config.json will take precedence over any environment variables.
| Environment variable | Config key |
|---|---|
| MQTTTHING_USERNAME | username |
| MQTTTHING_PASSWORD | password |
| MQTTTHING_URL | url |
MQTT Topics are configured within a topics object. Most topics are optional (including all of the topics described in this section).
getName - Topic that may be published to send HomeKit the name of the accessory (optional). HomeKit doesn't show name changes dynamically, so it's generally simpler just to configure the name with name.
getOnline - Topic that may be published to tell homebridge-mqttthing whether or not the accessory is online (optional). This is a Boolean value (see below) intended to be published as false by the MQTT Last Will and Testament (LWT) feature in order to notify homebridge-mqttthing that the accessory is offline. Accessories using this feature must also publish an online true status when available. The "not responding" state is not updated immediately. This feature is a little hack... but there is no other possibility to achieve anything similar. It will be visible after closing and reopening the App or sometimes by switching the room view. The trick is to respond to a get request from the App with an exception. But this is only possible when there is a get request.
getBatteryLevel - Topic that may be published by an accessory to indicate its current battery level, from 0 to 100 (optional).
getChargingState - Topic that may be published by an accessory to indicate its charging state (optional). Default values accepted are [ "NOT_CHARGING", "CHARGING", "NOT_CHARGEABLE" ]. These may be changed with the chargingStateValues setting.
getStatusLowBattery - Topic that may be published by an accessory to indicate whether it has a low battery (optional).
User functions may be applied to MQTT messages for custom payload encoding/decoding. Apply functions do this within the main configuration file, but are not supported by config-ui-x. Alternatively, an external codec may be used (see Codecs). When parsing JSON from messages, the JSONPath support may be useful.
If an MQTT message is not a simple value or does not match the expected syntax, it is possible to specify a JavaScript function that is called for the message every time it is received/published. For this, the topic string in the configuration can be replaced with an object with these properties:
topic - Topic string
apply - Javascript function to apply (must be a complete function body that returns a value). The function is called with one arguments: message, holding the original message, and state (optional).
e.g. Decoding a JSON payload:
"topics": {
"getCurrentTemperature": {
"topic": "outdoor",
"apply": "return JSON.parse(message).temperature.toFixed(1);"
}
}e.g. Scaling brightness from its internal 0-100 range to an external 0-255 range:
"getBrightness": {
"topic": "test/lightbulb/getBrightness",
"apply": "return Math.round( message / 2.55 );"
},
"setBrightness": {
"topic": "test/lightbulb/setBrightness",
"apply": "return Math.round( message * 2.55 );"
}The state parameter holds an object which may be used to store local state used by the apply function. Additionally, state.global points at an object shared between all topics.
This functionality is not currently available when editing MQTT topics using config-ui-x.
Homekit Boolean types like on/off use strings "true" and "false" in MQTT messages unless "integerValue": true is configured, in which case they use to "1" and "0". Alternatively, specific values can be configured using onValue and offValue (in which case integerValue is ignored). Other Homekit types (integer, string, etc.) are not affected by these settings.
integerValue - set to true to use the values 1 and 0 to represent Boolean values instead of the strings "true" and "false" (optional, defaults to false)
onValue - configure a specific Boolean true or on value (optional)
offValue - configure a specific Boolean false or off value (optional)
When onValue and offValue are configured, by default any other value received on the get topic will be ignored. To treat unrecognized received values as off, set otherValueOff: true.
onlineValue, offlineValue - configure specific values representing that an accessory is online or offline (received through getOnline). If not specified, the configured on and off values will be used to represent online and offline states (i.e. onValue/offValue if configured, otherwise 1 / 0 with integerValue: true or true / false with integerValue: false).
In mqttthing versions before 1.0.23, receiving any value not matching the configured 'on value' for a Boolean characteristic turned it off. From 1.0.23, the received message must match the offValue to turn off a characteristic. To turn off on any value except the onValue, omit configuration of offValue.
From version 1.0.23, mqttthing will not publish a message for a Boolean characteristic turning off if no offValue is configured.
The following configuration settings may be specified if required to change information service content:
manufacturer - sets the manufacturer name (defaults to mqttthing)
serialNumber - sets the serial number (defaults to hostname and accessory name)
model - sets the model name (defaults to the mqttthing accessory type)
firmwareRevision - sets the firmware revision number (defaults to mqttthing version)
MQTT messages may be published on start-up, e.g. to reset accessories to a known initial state, with startPub. This should contain an array of objects with topic and message
keys, i.e.:
"startPub": [
{ "topic": "test/lightbulb/setOn", "message": "1" },
{ "topic": "test/lightbulb/getOn", "message": "1" }
]Previously this was an object containing MQTT topics as keys, and values to be published as values. This format will still work but the format above is preferred.
For some accessory types you can enable the History Service powered by fakegato-history. It will show up in the Eve App. (Home.app does not support it).
Depending on the accessory type, fakegato-history may add extra entries every 10 minutes or may average the entries from the plugin and send data every 10 minutes.
History is currently supported for:
- Temperature Sensor
- Humidity Sensor
- Air Pressure Sensor
- Air Quality Sensor
- Motion Sensor
- Contact Sensor
- Outlet (power consumption)
- Switch
history - set to true for enabling History Service (Boolean, optional)
History options may be specified in a historyOptions object containing one or more of the following properties:
size - maximum size of stored data points (optional), default: 4032
noAutoTimer - enable/disable averaging (and repeating) 10min timer (optional). Set to true to disable auto-timer.
noAutoRepeat - enable/disable repetition of last value if no data was received in last 10min interval (optional). Set to true to disable auto-repeat.
mergeInterval - set merge interval [minutes] for events, which are very close in time (optional, for motion sensor only, not in combination with autoTimer/autoRepeat), default: 0
persistencePath - full path of directory in which to store history data (defaults to homebridge user storage path)
Avoid the use of "/" in characteristics of the Information Service (e.g. serial number, manufacturer, etc.), since this may cause data to not appear in the history. Note that if your Eve.app is controlling more than one accessory for each type, the serial number should be unique, otherwise Eve.app will merge the histories.
Some accessories support confirmation for some of their 'set' topics. When enabled by configuring confirmationPeriodms, the accessory must echo anything sent to appropriate setX subject(s) to the corresponding getX subject(s). Where homebridge-mqttthing doesn't see a confirmation within the configured confirmation period (specified in milliseconds), it will publish the set message again. Messages will be republished up to 3 times by default, but this can be changed by also specifying retryLimit.
Accessories supporting message confirmation list the topics supporting message confirmation below.
Mqttthing can optionally set an accessory as 'offline' when it doesn't receive confirmation messages. By default it does this if a getOnline topic hasn't been configured - i.e. if online state isn't already being managed explicitly. However, this behaviour can be overridden. Set confirmationIndicateOffline to true to indicate offline ('No Response') even when a getOnline topic is configured, or set confirmationIndicateOffline to false to disable offline indication when there is no response.
Rather like apply functions, a codec can be used to apply transformations to incoming and outgoing data. Unlike apply functions, a codec is written in a separate JavaScript file which is referenced by the configuration.
For further details, please see Codecs.md.
JSONPath syntax may now be used to extract values from JSON format messages. JSONPath syntax is introduced with a $ character in the topic name. MQTT-Thing subscribes to the topic before the $, and decodes the received JSON using the JSONPath syntax following the $.
For example, using the following configuration:
{
"type": "humiditySensor",
"name": "Sonoff-sv-humidity",
"topics": {
"getCurrentRelativeHumidity": "tele/sonoff-sv/SENSOR$.DHT11.Humidity"
},
"accessory": "mqttthing"
},
{
"type": "temperatureSensor",
"name": "Sonoff-sv-temperature",
"topics": {
"getCurrentTemperature": "tele/sonoff-sv/SENSOR$.DHT11.Temperature"
},
"accessory": "mqttthing"
}Published message:
topic: tele/sonoff-sv/SENSOR
message: {"Time":"2021-08-26T15:35:01","DHT11":{"Temperature":19.0,"Humidity":35.0},"TempUnit":"C"}
Results:
Sonoff-sv-humidity : 35
Sonoff-sv-temperature: 19
Following recent advice from Homebridge, MQTT-Thing attempts to validate that properties are only set to values of the correct types. Attempting to set a value to the wrong type or outside valid ranges will result in it being rejected with an error like "Ignoring invalid values [x] for - not an integer".
You may also see validation messages like "Unable to validate x, format [y]" which indicate gaps in the validation logic. Please report these through Github issues or on the Discord channel.
If validation causes issues for your configuration, it can be disabled for an accessory by setting set validate configuration setting to false.
{
"accessory": "mqttthing",
...
"validate": false
}For configuration details of supported accessories, please see Accessories.md.
The services provided by multiple accessories may be grouped together by creating an accessory of type custom containing multiple service definitions in a services array. For example,
the following configuration groups together two switches and a motion sensor:
{
"accessory": "mqttthing",
"type": "custom",
"name": "Composite",
"url": "mqttserver",
"logMqtt": true,
"integerValue": true,
"services": [
{
"type": "switch",
"name": "Switch 1",
"topics": {
"getOn": "home/get/switch1/POWER",
"setOn": "home/set/switch1/POWER"
}
},
{
"type": "switch",
"name": "Switch 2",
"topics": {
"getOn": "home/get/switch2/POWER",
"setOn": "home/set/switch2/POWER"
}
},
{
"type": "motionSensor",
"name": "My PIR",
"topics": {
"getMotionDetected": "home/get/pir/STATUS",
"getStatusActive": "home/get/pir/ACTIVE",
"getStatusFault": "home/get/pir/FAULT",
"getStatusLowBattery": "home/get/pir/BATLOW"
}
}
]
}Any settings which apply to all services may be defined within the custom-type accessory, e.g. integerValue above. Settings specified within individual services will override any defaults specified at the custom accessory level.
Custom accessories are only intended for use with simple services, not with accessories like 'weather station' which already combine multiple services.
Custom accessories cannot be configured through Config UI X.