<commit_before>[![npm](https://badgen.net/npm/v/homebridge-mqttthing/latest)](https://www.npmjs.com/package/homebridge-mqttthing)
[![npm](https://badgen.net/npm/dt/homebridge-mqttthing)](https://www.npmjs.com/package/homebridge-mqttthing)
[![Discord](https://img.shields.io/discord/432663330281226270?color=728ED5&logo=discord&label=discord)](https://discord.gg/MTpeMC)
[![verified-by-homebridge](https://badgen.net/badge/homebridge/verified/purple)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)

# Homebridge MQTT-Thing: Configuration

## Introduction

Configure the plugin in your homebridge `config.json` file. Most configuration settings can now also be entered using
[Homebridge Config UI X](https://www.npmjs.com/package/homebridge-config-ui-x).

MQTT topics used fall into two categories:

   * Control topics, of the form `setXXX`, are published by MQTT-Thing in order to control device state (e.g. to turn on a light).
   * Status/notification topics, of the form `getXXX`, are published by the device to notify MQTT-Thing that something has occurred (e.g. that a sensor has detected something or a control topic action has been performed).

**All values shown below (often within <>) are comments/descriptions, and should not be copied into your configuration file. For an example of an actual configuration file, please see `test/config.json`.**

   * [General Settings](#general-settings)
   * [MQTT Settings](#mqtt-settings)
   * [MQTT Topics](#mqtt-topics)
   * [Topic Apply Functions](#apply-functions)
   * [Boolean Value Settings](#boolean-value-settings)
   * [Accessory Information](#accessory-information)
   * [Publishing Values on Start-up](#publishing-values-on-start-up)
   * [History Service](#history-service)
   * [Confirmation](#confirmation)
   * [Codecs](#codecs)
   * [Validation](#validation)
   * [Accessories](#accessories)
   * [Grouped Accessories](#grouped-accessories)

## Common Settings

The following settings apply to all device types:

```javascript
{
    "accessory": "mqttthing",
    "type": "lightbulb",
    "name": "My lightbulb",
    "url": "mqtt://192.168.1.235:1883",
    "username": "MQTT_username",
    "password": "<PASSWORD>",
    "mqttOptions": { "keepalive": 30 },
    "mqttPubOptions": { "retain": true },
    "logMqtt": true,
    "topics": {
        "getName": 	        "my/get/name/topic",
        "getOnline":        "my/get/online/topic",
        "getBatteryLevel":  "my/get/battery-level/topic",
        "getChargingState": "my/get/battery-charging-state/topic",
        "getStatusLowBattery": "my/get/status-low-battery/topic"
    },
    "integerValue": true,
    "onlineValue": "Online",
    "offlineValue": "Offline",
    "chargingStateValues": [ "NotCharging", "Charging", "NotChargeable" ],
    "startPub": [
        { "topic": "topic1", "message": "message1" },
        { "topic": "topic2", "message": "message2" }
    ],<commit_msg>Set mqtt retain option to false in docs<commit_after>[![npm](https://badgen.net/npm/v/homebridge-mqttthing/latest)](https://www.npmjs.com/package/homebridge-mqttthing)
[![npm](https://badgen.net/npm/dt/homebridge-mqttthing)](https://www.npmjs.com/package/homebridge-mqttthing)
[![Discord](https://img.shields.io/discord/432663330281226270?color=728ED5&logo=discord&label=discord)](https://discord.gg/MTpeMC)
[![verified-by-homebridge](https://badgen.net/badge/homebridge/verified/purple)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)

# Homebridge MQTT-Thing: Configuration

## Introduction

Configure the plugin in your homebridge `config.json` file. Most configuration settings can now also be entered using
[Homebridge Config UI X](https://www.npmjs.com/package/homebridge-config-ui-x).

MQTT topics used fall into two categories:

   * Control topics, of the form `setXXX`, are published by MQTT-Thing in order to control device state (e.g. to turn on a light).
   * Status/notification topics, of the form `getXXX`, are published by the device to notify MQTT-Thing that something has occurred (e.g. that a sensor has detected something or a control topic action has been performed).

**All values shown below (often within <>) are comments/descriptions, and should not be copied into your configuration file. For an example of an actual configuration file, please see `test/config.json`.**

   * [General Settings](#general-settings)
   * [MQTT Settings](#mqtt-settings)
   * [MQTT Topics](#mqtt-topics)
   * [Topic Apply Functions](#apply-functions)
   * [Boolean Value Settings](#boolean-value-settings)
   * [Accessory Information](#accessory-information)
   * [Publishing Values on Start-up](#publishing-values-on-start-up)
   * [History Service](#history-service)
   * [Confirmation](#confirmation)
   * [Codecs](#codecs)
   * [Validation](#validation)
   * [Accessories](#accessories)
   * [Grouped Accessories](#grouped-accessories)

## Common Settings

The following settings apply to all device types:

```javascript
{
    "accessory": "mqttthing",
    "type": "lightbulb",
    "name": "My lightbulb",
    "url": "mqtt://192.168.1.235:1883",
    "username": "MQTT_username",
    "password": "<PASSWORD>",
    "mqttOptions": { "keepalive": 30 },
    "mqttPubOptions": { "retain": false },
    "logMqtt": true,
    "topics": {
        "getName": 	        "my/get/name/topic",
        "getOnline":        "my/get/online/topic",
        "getBatteryLevel":  "my/get/battery-level/topic",
        "getChargingState": "my/get/battery-charging-state/topic",
        "getStatusLowBattery": "my/get/status-low-battery/topic"
    },
    "integerValue": true,
    "onlineValue": "Online",
    "offlineValue": "Offline",
    "chargingStateValues": [ "NotCharging", "Charging", "NotChargeable" ],
    "startPub": [
        { "topic": "topic1", "message": "message1" },
        { "topic": "topic2", "message": "message2" }
    ],
{'fraction_non_alphanumeric': 0.15612749275609342, 'fraction_numerical': 0.01431736833134481, 'mean_word_length': 4.220640569395018, 'pattern_counts': {'":': 52, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 18, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4971830', 'n_tokens_mistral': 1987, 'n_tokens_neox': 1851, 'n_words': 421}