Plugwise xPL interface for v2 firmware

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…

10 thoughts on “Plugwise xPL interface for v2 firmware”

  1. Hi,

    Great that you build an xpl extention for Plugwise!

    Do you still work on it? I want to create to options:

    * detect and connect circles to the stick.
    * connect with sensors (Scan & Sense)

    Please let me know if I build something that is already in progress and how I can contribute to you release.

    Kind regards Ralph

  2. Hello Ralph,

    the xPL Plugwise code is semi-stable what I’m concerned (I’m using it without problems the last months). It is very easy to contribute changes. The code is open source and is available on github (https://github.com/hollie/xpl-perl). To contribute, just make a github account, clone my repository, and after you have added your changes send me a pull request. I can then easily integrate your addition in the main code database.

    I’m currently not working on integrating sensors or on adding circles to the network, so any code that would help supporting this is very welcome!

    Best regards,
    Lieven.

  3. Hi Lieven,
    I’m busy integrating your xpl-plugwise work on a QNAP NAS (with ARM cpu). I think I’m almost there, but I’m bumping on an error when starting the xpl-plugwise. The perl environment meets the prerequisites and XPL-Perl is compiled. I start the xpl-hub and xpl-logger and then I start the client like “/opt/bin/xpl-plugwise –verbose –plugwise-tty /dev/ttyUSB0”. Then I get this output:
    Listening on 192.168.1.253:59326
    Sending on 192.168.1.255
    Use of uninitialized value in subroutine entry at /opt/lib/perl5/site_perl/5.10.0/arm-linux/Digest/CRC.pm line 264.
    WR>STICK: 000AB43C

    When I want to list all the connected cicles, the xpl-plugwise outputs this:
    Use of uninitialized value $address in substr at /opt/lib/perl5/site_perl/5.10.0/xPL/Dock/Plugwise.pm line 954.
    Use of uninitialized value in subroutine entry at /opt/lib/perl5/site_perl/5.10.0/arm-linux/Digest/CRC.pm line 264.
    WR>STICK: 0026000D6F0000000000B034

    I get no xpl-stat back. (hub see’s everything’s connected, xpl-logger see’s the request going by).
    So I think the CRC.pm is the problem. Do you have any idea’s what could be the cause?

    This is the part round line 264 of CRC.pm:
    sub crc {
    my ($message,$width,$init,$xorout,$refout,$poly,$refin,$cont) = @_;
    _crc($message,$width,$init,$xorout,$refin,$refout,$cont,_tabinit($width,$poly,$refin)); <<<THIS
    }

    Thanks in advance (have a great 5th of May liberation day).

    Best regards,
    Bastiaan

  4. Hello Bastiaan,

    hmm, strange. At least everything points into the direction of a problem in the CRC module. I rely on this module to calculate the required CRC that is added to every line that is sent to/from the Stick, so it is normal that you get an error every time such a message is created (WR> or RD< in the log). I have successfully used the xPL lib on an ARM architecture (NLSU2) so I suspect it is something specific to your setup. Could you try to trace in the CRC module what parameter is uninitialized? Kind regards, Lieven. P.S. For further discussion on this: feel free to use the ticketing system on github: https://github.com/hollie/xpl-perl

  5. Thanks a lot for sharing this, i’ve just tryed it tonight with a freshly bought plugwise kit (2011 firmware), and it worked out of the box ! (whereas i had never set up an xpl hub before).

  6. It appears that the Circle plugs can store a set of on/off switch
    times and turn themselves on and off without having the Source running
    (no USB stick in operation).

    Do you know what the commands are to set up the table of timings?
    (I assume it is some sort of table, and that the settings
    can be interrogated).

  7. Hey Martin,

    yes, I am aware Circles support this ‘autonomous’ mode. I have not implemented this because I don’t see the value in doing that. I’m using specific home automation software (MisterHouse) for this purpose.

  8. Hi,

    I came across your site as I was searching for people using the Lantronix Xport!

    I know there are newer (better?) network modules (ESP8266, etc), but I recently inherited an Xport for free, so hoping to use that!

    Can you describe how you got it to work, or what hardware/software is needed? For example, after connecting my arduino uart directly to the xport (ttl levels), and the xport rj45 to my computer (crossover cable?) how does my arudino know what protocol the network host wants to use (tftp, http, telnet, etc)?

    I’m assuming the point of the xport is not to implement a tcp/ip stack on the controller, but not sure what arduino software I need to write to support the end pc networkuser application !

    Thanks!
    Ben

  9. Hey Ben,

    the best way to go is to read the reference manual for the XPort that you can find on the LanTronix website. Interfacing is trivial: just connect to the serial port on the XPort. You can then open a telnet session to the XPort over the network and all characters you send will be sent over the serial port and vice vera. Telnet is the only protocol that is supported on the devices I used.

    So there is no need to write special software for your microcontroller. Just a serial port interface is all you need.

    Best regards,
    Lieven.

Comments are closed.