So, I needed a few more Plugwise Circles to automate some devices at home. I’m using the very cool Perl toolkit by Mark Hindess to create an xPL compliant interface towards the devices on an NSLU2. Problem: the interface I used was only compatible with firmware v1, and of course the new Circles ship with a newer (and incompatible) firmware. Time to upgrade!

Thanks to the preparatory work of Maarten Damen and Roheve I didn’t have to reverse engineer the protocol myself. Credits to you guys! I upgraded the existing xpl-plugwise code that was originally developed by Jfn and I have put it in a git repository. It is available here.

I have tested the code on firmware v2.36 and v2.37. It seems the protocol was not changed after the last update. Thank you Plugwise 🙂

I have updated the xPL interface if you compare it to the original version of Jfn for Plugwise firmware v1: the power calculation logic is hidden from the user and the xPL messages are more matching the other schema defined by the project. Moreover, basic control can also be done with control.basic messages. You can query the status of Circles and switch them on and off. It is also possible to request a list of Circles that are known to the Circle+. You can query the live power consumption and you can readout the history energy usage averaged over 1-hour intervals.

I bought a separate Stick, Circle+ and Circle to be able to develop new features independently from the ‘live’ installation in our house. The live installation is used for long-duration testing. This second hardware set will also allow me to safely install future firmware updates in a development environment before applying them to the live installation. The fact that I did not have a separate environment was the reason it took me so long to upgrade to the new firmware. We’re relying too much on a working setup in our house to automatically switch lights and the amplifiers of our Squeezeboxen. Plugwise, if you read this, could you please reconsider opening up the protocol again? Closed protocols are so 1990’s…

The next sections show how the supported commands and responses look like for the various message schemas.

plugwise.basic

This is a custom schema that is specifically targeting the Plugwise devices. It is not officially endorsed by the xPL project team (yet?). It is mostly compatible with the original proposal by Jfn, with some modification to make it more compliant with existing schemas, but without breaking existing code to interface with Plugwise devices over xPL.

Controlling a Circle on

xpl-cmnd
{
hop=1
source=mhouse-mh.misterhouse
target=hollie-plugwise.hydra
}
plugwise.basic
{
command=on
device=551e4f
}

Generates this response:

xpl-stat
{
hop=1
source=hollie-plugwise.hydra
target=*
}
plugwise.basic
{
device=551E4F
type=output
onoff=on
}

Controlling a circle off

xpl-cmnd
{
hop=1
source=mhouse-mh.misterhouse
target=hollie-plugwise.hydra
}
plugwise.basic
{
command=off
device=994f99
}

Response:

xpl-stat
{
hop=1
source=hollie-plugwise.hydra
target=*
}
plugwise.basic
{
device=994F99
type=output
onoff=off
}

Request the state of a plug

This command allows you to retrieve some basic information on the status of a Circle. The response contains the onoff status, the address that is currently in use for the power consumption history, and the current date and time of the internal clock of the Circle. The address is important when you want to readout the power consumption over the last hour. See the ‘reading out power history‘ command below for more details on this.

xpl-cmnd
{
hop=1
source=mhouse-mh.misterhouse
target=hollie-plugwise.hydra
}
plugwise.basic
{
command=status
device=551e4f
}

Response:

xpl-stat
{
hop=1
source=hollie-plugwise.hydra
target=*
}
plugwise.basic
{
device=551E4F
type=output
onoff=on
address=239
datetime=201109201836
}

Requesting a list of known Circles

This command requests to the Circle+ (= the ZigBee coordinator) what other Circles are known. Internally, this command first queries for available Circles (max 64 excluding the Circle+) and then it requests for every detected plug the calibration values required for calculating the power consumption. This command is useful to ‘discover’ Circles in an application.

Do note that the values returned are a list of known devices by the coordinator (i.e. they have been part of the network in the past). It does not mean that all devices in the list are online at the time the command is sent.

Also note: if you issue this request and not all known nodes are online, it is normal that you receive some error responses. This is due to the fact that as a consequence of this command the xpl-perl Plugwise module also tries to retrieve the calibration values. If a certain circle is offline then this command will fail and an error response will be generated.

The request:

xpl-cmnd
{
hop=1
source=bnz-test.desktop
target=*
}
plugwise.basic
{
command=listcircles
}

And the corresponding response:

xpl-stat
{
hop=1
source=hollie-plugwise.hydra
target=*
}
plugwise.basic
{
command=listcircles
device00=98A5BE
device01=7310F6
}

Requesting the live power consumption

Now for the interesting commands if you want to retrieve the live power consumption of a Circle. In the previous version of the xpl-perl module for Plugwise you first needed to request the calibration information for a plug, then retrieve the number of pulses, and then do some calculations to determine the actual power consumption.
I have hidden all this code in the xpl-perl Plugwise module. Now you can request the live power consumption, and you, well, the live power consumption expressed in Watt. You get two results, one measurement over 1 sends, and one measurement over 8 seconds.

The corresponding xPL request looks like this:

xpl-cmnd
{
hop=1
source=bnz-sender.desktop
target=*
}
plugwise.basic
{
command=livepower
device=98A5BE
}

And the response:

xpl-stat
{
hop=1
source=hollie-plugwise.hydra
target=*
}
plugwise.basic
{
device=98A5BE
type=power
current=0.0229
current8=0.0263
units=kW
}

This means that the measured power over the last second interval is 22.9 W, and measured over the last 8 seconds the measured power consumption is 26.3 W.

Reading out historic power information

Every Circle keeps a log of the power consumption averaged out over one-hour time intervals. If you want to keep an eye on the average power consumption of a device, it is useful to be able to access that data. The alternative, polling the Circle frequently, will not yield as accurate results.

A critical piece of information to be able to read out the historic buffer is the current log address that is in use. Get it by sending a status request to the Circle. Then subtract one (we want to read out the last complete 1-hour interval) and send this command (assuming the output of the status command for Circle 7310F6 was ‘address=222’):

xpl-cmnd
{
hop=1
source=bnz-sender.desktop
target=*
}
plugwise.basic
{
command=history
device=7310F6
address=221
}

The corresponding response:

xpl-stat
{
hop=1
source=hollie-plugwise.hydra
target=*
}
plugwise.basic
{
device=7310F6
type=energy
current=0.044
units=kWh
datetime=201109131400
}

This response contains the following information: the ID of the device, the type of report that is generated, the energy used over the hour that is covered by the log address, the units in which the value is expressed (always kWh), and the date and time associated with the log address. This last piece of information is important for Circles that are not always online, and for cases where one wants to ‘dump’ the complete history that is present in the Circle memory.

control.basic

This is an official and supported message schema. The Plugwise devices can be controlled on and off. Other functions might be added later when it becomes clear how.

Controlling a Circle on

xpl-cmnd
{
hop=1
source=mhouse-mh.misterhouse
target=hollie-plugwise.hydra
}
control.basic
{
device=551e4f
type=output
current=enable
}

Generates this sensor.basic response:

xpl-stat
{
hop=1
source=hollie-plugwise.hydra
target=*
}
sensor.basic
{
device=551E4F
type=output
current=HIGH
}

Controlling a circle off

xpl-cmnd
{
hop=1
source=mhouse-mh.misterhouse
target=hollie-plugwise.hydra
}
control.basic
{
device=994f99
type=output
current=disable
}

Response:

xpl-stat
{
hop=1
source=hollie-plugwise.hydra
target=*
}
sensor.basic
{
device=994F99
type=output
current=LOW
}

log.basic

The Plugwise xPL client uses the standard log.basic message schema for reporting errors.

Error response

When an invalid command is issued or an invalid Circle ID is passed, an error response is generated. The error response contains a descriptive text string, the message that caused the error (in Stick dataformat) and the returned error code by the Stick.

xpl-stat
{
hop=1
source=bnz-plugwise.hydra
target=*
}
log.basic
{
type=err
text=Received error response
code=0023000D6F0000ABCDEF8EFB:00E1
}

Helper scripts

I wrote some helper scripts to generate the messages described in this document. You can find them here.

Have fun experimenting! Feedback is always welcome…