Plugwise unleashed document released

Today I am releasing the Plugwise Unleashed document. This document describes most of the Plugwise protocol.
The document can be downloaded from the downloads section on my site, or in the bottom of this post.
If you would like to know any more detail about the protocol, please drop a comment so I can have a look.
This is version 0.1 of the document so there might be some mistakes in it, please also let me know.

And last but not least if you like the document and use it, please at least reference my site/my document. Or, you could drop a donation that would be nice.

[download id=”5″]

You can leave a response, or trackback from your own site.

15 Responses to “Plugwise unleashed document released”

  1. Kronos says:

    Thank you very much for your work and your Documentation. Is it possible to get a little bit more detailed explanation how the Checksum has to be calculated? I try to implement Plugwise in my Windows based Home Automation System without using the original Plugwise Software.


  2. Smert says:

    Hi, thanks for your efforts and this doc.

    Implementing your script in Java, crc for the switch on package for one of my circles returns a 3-digit hex number.

    So then by playing a bit with it, I noticed that switch onoff packages containing powerstate code “00” indeed turn off a device, but any other power code “011” “1” or even “”-nothing turn the device on.

    Keep up the good work!

  3. Maarten says:

    @Smert: you need “01” to switch something on…

  4. Smert says:

    I don’t know, for me it works that way.
    As I said,

    “01” results in a shorter (wrong) crc for one of my circles so it doesn’t work. Then i noticed that no power on/off code (“01”, “00”) or whatever in it’s place (e.g. “001”, “101”) turns it on!

    I will post the exact messages and firmware info sometime.

  5. Marc Dirix says:

    I’ve also found the following.

    1) For newer firmware versions both returning ACK and DATA contain a command counter. These need to be considered when checking checksums.

    The ACK is now build as \5\5\3\3 0000 counter ACK CRC
    For DATA this is the same.

    2) For /the/ newest firmware turning on / off the circles (command 0017) has changed the acknowledge. For older circles it was 00D8 for both on and off. But newer firmware tends to return 0002 and 0003 for on / off repectively.

    3) To use the circle plus to detect known circles use the command “0018”.
    There are always 64 data-lines returned containing return command “0019” and either the mac of a circle, or FFFFFFFFFFFFFFFF.

  6. Olli says:

    When I try this I just get endless 0000000000C2 back from the stick. The same happens with any command I pass in. Anyone else experiencing problems like this? The kit works ok if I connect it to Windows/Plugwise Source.

  7. Marc Dirix says:

    @Olli can you type the complete string you send?

  8. Olli says:

    Hi Marc,

    Well what I am trying to do is to send first:


    and then:


    to each plug in order to get calibration response and then start looping:


    to each plug so I can read power data from them.

    While you would expect to get back 0000000000C1xxxx and then the response, what keeps happening to me is that I get back endless stream of 0000000000C2xxxx responses, which after reading various articles seems to be a waiting message from the stick while it is requesting the information.

    I have tried this with couple of different plug sets and seems to be the same result. It seems to me a bit like the connection jams or something. Do you guys close the serial port connection after each request/response or keep it open for multiple writes and reads?


  9. Marc Dirix says:

    I would say, either you forget to start the command with the command header “\5\5\3\3” or you have some strange portsettings.

  10. Paul Davies says:

    Hi Maarten,

    Thanks very much for this document. It’s helped us to develop a new application using the plugwise hardware.

    We’ve also managed to establish that the plugs communicate their energy consumption in bits 32-39 of the power information request. The value received can be converted to an integer and then to your preferred energy unit: we’ve found that multiplying the integer value by around 0.00942 gives energy consumption in watt hours, accurate within about 1.2% according to our testing.

    Hope this helps!


  11. Gary Knapper says:

    A guy at Plugwise suggested to look on this site for a Linux API for the Plugwise kit. I would like to be able to monitor and control the Plugwise kit remotely but without using their Windows PC based system. Is this an active open source project that is looking for contributors?

  12. Gary Knapper says:


    A guy at Plugwise dierected me to this site. I was thinking of buying some Plugwise smart sockets and light switches and would like to monitor and control them remotely but without using the Plugwise Windows PC system, but from Linux. I am happy writing my own code on a linux environment and I am looking for open source projects to do with Zigbee. Is this an active project and are you looking for contributors?

  13. Hollie says:


    is anybody aware of changes in the protocol between firmware version 2.27 (released 20090908) and version 2.34 (released 20101101)? I assume this document is based on v2.27.

    I plan to work on porting the xpl-perl interface to the new protocol. Currently it only supports the v1 of the firmware, but before I upgrade the hardware I’d like to check if I will be able to use this document as a basis for the port.

  14. […] I also used the findings I found at Maartens blog, but it is not complete yet, so that’s why I’m writing this. For the data frames […]

  15. Rongten says:


    Hello, I think there must be some difference between FW 2010 and 2009 since using a circle+ with FW2010 on domotiga that knows only FW 2009 some functionality (like power usage) are apparently not working correctly…


Leave a Reply