platypush.plugins.zigbee.mqtt

class platypush.plugins.zigbee.mqtt.ZigbeeMqttPlugin(host: str = 'localhost', port: int = 1883, base_topic: str = 'zigbee2mqtt', timeout: int = 60, tls_certfile: Optional[str] = None, tls_keyfile: Optional[str] = None, tls_version: Optional[str] = None, tls_ciphers: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None, **kwargs)[source]

This plugin allows you to interact with Zigbee devices over MQTT through any Zigbee sniffer and zigbee2mqtt.

In order to get started you’ll need:

  • A Zigbee USB adapter/sniffer (in this example I’ll use the CC2531.
  • A Zigbee debugger/emulator + downloader cable (only to flash the firmware).

Instructions:

  • Install cc-tool either from sources or from a package manager.

  • Connect the Zigbee to your PC/RaspberryPi in this way: USB -> CC debugger -> downloader cable -> CC2531 -> USB. The debugger and the adapter should be connected _at the same time_. If the later cc-tool command throws up an error, put the device in sync while connected by pressing the _Reset_ button on the debugger.

  • Check where the device is mapped. On Linux it will usually be /dev/ttyACM0.

  • Download the latest Z-Stack firmware to your device. Instructions for a CC2531 device:

    wget https://github.com/Koenkk/Z-Stack-firmware/raw/master/coordinator/Z-Stack_Home_1.2/bin/default/CC2531_DEFAULT_20190608.zip
    unzip CC2531_DEFAULT_20190608.zip
    [sudo] cc-tool -e -w CC2531ZNP-Prod.hex
    
  • You can disconnect your debugger and downloader cable once the firmware is flashed.

  • Install zigbee2mqtt. First install a node/npm environment, then either install zigbee2mqtt manually or through your package manager. Manual instructions:

    # Clone zigbee2mqtt repository
    [sudo] git clone https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
    [sudo] chown -R pi:pi /opt/zigbee2mqtt  # Or whichever is your user
    
    # Install dependencies (as user "pi")
    cd /opt/zigbee2mqtt
    npm install
    
  • You need to have an MQTT broker running somewhere. If not, you can install

    Mosquitto through your package manager on any device in your network.

  • Edit the /opt/zigbee2mqtt/data/configuration.yaml file to match the configuration of your MQTT broker:

    # MQTT settings
    mqtt:
        # MQTT base topic for zigbee2mqtt MQTT messages
        base_topic: zigbee2mqtt
        # MQTT server URL
        server: 'mqtt://localhost'
        # MQTT server authentication, uncomment if required:
        # user: my_user
        # password: my_password
    
  • Also make sure that permit_join is set to True, in order to allow Zigbee devices to join the network while you’re configuring it. It’s equally important to set permit_join to False once you have configured your network, to prevent accidental/malignant joins from outer Zigbee devices.

  • Start the zigbee2mqtt daemon on your device (the official documentation also contains instructions on how to configure it as a systemd service:

    cd /opt/zigbee2mqtt
    npm start
    
  • If you have Zigbee devices that are paired to other bridges, unlink them or do a factory reset to pair them to your new bridge.

  • If it all goes fine, once the daemon is running and a new device is found you should see traces like this in the output of zigbee2mqtt:

    zigbee2mqtt:info  2019-11-09T12:19:56: Successfully interviewed '0x00158d0001dc126a', device has successfully been paired
    
  • You are now ready to use this integration.

Requires:

  • paho-mqtt (pip install paho-mqtt)
__init__(host: str = 'localhost', port: int = 1883, base_topic: str = 'zigbee2mqtt', timeout: int = 60, tls_certfile: Optional[str] = None, tls_keyfile: Optional[str] = None, tls_version: Optional[str] = None, tls_ciphers: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None, **kwargs)[source]
Parameters:
  • host – Default MQTT broker where zigbee2mqtt publishes its messages (default: localhost).
  • port – Broker listen port (default: 1883).
  • base_topic – Topic prefix, as specified in /opt/zigbee2mqtt/data/configuration.yaml (default: ‘base_topic’).
  • timeout – If the command expects from a response, then this timeout value will be used (default: 60 seconds).
  • tls_cafile – If the connection requires TLS/SSL, specify the certificate authority file (default: None)
  • tls_certfile – If the connection requires TLS/SSL, specify the certificate file (default: None)
  • tls_keyfile – If the connection requires TLS/SSL, specify the key file (default: None)
  • tls_version – If the connection requires TLS/SSL, specify the minimum TLS supported version (default: None)
  • tls_ciphers – If the connection requires TLS/SSL, specify the supported ciphers (default: None)
  • username – If the connection requires user authentication, specify the username (default: None)
  • password – If the connection requires user authentication, specify the password (default: None)
bind_devices(source: str, target: str, endpoint: Optional[str] = None, **kwargs)[source]

Bind two devices. Binding makes it possible that devices can directly control each other without the intervention of zigbee2mqtt or any home automation software. You may want to use this feature to bind for example an IKEA/Philips Hue dimmer switch to a light bulb, or a Zigbee remote to a thermostat. Read more on the zigbee2mqtt binding page.

Parameters:
  • source – Name of the source device. It can also be a group name, although the support is still experimental.
  • target – Name of the target device.
  • endpoint – The target may support multiple endpoints (e.g. ‘left’, ‘down’, ‘up’ etc.). If so, you can bind the source to a specific endpoint on the target device.
  • kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
device_ban(device: str, **kwargs)[source]

Ban a device from the network.

Parameters:
  • device – Display name of the device.
  • kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
device_get(device: str, property: Optional[str] = None, **kwargs) → Dict[str, Any][source]

Get the properties of a device. The returned keys vary depending on the device. For example, a light bulb may have the “state” and “brightness” properties, while an environment sensor may have the “temperature” and “humidity” properties, and so on.

Parameters:
  • device – Display name of the device.
  • property – Name of the property that should be retrieved (default: all).
  • kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
Returns:

Key->value map of the device properties.

device_groups(device: str, **kwargs) → List[int][source]

List the groups a given device belongs to.

Parameters:
  • device – Display name of the device.
  • kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
Returns:

List of group IDs the device is linked to.

device_remove(device: str, force: bool = False, **kwargs)[source]

Remove a device from the network.

Parameters:
  • device – Display name of the device.
  • force – Force the remove also if the removal wasn’t acknowledged by the device. Note: a forced remove only removes the entry from the internal database, but the device is likely to connect again when restarted unless it’s factory reset (default: False).
  • kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
device_rename(name: str, device: Optional[str] = None, **kwargs)[source]

Rename a device on the network.

Parameters:
  • name – New name.
  • device – Current name of the device to rename. If no name is specified then the rename will affect the last device that joined the network.
  • kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
device_set(device: str, property: str, value: Any, **kwargs)[source]

Set a properties on a device. The compatible properties vary depending on the device. For example, a light bulb may have the “state” and “brightness” properties, while an environment sensor may have the “temperature” and “humidity” properties, and so on.

Parameters:
  • device – Display name of the device.
  • property – Name of the property that should be set.
  • value – New value of the property.
  • kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
device_set_option(device: str, option: str, value: Any, **kwargs)[source]

Change the options of a device. Options can only be changed, not added or deleted.

Parameters:
  • device – Display name of the device.
  • option – Option name.
  • value – New value.
  • kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
device_whitelist(device: str, **kwargs)[source]

Whitelist a device on the network. Note: once at least a device is whitelisted, all the other non-whitelisted devices will be removed from the network.

Parameters:
  • device – Display name of the device.
  • kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
devices(**kwargs) → List[Dict[str, Any]][source]

Get the list of devices registered to the service.

Parameters:kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
Returns:List of paired devices. Example output:
[
    {
        "dateCode": "20190608",
        "friendly_name": "Coordinator",
        "ieeeAddr": "0x00123456789abcde",
        "lastSeen": 1579640601215,
        "networkAddress": 0,
        "softwareBuildID": "zStack12",
        "type": "Coordinator"
    },
    {
        "dateCode": "20160906",
        "friendly_name": "My Lightbulb",
        "hardwareVersion": 1,
        "ieeeAddr": "0x00123456789abcdf",
        "lastSeen": 1579595191623,
        "manufacturerID": 4107,
        "manufacturerName": "Philips",
        "model": "8718696598283",
        "modelID": "LTW013",
        "networkAddress": 52715,
        "powerSource": "Mains (single phase)",
        "softwareBuildID": "1.15.2_r19181",
        "type": "Router"
    }
]
factory_reset(**kwargs)[source]

Perform a factory reset of the device. Of course, you should only do it if you know what you’re doing, as you will lose all the paired devices and may also lose the Z-Stack firmware.

Parameters:kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
group_add(name: str, id: Optional[int] = None, **kwargs)[source]

Add a new group.

Parameters:
  • name – Display name of the group.
  • id – Optional numeric ID (default: auto-generated).
  • kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
group_add_device(group: str, device: str, **kwargs)[source]

Add a device to a group.

Parameters:
  • group – Display name of the group.
  • device – Display name of the device to be added.
  • kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
group_remove(name: str, **kwargs)[source]

Remove a group.

Parameters:
  • name – Display name of the group.
  • kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
group_remove_device(group: str, device: Optional[str] = None, **kwargs)[source]

Remove a device from a group.

Parameters:
  • group – Display name of the group.
  • device – Display name of the device to be removed. If none is specified then all the devices registered to the specified group will be removed.
  • kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
group_rename(name: str, group: str, **kwargs)[source]

Rename a group.

Parameters:
  • name – New name.
  • group – Current name of the group to rename.
  • kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
group_set(group: str, property: str, value: Any, **kwargs)[source]

Set a properties on a group. The compatible properties vary depending on the devices on the group. For example, a light bulb may have the “state” (with values "ON" and "OFF") and “brightness” properties, while an environment sensor may have the “temperature” and “humidity” properties, and so on.

Parameters:
  • group – Display name of the group.
  • property – Name of the property that should be set.
  • value – New value of the property.
  • kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
groups(**kwargs)[source]

Get the groups registered on the device.

Parameters:kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
log_level(level: str, **kwargs)[source]

Change the log level at runtime. This change will not be persistent.

Parameters:
  • level – Possible values: ‘debug’, ‘info’, ‘warn’, ‘error’.
  • kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
permit_join(permit: bool = True, timeout: Optional[float] = None, **kwargs)[source]

Enable/disable devices from joining the network. This is not persistent (will not be saved to configuration.yaml).

Parameters:
  • permit – Set to True to allow joins, False otherwise.
  • timeout – Allow/disallow joins only for this amount of time.
  • kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
reset(**kwargs)[source]

Reset the adapter.

Parameters:kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).
unbind_devices(source: str, target: str, **kwargs)[source]

Un-bind two devices.

Parameters:
  • source – Name of the source device.
  • target – Name of the target device.
  • kwargs – Extra arguments to be passed to platypush.plugins.mqtt.MqttPlugin.publish`() (default: query the default configured device).