homebridge-easy-mqtt 1.2.0-beta.5 → 1.3.0-beta.0

package/CHANGELOG.md

@@ -2,24 +2,34 @@
 
 All notable changes to homebridge-dummy will be documented in this file.
 
-## 1.2.0-beta.1 (2025-08-??)
+## 1.3.0-beta.0 (2025-09-XX)
 
 ### HELP NEEDED! (no coding experience required)
 
 Would you like to see Homebridge Easy MQTT in your language? Please consider [getting involved](https://github.com/mpatfield/homebridge-easy-mqtt/issues/4).
 
+### Added
+- Support for arbitrary custom characteristics ([documentation](https://github.com/mpatfield/homebridge-easy-mqtt#custom-characteristics))
+- JSONPath support in setter topics ([documentation](https://github.com/mpatfield/homebridge-easy-mqtt#jsonpaths))
+- Banner image in config UI
+
+### Changed
+- Significant under-the-hood DRY cleanup to speed future development
+
+## 1.2.0 (2025-09-02)
+
 ### Added
 - Security System accessory type
 - Support for battery and status
 
 ### Fixed
-- Allow raw strings in mqtt messages
+- 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 modifyable
+- 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

package/README.md

@@ -1,8 +1,6 @@
-<!--
 <p align="center">
-<img src="https://github.com/mpatfield/homebridge-easy-mqtt/blob/latest/img/banner.png?raw=true" width="600">
+<img src="https://raw.githubusercontent.com/mpatfield/homebridge-easy-mqtt/refs/heads/latest/img/banner.png" width="600">
 </p>
--->
 
 <span align="center">
 
@@ -10,6 +8,8 @@
 
 Homebridge plugin to integrate simple MQTT devices into Apple HomeKit
 
+[![verified-by-homebridge](https://badgen.net/badge/homebridge/verified/purple)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)
+[![Discord](https://img.shields.io/discord/432663330281226270?color=728ED5&logo=discord&label=discord)](https://discord.com/channels/432663330281226270/1412178951295467542) \
 [![npm](https://img.shields.io/npm/dw/homebridge-easy-mqtt)](https://www.npmjs.com/package/homebridge-easy-mqtt)
 [![npm](https://img.shields.io/npm/dt/homebridge-easy-mqtt)](https://www.npmjs.com/package/homebridge-easy-mqtt)
 
@@ -49,6 +49,15 @@ Using the Homebridge Config UI is the easiest way to set up this plugin. However
         "password": "string",
         "options": "string"
       },
+      "customCharacteristics": [
+        {
+          "uuid": "string",
+          "name": "string",
+          "getTopic": "string",
+          "units": "string",
+        }
+        …
+      ],
       "topicGetStatusActive": "string",
       "topicGetCurrentLockState": "string",
       "topicGetTargetLockState": "string",
@@ -63,7 +72,7 @@ Using the Homebridge Config UI is the easiest way to set up this plugin. However
       "valueOff": "string",
       "disableLogging": false
     }
-    ...
+    …
   ],
   "verbose": false,
   "platform": "HomebridgeEasyMQTT"
@@ -187,7 +196,7 @@ You are able to pass in any arbitrary MQTT options via `mqtt.options` in the con
 
 ## 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:
+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:
 
 ```json
 { "time": 1750870005853, "state": 255 }
@@ -218,8 +227,68 @@ would use the topic
 
 `zwave/1/door_lock/currentMode$.state.number.value`
 
+You can do the same for the set topic if the device is expecting a JSON object rather than a raw value.
+
+If, for example, your device is expecting this message:
+
+```json
+{
+  "target": "away"
+}
+```
+
+instead of just the raw value "away" you can use:
+
+`zwave/4/security/set$.target`
+
+Again, the `$.target` at the end tells the MQTT client to wrap the value a JSON object.
+
+As with get topics, you can have an arbitrarily complex chain. So if, for example, you want this object:
+
+```json
+{
+  "target": {
+    "mode": {
+      "value": "away"
+    }
+  }
+}
+```
+
+then you would use the topic
+
+`zwave/4/security/set$.target.mode.value`
+
+## Custom Characteristics
+
+If you use a more advanced HomeKit app like [Eve](https://apps.apple.com/us/app/eve-for-matter-homekit/id917695792) or [Controller for Homekit](https://apps.apple.com/us/app/controller-for-homekit/id1198176727), you can add custom characteristics to display any arbitrary numeric information. Unfortunately, Apple currently doesn't offer a way to display this in the Home app.
+
+<img src="https://raw.githubusercontent.com/mpatfield/homebridge-easy-mqtt/refs/heads/latest/img/screenshot_1.png">
+
+Due to the complexity, this was intentionally left out of the plugin config UI, so this can only be configured manually.
+
+```json
+"customCharacteristics": [
+  {
+    "uuid": "string",
+    "name": "string",
+    "getTopic": "string",
+    "units": "string",
+  }
+]
+```
+
+- `uuid` — A unique string (recommend using a (UUID generator)[https://www.uuidgenerator.net/])
+- `name` — The display name for the characteristic
+- `getTopic` — The topic which provides the numeric value
+- `units` — (Optional) The units which will be displayed at the end of the numeric value
+
+Since `customCharacteristics` is an array, you may define as many custom characteristics as you wish.
+
 ## Credits
 
 [@arachnetech](https://github.com/arachnetech) for the fantastic [homebridge-mqttthing](https://github.com/arachnetech/homebridge-mqttthing) plugin which serves as the main inspiration for this project
 
+[Keryan Belahcene](https://www.instagram.com/keryan.me) for creating the [Flume](https://github.com/homebridge-plugins/homebridge-flume) header logo which I adapted for this plugin
+
 And to the amazing creators/contributors of [Homebridge](https://homebridge.io) who made this plugin possible!

package/config.schema.json

@@ -24,6 +24,22 @@
             "enum": [ "Lightbulb", "LockMechanism", "Outlet", "SecuritySystem", "Switch", "TemperatureSensor"],
             "enumNames": ["${config.enumNames.lightbulb}", "${config.enumNames.lockMechanism}", "${config.enumNames.outlet}", "${config.enumNames.securitySystem}", "${config.enumNames.switch}",  "${config.enumNames.temperatureSensor}"],
             "required": true
+          },
+          "manufacturer": {
+            "type": "string",
+            "title": "${config.title.manufacturer}"
+          },
+          "model": {
+            "type": "string",
+            "title": "${config.title.model}"
+          },
+          "serialNumber": {
+            "type": "string",
+            "title": "${config.title.serialNumber}"
+          },
+          "version": {
+            "type": "string",
+            "title": "${config.title.version}"
           }
         }
       },
@@ -51,6 +67,23 @@
             "placeholder": "{ \"protocolVersion\": \"4\", \"clientId\": \"my-client-id\", \"rejectUnauthorized\": true }"
           }
         }
+      },
+      "customCharacteristic": {
+        "type": "object",
+        "properties": {
+          "uuid": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "getTopic": {
+            "type": "string"
+          },
+          "units": {
+            "type": "string"
+          }
+        }
       }
     },
     "properties": {
@@ -65,6 +98,10 @@
           "properties": {
             "info": { "$ref": "#/definitions/info" },
             "mqtt": { "$ref": "#/definitions/mqtt" },
+            "customCharacteristics": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/customCharacteristic" }
+            },
             "temperatureUnits": {
               "type": "string",
               "enum": ["C", "F"],

package/dist/accessory/abstract/base.d.ts

@@ -4,11 +4,7 @@ import { CharacteristicType, BaseAccessoryConfig, ServiceType } from '../../mode
 import { Log } from '../../tools/log.js';
 export declare abstract class BaseAccessory<C extends BaseAccessoryConfig = BaseAccessoryConfig> extends MQTTAccessory<C> {
     constructor(Service: ServiceType, Characteristic: CharacteristicType, accessory: PlatformAccessory, config: C, log: Log);
-    protected addTopicHandlers(): void;
-    private getBatteryLevel;
-    private getBatteryLow;
-    private getStatusActive;
-    private onBatteryLevelUpdate;
+    private handleCustomCharacteristics;
     private onBatteryLowUpdate;
     private onStatusActiveUpdate;
 }

package/dist/accessory/abstract/base.js

@@ -1,4 +1,5 @@
 import { MQTTAccessory } from './mqtt.js';
+import { CustomCharacteristic } from './customCharacteristic.js';
 import { PLATFORM_NAME } from '../../homebridge/settings.js';
 import { strings } from '../../i18n/i18n.js';
 import { CharacteristicKey } from '../../model/enums.js';
@@ -10,35 +11,30 @@ export class BaseAccessory extends MQTTAccessory {
         accessory.getService(Service.AccessoryInformation)
             .setCharacteristic(Characteristic.Name, config.info.name)
             .setCharacteristic(Characteristic.ConfiguredName, config.info.name)
-            .setCharacteristic(Characteristic.Manufacturer, PLATFORM_NAME)
-            .setCharacteristic(Characteristic.Model, config.info.type)
-            .setCharacteristic(Characteristic.SerialNumber, config.info.id)
-            .setCharacteristic(Characteristic.FirmwareRevision, getVersion());
-        this.set(CharacteristicKey.BatteryLevel, 100);
-        this.bind(Characteristic.BatteryLevel, 'topicGetBatteryLevel', this.getBatteryLevel.bind(this));
-        this.set(CharacteristicKey.StatusLowBattery, false);
-        this.bind(Characteristic.StatusLowBattery, 'topicGetBatteryLow', this.getBatteryLow.bind(this));
-        this.set(CharacteristicKey.StatusActive, true);
-        this.bind(Characteristic.StatusActive, 'topicGetStatusActive', this.getStatusActive.bind(this));
+            .setCharacteristic(Characteristic.Manufacturer, config.info.manufacturer ?? PLATFORM_NAME)
+            .setCharacteristic(Characteristic.Model, config.info.model ?? config.info.type)
+            .setCharacteristic(Characteristic.SerialNumber, config.info.serialNumber ?? config.info.id)
+            .setCharacteristic(Characteristic.FirmwareRevision, config.info.version ?? getVersion());
+        this.setupCharacteristic(CharacteristicKey.BatteryLevel, 100, 'topicGetBatteryLevel', this.bindOnUpdateNumeric(CharacteristicKey.BatteryLevel, strings.accessory.batteryLevel), false);
+        this.setupCharacteristic(CharacteristicKey.StatusLowBattery, false, 'topicGetBatteryLow', this.onBatteryLowUpdate.bind(this), false);
+        this.setupCharacteristic(CharacteristicKey.StatusActive, true, 'topicGetStatusActive', this.onStatusActiveUpdate.bind(this), false);
+        this.handleCustomCharacteristics();
     }
-    addTopicHandlers() {
-        this.addTopicHandler('topicGetBatteryLevel', this.onBatteryLevelUpdate.bind(this), false);
-        this.addTopicHandler('topicGetBatteryLow', this.onBatteryLowUpdate.bind(this), false);
-        this.addTopicHandler('topicGetStatusActive', this.onStatusActiveUpdate.bind(this), false);
-    }
-    async getBatteryLevel() {
-        return this.get(CharacteristicKey.BatteryLevel);
-    }
-    async getBatteryLow() {
-        return this.get(CharacteristicKey.StatusLowBattery);
-    }
-    async getStatusActive() {
-        return this.get(CharacteristicKey.StatusActive);
-    }
-    async onBatteryLevelUpdate(topic, value) {
-        if (this.assertNumber(value, strings.accessory.badBatteryLevel)) {
-            const logString = strings.accessory.batteryLevel.replace('%d', `${value.toString()}%`);
-            this.onUpdate(CharacteristicKey.BatteryLevel, value, logString); // TODO not working
+    handleCustomCharacteristics() {
+        const keepUUIDs = new Set(Object.values(CharacteristicKey).map((key) => this.Characteristic[key].UUID));
+        const toRemove = this.accessoryService.characteristics.filter((characteristic) => !keepUUIDs.has(characteristic.UUID));
+        for (const characteristic of toRemove) {
+            characteristic.updateValue(null);
+            this.accessoryService.removeCharacteristic(characteristic);
+        }
+        if (!this.config.customCharacteristics) {
+            return;
+        }
+        for (const config of this.config.customCharacteristics) {
+            const customChar = CustomCharacteristic.create(this.accessoryService, this.Characteristic, config, this.name, this.log, this.config.disableLogging);
+            if (customChar !== undefined) {
+                this.addTopicHandler(customChar.topic, customChar.onUpdateHandler);
+            }
         }
     }
     async onBatteryLowUpdate(topic, value) {

package/dist/accessory/abstract/base.js.map

@@ -1 +1 @@
-{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/accessory/abstract/base.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/accessory/abstract/base.ts"],"names":[],"mappings":"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"}

package/dist/accessory/abstract/customCharacteristic.d.ts

@@ -0,0 +1,17 @@
+import { PrimitiveTypes, Service } from 'homebridge';
+import { CharacteristicType, CustomCharacteristicConfig } from '../../model/types.js';
+import { Log } from '../../tools/log.js';
+export declare class CustomCharacteristic {
+    private readonly config;
+    private readonly caller;
+    private readonly log;
+    private readonly disableLogging;
+    private characteristic;
+    private value;
+    static create(Service: Service, Characteristic: CharacteristicType, config: CustomCharacteristicConfig, caller: string, log: Log, disableLogging: boolean): CustomCharacteristic | undefined;
+    private constructor();
+    get topic(): string;
+    get onUpdateHandler(): (topic: string, value: PrimitiveTypes) => Promise<void>;
+    private getValue;
+    private onValueUpdate;
+}

package/dist/accessory/abstract/customCharacteristic.js

@@ -0,0 +1,65 @@
+import { strings } from '../../i18n/i18n.js';
+import { assert } from '../../tools/validation.js';
+export class CustomCharacteristic {
+    config;
+    caller;
+    log;
+    disableLogging;
+    characteristic;
+    value = null;
+    static create(Service, Characteristic, config, caller, log, disableLogging) {
+        if (!assert(log, config.name ?? CustomCharacteristic.name, config, 'name', 'uuid', 'getTopic')) {
+            return;
+        }
+        return new CustomCharacteristic(Service, Characteristic, config, caller, log, disableLogging);
+    }
+    constructor(Service, Characteristic, config, caller, log, disableLogging) {
+        this.config = config;
+        this.caller = caller;
+        this.log = log;
+        this.disableLogging = disableLogging;
+        if (Service.testCharacteristic(config.name)) {
+            this.characteristic = Service.getCharacteristic(config.name);
+        }
+        else {
+            const customCharacteristic = class CustomCharacteristic extends Characteristic {
+                constructor() {
+                    super(config.name, config.uuid, {
+                        format: "uint32" /* Formats.UINT32 */,
+                        perms: ["pr" /* Perms.PAIRED_READ */, "ev" /* Perms.NOTIFY */],
+                        unit: config.units,
+                    });
+                    this.value = this.getDefaultValue();
+                }
+            };
+            this.characteristic = Service.addCharacteristic(customCharacteristic);
+            this.characteristic.UUID = config.uuid;
+        }
+        this.characteristic.onGet(this.getValue.bind(this));
+    }
+    get topic() {
+        return this.config.getTopic;
+    }
+    get onUpdateHandler() {
+        return this.onValueUpdate.bind(this);
+    }
+    async getValue() {
+        return this.value;
+    }
+    async onValueUpdate(topic, value) {
+        if (typeof value !== 'number') {
+            this.log.error(strings.characteristic.badValue, this.caller, this.characteristic.displayName, `'${value}'`);
+            return;
+        }
+        if (value === this.value) {
+            return;
+        }
+        this.value = value;
+        this.characteristic.updateValue(this.value);
+        if (this.disableLogging) {
+            return;
+        }
+        this.log.always(strings.characteristic.updated, this.caller, this.characteristic.displayName, `'${value}'`);
+    }
+}
+//# sourceMappingURL=customCharacteristic.js.map

package/dist/accessory/abstract/customCharacteristic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"customCharacteristic.js","sourceRoot":"","sources":["../../../src/accessory/abstract/customCharacteristic.ts"],"names":[],"mappings":"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"}

package/dist/accessory/abstract/mqtt.d.ts

@@ -1,7 +1,8 @@
-import { Characteristic, CharacteristicGetHandler, CharacteristicSetHandler, CharacteristicValue, PlatformAccessory, PrimitiveTypes, Service, WithUUID } from 'homebridge';
+import { Characteristic, CharacteristicSetHandler, CharacteristicValue, PlatformAccessory, PrimitiveTypes, Service } from 'homebridge';
 import { CharacteristicKey } from '../../model/enums.js';
 import { CharacteristicType, MQTTAccessoryConfig, ServiceType } from '../../model/types.js';
 import { Log, LogType } from '../../tools/log.js';
+type OnUpdateHandler = (topic: string, value: PrimitiveTypes) => (Promise<void>);
 export declare abstract class MQTTAccessory<C extends MQTTAccessoryConfig> {
     protected readonly Service: ServiceType;
     protected readonly Characteristic: CharacteristicType;
@@ -13,24 +14,20 @@ export declare abstract class MQTTAccessory<C extends MQTTAccessoryConfig> {
     private readonly topicHandlers;
     protected readonly accessoryService: Service;
     constructor(Service: ServiceType, Characteristic: CharacteristicType, accessory: PlatformAccessory, config: C, log: Log);
-    private onMQTTConnect;
     protected abstract getAccessoryService(): Service;
-    protected bind(constructor: WithUUID<{
-        new (): Characteristic;
-    }>, getTopic: keyof C, getHandler: CharacteristicGetHandler, setTopic?: keyof C | undefined, setHandler?: CharacteristicSetHandler | undefined): void;
-    protected abstract addTopicHandlers(): void;
-    protected addTopicHandler(topicKey: keyof C, handler: (topic: string, value: PrimitiveTypes) => Promise<void>, assert?: boolean): void;
     protected get name(): string;
+    protected setupCharacteristic(characteristicKey: CharacteristicKey, defaultValue: CharacteristicValue, getTopicKey: keyof C, onUpdateHandler: OnUpdateHandler, assertGetTopic: boolean, setTopicKey?: keyof C | undefined, onSetHandler?: CharacteristicSetHandler | undefined): Characteristic | undefined;
+    protected bindOnUpdateNumeric(charKey: CharacteristicKey, logTemplate: string): OnUpdateHandler;
+    protected bindOnUpdateNumericBoolean(charKey: CharacteristicKey, valueKey: keyof C, logTrue: string, logFalse: string): OnUpdateHandler;
+    protected addTopicHandler(topic: string, handler: (topic: string, value: PrimitiveTypes) => Promise<void>): void;
     protected getRawValue(property: keyof C, assert?: boolean): string | undefined;
     protected getPrimitiveValue(property: keyof C, assert?: boolean): PrimitiveTypes | undefined;
     protected publish(topic: string, value: PrimitiveTypes): void;
     teardown(): void;
-    protected get(key: CharacteristicKey): CharacteristicValue;
-    protected set(key: CharacteristicKey, value: CharacteristicValue): void;
     protected assert(...keys: (keyof C)[]): boolean;
-    protected assertNumber(value: PrimitiveTypes, error: string): boolean;
     protected onUpdate(key: CharacteristicKey, value: CharacteristicValue, logString?: string | undefined): boolean;
     protected onSet(key: CharacteristicKey, value: CharacteristicValue, publish: PrimitiveTypes, topic: keyof C, logString: string | undefined): void;
     protected logIfDesired(message: string, ...parameters: string[]): void;
     protected logIfDesired(level: LogType, message: string, ...parameters: string[]): void;
 }
+export {};

package/dist/accessory/abstract/mqtt.js

@@ -1,8 +1,9 @@
+import { strings } from '../../i18n/i18n.js';
 import { AccessoryType } from '../../model/enums.js';
 import { MQTT } from '../../model/mqtt.js';
 import { LogType } from '../../tools/log.js';
-import { assert } from '../../tools/validation.js';
 import { toPrimitive } from '../../tools/primitive.js';
+import { assert } from '../../tools/validation.js';
 export class MQTTAccessory {
     Service;
     Characteristic;
@@ -10,7 +11,7 @@ export class MQTTAccessory {
     config;
     log;
     mqttClient;
-    properties = {};
+    properties = new Map();
     topicHandlers = [];
     accessoryService;
     constructor(Service, Characteristic, accessory, config, log) {
@@ -21,7 +22,11 @@ export class MQTTAccessory {
         this.log = log;
         const name = config.info.name;
         if (this.assert('mqtt')) {
-            this.mqttClient = new MQTT(log, config.mqtt, this.onMQTTConnect.bind(this), name);
+            this.mqttClient = new MQTT(log, config.mqtt, () => {
+                this.topicHandlers.forEach(topicHandler => {
+                    this.mqttClient?.subscribe(topicHandler.topic, topicHandler.handler);
+                });
+            }, name);
             this.mqttClient.connect();
         }
         this.accessoryService = this.getAccessoryService();
@@ -31,46 +36,61 @@ export class MQTTAccessory {
                 accessory.removeService(existingService);
             }
         }
-        this.addTopicHandlers();
     }
-    async onMQTTConnect() {
-        this.topicHandlers.forEach(topicHandler => {
-            this.mqttClient?.subscribe(topicHandler.topic, topicHandler.handler);
-        });
+    get name() {
+        return this.config.info.name;
     }
-    bind(constructor, getTopic, getHandler, setTopic = undefined, setHandler = undefined) {
-        if (this.config[getTopic] === undefined && (setTopic === undefined || setHandler === undefined || this.config[setTopic] !== undefined)) {
+    setupCharacteristic(characteristicKey, defaultValue, getTopicKey, onUpdateHandler, assertGetTopic, setTopicKey = undefined, onSetHandler = undefined) {
+        if (!getTopicKey.toString().startsWith('topic')) {
+            throw new Error(`Trying to fetch topic with unexpected property name '${getTopicKey.toString()}'`);
+        }
+        if (assertGetTopic) {
+            this.assert(getTopicKey);
+        }
+        if (this.config[getTopicKey] === undefined) {
             for (const characteristic of this.accessoryService.characteristics) {
-                if (characteristic.UUID === constructor.UUID) {
+                if (characteristic.UUID === this.Characteristic[characteristicKey].UUID) {
                     this.accessoryService.removeCharacteristic(characteristic);
                     break;
                 }
             }
             return;
         }
-        const characteristic = this.accessoryService.getCharacteristic(constructor);
-        if (this.config[getTopic] !== undefined) {
-            characteristic.onGet(getHandler);
-        }
-        if (setTopic !== undefined && setHandler !== undefined && this.config[setTopic] !== undefined) {
-            characteristic.onSet(setHandler);
+        const characteristic = this.accessoryService.getCharacteristic(this.Characteristic[characteristicKey]);
+        this.properties.set(characteristicKey, defaultValue);
+        characteristic.onGet(async () => {
+            return this.properties.get(characteristicKey) ?? null;
+        });
+        this.addTopicHandler(this.config[getTopicKey], onUpdateHandler);
+        if (setTopicKey !== undefined) {
+            if (!setTopicKey.toString().startsWith('topic')) {
+                throw new Error(`Trying to fetch topic with unexpected property name '${setTopicKey.toString()}'`);
+            }
+            if (!onSetHandler) {
+                throw new Error(`Missing onSetHandler for topic '${setTopicKey.toString()}'`);
+            }
+            characteristic.onSet(onSetHandler);
         }
+        return characteristic;
     }
-    addTopicHandler(topicKey, handler, assert = true) {
-        if (!topicKey.toString().startsWith('topic')) {
-            throw new Error(`Trying to fetch topic with unexpected property name '${topicKey.toString()}'`);
-        }
-        if (assert && !this.assert(topicKey)) {
-            return;
-        }
-        const topic = this.config[topicKey];
-        if (topic === undefined) {
-            return;
-        }
-        this.topicHandlers.push({ topic: topic, handler });
+    bindOnUpdateNumeric(charKey, logTemplate) {
+        return (async (_topic, value) => {
+            if (typeof value !== 'number') {
+                this.log.error(strings.accessory.badNumericValue, this.name, charKey, `'${value.toString()}'`);
+                return;
+            }
+            const logString = logTemplate.replace('%d', value.toString());
+            this.onUpdate(charKey, value, logString);
+        }).bind(this);
     }
-    get name() {
-        return this.config.info.name;
+    bindOnUpdateNumericBoolean(charKey, valueKey, logTrue, logFalse) {
+        return (async (_topic, value) => {
+            const numeric = value === this.getPrimitiveValue(valueKey) ? 1 : 0;
+            this.onUpdate(charKey, numeric, numeric ? logTrue : logFalse);
+        }).bind(this);
+    }
+    addTopicHandler(topic, handler) {
+        this.topicHandlers.push({ topic: topic, handler: handler });
     }
     getRawValue(property, assert = true) {
         if (!property.toString().startsWith('value')) {
@@ -91,27 +111,14 @@ export class MQTTAccessory {
     teardown() {
         this.mqttClient?.teardown();
     }
-    get(key) {
-        return this.properties[key];
-    }
-    set(key, value) {
-        this.properties[key] = value;
-    }
     assert(...keys) {
         return assert(this.log, this.name, this.config, ...keys);
     }
-    assertNumber(value, error) {
-        if (typeof value === 'number') {
-            return true;
-        }
-        this.log.error(error, this.name, `'${value}'`);
-        return false;
-    }
     onUpdate(key, value, logString = undefined) {
-        if (value === this.get(key)) {
+        if (value === this.properties.get(key)) {
             return false;
         }
-        this.set(key, value);
+        this.properties.set(key, value);
         this.accessoryService.updateCharacteristic(this.Characteristic[key], value);
         if (logString) {
             this.logIfDesired(logString);
@@ -122,10 +129,10 @@ export class MQTTAccessory {
         if (!this.assert(topic)) {
             return;
         }
-        if (logString && value !== this.get(key)) {
+        if (logString && value !== this.properties.get(key)) {
             this.logIfDesired(logString);
         }
-        this.set(key, value);
+        this.properties.set(key, value);
         this.accessoryService.updateCharacteristic(this.Characteristic[key], value);
         this.publish(this.config[topic], publish);
     }