homebridge-easy-mqtt 1.4.0-beta.1 → 1.4.0-beta.11

package/CHANGELOG.md

@@ -2,14 +2,22 @@
 
 All notable changes to homebridge-dummy will be documented in this file.
 
-## 1.4.0-beta.1 (2025-09-XX)
+## 1.4.0-beta.10 (2025-09-23)
 
 ### Added
-- Support for HeaterCooler
+- Support for Air Purifier, HeaterCooler, LightSensor, and Valve
+- FilterMaintenance to climate control accessories
+- Broker, username, and password can be set via environment variables ([documentation](https://github.com/mpatfield/homebridge-easy-mqtt#environment-variables))
+- Publish arbitrary MQTT messages on connect ([documentation] (https://github.com/mpatfield/homebridge-easy-mqtt#mqtt-onconnect))
+- Traduceri în limba română. Mulțumesc, [@rursache](https://github.com/sponsors/rursache)!
 
 ### Changed
 - Optimized MQTT connections by sharing across multiple accessories when possible
     - Previously, every accessory had its own connection
+- Better field validation in config UI (Thank you, [@justjam2013](https://github.com/sponsors/justjam2013) for teaching me this!)
+
+### Fixed
+- Config UI rendering issue when migrating deprecated fields
 
 ### Notes
 Would you like to see Homebridge Easy MQTT in your language? Please consider [getting involved](https://github.com/mpatfield/homebridge-easy-mqtt/issues/4). No coding experience required!

package/README.md

@@ -64,7 +64,14 @@ Using the Homebridge Config UI is the easiest way to set up this plugin. However
         "broker": "string",
         "username": "string",
         "password": "string",
-        "options": "string"
+        "options": "string",
+        "onConnect": [
+          {
+            "topic": "string",
+            "message": "string",
+          }
+          …
+        ]
       },
       "customCharacteristics": [
         {
@@ -97,10 +104,21 @@ Required fields are marked with an asterisk (*)
 - `version` - 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
+- `broker` - The URL and port to use for communicating with your MQTT device, defaults to `mqtt://127.0.0.1:1883/`
 - `username` - Username
 - `password` - Password
 - `options` - See [MQTT Options](#mqtt-options) below
+- `onConnect` - See [MQTT OnConnect](#mqtt-onconnect) below
+
+#### Environment Variables
+
+Alternatively, you may set the following environment variables for broker, username, and password:
+
+- `EASYMQTT_BROKER` - expects a fully formed url, `protocol://host:port/` where port is optional
+- `EASYMQTT_USERNAME`
+- `EASYMQTT_PASSWORD`
+
+Note that setting the this information in the JSON config will override the environment variables.
 
 ## Topics & Values
 
@@ -110,6 +128,8 @@ You may define topics using a JSONPath dot notation to assist the parser in find
 
 As with topics, you will also 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.
 
+These values are used for both determining current state and, where appropriate, publishing the new state to MQTT
+
 ### General Purpose
 - `topicGetStatusActive` - Whether or not the accessory is connected/reachable
 - `topicGetBatteryLow` - Wether or not the accessory has a low battery
@@ -118,12 +138,12 @@ As with topics, you will also need to populate the appropriate values based on t
 - `valueBatteryLow` - Accessory has a low battery level
 
 ### On/Off Accessories
+
+#### Lightbulb
 - `topicGetOn*` - The current state of the outlet, i.e. on/off
 - `topicSetOn*` - For setting the state of the outlet
 - `valueOn*` - Turned on, e.g. "true", or "1", or "On"
 - `valueOff*` - Turned off, e.g. "false", or "0", or "Off"
-
-#### Lightbulb
 - `topicGetBrightness` - The current brightness as a percent
 - `topicSetBrightness` - For setting the brightness
 - `topicGetColorTemperature` - The current color temperature of the lightbulb
@@ -134,76 +154,178 @@ As with topics, you will also need to populate the appropriate values based on t
 - `topicSetSaturation` - For setting the saturation setting of the lightbulb
 
 #### Outlet
+- `topicGetOn*` - The current state of the outlet, i.e. on/off
+- `topicSetOn*` - For setting the state of the outlet
+- `valueOn*` - Turned on, e.g. "true", or "1", or "On"
+- `valueOff*` - Turned off, e.g. "false", or "0", or "Off"
 - `topicGetOutletInUse` - Whether or not the outlet is currently being used
 - `valueOutletInUse` - Currently being used, e.g. "true", or "1", or "On"
 
 #### Switch
--
+- `topicGetOn*` - The current state of the outlet, i.e. on/off
+- `topicSetOn*` - For setting the state of the outlet
+- `valueOn*` - Turned on, e.g. "true", or "1", or "On"
+- `valueOff*` - Turned off, e.g. "false", or "0", or "Off"
 
 ### Sensors
-- `topicGetStatusFault` - Whether or not the sensor has a generic fault
-- `topicGetStatusTampered` - Whether or not the sensor has been tampered with
-- `valueFault` - Accessory has a fault
-- `valueTampered` - Accessory has been tampered with
 
 #### CarbonDioxideSensor
 - `topicGetCarbonDioxideDetected*` - Whether or not the sensor has detected carbon dioxide
 - `topicGetCarbonDioxideLevel` - The current carbon dioxide level
 - `topicGetCarbonDioxidePeakLevel` - The peak carbon dioxide level
+- `topicGetStatusFault` - Whether or not the sensor has a generic fault
+- `topicGetStatusTampered` - Whether or not the sensor has been tampered with
 - `valueCarbonDioxideDetected*` - Accessory has detected carbon dioxide
+- `valueFault` - Accessory has a fault
+- `valueTampered` - Accessory has been tampered with
 
 #### CarbonMonoxideSensor
 - `topicGetCarbonMonoxideDetected*` - Whether or not the sensor has detected carbon monoxide
 - `topicGetCarbonMonoxideLevel` - The current carbon monoxide level
 - `topicGetCarbonMonoxidePeakLevel` - The peak carbon monoxide level
+- `topicGetStatusFault` - Whether or not the sensor has a generic fault
+- `topicGetStatusTampered` - Whether or not the sensor has been tampered with
 - `valueCarbonMonoxideDetected*` - Accessory has detected carbon monoxide
+- `valueFault` - Accessory has a fault
+- `valueTampered` - Accessory has been tampered with
 
 #### ContactSensor
 - `topicGetContactSensorState*` - Whether or not sensor has detected contact
+- `topicGetStatusFault` - Whether or not the sensor has a generic fault
+- `topicGetStatusTampered` - Whether or not the sensor has been tampered with
 - `valueContactDetected*` - Accessory has detected contact
+- `valueFault` - Accessory has a fault
+- `valueTampered` - Accessory has been tampered with
 
 ### HumiditySensor
-- `topicGetCurrentRelativeHumidity` - The current relatively humidity
+- `topicGetCurrentRelativeHumidity*` - The current relatively humidity
+- `topicGetStatusFault` - Whether or not the sensor has a generic fault
+- `topicGetStatusTampered` - Whether or not the sensor has been tampered with
+- `valueFault` - Accessory has a fault
+- `valueTampered` - Accessory has been tampered with
 
 #### LeakSensor
 - `topicGetLeakDetected*` - Whether or not sensor has detected a leak
+- `topicGetStatusFault` - Whether or not the sensor has a generic fault
+- `topicGetStatusTampered` - Whether or not the sensor has been tampered with
 - `valueLeakDetected*` - Accessory has detected a leak
+- `valueFault` - Accessory has a fault
+- `valueTampered` - Accessory has been tampered with
+
+#### LightSensor
+- `topicGetCurrentAmbientLightLevel*` - The current light level in lux units
+- `topicGetStatusFault` - Whether or not the sensor has a generic fault
+- `topicGetStatusTampered` - Whether or not the sensor has been tampered with
+- `valueFault` - Accessory has a fault
+- `valueTampered` - Accessory has been tampered with
 
 #### MotionSensor
 - `topicGetMotionDetected*` - Whether or not sensor has detected motion
+- `topicGetStatusFault` - Whether or not the sensor has a generic fault
+- `topicGetStatusTampered` - Whether or not the sensor has been tampered with
 - `valueMotionDetected*` - Accessory has detected motion
+- `valueFault` - Accessory has a fault
+- `valueTampered` - Accessory has been tampered with
 
 #### OccupancySensor
 - `topicGetOccupancyDetected*` - Whether or not sensor has detected occupancy
+- `topicGetStatusFault` - Whether or not the sensor has a generic fault
+- `topicGetStatusTampered` - Whether or not the sensor has been tampered with
 - `valueOccupancyDetected*` - Accessory has detected occupancy
+- `valueFault` - Accessory has a fault
+- `valueTampered` - Accessory has been tampered with
 
 #### SmokeSensor
 - `topicGetSmokeDetected*` - Whether or not sensor has detected smoke
+- `topicGetStatusFault` - Whether or not the sensor has a generic fault
+- `topicGetStatusTampered` - Whether or not the sensor has been tampered with
 - `valueSmokeDetected*` - Accessory has detected smoke
+- `valueFault` - Accessory has a fault
+- `valueTampered` - Accessory has been tampered with
 
 #### TemperatureSensor
 - `topicGetCurrentTemperature*` - The current temperature of the sensor
 - `temperatureUnits` - The temperature units of the incoming value supplied by the sensor, `C` for Celsius  (default) `F` for Fahrenheit
+- `topicGetStatusFault` - Whether or not the sensor has a generic fault
+- `topicGetStatusTampered` - Whether or not the sensor has been tampered with
+- `valueFault` - Accessory has a fault
+- `valueTampered` - Accessory has been tampered with
 
 ### Climate Controllers
+
+#### Thermostat
 - `temperatureUnits` - The temperature units of the incoming value supplied by the thermostat, `C` for Celsius  (default) `F` for Fahrenheit
+- `topicGetCurrentTemperature*` - Get the current temperature
+- `topicGetCurrentHeatingCoolingState*` - Get the current mode (i.e. cooling, heating, off)
+- `topicGetTargetHeatingCoolingState*` - Get the target mode (i.e. auto, cooling, heating, off)
+- `topicSetTargetHeatingCoolingState*` - Set the target mode (i.e. auto, cooling, heating, off)
+- `topicGetTargetTemperature*` - Get the target temperature
+- `topicSetTargetTemperature*` - Set the target temperature
 - `topicGetCoolingThresholdTemperature` - Get the cooling threshold temperature
 - `topicSetCoolingThresholdTemperature` - Set the cooling threshold temparture
 - `topicGetHeatingThresholdTemperature` - Get the heating threshold temperature
 - `topicSetHeatingThresholdTemperature` - Set the heating threshold temperature
+- `topicGetCurrentRelativeHumidity` - Get the current humidity
+- `topicGetTargetRelativeHumidity` - Get the target humidity
+- `topicSetTargetRelativeHumidity` - Set the target humidity
+- `topicGetFilterChangeIndication` - Whether or not the filter needs to be changed. *Required if other filter topics are defined.
+- `topicGetFilterLifeLevel` - Filter life remaining as a percentage
+- `topicResetFilterIndication` - Used to reset the filter
+- `valueModeAuto` - Auto mode
+- `valueModeCool` - Cool mode
+- `valueModeHeat` - Heat mode
+- `valueModeOff` - Thermostat off
+- `valueFilterChange` - Indicates that the filter needs to be changed. *Required if `topicGetFilterChangeIndication` is defined.
+
+#### Air Purifier
+- `topicGetActive*` - Get whether or not the accessory is currently active
+- `topicSetActive*` - Set whether or not the accessory is currently active
+- `topicGetCurrentPurifierState*` - Get the current mode (i.e. inactive, idle, purifying)
+- `topicGetTargetPurifierState*` - Get the target mode (i.e. auto, manual)
+- `topicSetTargetPurifierState*` - Set the target mode (i.e. auto, manual)
+- `topicGetLockPhysicalControls` - Get whether or not the physical controls are locked
+- `topicSetLockPhysicalControls` - Set whether or not the physical controls are locked
+- `topicGetRotationSpeed` - Get the rotation speed as a percentage
+- `topicSetRotationSpeed` - Set the rotation speed as a percentage
+- `topicGetSwingMode` - Get whether or not accessory is oscillating
+- `topicSetSwingMode` - Set whether or not accessory is oscillating
+- `topicGetFilterChangeIndication` - Whether or not the filter needs to be changed. *Required if other filter topics are defined.
+- `topicGetFilterLifeLevel` - Filter life remaining as a percentage
+- `topicResetFilterIndication` - Used to reset the filter
+- `valueStateActive*` - Accessory is currently active
+- `valueStateInactive*` - Accessory is currently inactive
+- `valueModeAuto` - Auto target mode
+- `valueModeIdle` - Idle mode
+- `valueModeInactive` - Inactive mode
+- `valueModeManual` - Manual target mode
+- `valueModePurifying` - Purifying mode
+- `valueControlLock` - Physical controls are locked
+- `valueControlUnlock` - Physical controls are unlocked
+- `valueSwingEnabled` - Accessory is oscillating
+- `valueSwingDisabled` - Accessory is not oscillating
+- `valueFilterChange` - Indicates that the filter needs to be changed. *Required if `topicGetFilterChangeIndication` is defined.
 
 #### HeaterCooler
+- `temperatureUnits` - The temperature units of the incoming value supplied by the thermostat, `C` for Celsius  (default) `F` for Fahrenheit
 - `topicGetActive*` - Get whether or not the accessory is currently active
 - `topicSetActive*` - Set whether or not the accessory is currently active
+- `topicGetCurrentTemperature*` - Get the current temperature
 - `topicGetCurrentHeaterCoolerState*` - Get the current mode (i.e. inactive, idle, heating, cooling)
 - `topicGetTargetHeaterCoolerState*` - Get the target mode (i.e. auto, heat, cool)
 - `topicSetTargetHeaterCoolerState*` - Set the target mode (i.e. auto, heat, cool)
+- `topicGetCoolingThresholdTemperature` - Get the cooling threshold temperature
+- `topicSetCoolingThresholdTemperature` - Set the cooling threshold temparture
+- `topicGetHeatingThresholdTemperature` - Get the heating threshold temperature
+- `topicSetHeatingThresholdTemperature` - Set the heating threshold temperature
 - `topicGetLockPhysicalControls` - Get whether or not the physical controls are locked
 - `topicSetLockPhysicalControls` - Set whether or not the physical controls are locked
 - `topicGetRotationSpeed` - Get the rotation speed as a percentage
 - `topicSetRotationSpeed` - Set the rotation speed as a percentage
 - `topicGetSwingMode` - Get whether or not accessory is oscillating
 - `topicSetSwingMode` - Set whether or not accessory is oscillating
+- `topicGetFilterChangeIndication` - Whether or not the filter needs to be changed. *Required if other filter topics are defined.
+- `topicGetFilterLifeLevel` - Filter life remaining as a percentage
+- `topicResetFilterIndication` - Used to reset the filter
 - `valueStateActive*` - Accessory is currently active
 - `valueStateInactive*` - Accessory is currently inactive
 - `valueModeAuto` - Mode is auto
@@ -215,21 +337,7 @@ As with topics, you will also need to populate the appropriate values based on t
 - `valueControlUnlock` - Physical controls are unlocked
 - `valueSwingEnabled` - Accessory is oscillating
 - `valueSwingDisabled` - Accessory is not oscillating
-
-#### Thermostat
-- `topicGetCurrentHeatingCoolingState*` - Get the current mode (i.e. cooling, heating, off)
-- `topicGetTargetHeatingCoolingState*` - Get the target mode (i.e. auto, cooling, heating, off)
-- `topicSetTargetHeatingCoolingState*` - Set the target mode (i.e. auto, cooling, heating, off)
-- `topicGetCurrentTemperature*` - Get the current temperature
-- `topicGetTargetTemperature*` - Get the target temperature
-- `topicSetTargetTemperature*` - Set the target temperature
-- `topicGetCurrentRelativeHumidity` - Get the current humidity
-- `topicGetTargetRelativeHumidity` - Get the target humidity
-- `topicSetTargetRelativeHumidity` - Set the target humidity
-- `valueModeAuto` - Auto mode
-- `valueModeCool` - Cool mode
-- `valueModeHeat` - Heat mode
-- `valueModeOff` - Thermostat off
+- `valueFilterChange` - Indicates that the filter needs to be changed. *Required if `topicGetFilterChangeIndication` is defined.
 
 ### Others
 
@@ -255,6 +363,24 @@ As with topics, you will also need to populate the appropriate values based on t
 - `valueFault` - Accessory has a fault
 - `valueTampered` - Accessory has been tampered with
 
+#### Valve
+- `valveType` -  One of `GENERIC_VALVE` (default), `IRRIGATION`, `SHOWER_HEAD`, or `WATER_FAUCET`
+- `topicGetValveActive*` - For getting whether or not the valve is active
+- `topicSetValveActive*` - For setting whether or not the valve is active
+- `topicGetValveInUse*` - For getting whether or not the valve is in use
+- `topicGetStatusFault` - For getting whether or not there is a fault
+- `topicGetValveIsConfigured` - For getting wether or not valve is configured
+- `topicSetValveIsConfigured` - For setting wether or not valve is configured
+- `topicGetValveSetDuration` - For getting the set duration in seconds
+- `topicSetValveSetDuration` - For setting the set duration in seconds
+- `topicGetValveRemainingDuration` - For getting the time remaining in seconds
+- `valueActive*` - Valve is active, e.g. "true", or "1", or "active"
+- `valueInactive*` - Valve is not active e.g. "false", or "0", or "active"
+- `valueInUse*` - Valve is in use, e.g. "true", or "1", or "used"
+- `valueConfigured` - Valve is configured, e.g. "true", or "1", or "configured"
+- `valueNotConfigured` - Valve is not configured, e.g. "false", or "0", or "unconfigured"
+- `valueFault` - Valve has a fault, e.g. "error", or "-1"
+
 ## Logging/Debugging:
 
 By default, devices will log activity, for example when a Switch is turned on or a LockMechanism is unlocked.
@@ -275,6 +401,25 @@ You are able to pass in any arbitrary MQTT options via `mqtt.options` in the con
 "options": "{ \"protocolVersion\": \"4\", \"clientId\": \"my-client-id\", \"rejectUnauthorized\": true }"
 ```
 
+## MQTT OnConnect
+
+Accessories can be configured to publish any number of arbitratry messages to the MQTT server on connect. This can be useful to invoke accessories to give updates on their current status.
+
+Each entry should have a topic and a message:
+
+```
+"onConnect": [
+  {
+    "topic": "some/arbitrary/topic",
+    "message": "connected",
+  },
+  {
+    "topic": "another/arbitrary/topic",
+    "message": "{ \"value\": \"can also be json\" }",
+  }
+]
+```
+
 ## JSONPaths
 
 For some devices, the desired values in the MQTT messages are embedded within a JSON object. For example, here is the MQTT message for my door lock that is received when the door is locked: