matterbridge-dyson-robot.schema.json

{
    "title": "Matterbridge Dyson Robot Vacuum and Air Treatment Devices Plugin",
    "description": "Dyson Robot Vacuum and Air Treatment Devices",
    "type": "object",
    "required": [
        "provisioningMethod"
    ],
    "properties": {
        "name": {
            "description": "Plugin name",
            "type": "string",
            "readOnly": true,
            "ui:widget": "hidden"
        },
        "type": {
            "description": "Plugin type",
            "type": "string",
            "readOnly": true,
            "ui:widget": "hidden"
        },
        "provisioningMethod": {
            "title": "Provisioning Method",
            "description": "Select how the plugin should connect to the Dyson robot vacuum and air treatment devices. This setting determines how the plugin connects to the devices and how the MQTT broker credentials are provided. For the simplest and most compatible setup, select 'Connect via AWS IoT gateway / Configure using MyDyson account' and enter your MyDyson account credentials. The 'Connect via Local Network' options all require manual configuration of device IP addresses and other details, and may not be supported by some newer Dyson models or firmware versions, but have the benefit of connecting directly to the devices instead of routing via cloud services.",
            "type": "string",
            "oneOf": [
                {
                    "const": "Remote Account",
                    "title": "Connect via AWS IoT Gateway / Configure using MyDyson account [recommended]"
                },
                {
                    "const": "Local Account",
                    "title": "Connect via Local Network / Configure using MyDyson account"
                },
                {
                    "const": "Local Wi-Fi",
                    "title": "Connect via Local Network / Configure using Wi-Fi Setup credentials"
                },
                {
                    "const": "Local MQTT",
                    "title": "Connect via Local Network / Configure using MQTT credentials"
                }
            ],
            "default": "Remote Account"
        },
        "enableServerRvc": {
            "description": "Expose each robot vacuum as a standalone Matter node using Matterbridge's 'server' mode. When enabled, each robot vacuum has its own Matter fabric that must be manually paired, ensuring compatibility with Matter controllers such as the Apple Home app. When disabled, all devices are bridged within a single Matter node, which may not function correctly with some Matter controllers.",
            "type": "boolean",
            "default": true
        },
        "simpleModeTagsRvc": {
            "description": "Use simplified ModeTag values for robot vacuum cleaners. When enabled, only the single most descriptive ModeTag is used for each cleaning (power) mode, which may improve compatibility with Matter controllers that have limited support for multiple tags, such as the Apple Home app.",
            "type": "boolean",
            "default": true
        },
        "logMapStyle": {
            "description": "Select how robot vacuum cleaner maps should be displayed in the log at the end of cleans.",
            "type": "string",
            "oneOf": [
                {
                    "const": "Off",
                    "title": "No map logging"
                },
                {
                    "const": "Monospaced",
                    "title": "Highest quality (requires monospaced font)"
                },
                {
                    "const": "Matterbridge",
                    "title": "Optimised for Matterbridge frontend"
                }
            ],
            "default": "Matterbridge"
        },
        "wildcardTopic": {
            "description": "Subscribe to all MQTT topics. For direct connections via the local network this uses the '#' wildcard, which is useful for discovering new endpoints or checking that the rootTopic and serialNumber have been correctly configured. However, the AWS IoT gateway does not allow wildcard subscriptions. For AWS IoT connections, this option instead adds a subscription to the command topic. When this option is disabled only the expected status topic(s) are subscribed.",
            "type": "boolean",
            "default": true
        },
        "whiteList": {
            "description": "Only expose robot vacuum and air treatment devices listed here, identified by their serial number (the MQTT username). Leave empty to expose all devices.",
            "type": "array",
            "items": {
                "$ref": "#/definitions/deviceSerialNumber"
            },
            "uniqueItems": true,
            "selectFrom": "serial",
            "default": []
        },
        "blackList": {
            "description": "Exclude any robot vacuum and air treatment devices listed here, identified by their serial number (the MQTT username). Leave empty to expose all devices.",
            "type": "array",
            "items": {
                "$ref": "#/definitions/deviceSerialNumber"
            },
            "uniqueItems": true,
            "selectFrom": "serial",
            "default": []
        },
        "entityWhiteList": {
            "title": "Entity White List",
            "description": "Only expose Matter device types listed here: Air Purifier, Air Quality Sensor, Composed Air Purifier, Humidity Sensor, Temperature Sensor, or Thermostat. This applies to all air treatment devices, but does not affect robot vacuum devices. Leave empty to expose all device types.",
            "type": "array",
            "items": {
                "$ref": "#/definitions/entity"
            },
            "uniqueItems": true,
            "default": []
        },
        "entityBlackList": {
            "title": "Entity Black List",
            "description": "Exclude any Matter device types listed here: Air Purifier, Air Quality Sensor, Composed Air Purifier, Humidity Sensor, Temperature Sensor, or Thermostat. This applies to all air treatment devices, but does not affect robot vacuum devices. Leave empty to expose all device types.",
            "type": "array",
            "items": {
                "$ref": "#/definitions/entity"
            },
            "uniqueItems": true,
            "default": [
                "Composed Air Purifier",
                "Humidity Sensor",
                "Temperature Sensor"
            ]
        },
        "deviceEntityBlackList": {
            "description": "Exclude Matter device types per air treatment device. This does not affect robot vacuum devices. Enter the device's serial number (the MQTT username) in the first field, and in the list add all of the device types to exclude for that device.",
            "type": "object",
            "uniqueItems": true,
            "selectFrom": "serial",
            "additionalProperties": {
                "description": "Exclude any device types listed here.",
                "type": "array",
                "uniqueItems": true,
                "items": {
                    "type": "string"
                },
                "selectDeviceEntityFrom": "name"
            },
            "default": {}
        },
        "debug": {
            "description": "Capture debug-level logging from this plugin, overriding the Matterbridge global log level setting.",
            "type": "boolean",
            "default": false
        },
        "debugFeatures": {
            "description": "Advanced diagnostics: Enable only for troubleshooting or development.",
            "type": "array",
            "uniqueItems": true,
            "items": {
                "type": "string",
                "enum": [
                    "Log Endpoint Debug",
                    "Log API Headers",
                    "Log API Bodies",
                    "Log MQTT Client",
                    "Log MQTT Payloads",
                    "Log MQTT Payloads as JSON",
                    "Log Serial Numbers",
                    "Log Debug as Info"
                ]
            },
            "default": []
        },
        "unregisterOnShutdown": {
            "description": "Unregister all exposed devices on shutdown (used for development/testing).",
            "type": "boolean",
            "default": false,
            "ui:widget": "hidden"
        }
    },
    "dependencies": {
        "provisioningMethod": {
            "oneOf": [
                {
                    "properties": {
                        "provisioningMethod": {
                            "const": "Remote Account"
                        },
                        "dysonAccount": {
                            "$ref": "#/definitions/dysonAccount"
                        }
                    },
                    "required": [
                        "dysonAccount"
                    ]
                },
                {
                    "properties": {
                        "provisioningMethod": {
                            "const": "Local Account"
                        },
                        "dysonAccount": {
                            "$ref": "#/definitions/dysonAccount"
                        },
                        "devices": {
                            "title": "Local Network Configurations for MyDyson Account Devices",
                            "description": "Use + to add a new item for each robot vacuum or air treatment device to be exposed. For each device enter its serial number and local network configuration.",
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/deviceAccount"
                            },
                            "minItems": 1,
                            "uniqueItems": true
                        }
                    },
                    "required": [
                        "dysonAccount",
                        "devices"
                    ]
                },
                {
                    "properties": {
                        "provisioningMethod": {
                            "const": "Local Wi-Fi"
                        },
                        "devices": {
                            "title": "Local Network Configurations and Wi-Fi Setup Credentials",
                            "description": "Use + to add a new item for each robot vacuum or air treatment device to be exposed. For each device enter a friendly name that will be used to identify it, its Wi-Fi setup credentials, and its local network configuration. The Wi-Fi setup credentials can be found on a label attached to the product (behind the clear bin of robot vacuums or underneath the base of air treatment devices) or its operating manual. These details are used to derive the MQTT configuration, but may not be compatible with more recent Dyson models.",
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/deviceWifi"
                            },
                            "minItems": 1,
                            "uniqueItems": true
                        }
                    },
                    "required": [
                        "devices"
                    ]
                },
                {
                    "properties": {
                        "provisioningMethod": {
                            "const": "Local MQTT"
                        },
                        "devices": {
                            "title": "Local Network Configurations and MQTT Credentials",
                            "description": "Use + to add a new item for each robot vacuum or air treatment device to be exposed. For each device enter a friendly name that will be used to identify it, its MQTT credentials, and its local network configuration. The MQTT credentials can be found using tools such as opendyson.",
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/deviceMqtt"
                            },
                            "minItems": 1,
                            "uniqueItems": true
                        }
                    },
                    "required": [
                        "devices"
                    ]
                }
            ]
        }
    },
    "definitions": {
        "dysonAccount": {
            "title": "MyDyson Account Configuration",
            "description": "Enter the email address and password used to login to the MyDyson app, and then click START AUTH to begin authorising access to your account. A one-time password (OTP) code should then be sent to the specified email address. Enter the OTP code and click SUBMIT CODE to complete the authorization process. The code is only valid for a short time and can only be used once. If you do not receive a code then check your spam folder or try again.",
            "type": "object",
            "properties": {
                "email": {
                    "description": "MyDyson account email address.",
                    "title": "e.g. leia@resistance.clean",
                    "type": "string",
                    "format": "email"
                },
                "password": {
                    "description": "MyDyson account password.",
                    "title": "e.g. Dyson4Life!",
                    "type": "string",
                    "minLength": 1
                },
                "china": {
                    "description": "Select this option if your MyDyson account is registered in China. This selects the correct server URL for the account.",
                    "type": "boolean",
                    "default": false
                },
                "token": {
                    "description": "As an alternative to providing the MyDyson account configuration, a pre-authenticated token may be used instead. (If opendyson is used then this can be found in '~/.config/libdyson/config.yml'.) This value is primarily intended for automated testing, and should normally be left blank.",
                    "title": "Leave blank unless you know what you are doing",
                    "type": "string",
                    "pattern": "^[A-Z0-9]{64}-1$",
                    "ui:widget": "hidden"
                }
            },
            "dependencies": {
                "password": {
                    "properties": {
                        "startAuth": {
                            "description": "After entering the email and password start the authorization process.",
                            "type": "boolean",
                            "buttonText": "START AUTH",
                            "buttonClose": false,
                            "buttonSave": false,
                            "default": false
                        },
                        "finishAuth": {
                            "description": "One-time password (OTP) code from email.",
                            "type": "boolean",
                            "buttonField": "SUBMIT CODE",
                            "buttonClose": false,
                            "buttonSave": false,
                            "textPlaceholder": "e.g. 123456",
                            "default": false
                        }
                    }
                }
            },
            "oneOf": [
                {
                    "required": [
                        "email",
                        "password",
                        "china"
                    ]
                },
                {
                    "required": [
                        "token",
                        "china"
                    ]
                }
            ]
        },
        "deviceAccount": {
            "title": "Device Configuration",
            "type": "object",
            "properties": {
                "serialNumber": {
                    "$ref": "#/definitions/deviceSerialNumber"
                },
                "host": {
                    "$ref": "#/definitions/deviceHost"
                },
                "port": {
                    "$ref": "#/definitions/devicePort"
                }
            },
            "required": [
                "serialNumber",
                "host",
                "port"
            ]
        },
        "deviceWifi": {
            "title": "Device Configuration",
            "type": "object",
            "properties": {
                "name": {
                    "$ref": "#/definitions/deviceName"
                },
                "host": {
                    "$ref": "#/definitions/deviceHost"
                },
                "port": {
                    "$ref": "#/definitions/devicePort"
                },
                "ssid": {
                    "$ref": "#/definitions/deviceWifiSsid"
                },
                "password": {
                    "$ref": "#/definitions/deviceWifiPassword"
                }
            },
            "required": [
                "name",
                "host",
                "port",
                "ssid",
                "password"
            ]
        },
        "deviceMqtt": {
            "title": "Device Configuration",
            "type": "object",
            "properties": {
                "name": {
                    "$ref": "#/definitions/deviceName"
                },
                "host": {
                    "$ref": "#/definitions/deviceHost"
                },
                "port": {
                    "$ref": "#/definitions/devicePort"
                },
                "serialNumber": {
                    "$ref": "#/definitions/deviceSerialNumber"
                },
                "password": {
                    "$ref": "#/definitions/devicePassword"
                },
                "rootTopic": {
                    "$ref": "#/definitions/deviceRootTopic"
                }
            },
            "required": [
                "name",
                "host",
                "port",
                "serialNumber",
                "password",
                "rootTopic"
            ]
        },
        "entity": {
            "type": "string",
            "enum": [
                "Air Purifier",
                "Air Quality Sensor",
                "Composed Air Purifier",
                "Humidity Sensor",
                "Temperature Sensor",
                "Thermostat"
            ]
        },
        "deviceName": {
            "description": "Friendly name used to identify the robot vacuum or air treatment device. This is used as the Matter NodeLabel for the device.",
            "title": "e.g. Sweep",
            "type": "string",
            "minLength": 1,
            "maxLength": 64
        },
        "deviceHost": {
            "description": "Local network hostname or IP address of the robot vacuum or air treatment device.",
            "title": "e.g. sweep.local or 192.168.0.100",
            "type": "string",
            "format": "hostname"
        },
        "devicePort": {
            "description": "MQTT port number. This should usually be left at its default value of 1883.",
            "title": "e.g. 1883",
            "type": "integer",
            "default": 1883,
            "ui:widget": "hidden"
        },
        "deviceWifiSsid": {
            "description": "Product SSID from the label attached to the product or its operating manual.",
            "title": "e.g. DYSON-XXX-YY-ZZZZZZZZ-NNN",
            "type": "string",
            "pattern": "^(((360EYE-)?[A-Z0-9]{3}-[A-Z]{2}-[A-Z0-9]{8,})|(DYSON-[A-Z0-9]{3}-[A-Z]{2}-[A-Z0-9]{8,}-[0-9]{3}[A-Z]?))$"
        },
        "deviceWifiPassword": {
            "description": "Product Wi-Fi Password from the label attached to the product or its operating manual.",
            "title": "e.g. xxxxxxxx",
            "type": "string",
            "pattern": "^[A-Za-z0-9]{8,}$"
        },
        "deviceSerialNumber": {
            "description": "Serial number of the robot vacuum or air treatment device. (This is also used as the MQTT username and as part of its MQTT topic names.)",
            "title": "e.g. XXX-YY-ZZZZZZZZ",
            "type": "string",
            "pattern": "^[A-Z0-9]{3}-[A-Z]{2}-[A-Z0-9]{8,}$"
        },
        "devicePassword": {
            "description": "MQTT password.",
            "type": "string",
            "pattern": "^[A-Za-z0-9+/]{86}==$"
        },
        "deviceRootTopic": {
            "description": "MQTT root topic (Dyson internal product type).",
            "type": "string",
            "oneOf": [
                {
                    "const": "N223",
                    "title": "N223 = Dyson 360 Eye (RB01)"
                },
                {
                    "const": "276",
                    "title": "276 = Dyson 360 Heurist (RB02)"
                },
                {
                    "const": "277",
                    "title": "277 = Dyson 360 Vis Nav (RB03)"
                },
                {
                    "const": "RB05",
                    "title": "RB05 = Dyson Spot+Scrub Ai (RB05)"
                },
                {
                    "const": "358",
                    "title": "358 = Dyson Pure Humidify+Cool (PH01 or PH02)"
                },
                {
                    "const": "358E",
                    "title": "358E = Dyson Pure Humidify+Cool (PH03 or PH04)"
                },
                {
                    "const": "358K",
                    "title": "358K = Dyson Pure Humidify+Cool Formaldehyde (PH04 or PH05)"
                },
                {
                    "const": "438",
                    "title": "438 = Dyson Pure Cool (TP04 or TP06)"
                },
                {
                    "const": "438E",
                    "title": "438E = Dyson Pure Cool Formaldehyde (TP07 or TP09)"
                },
                {
                    "const": "438K",
                    "title": "438K = Dyson Pure Cool Formaldehyde (TP07, TP09, TP12, or PC2)"
                },
                {
                    "const": "438M",
                    "title": "438M = Dyson Pure Cool (TP11 or PC1)"
                },
                {
                    "const": "455",
                    "title": "455 = Dyson Pure Hot+Cool Link (HP02)"
                },
                {
                    "const": "455A",
                    "title": "455A = Dyson Pure Hot+Cool Link (HP02)"
                },
                {
                    "const": "469",
                    "title": "469 = Dyson Pure Cool Link Desk (DP01)"
                },
                {
                    "const": "475",
                    "title": "475 = Dyson Pure Cool Link (TP02)"
                },
                {
                    "const": "520",
                    "title": "520 = Dyson Pure Cool Desk (DP04)"
                },
                {
                    "const": "527",
                    "title": "527 = Dyson Pure Hot+Cool (HP04 or HP06)"
                },
                {
                    "const": "527E",
                    "title": "527E = Dyson Purifier Hot+Cool (HP07)"
                },
                {
                    "const": "527K",
                    "title": "527K = Dyson Purifier Hot+Cool Formaldehyde (HP09)"
                },
                {
                    "const": "527M",
                    "title": "527M = Dyson Purifier Hot+Cool (HP1/HP11)"
                },
                {
                    "const": "664",
                    "title": "664 = Dyson Purifier Big+Quiet Series (BP02, BP03, BP04, or BP06)"
                },
                {
                    "const": "739",
                    "title": "739 = Dyson Cool (CF1 or AM12)"
                }
            ]
        }
    }
}