@uboness/homebridge-mqtt 0.0.1

package/README.md

@@ -0,0 +1,3587 @@
+# Homebridge Mqtt Plugin
+
+## !! Experimental !!
+
+- [Core Ideas](#core-ideas)
+  - [Device Configuration](#device-configuration)
+- [Settings](#settings)
+  - [Templates](#templates)
+- [Converters Reference](#converters-reference)
+- [Characteristics Reference](#characteristics-reference)
+- [Services Reference](#services-reference)
+  - [air-quality-sensor](#air-quality-sensor)
+  - [battery](#battery)
+  - [button](#button)
+  - [co2-sensor](#co2-sensor)
+  - [contact-sensor](#contact-sensor)
+  - [co-sensor](#co-sensor)
+  - [door](#door)
+  - [doorbell](#doorbell)
+  - [fan](#fan)
+  - [humidifier-dehumidifier](#humidifier-dehumidifier)
+  - [humidity-sensor](#humidity-sensor)
+  - [leak-sensor](#leak-sensor)
+  - [lightbulb](#lightbulb)
+  - [light-sensor](#light-sensor)
+  - [lock](#lock)
+  - [microphone](#microphone)
+  - [motion-sensor](#motion-sensor)
+  - [occupancy-sensor](#occupancy-sensor)
+  - [outlet](#outlet)
+  - [security-system](#security-system)
+  - [smoke-sensor](#smoke-sensor)
+  - [speaker](#speaker)
+  - [switch](#switch)
+  - [temperature-sensor](#temperature-sensor)
+  - [thermostat](#thermostat)
+  - [window](#window)
+  - [window-covering](#window-covering)
+  
+
+This plugin enables the configuration of devices (HomeKit accessories) that are driven by MQTT topics.
+
+## Core Ideas
+ - Multiple brokers are supported
+ - Each broker defines:
+   - a unique id
+   - connection settings to a single MQTT broker
+   - `baseTopic` a "prefix" topic that will be prepended to all topics configured by the devices & templates
+   - device configurations - all driven by topics within the broker
+   - device templates - reusable device configuration segments (helps keep configuration clean and simple)
+
+### Device Configuration
+A device configuration is made out of:
+- `id` - This identifies the device in homebridge, so it needs to be unique within the Homebridge instance.
+- `type` - The primary service type
+- `name` - Serves as both the primary service name and the HomeKit accessory name
+- `deviceName` - If set, serves as the accessory name (used to separate the accessory and primary service names)
+- `topics` - Defines the characteristics of the primary service and their associated (read/write) topics from/to which values will be read/written
+- `services` - An array of additional (secondary) services that are part of the HomeKit accessory.
+
+Here's an example of a simple lightbulb accessory that happens to have a built-in light sensor:
+
+```json
+{
+  "id": "my-ceiling-light",
+  "type": "lightbulb",
+  "name": "My Ceiling Lamp",
+  "topics": {
+    "on": {
+      "get": "my-home/my-room/my-ceiling-light/on",
+      "set": "my-home/my-room/my-ceiling-light/on/set",
+      "converter": "boolean"
+    },
+    "brightness": {
+      "get": "my-home/my-room/my-ceiling-light/brightness",
+      "set": "my-home/my-room/my-ceiling-light/brightness/set"
+    }
+  },
+  "services": [
+    {
+      "type": "light-sensor",
+      "name": "Light Sensor",
+      "topics": {
+        "ambientLevel": {
+          "get": "my-home/my-room/my-ceiling-light/lux",
+          "set": "my-home/my-room/my-ceiling-light/lux/set"
+        }
+      }
+    }
+  ]
+}
+```
+Each service type defines a set of required characteristics which must be configured within the `topics` configuration
+(e.g. A `switch` service must define the `on` characteristic).
+
+There may also be optional characteristics that a service can support (e.g. all sensor services support the 
+`statusLowBattery` characteristic, though it's optional).
+
+The HomeKit Accessory Protocol (HAP) Specification define the services supported in homekit and their required/optional
+characteristics. This plugin roughly follows these specifications with a few exceptions here and there.
+
+In the example above, the configured MQTT topics hold the values that will eventually be read/published by
+the relevant characteristics. MQTT values are strings and therefore we need a way to convert these values to the appropriate
+type that is expected by each characteristic. This is the role of the `converter`. Each characteristic support a set of
+converters that helps in converting different formats. For example, as in the above, by default, the `on` characteristic
+expects `1` (for "on") and `0` (for "off") values. But if the MQTT value holds `true` and `false` instead, the `boolean`
+converter will be able to handle it. What if the MQTT values is `YES` and `NO`? Well, there's a converter
+for that too - a more generic one: `converter: { "on": "YES", "off": "NO" }` - in this case, we indicate which MQTT
+values represent `on` and `off`.
+
+Some systems (e.g. zigbee2mqtt) publish JSON values to their MQTT topic. To fetch a JSON value, you append
+the "path" to the value within the JSON to the topic itself, using the `$` sign as a separator. For example,
+the following hum characteristic configuration reads/writes the hue values from/to JSON values in the MQTT topics:
+
+```json
+{
+  "hue": {
+    "get": "zigbee2mqtt/Garage Led$color.hue",      // reads from
+    "set": "zigbee2mqtt/Garage Led/set$color.hue"   // publishes to
+  }
+}
+```
+In the above, the topic is `zigbee2mqtt/Garage Led` holds a JSON object of the form:
+```json
+{
+  //...
+  "color": {
+    "hue": 212,
+    "saturation": 10,
+    "x": 0.3131,
+    "y": 0.3232
+  }
+  //...
+}
+```
+With the `$` syntax, the plugin knows how to read it and extract the appropriate value.
+
+Similarly, when publishing a value to the `zigbee2mqtt/Garage Led/set` topic, the plugin will create a JSON value of
+the following form:
+
+```json
+{ "color": { "hue": 200 }}
+```
+
+At the moment, not all HAP services are supported by this plugins, but certainly a big chunk of the most common ones.
+More services/characteristics may be added in the future.
+
+There are many service types to choose from and many characteristic types as well, all of which are 
+
+## Settings
+
+Here's an example of the plugin configuration:
+
+```json
+{
+    "name": "Mqtt",
+    "platform": "Mqtt",
+    "logger": {
+      "trace": false // change to 'true' to output extensive logs (only works when HB runs in debug mode)
+    },
+    "servers": [
+      {
+        "id": "knx",
+        "host": "mqtt.local",
+        "port": 1883,
+        "auth": { // optional, remove if your MQTT broker doesn't require authentication
+          "username": "<username>",
+          "password": "<password>"
+        },
+        "baseTopic": "knx",
+        "templates": [
+          // all the KNX device templates are configued here (see below)
+        ],
+        "devices": [
+          // all the KNX devices are configured here
+        ]
+      },
+      {
+        "id": "zigbee2mqtt",
+        "host": "mqtt.local",
+        "port": 1883,
+        "auth": { // optional, remove if your MQTT broker doesn't require authentication
+          "username": "<username>",
+          "password": "<password>"
+        },
+        "baseTopic": "z2m",
+        "templates": [
+          // all the z2m device templates are configued here (see below)
+        ],
+        "devices": [
+          // all the z2m devices are configured here
+        ]
+      }
+    ]
+}
+```
+In the example above, the plugin is configured with 2 brokers - one that holds all KNX devices values and another that
+is the [zigbee2mqtt](https://www.zigbee2mqtt.io/) broker.
+
+If you look closely thought, they are actually pointing to
+the same server - they could point to different servers, but in this case it's the same server and the only thing that
+really differentiate them is the `baseTopic` - all KNX values are under the `knx` base topic while all the `zigbee2mqtt`
+topics are under the `z2m` base topic.
+
+In this case, we could have also use a single MQTT connection by dropping the `baseTopic` setting and make sure that the
+devices use the full MQTT topic paths in their configurations. So there are a lot of possibilities to design this in a
+way to best fit your setup.
+
+### Templates
+
+We've seen above an example of a device configuration. These configurations may vary from simple to complex, depending on
+the type of services (and the number of services) each device/accessory has. But event in its simplest form, like a simple
+`switch` device with a single primary `switch` service that only has one `on` characteristic, when you have many of such
+services defined, the configuration may look quite cumbersome. More over, it really depends on the setup you have at home, 
+but it is often the case that the same physical device types are used across the house, for example:
+
+- If you have KNX installed in the house, the setups for all your switches in the house is most likely similar and the
+  only thing that changes between them is the KNX group addresses that are associated with them.
+
+- If you have a Hue bridge at home, and you're using Hue motion sensor, it's very likely you have a bunch of those and
+  zigbee2mqtt will expose their state in similar ways (just under a different base topic)
+
+There can be many examples as the two above, but the point is, with the normal device configuration as we've seen, you'll 
+find yourself copy-pasting configurations all over the place. This is where **Templates** enter the picture.
+
+But first, lets say we have 2 Hue motion sensors in the house and we configure them without templates, here's how it might
+look like:
+
+```json
+{
+  //...
+  "devices": [
+    {
+      "id": "garage-motion",
+      "name": "Garage Motion",
+      "type": "motion-sensor",
+      "topics": {
+        "motionDetected": {
+          "get": "Garage Motion$occupancy",
+          "converter": "boolean"
+        }
+      },
+      "services": [
+        {
+          "name": "Battery Level",
+          "type": "battery",
+          "topics": {
+            "batteryLevel": {
+              "get": "Garage Motion$battery"
+            }
+          }
+        },
+        {
+          "name": "Light Sensor",
+          "type": "light-sensor",
+          "topics": {
+            "ambientLevel": {
+              "get": "Garage Motion$illuminance_lux"
+            }
+          }
+        },
+        {
+          "name": "Temperature Sensor",
+          "type": "temperature-sensor",
+          "topics": {
+            "currentTemperature": {
+              "get": "Garage Motion$temperature"
+            }
+          }
+        }
+      ]
+    },
+    {
+      "id": "stairs-motion",
+      "name": "Stairs Motion",
+      "type": "motion-sensor",
+      "topics": {
+        "motionDetected": {
+          "get": "Stairs Motion$occupancy",
+          "converter": "boolean"
+        }
+      },
+      "services": [
+        {
+          "name": "Battery Level",
+          "type": "battery",
+          "topics": {
+            "batteryLevel": {
+              "get": "Stairs Motion$battery"
+            }
+          }
+        },
+        {
+          "name": "Light Sensor",
+          "type": "light-sensor",
+          "topics": {
+            "ambientLevel": {
+              "get": "Stairs Motion$illuminance_lux"
+            }
+          }
+        },
+        {
+          "name": "Temperature Sensor",
+          "type": "temperature-sensor",
+          "topics": {
+            "currentTemperature": {
+              "get": "Stairs Motion$temperature"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+Ouch... as you can see, just defining 2 motion sensors already looks quite cumbersome and complex. And even more annoying, 
+the two configurations are almost identical - the only thing that differs them is the base topic of the device (which makes
+sense, because these are both Hue motion sensors, supporting the same characteristics and controlled by the same system (zigbee2mqtt)).
+
+Surely we can do better - We can define a template for a hue motion sensor and have both devices point to it:
+
+```json
+{
+  "templates": [
+    {
+      "id": "hue-motion-sensor",
+      "type": "motion-sensor",
+      "topics": {
+        "motionDetected": {
+          "get": "{{baseTopic}}$occupancy",
+          "converter": "boolean"
+        }
+      },
+      "services": [
+        {
+          "name": "Battery Level",
+          "type": "battery",
+          "topics": {
+            "batteryLevel": {
+              "get": "{{baseTopic}}$battery"
+            }
+          }
+        },
+        {
+          "name": "Light Sensor",
+          "type": "light-sensor",
+          "topics": {
+            "ambientLevel": {
+              "get": "Stairs {{baseTopic}}$illuminance_lux"
+            }
+          }
+        },
+        {
+          "name": "Temperature Sensor",
+          "type": "temperature-sensor",
+          "topics": {
+            "currentTemperature": {
+              "get": "{{baseTopic}}$temperature"
+            }
+          }
+        }
+      ]
+    }
+  ],
+  "devices": [
+    {
+      "id": "garage-motion",
+      "name": "Garage Motion",
+      "baseTopic": "Garage Motion",
+      "template": "hue-motion-sensor"
+    },
+    {
+      "id": "stairs-motion",
+      "name": "Stairs Motion",
+      "baseTopic": "Stairs Motion",
+      "template": "hue-motion-sensor"
+    }
+  ]
+}
+```
+The template above defines the typical structure of a Hue motion sensor device and it uses parameter placeholders to
+make it reusable. Then, when defining the devices, all that is required is to point to the template and provide a value
+to the template parameters (`baseTopic` in this case). Now imagine you have 10 such motion sensors in the house - this
+makes their configuration a breeze. More over, it's great for maintenance - if you need to change how you handle a motion
+sensor, you just need to change the template and all motion sensor devices will automatically be updated.
+
+It's also possible to use parameter placeholder in normal device configuration. For example
+
+```json
+{
+  "devices": [
+    {
+      "id": "garage-motion",
+      "name": "Garage Motion",
+      "type": "motion-sensor",
+      "topic": "Garage Motion",
+      "topics": {
+        "motionDetected": {
+          "get": "{{topic}}$occupancy",
+          "converter": "boolean"
+        }
+      },
+      "services": [
+        {
+          "name": "Battery Level",
+          "type": "battery",
+          "topics": {
+            "batteryLevel": {
+              "get": "{{topic}}$battery"
+            }
+          }
+        },
+        {
+          "name": "Light Sensor",
+          "type": "light-sensor",
+          "topics": {
+            "ambientLevel": {
+              "get": "{{topic}}$illuminance_lux"
+            }
+          }
+        },
+        {
+          "name": "Temperature Sensor",
+          "type": "temperature-sensor",
+          "topics": {
+            "currentTemperature": {
+              "get": "{{topic}}$temperature"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+In the above example, we only need to define the `topic` of the accessory once in a parameter and 
+have all topics reference it. If the topic changes, we only need to change one place. Though again, the use
+of templates has the potential of a greater added value overall.
+
+## Converters Reference
+
+### Booleans
+- `boolean` - Converts "true" and "false" string values or `true` and `false` JSON values.
+- `one-zero` - Converts "1" and "0" to `true` and `false` (also `1` and `0` numeric JSON values)
+- `{ "on": "<on_value>", "off": "<off_value>" }` - Indicates the values that represent `true` (on) and `false` (off)
+
+### Percentages (%)
+- `homekit` - Homekit expects numbers between 0 - 100.
+- `decimal` - Converts numbers between 0 - 1 (`0.34` indicates `34%`)
+- `{ "min": <number>, "max": <number> }` - Translate any number between these bounds to a percentage value. Any number above the max will be converted to `max` and any number below the min will be converted to `min`.
+
+### Hue
+- `homekit` - Homekit expects numbers representing arc degrees (0 - 360)
+- `percent-integer` - Converts a percentage value between 0 - 100
+- `percent-decimal` - Converts a percentage value between 0 - 1
+
+### Color Temperatures
+- `homekit` - Homekit expects numbers in mirek units ($mirek = \frac{1,000,000}{Kelvin}$)
+- `mirek` - same as `homekit`
+- `kelvin` - Converts numbers in kelvin units
+
+### Illuminance
+- `homekit` - Homekit expects numbers in lux units
+- `lux` - same as `homekit`
+- `log-scale-lux` - Expects number in log scale values as used by Hue ($lux =(\frac{logscale-1}{10000})^{10}$)
+
+### Temperatures
+- `homekit` - Homekit expects temperature to be in Celsius
+- `celsius` - same as `homekit`
+- `fahrenheit` - Expects temperatures to be in Fahrenheit units 
+
+
+## Characteristics Reference
+- [Common Characteristics](#common-characteristics)
+- [Common Sensor Characteristics](#common-sensor-characteristics)
+- [active](#code-stylecolor-greenactivecode)
+- [airQuality](#code-stylecolor-greenairQualitycode)
+- [ambientLightLevel](#code-stylecolor-greenambientLightLevelcode)
+- [batteryLevel](#code-stylecolor-greenbatteryLevelcode)
+- [brightness](#code-stylecolor-greenbrightnesscode)
+- [co2Detected](#code-stylecolor-greenco2Detectedcode)
+- [co2Level](#code-stylecolor-greenco2Levelcode)
+- [co2PeakLevel](#code-stylecolor-greenco2PeakLevelcode)
+- [coDetected](#code-stylecolor-greencoDetectedcode)
+- [coLevel](#code-stylecolor-greencoLevelcode)
+- [coPeakLevel](#code-stylecolor-greencoPeakLevelcode)
+- [chargingState](#code-stylecolor-greenchargingStatecode)
+- [colorTemperature](#code-stylecolor-greencolorTemperaturecode)
+- [contactSensorState](#code-stylecolor-greencontactSensorStatecode)
+- [coolingThreshold](#code-stylecolor-greencoolingThresholdcode)
+- [currentFanState](#code-stylecolor-greencurrentFanStatecode)
+- [currentHeatingCoolingState](#code-stylecolor-greencurrentHeatingCoolingStatecode)
+- [currentHorizontalTiltAngle](#code-stylecolor-greencurrentHorizontalTiltAnglecode)
+- [currentHumidifierDehumidifierState](#code-stylecolor-greencurrentHumidifierDehumidifierStatecode)
+- [currentPosition](#code-stylecolor-greencurrentPositioncode)
+- [currentRelativeHumidity](#code-stylecolor-greencurrentRelativeHumiditycode)
+- [currentTemperature](#code-stylecolor-greencurrentTemperaturecode)
+- [currentVerticalTiltAngle](#code-stylecolor-greencurrentVerticalTiltAnglecode)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode)
+- [heatingThreshold](#code-stylecolor-greenheatingThresholdcode)
+- [holdPosition](#code-stylecolor-greenholdPositioncode)
+- [hue](#code-stylecolor-greenhuecode)
+- [leakDetected](#code-stylecolor-greenleakDetectedcode)
+- [lockCurrentState](#code-stylecolor-greenlockCurrentStatecode)
+- [lockPhysicalControls](#code-stylecolor-greenlockPhysicalControlscode)
+- [lockTargetState](#code-stylecolor-greenlockTargetStatecode)
+- [motionDetected](#code-stylecolor-greenmotionDetectedcode)
+- [mute](#code-stylecolor-greenmutecode)
+- [no2Density](#code-stylecolor-greenno2Densitycode)
+- [obstructionDetected](#code-stylecolor-greenobstructionDetectedcode)
+- [occupancyDetected](#code-stylecolor-greenoccupancyDetectedcode)
+- [on](#code-stylecolor-greenoncode)
+- [outletInUse](#code-stylecolor-greenoutletInUsecode)
+- [ozoneDensity](#code-stylecolor-greenozoneDensitycode)
+- [pm10Density](#code-stylecolor-greenpm10Densitycode)
+- [pm25Density](#code-stylecolor-greenpm25Densitycode)
+- [positionState](#code-stylecolor-greenpositionStatecode)
+- [pressEvent](#code-stylecolor-greenpressEventcode)
+- [dehumidifierThreshold](#code-stylecolor-greendehumidifierThresholdcode)
+- [humidifierThreshold](#code-stylecolor-greenhumidifierThresholdcode)
+- [rotationDirection](#code-stylecolor-greenrotationDirectioncode)
+- [rotationSpeed](#code-stylecolor-greenrotationSpeedcode)
+- [saturation](#code-stylecolor-greensaturationcode)
+- [alarmType](#code-stylecolor-greenalarmTypecode)
+- [securitySystemCurrentState](#code-stylecolor-greensecuritySystemCurrentStatecode)
+- [securitySystemTargetState](#code-stylecolor-greensecuritySystemTargetStatecode)
+- [smokeDetected](#code-stylecolor-greensmokeDetectedcode)
+- [so2Density](#code-stylecolor-greenso2Densitycode)
+- [statusFault](#code-stylecolor-greenstatusFaultcode)
+- [statusLowBattery](#code-stylecolor-greenstatusLowBatterycode)
+- [statusTampered](#code-stylecolor-greenstatusTamperedcode)
+- [swingMode](#code-stylecolor-greenswingModecode)
+- [targetFanState](#code-stylecolor-greentargetFanStatecode)
+- [targetHeatingCoolingState](#code-stylecolor-greentargetHeatingCoolingStatecode)
+- [targetHorizontalTiltAngle](#code-stylecolor-greentargetHorizontalTiltAnglecode)
+- [targetHumidifierDehumidifierState](#code-stylecolor-greentargetHumidifierDehumidifierStatecode)
+- [targetPosition](#code-stylecolor-greentargetPositioncode)
+- [targetRelativeHumidity](#code-stylecolor-greentargetRelativeHumiditycode)
+- [targetTemperature](#code-stylecolor-greentargetTemperaturecode)
+- [targetVerticalTiltAngle](#code-stylecolor-greentargetVerticalTiltAnglecode)
+- [temperatureDisplayUnits](#code-stylecolor-greentemperatureDisplayUnitscode)
+- [vocDensity](#code-stylecolor-greenvocDensitycode)
+- [volume](#code-stylecolor-greenvolumecode)
+- [waterLevel](#code-stylecolor-greenwaterLevelcode)
+
+
+### Common Characteristics
+
+The following characteristic are optional and may be configured on any service type
+- [statusFault](#statusFault)
+- [faultMessage](#code-stylecolor-greenfaultmessagecode)
+
+### Common Sensor Characteristics
+
+In addition to the above common characteristics, sensor devices may also support the following ones:
+- [statusLowBattery](#statusLowBatter)
+- [statusTampered](#statusTampered)
+
+### <code style="color: green">active</code>
+
+Indicates whether the service is currently active. By default, will look for values `0` or `1` where `1` indicates
+`on`/`true` and `0` indicates `off`/`false`.
+Values can be converted using the [Booleans](#booleans) converter.
+
+#### Services
+- [speaker](#speaker)
+- [humidifier-dehumidifier](#humidifier-dehumidifier)
+
+#### Configuration
+```json
+{
+  "topics": {
+    "active": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "boolean" | { "min": <number>, "max": <number> }
+    }
+  }
+}
+```
+
+### <code style="color: green">airQuality</code>
+
+Describes the subject assessment of air quality. By default, will look for the following values:
+- `0` - indicates "unknown"
+- `1` - indicates "excellent"
+- `2` - indicates "good"
+- `3` - indicates "fair"
+- `4` - indicates "inferior"
+- `5` - indicates "poor"
+
+You can customize the read/published values using a value map converter (as shown below)
+
+#### Services
+- [air-quality-sensor](#air-quality-sensor)
+
+#### Configuration
+```json
+{
+  "topics": {
+    "airQuality": {
+      "get": "<read_topic>",
+      "converter"?: {
+        "unknown"?:   "<value representing 'unknown'>",
+        "excellent"?: "<value representing 'excellent'>",
+        "good"?:      "<value representing 'good'>",
+        "fair"?:      "<value representing 'fair'>",
+        "inferior"?:  "<value representing 'inferior'>",
+        "poor"?:      "<value representing 'poor'>"
+      }
+    }
+  }
+}
+```
+
+
+### <code style="color: green">ambientLightLevel</code>
+
+Indicates the current light level in `lux` numeric units.
+Values can be converted using the [Illuminance](#illuminance) converter.
+
+#### Services
+- [light-sensor](#light-sensor)
+
+#### Configuration
+```json
+{
+  "topics": {
+    "ambientLightLevel": {
+      "get": "<read_topic>",
+      "converter"?: log-scale-lux"
+    }
+  }
+}
+```
+
+
+### <code style="color: green">batteryLevel</code>
+
+Describes the current level of the battery in a numeric value representing a percentage.
+Values can be converted using the [Percentages](#percentages-) converter.
+
+#### Services
+- [battery](#battery)
+
+#### Configuration
+```json
+{
+  "topics": {
+    "batteryLevel": {
+      "get": "<read_topic>",
+      "converter"?: "decimal" | { "min": <number>, "max": <number> }
+    }
+  }
+}
+```
+
+### <code style="color: green">brightness</code>
+
+Describes a level of brightness in a numeric value representing a percentage.
+Values can be converted using the [Percentages](#percentages) converter.
+
+#### Services
+- [lightbulb](#lightbulb)
+- [doorbell](#doorbell)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "brightness": {
+      "get": "<read_topic>",
+      "get": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
+    }
+  }
+}
+```
+
+### <code style="color: green">co2Detected</code>
+
+Indicates if a sensor detects abnormal levels of Carbon Dioxide. By default, will look for `0` (indicating "not detected")
+or `1` (indicating "detected").
+Values can be converted using the [Booleans](#booleans) converter.
+
+#### Services
+- [co2-sensor](#co2-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "co2Detected": {
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'detected' value", "off": "'not-detected' value" }
+    }
+  }
+}
+```
+
+
+### <code style="color: green">co2Level</code>
+
+Indicates the detected level of Carbon Dioxide - a numeric value indicating parts per million (ppm).
+
+#### Services
+- [co2-sensor](#co2-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "co2Level": {
+      "get": "<read_topic>"
+    }
+  }
+}
+```
+
+### <code style="color: green">co2PeakLevel</code>
+
+Indicates the highest detected level of Carbon Dioxide detected by a sensor - a numeric value indicating parts per
+million (ppm).
+
+#### Services
+- [co2-sensor](#co2-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "co2PeakLevel": {
+      "get": "<read_topic>"
+    }
+  }
+}
+```
+
+
+### <code style="color: green">coDetected</code>
+
+Indicates if a sensor detects abnormal levels of Carbon Monoxide. By default, will look for `0` (indicating "not detected")
+or `1` (indicating "detected").
+Values can be converted using the [Booleans](#booleans) converter.
+
+#### Services
+- [co-sensor](#co-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "coDetected": {
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'detected' value", "off": "'not-detected' value" }
+    }
+  }
+}
+```
+
+### <code style="color: green">coLevel</code>
+
+Indicates the detected level of Carbon Monoxide - a numeric value indicating parts per million (ppm).
+
+#### Services
+- [co-sensor](#co-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "coLevel": {
+      "get": "<read_topic>"
+    }
+  }
+}
+```
+
+### <code style="color: green">coPeakLevel</code>
+
+Indicates the highest detected level of Carbon Monoxide detected by a sensor - a numeric value indicating parts per
+million (ppm).
+
+#### Services
+- [co-sensor](#co-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "coPeakLevel": {
+      "get": "<read_topic>"
+    }
+  }
+}
+```
+
+### <code style="color: green">chargingState</code>
+
+Indicates whether the battery-ran device is currently charging or not.
+Values can be converted using the [Booleans](#booleans) converter.
+
+#### Services
+- [battery](#battery)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "chargingState": {
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'charging' value", "off": "'not-charging' value" }
+    }
+  }
+}
+```
+
+
+### <code style="color: green">colorTemperature</code>
+
+Describes color temperature - a numeric value in the mirek scale
+Values can be converted using the [Color Temperatures](#color-temperatures) converter.
+
+#### Services
+- [lightbulb](#lightbulb)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "colorTemperature": {
+      "get": "<read_topic>",
+      "set": "<read_topic>",
+      "converter"?: "kelvin"
+    }
+  }
+}
+```
+
+### <code style="color: green">contactSensorState</code>
+
+Describes the state of a contact sensor. By default, will look for `0` (indicating "no contact") and `1` (indicating "contact")
+Values can be converted using the [Booleans](#booleans) converter.
+
+#### Services
+- [contact-sensor](#contact-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "contactSensorState": {
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'contact' value", "off": "'no-contact' value" }
+    }
+  }
+}
+```
+
+
+### <code style="color: green">coolingThreshold</code>
+
+Describes the cooling threshold in Celsius for accessories that support heating and cooling.
+If the thermostat operates in an "auto" mode and the current temperature goes above this
+threshold the thermostat will start cooling.
+Values can be converted using the [Temperatures](#temperatures) converter.
+
+#### Services
+- [thermostat](#thermostat)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "coolingThreshold": {
+      "get": "<read_topic>",
+      "set": "<read_topic>",
+      "converter"?: "fahrenheit"
+    }
+  }
+}
+```
+
+### <code style="color: green">currentFanState</code>
+
+> [!NOTE]
+> When used as part of a `fan` service, this can be shorten to `currentState`
+
+Describes the current state of the fan. Expects the following numeric values:
+- `0` - indicating "inactive" state
+- `1` - indicating "idle" state
+- `2` - indicating "blowing air" state
+
+Other values can be converted using a value-map converter (as shown below).
+
+#### Services
+- [fan](#fan)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "currentFanState": {
+      "get": "<read_topic>",
+      "converter"?: {
+        "inactive"?:    "'inactive' state value",
+        "idle"?:        "'idle' state value",
+        "blowingAir"?:  "'blowing air' state value"
+      }
+    }
+  }
+}
+```
+
+### <code style="color: green">currentHeatingCoolingState</code>
+
+> [!NOTE]
+> When used as part of a `thermostat` service, this can be shorten to `currentState`
+
+Describes the current mode of a thermostat. Expects the following numeric values:
+- `0` - indicating "off" state
+- `1` - indicating "heat" state
+- `2` - indicating "cool" state
+
+Other values can be converted using a value-map converter (as shown below).
+
+#### Services
+- [thermostat](#thermostat)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "currentHeatingCoolingState": {
+      "get": "<read_topic>",
+      "converter"?: {
+          "off"?:   "'off' state value",
+          "heat"?:  "'heat' state value",
+          "cool"?:  "'cool' state value"
+        }
+    }
+  }
+}
+```
+
+### <code style="color: green">currentHorizontalTiltAngle</code>
+
+Describes the current angle of the horizontal slats of the device. A numeric value in arc degrees, ranging
+between `-90` - `90`.
+
+#### Services
+- [window-covering](#window-convering)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "currentHorizontalTiltAngle": {
+      "get": "<read_topic>"
+    }
+  }
+}
+```
+
+### <code style="color: green">currentHumidifierDehumidifierState</code>
+
+> [!NOTE]
+> When used as part of a `humidifier-dehumidifier` service, this can be shorten to `currentState`
+
+Describes the current state of a humidifier or/and a dehumidifier. Expecting the following numeric values:
+- `0` - indicating `inactive` state
+- `1` - indicating `idle` state
+- `2` - indicating `humidifying` state
+- `3` - indicating `dehumidifying` state
+
+Other values can be converted using a value-map converter (as shown below).
+
+#### Services
+- [humidifier-dehumidifier](#humidifier-dehumidifier)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "currentHumidifierDehumidifierState": {
+      "get": "<read_topic>",
+      "converter"?: {
+        "inactive"?:       "'inactive' state value",
+        "idle"?:           "'idle' state value",
+        "humidifying"?:    "'humidifying' state value",
+        "dehumidifying"?:  "'dehumidifying' state value"
+      }
+    }
+  }
+}
+```
+                                              
+
+### <code style="color: green">currentPosition</code>
+
+Describes the current position of accessories as a percentage value. `0` typically indicates "fully closed" while `100` 
+indicates "fully open". Some services (e.g. `window-covering` let you reverse this).
+Other values can be converted using the [Percentages](#percentages-) converter.
+
+#### Services
+- [window](#window)
+- [door](#door)
+- [window-covering](#window-covering)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "currentPosition": {
+      "get": "<read_topic>",
+      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
+    }
+  }
+}
+```
+
+
+### <code style="color: green">currentRelativeHumidity</code>
+
+Describes the current relative humidity of the device's environment. By default, expecting a numeric value
+between `0` and `100` representing a percentage.
+Other values can be converted using the [Percentages](#percentages-) converter.
+
+#### Services
+- [humidity-sensor](#humidity-sensor)
+- [humidifier-dehumidifier](#humidifier-dehumidifier)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "currentRelativeHumidity": {
+      "get": "<read_topic>",
+      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
+    }
+  }
+}
+```
+
+
+### <code style="color: green">currentTemperature</code>
+
+Describes the current temperature of the environment in Celsius
+Other values can be converted using the [Temperatures](#temperatures) converter.
+
+By default, values range between `10.0` and `38.0` with a minimum step of `0.1`. This can be adjusted in 
+the configuration (as shown below).
+
+#### Services
+- [thermostat](#thermostat)
+- [temperature-sensor](#temperature-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "currentTemperature": {
+      "get": "<read_topic>",
+      "converter"?: "fahrenheit",
+      "minValue"?: <number>, // in celsius (regardless of the converter), defaut: 10.0 
+      "maxValue"?: <number>, // in celsius (regardless of the converter), defaut: 38.0
+      "minStep"?: <number>   // in celsius (regardless of the converter), defaut: 0.1
+    }
+  }
+}
+```
+
+### <code style="color: green">currentVerticalTiltAngle</code>
+
+Describes the current angle of the vertical slats of the device. Expecting a numeric value representing arc degrees 
+between `-90` and `90`.
+
+#### Services
+- [window-covering](#window-convering)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "currentVerticalTiltAngle": {
+      "get": "<read_topic>"
+    }
+  }
+}
+```
+
+### <code style="color: green">faultMessage</code>
+
+A non-standard homekit characteristic indicating a fault message in case the device if faulty.
+
+> [!NOTE]
+> As a non-standard characteristic, this will no show up in the Home app, though other apps that support this
+> custom characteristic will show it (e.g. [Eve](https://www.evehome.com/en/eve-app)) 
+
+#### Services
+
+This characteristic is optional and can be configured on all service types.
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "faultMessage": {
+      "get": "<read_topic>"
+    }
+  }
+}
+```
+
+### <code style="color: green">heatingThreshold</code>
+
+Describes the heating threshold in Celsius for accessories that support heating and cooling.
+If the thermostat operates in an "auto" mode and the current temperature goes below this
+threshold the thermostat will start heating.
+Values can be converted using the [Temperatures](#temperatures) converter.
+
+#### Services
+- [thermostat](#thermostat)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "heatingThreshold": {
+      "get": "<read_topic>",
+      "set": "<read_topic>",
+      "converter"?: "fahrenheit"
+    }
+  }
+}
+```
+
+
+### <code style="color: green">holdPosition</code>
+
+Used to signal a device that it should stop it current operations in its current position (typically used for
+window-covering). This characteristic doesn't hold a value. To signal a "hold" it sets a value in the configured
+`set` topic. By default, it sets the value to `1`, though this can be changed in the configuration (as shown below). 
+
+#### Services
+- [window-covering](#window-covering)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "holdPosition": {
+      "set": "<write_topic>",
+      "value"?: "any value that the device will understand as a 'hold' command"
+    }
+  }
+}
+```
+
+### <code style="color: green">hue</code>
+
+Describes hue or color. A hue is typically measured as an arc degree in a [Hue Wheel](). Expects, a numeric value
+between `0` and `360`.
+Percentage values (e.g. 34% of 360) are also supported and be configured using the [Hue Converter](#hue)
+
+#### Services
+- [lightbulb](#lightbulb)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "hue": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "percent-integer" | "percent-decimal"
+    }
+  }
+}
+```
+
+### <code style="color: green">leakDetected</code>
+
+Indicates if a sensor detected a leak (e.g. water leak, gas leak). By default, will look for `0` (indicating "not detected")
+or `1` (indicating "detected").
+Values can be converted using the [Booleans](#booleans) converter.
+
+#### Services
+- [leak-sensor](#leak-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "leakDetected": {
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'detected'>", "off": "value indicating 'not-detected'" }
+    }
+  }
+}
+```
+
+
+### <code style="color: green">lockCurrentState</code>
+
+> [!NOTE]
+> When used as part of a `lock` service, this can be shorten to `currentState`
+
+Describes the current state of a lock. Expecting the following numeric values:
+- `0` - indicating "unsecured" state
+- `1` - indicating "secured" state
+- `2` - indicating "jammed" state
+- `3` - indicating "unknown" state
+
+Other values can be converted using a value-map converter (as shown below).
+
+#### Services
+- [lock](#lock)
+- [garage-door](#garage-door)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "lockCurrentState": {
+      "get": "<read_topic>",
+      "converter"?: {
+        "unsecured"?:   "'unsecured' state value",
+        "secured"?:     "'secured' state value",
+        "jammed"?:      "'jammed' state value",
+        "unknown"?:     "'unknown' state value"
+      }
+    }
+  }
+}
+```
+
+
+### <code style="color: green">lockPhysicalControls</code>
+
+Describes a way to lock a set of physical controls on an accessory (eg. child lock). By default, will look for `0`
+(indicating "not detected") or `1` (indicating "detected").
+Values can be converted using the [Booleans](#booleans) converter.
+
+#### Services
+- [fan](#fan)
+- [humidifier-dehumidifier](#humidifier-dehumidifier)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "lockPhysicalControls": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "boolean" | { "": "<value indicating 'locked'>", "off": "value indicating 'not-locked'" }
+    }
+  }
+}
+```
+
+### <code style="color: green">lockTargetState</code>
+
+> [!NOTE]
+> When used as part of a [`lock-mechansim`](#lock) service, this can be shorten to `targetState`
+
+Describes the current state of a lock. Expecting the following numeric values:
+- `0` - indicating "unsecured" state
+- `1` - indicating "secured" state
+
+Other values can be converted using a converter (as shown below).
+
+#### Services
+- [lock](#lock)
+- [garage-door](#garage-door)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "lockTargetState": {
+      "get": "<read_topic>",
+      "get": "<write_topic>",
+      "converter"?: "boolean" | { "secured": "<value indicating 'secured'>", "unsecured": "value indicating 'unsecured'" } // a boolean 'true' indicates 'secured'
+    }
+  }
+}
+```
+
+### <code style="color: green">motionDetected</code>
+
+Indicates if a sensor detected motion. By default, will look for `true` (indicating "detected")
+or `false` (indicating "not-detected").
+Values can be converted using the [Booleans](#booleans) converter.
+
+#### Services
+- [motion-sensor](#motion-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "motionDetected": {
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'detected'>", "off": "value indicating 'not-detected'" }
+    }
+  }
+}
+```
+
+### <code style="color: green">mute</code>
+
+Allows the control of audio input or output accessory. By default, will look for `true` (indicating "muted")
+or `false` (indicating "not-muted").
+Values can be converted using the [Booleans](#booleans) converter.
+
+#### Services
+- [speaker](#speaker)
+- [doorbell](#doorbell)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "motionDetected": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'muted'>", "off": "value indicating 'not-muted'" }
+    }
+  }
+}
+```
+
+### <code style="color: green">no2Density</code>
+
+Indicates the current Nitrogen Dioxide density. A numeric value in $micrograms/m^3$ units. 
+
+#### Services
+- [air-quality-sensor](#air-quality-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "no2Density": {
+      "get": "<read_topic>"
+    }
+  }
+}
+```
+
+
+### <code style="color: green">obstructionDetected</code>
+
+Describes the current state of an obstruction sensor. By default, will look for `true` (indicating "detected")
+or `false` (indicating "not detected").
+Values can be converted using the [Booleans](#booleans) converter.
+
+#### Services
+- [door](#door)
+- [window](#window)
+- [garage-door](#garage-door)
+- [window-covering](#window-covering)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "obstructionDetected": {
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'detected'>", "off": "value indicating 'not-detected'" }
+    }
+  }
+}
+```
+
+
+### <code style="color: green">occupancyDetected</code>
+
+Indicates if occupancy was detected (e.g. a person present). By default, will look for `1` (indicating "detected")
+or `0` (indicating "not detected").
+Values can be converted using the [Booleans](#booleans) converter.
+
+#### Services
+- [occupancy-sensor](#occupancy-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "occupancyDetected": {
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'detected'>", "off": "value indicating 'not-detected'" }
+    }
+  }
+}
+```
+
+
+### <code style="color: green">on</code>
+
+Represents the states for “on” and “off”. By default, will look for `true` (indicating "on")
+or `false` (indicating "off").
+Values can be converted using the [Booleans](#booleans) converter.
+
+#### Services
+- [lightbulb](#lightbulb)
+- [outlet](#outlet)
+- [switch](#switch)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "on": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'on'>", "off": "value indicating 'off'" }
+    }
+  }
+}
+```
+
+
+
+### <code style="color: green">outletInUse</code>
+
+describes if the power outlet has an appliance physically plugged in. By default, will look for `true` (indicating "in-use")
+or `false` (indicating "not-in-use").
+Values can be converted using the [Booleans](#booleans) converter.
+
+#### Services
+- [outlet](#outlet)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "outletInUse": {
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'in-use'>", "off": "value indicating 'not-in-use'" }
+    }
+  }
+}
+```
+
+### <code style="color: green">ozoneDensity</code>
+
+Indicates the current ozone density. A numeric value in $micrograms/m^3$ units.
+
+#### Services
+- [air-quality-sensor](#air-quality-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "ozoneDensity": {
+      "get": "<read_topic>"
+    }
+  }
+}
+```
+
+
+### <code style="color: green">pm10Density</code>
+
+Indicates the current PM10 micrometer particulate density. A numeric value in $micrograms/m^3$ units.
+
+#### Services
+- [air-quality-sensor](#air-quality-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "pm10Density": {
+      "get": "<read_topic>"
+    }
+  }
+}
+```
+
+### <code style="color: green">pm25Density</code>
+
+Indicates the current PM2.5 micrometer particulate density. A numeric value in $micrograms/m^3$ units.
+
+#### Services
+- [air-quality-sensor](#air-quality-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "pm25Density": {
+      "get": "<read_topic>"
+    }
+  }
+}
+```
+
+### <code style="color: green">positionState</code>
+
+Describes the state of the position of accessories. Expecting the following numeric values:
+- `0` - indicating "closing" state
+- `1` - indicating "opening" state
+- `2` - indicating "stopped" state
+
+Other values can be converted using a value-map converter (as shown below).
+
+#### Services
+- [door](#door)
+- [window](#window)
+- [window-covering](#window-covering)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "lockCurrentState": {
+      "get": "<read_topic>",
+      "converter"?: {
+        "closing"?: "'closing' state value",
+        "opening"?: "'opening' state value",
+        "stopped"?: "'stopped' state value"
+      }
+    }
+  }
+}
+```
+
+
+### <code style="color: green">pressEvent</code>
+
+Describes a press event generated by a button. This characteristic doesn't hold a value nor publishes a 
+value to an MQTT topic. All it does is monitor an MQTT topic and based on the value received it triggers
+the appropriate event. By default, it expects the following numeric values:
+- `0` - indicating "single-press" event
+- `1` - indicating "double-press" event
+- `2` - indicating "long-press" event
+
+Other values can be converted using a value-map converter (as shown below).
+
+#### Services
+- [button](#button)
+- [doorbell](#doorbell)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "pressEvent": {
+      "get": "<read_topic>",
+      "converter"?: {
+        "single"?:  "value indicating a 'single' press event",
+        "double"?:  "value indicating a 'double' press event",
+        "long"?:    "value indicating a 'long' press event"
+      }
+    }
+  }
+}
+```
+
+### <code style="color: green">dehumidifierThreshold</code>
+
+Describes the relative humidity dehumidifier threshold, representing the maximum relative humidity that must be reached
+before a dehumidifier is turned on. Expects a numeric value indicating the humidity in percentage between 
+`0` and `100`.
+
+Other values can be converted using a [Percentages](#percentages-) converter (as shown below).
+
+#### Services
+- [humidifier-dehumidifier](#humidifier-dehumidifier)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "dehumidifierThreshold": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>, "max":  <number> }
+    }
+  }
+}
+```
+
+### <code style="color: green">humidifierThreshold</code>
+
+Describes the relative humidity humidifier threshold, representing the minimum relative humidity that must be reached
+before a humidifier is turned on. Expects a numeric value indicating the humidity in percentage between
+`0` and `100`.
+
+Other values can be converted using a [Percentages](#percentages-) converter (as shown below).
+
+#### Services
+- [humidifier-dehumidifier](#humidifier-dehumidifier)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "humidifierThreshold": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>, "max":  <number> }
+    }
+  }
+}
+```
+
+
+### <code style="color: green">rotationDirection</code>
+
+describes the direction of rotation of a fan. Expects the following numeric values:
+- `0` - indicates `clockwise` direction
+- `1` - indicates `counter-clockwise` direction
+
+Other values can be converted using a value-map converter (as shown below).
+
+#### Services
+- [fan](#fan)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "rotationDirection": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: { "clockwise": "value representing 'clockwise'", "counter-clockwise":  "value representing 'counter-clockwise'" }
+    }
+  }
+}
+```
+
+
+### <code style="color: green">rotationSpeed</code>
+
+Describes the rotation speed of a fan. A numeric value representing the speed as a percentage between 
+`0` and `100`, where `0` indicates no speed and `100` indicates maximum speed.
+
+Other values are supported using the following converters:
+- `decimal` - expects a values representing the speed as a percentage value between `0` and `1` (e.g. `0.36` indicates `36%`)
+- `{ "min": <number>, "max": <number> }` - expects a value between the `min` and `max` value, from which it deduce the speed percentage.
+- `<number>` - A converter holding a number indicates the number of supported speed levels, expecting a number between `0` and the configured number.
+  For example, `converter: 5` indicates there are 6 speed levels to look for - `0`, `1`, `2`, `3`, `4`, `5`.
+- `string[]` - A converter holding an array of values, each representing a level. The speed level of each value is the index
+               of that value in the array - the first value will always represent "no speed". For example, `converter: [ "off", "low", "medium", "high" ]` will expect all to
+               receive any of these values. If, for example, it receives a `low` value, then it knows this value represents
+               `33%` speed level, as it's the first out of 3 possible speed levels (excl. the first one which is "no-speed").
+
+#### Services
+- [fan](#fan)
+- [humidifier-dehumidifier](#humidifier-dehumidifier)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "rotationDirection": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min":  <number>, "max":  <number> } | <number> | string[]
+    }
+  }
+}
+```
+
+
+### <code style="color: green">saturation</code>
+
+Describes color saturation. A numeric value indicating a percentage.
+
+Values can be converted using the [Percentages](#percentages-) converter.
+
+#### Services
+- [lightbulb](#lightbulb)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "saturation": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>, "max": <number> }
+    }
+  }
+}
+```
+
+### <code style="color: green">alarmType</code>
+
+describes the type of alarm triggered by a security system. The only alarm type that is currently supported
+by homekit is an "unknown" type. For this reason, by default, these are the values it expects:
+- `0` - indicating the alarm is cleared
+- any other value - indicating the generic "unknown" type.
+
+It is possible to configure a different values to indicate the `cleared` state (as shown below)
+
+#### Services
+- [security-system](#security-system)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "alarmType": {
+      "get": "<read_topic>",
+      "converter"?: { "cleared":  "value representing a 'cleared` state"}
+    }
+  }
+}
+```
+
+
+### <code style="color: green">securitySystemCurrentState</code>
+
+> [!NOTE]
+> When used as part of a `security-system` service, this can be shorten to `currentState`
+
+Describes the state of a security system. Expecting the following numeric values:
+- `0` - "stay" state
+- `1` - "away" state
+- `2` - "night" state
+- `3` - "disarmed" state
+- `4` - "triggered" state
+
+Other values can be converted using a value-map converter (as shown below).
+
+#### Services
+- [security-system](#security-system)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "securitySystemCurrentState": {
+      "get": "<read_topic>",
+      "converter"?: {
+        "stay"?:      "'stay' state value",
+        "away"?:      "'away' state value",
+        "night"?:     "'night' state value",
+        "disarmed"?:  "'disarmed' state value",
+        "triggered"?: "'triggered' state value",
+      }
+    }
+  }
+}
+```
+
+### <code style="color: green">securitySystemTargetState</code>
+
+> [!NOTE]
+> When used as part of a `security-system` service, this can be shorten to `targetState`
+
+Describes the target state of the security system. Expecting the following numeric values:
+- `0` - "stay" state
+- `1` - "away" state
+- `2` - "night" state
+- `3` - "disarm" state
+
+Other values can be converted using a value-map converter (as shown below).
+
+It is also possible to limit the supported values using the `validValues` settings.
+
+#### Services
+- [security-system](#security-system)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "securitySystemTargetState": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: {
+        "stay"?:      "'stay' state value",
+        "away"?:      "'away' state value",
+        "night"?:     "'night' state value",
+        "disarm"?:    "'disarm' state value",
+      },
+      "validValues"?: string[] // e.g. [ "stay", "away", "disarm" ] to not show the 'night' option.
+    }
+  }
+}
+```
+
+### <code style="color: green">smokeDetected</code>
+
+Indicates if a sensor detects abnormal levels of smoke. By default, will look for `0` (indicating "not detected")
+or `1` (indicating "detected").
+Values can be converted using the [Booleans](#booleans) converter.
+
+#### Services
+- [smoke-sensor](#smoke-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "smokeDetected": {
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'detected'>", "off": "value indicating 'not-detected'" }
+    }
+  }
+}
+```
+
+
+### <code style="color: green">so2Density</code>
+
+Indicates the current Sulphur Dioxide density. A numeric value in $micrograms/m^3$ units.
+
+#### Services
+- [air-quality-sensor](#air-quality-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "so2Density": {
+      "get": "<read_topic>"
+    }
+  }
+}
+```
+
+
+### <code style="color: green">statusFault</code>
+
+Indicates the device is faulty. Expecting a `1` indicating a "general fault" and `0` indicating there's no fault.
+Other values can be converted using the [Booleans](#booleans) converter.
+
+#### Services
+This characteristic is optional on all services. 
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "statusFault": {
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    }
+  }
+}
+```
+
+
+### <code style="color: green">statusLowBattery</code>
+
+Describes an accessory which has been tampered with. By default, will look for `0` indicating battery
+level is not low, and `1` indicating "low-battery" status.
+Other values can be converted using the [Booleans](#booleans) converter.
+
+#### Services
+This characteristic is optional on all sensor services.
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "statusLowBattery": {
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'low' status value", "off":  "'not-low' status value"}
+    }
+  }
+}
+```
+
+
+### <code style="color: green">statusTampered</code>
+
+Indicates if a battery-ran device is running low on battery. By default, will look for `0` indicating battery
+level is not low, and `1` indicating "low-battery" status.
+Other values can be converted using the [Booleans](#booleans) converter.
+
+#### Services
+This characteristic is optional on all sensor services.
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "statusTampered": {
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'tampered' status value", "off":  "'not-tampered' status value"}
+    }
+  }
+}
+```
+
+
+### <code style="color: green">swingMode</code>
+
+Indicates if swing mode is enabled. By default, will look for `0` indicating swing "disabled" mode, and `1`
+indicating swing "enabled" mode.
+Other values can be converted using the [Booleans](#booleans) converter.
+
+#### Services
+- [fan](#fan)
+- [humidifier-dehumidifier](#humidifier-dehumidifier)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "swingMode": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "boolean" | { "on": "'enabled' mode value", "off":  "'disabled' mode value"}
+    }
+  }
+}
+```
+
+
+### <code style="color: green">targetFanState</code>
+
+> [!NOTE]
+> When used as part of a `fan` service, this can be shorten to `targetState`
+
+Describes the target state of the fan. Expecting the following numeric values:
+- `0` - indicates a "manual" state
+- `1` - indicates an "auto" state
+
+Other values can be converted using the value-map converter (as show below).
+
+#### Services
+- [fan](#fan)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "targetFanState": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: { "auto": "'auto' state value", "manual":  "'manual' state value"}
+    }
+  }
+}
+```
+
+### <code style="color: green">targetHeatingCoolingState</code>
+
+> [!NOTE]
+> When used as part of a `thermostat` service, this can be shorten to `targetState`
+
+Describes the target mode of a thermostat. Expects the following numeric values:
+- `0` - indicating "off" state
+- `1` - indicating "heat" state
+- `2` - indicating "cool" state
+- `3` - indicating "auto" state
+
+Other values can be converted using a value-map converter (as shown below).
+
+It is also possible to limit the possible values using the `validValues` setting.
+
+#### Services
+- [thermostat](#thermostat)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "targetHeatingCoolingState": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: {
+        "off"?:   "'off' state value",
+        "heat"?:  "'heat' state value", 
+        "cool"?:  "'cool' state value",
+        "auto"?:  "'auto' state value",
+      },
+      "validValues": string[]  // e.g. [ "off", "auto" ] to only provide the user to stop the operation of the device
+    }
+  }
+}
+```
+
+### <code style="color: green">targetHorizontalTiltAngle</code>
+
+Describes the target angle of the horizontal slats of the device. A numeric value in arc degrees, ranging
+between `-90` - `90`.
+
+#### Services
+- [window-covering](#window-convering)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "targetHorizontalTiltAngle": {
+      "get": "<read_topic>",
+      "set": "<write_topic>"
+    }
+  }
+}
+```
+
+### <code style="color: green">targetHumidifierDehumidifierState</code>
+
+> [!NOTE]
+> When used as part of a `humidifier-dehumidifier` service, this can be shorten to `targetState`
+
+Describes the target state of a humidifier or/and a dehumidifier. Expecting the following numeric values:
+- `0` - indicating `humidifierDehumidifier` state - only applicable to devices that are both humidifiers and dehumidifiers, 
+this indicates that the device should always keep the humidity at bay, by both humidifying when humidity is low and
+dehumidifying when humidity is high (both low and high humidity levels are determined by the 
+[humidifierThreshold](#code-stylecolor-greenhumidifierthresholdcode) and
+[dehumidifierThreshold](#code-stylecolor-greendehumidifierthresholdcode) characteristics.
+ 
+- `1` - indicating `humidifier` state - only applicable to devices that are humidifiers. Indicating that the device should
+humidify if the humidity level is too low (reaches the [humidifierThreshold](#code-stylecolor-greenhumidifierthresholdcode)).
+
+- `2` - indicating `dehumidifier` state - only applicable to devices that are dehumidifiers. Indicating that the device should
+  dehumidify if the humidity level is too hight (reaches the [dehumidifierThreshold](#code-stylecolor-greendehumidifierthresholdcode)).
+
+Other values can be converted using a value-map converter (as shown below).
+
+#### Services
+- [humidifier-dehumidifier](#humidifier-dehumidifier)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "targetHumidifierDehumidifierState": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: {
+        "humidifierDehumidifier"?:  "'humidifierDehumidifier' state value",
+        "humidifier"?:              "'humidifier' state value",
+        "dehumidifier"?:            "'dehumidifier' state value"
+      }
+    }
+  }
+}
+```
+
+### <code style="color: green">targetPosition</code>
+
+Describes the target position of accessories as a percentage value. `0` typically indicates "fully closed" while `100`
+indicates "fully open". Some services (e.g. `window-covering` let you reverse this).
+Other values can be converted using the [Percentages](#percentages-) converter.
+
+#### Services
+- [window](#window)
+- [door](#door)
+- [window-covering](#window-covering)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "targetPosition": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
+    }
+  }
+}
+```
+
+### <code style="color: green">targetRelativeHumidity</code>
+
+Describes the target relative humidity that the device should actively attempt to reach. By default, expecting a numeric
+value between `0` and `100` representing a percentage.
+Other values can be converted using the [Percentages](#percentages-) converter.
+
+#### Services
+- [thermostat](#thermostat)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "targetRelativeHumidity": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
+    }
+  }
+}
+```
+
+### <code style="color: green">targetTemperature</code>
+
+Describes the target temperature of the environment in Celsius.
+Other values can be converted using the [Temperatures](#temperatures) converter.
+
+By default, values range between `10.0` and `38.0` with a minimum step of `0.1`. This can be adjusted in
+the configuration (as shown below).
+
+#### Services
+- [thermostat](#thermostat)
+- [temperature-sensor](#temperature-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "currentTemperature": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "fahrenheit",
+      "minValue"?: <number>, // in celsius (regardless of the converter), defaut: 10.0 
+      "maxValue"?: <number>, // in celsius (regardless of the converter), defaut: 38.0
+      "minStep"?: <number>   // in celsius (regardless of the converter), defaut: 0.1
+    }
+  }
+}
+```
+
+### <code style="color: green">targetVerticalTiltAngle</code>
+
+Describes the target angle of the vertical slats of the device. Expecting a numeric value representing arc degrees
+between `-90` and `90`.
+
+#### Services
+- [window-covering](#window-convering)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "targetVerticalTiltAngle": {
+      "get": "<read_topic>",
+      "set": "<write_topic>"
+    }
+  }
+}
+```
+
+### <code style="color: green">temperatureDisplayUnits</code>
+
+Describes units of temperature used for presentation purposes. Expecting the following numeric values:
+- `0` - indicating `celsius`
+- `1` - indicating `fahrentheit`
+
+Other values can be converted using a value-map converter (as shown below).
+
+#### Services
+- [thermostat](#thermostat)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "temperatureDisplayUnits": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: { "celsius": "value indicating 'celsius'", "fahrenheit": "value indicating 'fahrenheit'" }
+    }
+  }
+}
+```
+
+### <code style="color: green">vocDensity</code>
+
+Indicates the current volatile organic compound density. A numeric value in $micrograms/m^3$ units.
+
+#### Services
+- [air-quality-sensor](#air-quality-sensor)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "vocDensity": {
+      "get": "<read_topic>"
+    }
+  }
+}
+```
+
+
+### <code style="color: green">volume</code>
+
+Enables controlling the input or output volume of an audio device. By default, expecting a numeric value
+between `0` and `100` representing a percentage.
+Other values can be converted using the [Percentages](#percentages-) converter.
+
+#### Services
+- [speaker](#speaker)
+- [doorbell](#doorbell)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "volume": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>, "max": <number> }
+    }
+  }
+}
+```
+
+### <code style="color: green">waterLevel</code>
+
+Indicating the current water level of the device. By default, expecting a numeric value between `0` and `100`
+representing a percentage.
+Other values can be converted using the [Percentages](#percentages-) converter.
+
+#### Services
+- [humidifier-dehumidifier](#humidifier-dehumidifier)
+
+#### Configuration
+
+```json
+{
+  "topics": {
+    "waterLevel": {
+      "get": "<read_topic>",
+      "converter"?: "decimal" | { "min": <number>, "max": <number> }
+    }
+  }
+}
+```
+
+## Services Reference
+- [air-quality-sensor](#air-quality-sensor)
+- [battery](#battery)
+- [button](#button)
+- [co2-sensor](#co2-sensor)
+- [contact-sensor](#contact-sensor)
+- [co-sensor](#co-sensor)
+- [door](#door)
+- [doorbell](#doorbell)
+- [fan](#fan)
+- [humidifier-dehumidifier](#humidifier-dehumidifier)
+- [humidity-sensor](#humidity-sensor)
+- [leak-sensor](#leak-sensor)
+- [lightbulb](#lightbulb)
+- [light-sensor](#light-sensor)
+- [lock](#lock)
+- [microphone](#microphone)
+- [motion-sensor](#motion-sensor)
+- [occupancy-sensor](#occupancy-sensor)
+- [outlet](#outlet)
+- [security-system](#security-system)
+- [smoke-sensor](#smoke-sensor)
+- [speaker](#speaker)
+- [switch](#switch)
+- [temperature-sensor](#temperature-sensor)
+- [thermostat](#thermostat)
+- [window](#window)
+- [window-covering](#window-covering)
+
+
+### air-quality-sensor
+
+Characteristics:
+- [airQuality](#code-stylecolor-greenairqualitycode) (required)
+- [airQuality](#code-stylecolor-greenairqualitycode) (optional)
+- [ozoneDensity](#code-stylecolor-greenozonedensitycode) (optional)
+- [no2Density](#code-stylecolor-greenno2densitycode) (optional)
+- [so2Density](#code-stylecolor-greenso2Densitycode) (optional)
+- [pm25Density](#code-stylecolor-greenpm25Densitycode) (optional)
+- [pm10Density](#code-stylecolor-greenpm10Densitycode) (optional)
+- [vocDensity](#code-stylecolor-greenvocDensitycode) (optional)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+- [statusLowBattery](#code-stylecolor-greenstatusLowBatterycode) (optional)
+- [statusTampered](#code-stylecolor-greenstatusTamperedcode) (optional)
+ 
+```json
+{
+  "name": "<custom name>",
+  "type": "air-quality-sensor",
+  "topics": {
+    "airQuality": {           //required
+      "get": "<topic>",
+      "converter"?: { "unknown": string, "excellent": stirng, "good": string, "fair": string, "inferior": stirng, "port": string }
+    },
+    "ozoneDensity"?: {        // optional
+      "get": "<topic>"
+    },
+    "no2Density"?: {          // optional
+      "get": "<topic>"
+    },
+    "so2Density"?: {          // optional
+      "get": "<topic>"
+    },
+    "pm25Density"?: {         // optional
+      "get": "<topic>"
+    },
+    "pm10Density"?: {         // optional
+      "get": "<topic>"
+    },
+    "vocDensity"?: {          // optional
+      "get": "<topic>"
+    },
+    "statusFault"?: {         // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {        // optional
+      "get": "<topic>"
+    },
+    "statusLowBattery"?: {    // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'low' status value", "off":  "'not-low' status value"}
+    },
+    "statusTampered"?: {      // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'tampered' status value", "off":  "'not-tampered' status value"}
+    }
+  }
+}
+```
+
+### battery
+
+Characteristics:
+- [batteryLevel](#code-stylecolor-greenbatteryLevelcode) (required)
+- [chargingState](#code-stylecolor-greenchargingStatecode) (optional)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+- [statusLowBattery](#code-stylecolor-greenstatusLowBatterycode) (optional)
+- [statusTampered](#code-stylecolor-greenstatusTamperedcode) (optional)
+
+```json
+{
+  "name": "<custom name>",
+  "type": "battery",
+  "topics": {
+    "batteryLevel": {           //required
+      "get": "<topic>",
+      "converter"?: "decimal" | { "min": <number>, "max": <number> }
+    },
+    "chargingState"?: {         // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'charging' value", "off": "'not-charging' value" }
+    },
+    "statusFault"?: {           // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {          // optional
+      "get": "<topic>"
+    },
+    "statusLowBattery"?: {      // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'low' status value", "off":  "'not-low' status value"}
+    },
+    "statusTampered"?: {        // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'tampered' status value", "off":  "'not-tampered' status value"}
+    }
+  }
+}
+```
+
+### button
+
+Characteristics:
+- [pressEvent](#code-stylecolor-greenpressEventcode) (required)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+
+```json
+{
+  "name": "<custom name>",
+  "type": "button",
+  "topics": {
+    "pressEvent": {         //required
+      "get": "<read_topic>",
+      "converter"?: {
+        "single"?:  "value indicating a 'single' press event",
+        "double"?:  "value indicating a 'double' press event",
+        "long"?:    "value indicating a 'long' press event"
+      }
+    },
+    "statusFault"?: {       // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {      // optional
+      "get": "<topic>"
+    }
+  }
+}
+```
+
+### co2-sensor
+
+Characteristics:
+- [co2Detected](#code-stylecolor-greenco2Detectedcode) (required)
+- [co2Level](#code-stylecolor-greenco2Levelcode) (optional)
+- [co2PeakLevel](#code-stylecolor-greenco2PeakLevelcode) (optional)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+- [statusLowBattery](#code-stylecolor-greenstatusLowBatterycode) (optional)
+- [statusTampered](#code-stylecolor-greenstatusTamperedcode) (optional)
+
+```json
+{
+  "name": "<custom name>",
+  "type": "co2-sensor",
+  "topics": {
+    "co2Detected": {          //required
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'detected' value", "off": "'not-detected' value" }
+    },
+    "co2Level"?: {            // optional
+      "get": "<read_topic>"
+    },
+    "co2PeakLevel"?: {        // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "statusFault"?: {         // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {        // optional
+      "get": "<topic>"
+    },
+    "statusLowBattery"?: {    // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'low' status value", "off":  "'not-low' status value"}
+    },
+    "statusTampered"?: {      // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'tampered' status value", "off":  "'not-tampered' status value"}
+    }
+  }
+}
+```
+
+### contact-sensor
+
+Characteristics:
+- [contactSensorState](#code-stylecolor-greencontactSensorStatecode) (required)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+- [statusLowBattery](#code-stylecolor-greenstatusLowBatterycode) (optional)
+- [statusTampered](#code-stylecolor-greenstatusTamperedcode) (optional)
+
+```json
+{
+  "name": "<custom name>",
+  "type": "contact-sensor",
+  "topics": {
+    "contactSensorState": {       //required
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'contact' value", "off": "'no-contact' value" }
+    },
+    "statusFault"?: {             // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {            // optional
+      "get": "<topic>"
+    },
+    "statusLowBattery"?: {        // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'low' status value", "off":  "'not-low' status value"}
+    },
+    "statusTampered"?: {          // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'tampered' status value", "off":  "'not-tampered' status value"}
+    }
+  }
+}
+```
+
+### co-sensor
+
+Characteristics:
+- [coDetected](#code-stylecolor-greencoDetectedcode) (required)
+- [coLevel](#code-stylecolor-greencoLevelcode) (optional)
+- [coPeakLevel](#code-stylecolor-greencoPeakLevelcode) (optional)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+- [statusLowBattery](#code-stylecolor-greenstatusLowBatterycode) (optional)
+- [statusTampered](#code-stylecolor-greenstatusTamperedcode) (optional)
+
+```json
+{
+  "name": "<custom name>",
+  "type": "co-sensor",
+  "topics": {
+    "coDetected": {           //required
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'detected' value", "off": "'not-detected' value" }
+    },
+    "coLevel"?: {             // optional
+      "get": "<read_topic>"
+    },
+    "coPeakLevel"?: {         // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "statusFault"?: {         // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {        // optional
+      "get": "<topic>"
+    },
+    "statusLowBattery"?: {    // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'low' status value", "off":  "'not-low' status value"}
+    },
+    "statusTampered"?: {      // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'tampered' status value", "off":  "'not-tampered' status value"}
+    }
+  }
+}
+```
+
+### door
+
+Characteristics:
+- [currentPosition](#code-stylecolor-greencurrentPositioncode) (required)
+- [targetPosition](#code-stylecolor-greentargetPositioncode) (required)
+- [positionState](#code-stylecolor-greenpositionStatecode) (required)
+- [holdPosition](#code-stylecolor-greenholdPositioncode) (optional)
+- [obstructionDetected](#code-stylecolor-greenobstructionDetectedcode) (optional)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+
+```json
+{
+  "name": "<custom name>",
+  "type": "door",
+  "topics": {
+    "currentPosition": {          //required
+      "get": "<read_topic>",
+      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
+    },
+    "targetPosition": {           // required
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
+    },
+    "positionState": {            // required
+      "get": "<read_topic>",
+      "converter"?: {
+        "closing"?: "'closing' state value",
+        "opening"?: "'opening' state value",
+        "stopped"?: "'stopped' state value"
+      }
+    },
+    "holdPosition"?: {            // optional
+      "set": "<write_topic>",
+      "value"?: "any value that the device will understand as a 'hold' command"
+    },
+    "obstructionDetected"?: {     // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'detected'>", "off": "value indicating 'not-detected'" }
+    },
+    "statusFault"?: {             // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {            // optional
+      "get": "<topic>"
+    }
+  }
+}
+```
+
+### doorbell
+
+Characteristics:
+- [pressEvent](#code-stylecolor-greenpressEventcode) (required)
+- [volume](#code-stylecolor-greenvolumecode) (optional)
+- [brightness](#code-stylecolor-greenbrightnesscode) (optional)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+
+```json
+{
+  "name": "<custom name>",
+  "type": "doorbell",
+  "topics": {
+    "pressEvent": {         //required
+      "get": "<read_topic>",
+      "converter"?: {
+        "single"?:  "value indicating a 'single' press event",
+        "double"?:  "value indicating a 'double' press event",
+        "long"?:    "value indicating a 'long' press event"
+      }
+    },
+    "volume"?: {            // optional
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>, "max": <number> }
+    },
+    "brightness"?: {        // optional
+      "get": "<read_topic>",
+      "get": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
+    },
+    "statusFault"?: {       // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {      // optional
+      "get": "<topic>"
+    }
+  }
+}
+```
+
+### fan
+
+Characteristics:
+- [active](#code-stylecolor-greenactivecode) (required)
+- [currentState](#code-stylecolor-greencurrentFanStatecode) (required) (can also be `currentFanState`)
+- [targetState](#code-stylecolor-greentargetFanStatecode) (required) (can also be `targetFanState`)
+- [rotationDirection](#code-stylecolor-greenrotationDirectioncode) (optional)
+- [rotationSpeed](#code-stylecolor-greenrotationSpeedcode) (optional)
+- [swingMode](#code-stylecolor-greenswingModecode) (optional)
+- [lockPhysicalControls](#code-stylecolor-greenlockPhysicalControlscode) (optional)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+
+```json
+{
+  "name": "<custom name>",
+  "type": "fan",
+  "topics": {
+    "active": {               //required
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "boolean" | { "min": <number>, "max": <number> }
+    },
+    "currentState": {         // required
+      "get": "<read_topic>",
+      "converter"?: {
+        "inactive"?:    "'inactive' state value",
+        "idle"?:        "'idle' state value",
+        "blowingAir"?:  "'blowing air' state value"
+      }
+    },
+    "targetState": {          // required
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: { "auto": "'auto' state value", "manual":  "'manual' state value"}
+    },
+    "rotationDirection"?: {   // optional
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: { "clockwise": "value representing 'clockwise'", "counter-clockwise":  "value representing 'counter-clockwise'" }
+    },
+    "rotationSpeed"?: {       // optional
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min":  <number>, "max":  <number> } | <number> | string[]
+    },
+    "swingMode"?: {           // optional
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "boolean" | { "on": "'enabled' mode value", "off":  "'disabled' mode value"}
+    },
+    "lockPhysicalControls"?: {// optional
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'locked'>", "off": "value indicating 'not-locked'" }
+    },
+    "statusFault"?: {         // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {        // optional
+      "get": "<topic>"
+    }
+  }
+}
+```
+
+### humidifier-dehumidifier
+
+Characteristics:
+- [currentState](#code-stylecolor-greencurrentHumidifierDehumidifierStatecode) (required) (can also be `currentHumidifierDehumidifierState`)
+- [targetState](#code-stylecolor-greentargetHumidifierDehumidifierStatecode) (required) (can also be `targetHumidifierDehumidifierState`)
+- [humidifierThreshold](#code-stylecolor-greenhumidifierThresholdcode) (optional)
+- [dehumidifierThreshold](#code-stylecolor-greendehumidifierThresholdcode) (optional)
+- [rotationSpeed](#code-stylecolor-greenrotationSpeedcode) (optional)
+- [swingMode](#code-stylecolor-greenswingModecode) (optional)
+- [waterLevel](#code-stylecolor-greenwaterLevelcode) (optional)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+
+```json
+{
+  "name": "<custom name>",
+  "type": "humidifier-dehumidifier",
+  "topics": {
+    "currentState": {         // required
+      "get": "<read_topic>",
+      "converter"?: {
+        "inactive"?:       "'inactive' state value",
+        "idle"?:           "'idle' state value",
+        "humidifying"?:    "'humidifying' state value",
+        "dehumidifying"?:  "'dehumidifying' state value"
+      }
+    },
+    "targetState": {          // required
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: {
+        "humidifierDehumidifier"?:  "'humidifierDehumidifier' state value",
+        "humidifier"?:              "'humidifier' state value",
+        "dehumidifier"?:            "'dehumidifier' state value"
+      }
+    },
+    "humidifierThreshold"?: {   // optional
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>, "max":  <number> }
+    },
+    "dehumidifierThreshold"?: {   // optional
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>, "max":  <number> }
+    },
+    "rotationSpeed"?: {       // optional
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min":  <number>, "max":  <number> } | <number> | string[]
+    },
+    "swingMode"?: {           // optional
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "boolean" | { "on": "'enabled' mode value", "off":  "'disabled' mode value"}
+    },
+    "waterLevel": {           // optional
+        "get": "<read_topic>",
+        "converter"?: "decimal" | { "min": <number>, "max": <number> }
+    }
+    "statusFault"?: {         // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {        // optional
+      "get": "<topic>"
+    }
+  }
+}
+```
+
+
+### humidity-sensor
+
+Characteristics:
+- [currentRelativeHumidity](#code-stylecolor-greencurrentRelativeHumiditycode) (required)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+- [statusLowBattery](#code-stylecolor-greenstatusLowBatterycode) (optional)
+- [statusTampered](#code-stylecolor-greenstatusTamperedcode) (optional)
+
+
+```json
+{
+  "name": "<custom name>",
+  "type": "humidity-sensor",
+  "topics": {
+    "currentRelativeHumidity": {         // required
+      "get": "<read_topic>",
+      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
+    },
+    "statusFault"?: {                   // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {                  // optional
+      "get": "<topic>"
+    },
+      "statusLowBattery"?: {            // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'low' status value", "off":  "'not-low' status value"}
+    },
+    "statusTampered"?: {                // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'tampered' status value", "off":  "'not-tampered' status value"}
+    }
+  }
+}
+```
+
+### leak-sensor
+
+Characteristics:
+- [leakDetected](#code-stylecolor-greenleakDetectedcode) (required)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+- [statusLowBattery](#code-stylecolor-greenstatusLowBatterycode) (optional)
+- [statusTampered](#code-stylecolor-greenstatusTamperedcode) (optional)
+
+
+```json
+{
+  "name": "<custom name>",
+  "type": "leak-sensor",
+  "topics": {
+    "leakDetected": {                   // required
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'detected'>", "off": "value indicating 'not-detected'" }
+    },
+    "statusFault"?: {                   // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {                  // optional
+      "get": "<topic>"
+    },
+      "statusLowBattery"?: {            // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'low' status value", "off":  "'not-low' status value"}
+    },
+    "statusTampered"?: {                // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'tampered' status value", "off":  "'not-tampered' status value"}
+    }
+  }
+}
+```
+
+### lightbulb
+
+Characteristics:
+- [on](#code-stylecolor-greenoncode) (required)
+- [brightness](#code-stylecolor-greenbrightnesscode) (optional)
+- [saturation](#code-stylecolor-greensaturationcode) (optional)
+- [hue](#code-stylecolor-greenhuecode) (optional)
+- [colorTemperature](#code-stylecolor-greencolorTemperaturecode) (optional)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+
+```json
+{
+  "name": "<custom name>",
+  "type": "lightbulb",
+  "topics": {
+    "on": {                           // required
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'on'>", "off": "value indicating 'off'" }
+    },
+    "brightness": {                   // optional
+      "get": "<read_topic>",
+      "get": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
+    },
+    "saturation": {                   // optional
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>, "max": <number> }
+    },
+    "hue": {                          // optional
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "percent-integer" | "percent-decimal"
+    },
+    "colorTemperature": {             // optional
+      "get": "<read_topic>",
+      "set": "<read_topic>",
+      "converter"?: "kelvin"
+    },
+    "statusFault"?: {                 // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {                // optional
+      "get": "<topic>"
+    }
+  }
+}
+```
+
+### light-sensor
+
+Characteristics:
+- [ambientLightLevel](#code-stylecolor-greenambientLightLevelcode) (required)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+- [statusLowBattery](#code-stylecolor-greenstatusLowBatterycode) (optional)
+- [statusTampered](#code-stylecolor-greenstatusTamperedcode) (optional)
+
+
+```json
+{
+  "name": "<custom name>",
+  "type": "light-sensor",
+  "topics": {
+    "ambientLightLevel": {                // required
+      "get": "<read_topic>",
+      "converter"?: log-scale-lux"
+    },
+    "statusFault"?: {                     // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {                    // optional
+      "get": "<topic>"
+    },
+      "statusLowBattery"?: {              // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'low' status value", "off":  "'not-low' status value"}
+    },
+    "statusTampered"?: {                  // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'tampered' status value", "off":  "'not-tampered' status value"}
+    }
+  }
+}
+```
+
+### lock
+
+Characteristics:
+- [currentState](#code-stylecolor-greenlockCurrentStatecode) (required) (can also be `lockCurrentState`)
+- [targetState](#code-stylecolor-greenlockTargetStatecode) (optional) (can also be `lockTargetState`)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+
+```json
+{
+  "name": "<custom name>",
+  "type": "lock",
+  "topics": {
+    "currentState": {                 // required
+      "get": "<read_topic>",
+      "converter"?: {
+        "unsecured"?:   "'unsecured' state value",
+        "secured"?:     "'secured' state value",
+        "jammed"?:      "'jammed' state value",
+        "unknown"?:     "'unknown' state value"
+      }
+    },
+    "targetState": {                  // required
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "boolean" | { "secured": "<value indicating 'secured'>", "unsecured": "value indicating 'unsecured'" }
+    },
+    "statusFault"?: {                 // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {                // optional
+      "get": "<topic>"
+    }
+  }
+}
+```
+
+### microphone
+
+Characteristics:
+- [mute](#code-stylecolor-greenmutecode) (required)
+- [volume](#code-stylecolor-greenvolumecode) (optional)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+
+```json
+{
+  "name": "<custom name>",
+  "type": "microphone",
+  "topics": {
+    "mute": {                         // required
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'muted'>", "off": "value indicating 'not-muted'" }
+    },
+    "volume": {                       // required
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>, "max": <number> }
+    },
+    "statusFault"?: {                 // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {                // optional
+      "get": "<topic>"
+    }
+  }
+}
+```
+
+### motion-sensor
+
+Characteristics:
+- [motionDetected](#code-stylecolor-greenmotionDetectedcode) (required)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+- [statusLowBattery](#code-stylecolor-greenstatusLowBatterycode) (optional)
+- [statusTampered](#code-stylecolor-greenstatusTamperedcode) (optional)
+
+
+```json
+{
+  "name": "<custom name>",
+  "type": "motion-sensor",
+  "topics": {
+    "motionDetected": {                   // required
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'detected'>", "off": "value indicating 'not-detected'" }
+    },
+    "statusFault"?: {                     // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {                    // optional
+      "get": "<topic>"
+    },
+      "statusLowBattery"?: {              // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'low' status value", "off":  "'not-low' status value"}
+    },
+    "statusTampered"?: {                  // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'tampered' status value", "off":  "'not-tampered' status value"}
+    }
+  }
+}
+```
+
+### occupancy-sensor
+
+Characteristics:
+- [occupancyDetected](#code-stylecolor-greenoccupancyDetectedcode) (required)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+- [statusLowBattery](#code-stylecolor-greenstatusLowBatterycode) (optional)
+- [statusTampered](#code-stylecolor-greenstatusTamperedcode) (optional)
+
+
+```json
+{
+  "name": "<custom name>",
+  "type": "occupancy-sensor",
+  "topics": {
+    "occupancyDetected": {                // required
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'detected'>", "off": "value indicating 'not-detected'" }
+    },
+    "statusFault"?: {                     // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {                    // optional
+      "get": "<topic>"
+    },
+      "statusLowBattery"?: {              // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'low' status value", "off":  "'not-low' status value"}
+    },
+    "statusTampered"?: {                  // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'tampered' status value", "off":  "'not-tampered' status value"}
+    }
+  }
+}
+```
+
+### outlet
+
+Characteristics:
+- [on](#code-stylecolor-greenoncode) (required)
+- [outletInUse](#code-stylecolor-greenoutletInUsecode) (optional)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+
+```json
+{
+  "name": "<custom name>",
+  "type": "outlet",
+  "topics": {
+    "on": {                           // required
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'on'>", "off": "value indicating 'off'" }
+    },
+    "outletInUse": {                  // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'in-use'>", "off": "value indicating 'not-in-use'" }
+    },
+    "statusFault"?: {                 // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {                // optional
+      "get": "<topic>"
+    }
+  }
+}
+```
+
+### security-system
+
+Characteristics:
+- [currentState](#code-stylecolor-greensecuritySystemCurrentStatecode) (required) (can also be `securitySystemCurrentState`)
+- [targetState](#code-stylecolor-greensecuritySystemTargetStatecode) (required) (can also be `securitySystemTargetState`) 
+- [alarmType](#code-stylecolor-greenalarmTypecode) (optional) 
+- [statusTampered](#code-stylecolor-greenstatusTamperedcode) (optional)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+
+```json
+{
+  "name": "<custom name>",
+  "type": "security-system",
+  "topics": {
+    "currentState": {                 // required
+      "get": "<read_topic>",
+      "converter"?: {
+        "stay"?:      "'stay' state value",
+        "away"?:      "'away' state value",
+        "night"?:     "'night' state value",
+        "disarmed"?:  "'disarmed' state value",
+        "triggered"?: "'triggered' state value",
+      }
+    },
+    "targetState": {                  // required
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: {
+        "stay"?:      "'stay' state value",
+        "away"?:      "'away' state value",
+        "night"?:     "'night' state value",
+        "disarm"?:    "'disarm' state value",
+      },
+      "validValues"?: string[] // e.g. [ "stay", "away", "disarm" ] to not show the 'night' option.
+    },
+    "alarmType": {                    // optional
+      "get": "<read_topic>",
+      "converter"?: { "cleared":  "value representing a 'cleared` state"}
+    },
+    "statusTampered": {               // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'tampered' status value", "off":  "'not-tampered' status value"}
+    }
+    "statusFault"?: {                 // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {                // optional
+      "get": "<topic>"
+    }
+  }
+}
+```
+
+### smoke-sensor
+
+Characteristics:
+- [smokeDetected](#code-stylecolor-greensmokeDetectedcode) (required)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+- [statusLowBattery](#code-stylecolor-greenstatusLowBatterycode) (optional)
+- [statusTampered](#code-stylecolor-greenstatusTamperedcode) (optional)
+
+
+```json
+{
+  "name": "<custom name>",
+  "type": "smoke-sensor",
+  "topics": {
+    "smokeDetected": {                    // required
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'detected'>", "off": "value indicating 'not-detected'" }
+    },
+    "statusFault"?: {                     // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {                    // optional
+      "get": "<topic>"
+    },
+      "statusLowBattery"?: {              // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'low' status value", "off":  "'not-low' status value"}
+    },
+    "statusTampered"?: {                  // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'tampered' status value", "off":  "'not-tampered' status value"}
+    }
+  }
+}
+```
+
+### speaker
+
+Characteristics:
+- [mute](#code-stylecolor-greenmutecode) (required)
+- [volume](#code-stylecolor-greenvolumecode) (optional)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+
+```json
+{
+  "name": "<custom name>",
+  "type": "speaker",
+  "topics": {
+    "mute": {                         // required
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'muted'>", "off": "value indicating 'not-muted'" }
+    },
+    "volume": {                       // required
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>, "max": <number> }
+    },
+    "statusFault"?: {                 // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {                // optional
+      "get": "<topic>"
+    }
+  }
+}
+```
+
+### switch
+
+Characteristics:
+- [on](#code-stylecolor-greenoncode) (required)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+
+```json
+{
+  "name": "<custom name>",
+  "type": "outlet",
+  "topics": {
+    "on": {                           // required
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'on'>", "off": "value indicating 'off'" }
+    },
+    "statusFault"?: {                 // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {                // optional
+      "get": "<topic>"
+    }
+  }
+}
+```
+
+### temperature-sensor
+
+Characteristics:
+- [currentTemperature](#code-stylecolor-greencurrentTemperaturecode) (required)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+- [statusLowBattery](#code-stylecolor-greenstatusLowBatterycode) (optional)
+- [statusTampered](#code-stylecolor-greenstatusTamperedcode) (optional)
+
+
+```json
+{
+  "name": "<custom name>",
+  "type": "smoke-sensor",
+  "topics": {
+    "currentTemperature": {               // required
+      "get": "<read_topic>",
+      "converter"?: "fahrenheit",
+      "minValue"?: <number>, // in celsius (regardless of the converter), defaut: 10.0 
+      "maxValue"?: <number>, // in celsius (regardless of the converter), defaut: 38.0
+      "minStep"?: <number>   // in celsius (regardless of the converter), defaut: 0.1
+    },
+    "statusFault"?: {                     // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {                    // optional
+      "get": "<topic>"
+    },
+    "statusLowBattery"?: {                // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'low' status value", "off":  "'not-low' status value"}
+    },
+    "statusTampered"?: {                  // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'tampered' status value", "off":  "'not-tampered' status value"}
+    }
+  }
+}
+```
+
+### thermostat
+
+Characteristics:
+- [currentTemperature](#code-stylecolor-greencurrentTemperaturecode) (required)
+- [targetTemperature](#code-stylecolor-greentargetTemperaturecode) (required)
+- [currentState](#code-stylecolor-greencurrentHeatingCoolingStatecode) (optional) (can also be `currentHeatingCoolingState`)
+- [targetState](#code-stylecolor-greentargetHeatingCoolingStatecode) (optional) (can also be `targetHeatingCoolingState`)
+- [temperatureDisplayUnits](#code-stylecolor-greentemperatureDisplayUnitscode) (optional)
+- [coolingThreshold](#code-stylecolor-greencoolingThresholdcode) (optional)
+- [heatingThreshold](#code-stylecolor-greenheatingThresholdcode) (optional)
+- [currentRelativeHumidity](#code-stylecolor-greencurrentRelativeHumiditycode) (optional)
+- [targetRelativeHumidity](#code-stylecolor-greentargetRelativeHumiditycode) (optional)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+
+Additional Settings:
+
+- `hvacType` (optional) - only used when `currentHeatingCoolingState` is not set. Can have one of the following values:
+  - `heat-cool`: depending on the current and target temp. `heat`/`cool`/`off` will be set as the current state
+  - `heat-only`: depending on the current and target temp. `heat`/`off` will be set as the current state
+  - `cool-only`: depending on the current and target temp. `cool`/`off` will be set as the current state
+
+
+- `stateThreshold` (optional) - Only used when `currentHeatingCoolingState` is not set. A numeric values that determines
+when the current state will change (based on the current and target temperatures). e.g.
+  - if `target > current + threshold` the state will either be `heat` or `off` (depending on the `hvacType`)
+  - if `target < current - threshold` the state will either be `cool` or `off` (depending on the `hvacType`)
+  - otherwise, the state will be `off`
+
+
+```json
+{
+  "name": "<custom name>",
+  "type": "thermostat",
+  "hvacType"?: "heat-cool" | "heat-only" | "cool-only",
+  "stateThreshold"?: <number>,
+  "topics": {
+    "currentTemperature": {               // required
+      "get": "<read_topic>",
+      "converter"?: "fahrenheit",
+      "minValue"?: <number>, // in celsius (regardless of the converter), defaut: 10.0 
+      "maxValue"?: <number>, // in celsius (regardless of the converter), defaut: 38.0
+      "minStep"?: <number>   // in celsius (regardless of the converter), defaut: 0.1
+    },
+    "targetTemperature": {                // required
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "fahrenheit",
+      "minValue"?: <number>, // in celsius (regardless of the converter), defaut: 10.0 
+      "maxValue"?: <number>, // in celsius (regardless of the converter), defaut: 38.0
+      "minStep"?: <number>   // in celsius (regardless of the converter), defaut: 0.1
+    },
+    "currentState": {                      // optional
+      "get": "<read_topic>",
+      "converter"?: {
+        "off"?:   "'off' state value",
+        "heat"?:  "'heat' state value",
+        "cool"?:  "'cool' state value"
+      }
+    },
+    "targetState": {
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: {
+        "off"?:   "'off' state value",
+        "heat"?:  "'heat' state value",
+        "cool"?:  "'cool' state value",
+        "auto"?:  "'auto' state value",
+      },
+      "validValues": string[]  // e.g. [ "off", "auto" ] to only provide the user to stop the operation of the device
+    },
+    "temperatureDisplayUnits": {          // optional
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: { "celsius": "value indicating 'celsius'", "fahrenheit": "value indicating 'fahrenheit'" }
+    },
+    "coolingThreshold": {                 // optional
+      "get": "<read_topic>",
+      "set": "<read_topic>",
+      "converter"?: "fahrenheit"
+    },
+    "heatingThreshold": {                 // optional
+      "get": "<read_topic>",
+      "set": "<read_topic>",
+      "converter"?: "fahrenheit"
+    },
+    "currentRelativeHumidity": {          // optional
+      "get": "<read_topic>",
+      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
+    },
+    "targetRelativeHumidity": {           // optional
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
+    },       
+    "statusFault"?: {                     // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {                    // optional
+      "get": "<topic>"
+    }
+  }
+}
+```
+
+### window
+
+Characteristics:
+- [currentPosition](#code-stylecolor-greencurrentPositioncode) (required)
+- [targetPosition](#code-stylecolor-greentargetPositioncode) (required)
+- [positionState](#code-stylecolor-greenpositionStatecode) (required)
+- [holdPosition](#code-stylecolor-greenholdPositioncode) (optional)
+- [obstructionDetected](#code-stylecolor-greenobstructionDetectedcode) (optional)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+
+```json
+{
+  "name": "<custom name>",
+  "type": "window",
+  "topics": {
+    "currentPosition": {          //required
+      "get": "<read_topic>",
+      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
+    },
+    "targetPosition": {           // required
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
+    },
+    "positionState": {            // required
+      "get": "<read_topic>",
+      "converter"?: {
+        "closing"?: "'closing' state value",
+        "opening"?: "'opening' state value",
+        "stopped"?: "'stopped' state value"
+      }
+    },
+    "holdPosition"?: {            // optional
+      "set": "<write_topic>",
+      "value"?: "any value that the device will understand as a 'hold' command"
+    },
+    "obstructionDetected"?: {     // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'detected'>", "off": "value indicating 'not-detected'" }
+    },
+    "statusFault"?: {             // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {            // optional
+      "get": "<topic>"
+    }
+  }
+}
+```
+
+### window-covering
+
+Characteristics:
+- [currentPosition](#code-stylecolor-greencurrentPositioncode) (required)
+- [targetPosition](#code-stylecolor-greentargetPositioncode) (required)
+- [positionState](#code-stylecolor-greenpositionStatecode) (optional)
+- [holdPosition](#code-stylecolor-greenholdPositioncode) (optional)
+- [obstructionDetected](#code-stylecolor-greenobstructionDetectedcode) (optional)
+- [currentHorizontalTiltAngle](#code-stylecolor-greencurrentHorizontalTiltAnglecode) (optional)
+- [targetHorizontalTiltAngle](#code-stylecolor-greentargetHorizontalTiltAnglecode) (optional)
+- [currentVerticalTiltAngle](#code-stylecolor-greencurrentVerticalTiltAnglecode) (optional)
+- [targetVerticalTiltAngle](#code-stylecolor-greentargetVerticalTiltAnglecode) (optional)
+- [statusFault](#code-stylecolor-greenstatusFaultcode) (optional)
+- [faultMessage](#code-stylecolor-greenfaultMessagecode) (optional)
+
+```json
+{
+  "name": "<custom name>",
+  "type": "window-covering",
+  "topics": {
+    "currentPosition": {                //required
+      "get": "<read_topic>",
+      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
+    },
+    "targetPosition": {                 // required
+      "get": "<read_topic>",
+      "set": "<write_topic>",
+      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
+    },
+    "positionState?": {                 // optional
+      "get": "<read_topic>",
+      "converter"?: {
+        "closing"?: "'closing' state value",
+        "opening"?: "'opening' state value",
+        "stopped"?: "'stopped' state value"
+      }
+    },
+    "holdPosition"?: {                    // optional
+      "set": "<write_topic>",
+      "value"?: "any value that the device will understand as a 'hold' command"
+    },
+    "obstructionDetected"?: {             // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "<value indicating 'detected'>", "off": "value indicating 'not-detected'" }
+    },
+    "currentHorizontalTiltAngle"?: {      // optional
+      "get": "<read_topic>"
+    },
+    "targetHorizontalTiltAngle"?: {
+      "get": "<read_topic>",
+      "set": "<write_topic>"
+    },
+    "currentVerticalTiltAngle"?: {        // optional
+      "get": "<read_topic>"
+    },
+    "targetVerticalTiltAngle"?: {         // optional
+      "get": "<read_topic>",
+      "set": "<write_topic>"
+    }
+    "statusFault"?: {                     // optional
+      "get": "<read_topic>",
+      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
+    },
+    "faultMessage"?: {                    // optional
+      "get": "<topic>"
+    }
+  }
+}
+```