Converters

All devices are described by a specification with a list of converters in this file. It has a description of how converters work.

You can write you own external converter without change integration code. Just create xiaomi_gateway3.py file in Hass config folder. The first line should be:

from custom_components.xiaomi_gateway3.core.converters.devices import *

• Devices are checked by model name: string for Zigbee device and number for BLE and Mesh devices
• one specification can describe several models of devices as long as they do not have differences
• the new device is added to the top of the list, so it will have a higher priority when checking for a model match and you can override the built-in converters

Xiaomi Zigbee or Mesh devices

from custom_components.xiaomi_gateway3.core.converters.devices import *

DEVICES = [{
    "lumi.switch.n0agl1": ["Aqara", "Relay T1", "SSM-U01"],
    "required": [
        Converter("switch", "switch", mi="2.p.1"),  # bool
        MathConv("energy", "sensor", mi="3.p.1", multiply=0.001, round=2),
        MathConv("power", "sensor", mi="3.p.2", round=2),
    ],
    "optional": [
        ZigbeeStats,
        BoolConv("led", "switch", mi="4.p.1"),  # uint8
        MapConv("power_on_state", "select", mi="5.p.1", map={0: "off", 1: "previous"}),
    ],
}] + DEVICES

Other Zigbee devices

Some tips:

• ZOnOffConv - this is simple converter for on/off devices (relays and light)
  • first argument - it's entity name in Hass, example: switch, plug, outlet, channel_1, etc.
  • second argument - entity type in Hass, example: switch or light
• For multichannel devices you need add endpoint parameter, example: ep=2
• Some single-channel devices don't work on the 1st endpoint, you must also add enpoint parameter
• ZigbeeStats, ZTuyaPowerOn - this are converters with already specified the attribute name and entity type

Simple relay

from custom_components.xiaomi_gateway3.core.converters.devices import *

DEVICES = [{
    "01MINIZB": ["Sonoff", "Mini", "ZBMINI"],
    "required": [ZOnOffConv("switch", "switch")],
    "optional": [ZigbeeStats],
}] + DEVICES

Dimmer with brightness

DEVICES = [{
    "FNB56-ZSC01LX1.2": ["Unknown", "Dimmer", "LXZ8-02A"],
    "required": [
        ZOnOffConv("light", "light"),
        ZBrightnessConv("brightness", parent="light"),
    ],
    "optional": [ZigbeeStats],
}] + DEVICES

Relay with polling power

DEVICES = [{
    "TS0121": ["BlitzWolf", "Plug", "BW-SHP13"],
    "support": 5,
    "required": [
        ZOnOffConv("plug", "switch"),
        ZCurrent, ZPower, ZVoltagePoll,  # once per 60 seconds
    ],
    "optional": [
        ZigbeeStats, ZTuyaPowerOn,
        ZEnergyConv("energy", "sensor", multiply=0.01),  # once per 5 minutes
    ],
}] + DEVICES

Multichannel relay

Tuya multichannel relay with optional power_on_state.

DEVICES = [{
    "TS0115": ["UseeLink", "Power Strip", "SM-SO306E"],
    "required": [
        ZOnOffConv("channel_1", "switch", ep=1),
        ZOnOffConv("channel_2", "switch", ep=2),
        ZOnOffConv("channel_3", "switch", ep=3),
        ZOnOffConv("channel_4", "switch", ep=4),
        ZOnOffConv("usb", "switch", ep=7),
    ],
    "optional": [ZigbeeStats, ZTuyaPowerOn],
}] + DEVICES

Aqara Buttons

class ZAqaraOppleConv(Converter):
    zigbee = "multistate_input"
    map = {0: HOLD, 1: SINGLE, 2: DOUBLE, 3: TRIPLE, 255: RELEASE}

    def decode(self, device: "XDevice", payload: dict, value: Any):
        button = value["endpoint"]
        value = self.map.get(value["present_value"], UNKNOWN)
        payload[self.attr] = f"button_{button}_{value}"

DEVICES = [{
    "lumi.remote.b286opcn01": ["Aqara", "Opple Two Button", "WXCJKG11LM"],
    "lumi.remote.b486opcn01": ["Aqara", "Opple Four Button", "WXCJKG12LM"],
    "lumi.remote.b686opcn01": ["Aqara", "Opple Six Button", "WXCJKG13LM"],
    "required": [ZAqaraOppleConv("action", "sensor")],
    "optional": [ZigbeeStats],
}] + DEVICES