Skip to main content

Async library for Plugwise USB-stick

Project description

python-plugwise: An async python library to control Plugwise plugs Circle+ and Circle

This library was created to extent my Home Assisstant setup with the Plugwise legacy USB-stick to control the linked Circle+ and Circle plugs which could be controlled by the legacy Windows Source application supplied by Plugwise. As the primary goal is to support Plugwise nodes in Home Assistant, it can also be used independently.

Be aware this library does NOT support the new Plug (identified by having a local button) which complies to the Zigbee standard, while this is not the case for the legacy plugwise devices.

There's no official documentation available about the protocol of the Plugwise so this library is based on partial reverse engineering by Maarten Damen and several other sources and openHAB

The latest version of the library is published as a python package on pypi and currently supports the devices and functions listed below:

Plugwise node Relay control Power monitoring Comments
Circle+ Yes Yes Working
Circle Yes Yes Working
Scan N/A N/A Working
Sense N/A N/A Experimental (not tested)
Switch No No Not supported yet
Stealth Yes Yes Experimental (not tested)
Sting No No Not supported yet

When the connection to the stick is initialized it will automatically do a discovery of all linked nodes.

I would like to extend this library to support other Plugwise device types, unfortunately I do not own these devices so I'm unable to test. So feel free to submit pull requests or log issues through github for functionality you like to have included.

This library supports linking or removing nodes from the Plugwise network. The easiest way of linking new nodes is after connection calling:

<stick_object>.allow_join_requests(True, True)

This will automatically add any new node not yet registered to any network (i.e. after it is set back to factory defaults)


To install and use this library standalone use the following command:

pip install python-plugwise

If you want to control the Plugwise devices from Home Assistant, do not install this library but install this custom integration instead.

Example usage

The library currently only supports a USB (serial) connection (socket connection is in development) to the Plugwise stick. In order to use the library, you need to first initialize the stick and trigger a scan to query the Circle+ for all linked nodes in the Plugwise Zigbee network.

import plugwise
from plugwise.constants import SENSOR_POWER_USE

def scan_finished():
    Callback for init finished

    def power_update(power_use):
        Callback for new power use value
        print("New power use value : " + str(round(power_use, 2)))

    print("== Initialization has finished ==")
    for mac in plugwise.nodes():
        print ("- type  : " + str(plugwise.node(mac).get_node_type()))
        print ("- mac   : " + mac)
        print ("- state : " + str(plugwise.node(mac).get_available()))
        print ("- update: " + str(plugwise.node(mac).get_last_update()))
        print ("- hw ver: " + str(plugwise.node(mac).get_hardware_version()))
        print ("- fw ver: " + str(plugwise.node(mac).get_firmware_version()))
        print ("- relay : " + str(plugwise.node(mac).get_relay_state()))
        print ("")
    print ("circle+ = " + plugwise.nodes()[0])
    node = plugwise.node(plugwise.nodes()[0])
    mac = node.get_mac()
    print("Register callback for power use updates of node " + mac)
    node.subscribe_callback(power_update, SENSOR_POWER_USE["state"])

    print("start auto update every 10 sec")

    print ("Circle+ Poweruse last second (W)             : " + str(node.get_power_usage()))
    print ("Circle+ Poweruse last 8 seconds (W)          : " + str(node.get_power_usage_8_sec()))
    print ("Circle+ Power consumption current hour (kWh) : " + str(node.get_power_consumption_current_hour()))
    print ("Circle+ Power consumption previous hour (kWh): " + str(node.get_power_consumption_previous_hour()))
    print ("Circle+ Power consumption today (kWh)        : " + str(node.get_power_consumption_today()))
    print ("Circle+ Power consumption yesterday (kWh)    : " + str(node.get_power_consumption_yesterday()))
    print ("Circle+ Power production previous hour (kWh) : " + str(node.get_power_production_current_hour()))
    print ("Circle+ Power production current hour (kWh)  : " + str(node.get_power_production_previous_hour()))
    print ("Circle+ Ping roundtrip (ms)                  : " + str(node.get_ping()))
    print ("Circle+ RSSI in                              : " + str(node.get_rssi_in()))
    print ("Circle+ RSSI out                             : " + str(node.get_rssi_out()))

## Main ##
port = "/dev/ttyUSB0"  # or "com1" at Windows
plugwise = plugwise.stick(port, scan_finished, True)

print("stop auto update")


print("Exiting ...")


You can use as an example to get power usage from the Circle+

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python-plugwise-2.0.2.tar.gz (39.2 kB view hashes)

Uploaded source

Built Distribution

python_plugwise-2.0.2-py3-none-any.whl (46.5 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page