Plugwise protocol unleashed part 3: internal clock information

Introduction

In the Plugwise protocol unleashed series, I will describe the plugwise protocol. As far as I have been able to re-engineer it. I did this re-engineering work because there is no Linux/OSX software available to control your plugwise devices. All information in these series are based on the 2.0 firmware version!

DISCLAIMER: use of the information in these articles is at your own risk.
This information is not supported by Plugwise B.V. in any way.

In this part of the series we will have a look at the device information request and response.

Circle internal clock

This blog post is about the internal clock of the Plugwise circle. This internal clock is used to for example log information about kWh usage per hour.
It’s important to keep the internal clock in sync with your PC, for correct data readings. Imagine this going wrong: logged kWh information about an device appears in a different hour. Not something you want.

So, how to test this? Well I just fiddled around a bit with my PC’s date and time.
Using a serial port sniffer I was able to see the following (unknown) data:

clock_info1
Image 1: serial port sniffing log after the clock change.

Following after that is the following data:

clock_info2
Image 2: more data following the clock change.

So looking at this I realized that code 003E must be some kind of extra check, to see if the clock is out of sync.
The 0016 must be the clock set command as it contains extra data in the command.

The clock information request (003E)

The request is fairly easy:

003E000D6F000055XXXXBF07

003E -> This is the request command code.
000D6F000055XXXX -> This is the mac address of the circle.
BF07 -> This is the CRC16 checksum

The response looks like this:

003F0D52000D6F0000552XXX1325350401457A0EFF

Split up for readability:

003F 0D52 000D6F0000552XXX 13 25 35 04 01 457A 0EFF

003F -> request return command code.
0D52 -> reverse checksum
000D6F0000552XXX -> mac address
13 -> internal clock hour (HEX)
25 -> internal clock minutes (HEX)
35 -> internal clock seconds (HEX)
04 -> internal clock day of the week (HEX)
01 -> ?
457A -> ? looks like some kind of checksum to me.
0EFF -> CRC16 checksum

The clock set command

The clock set request looks like this:

0016000D6F0000551C140A021501FFFFFFFF112536043B11

Split up for readability:

0016 000D6F0000551XXX 0A 02 1501 FFFFFFFF 11 25 36 04 3B11

0016 -> Command code
000D6F0000551XXX -> Mac address
OA -> Year (HEX) note this is the year in the plugwise style: 2010 = 10 (always substract 2000)
02 -> Month (HEX)
1501 -> Number of minutes (HEX)
FFFFFFFF -> Log buffer address (you can use this to reset your log buffers, more on this in later posts), FFFFFFFF won’t reset a thing!
11 -> Hour (HEX)
25 -> Minute (HEX)
36 -> Second (Hex)
04 -> Day of the week (HEX)
3B11 -> CRC16 checksum

So now we know how to read and set the internal clock of the plugwise circle.
See you guys next week!
Let me know if you have any questions, and also if there is anything specific you would like to see in the next plugwise unleashed post!

This is a multipart series, the other parts can be found here:
Plugwise protocol unleashed part 1:  introduction
Plugwise protocol unleashed part 2: device information

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

17 Responses to “Plugwise protocol unleashed part 3: internal clock information”

  1. […] the rest here: Plugwise protocol unleashed part 3: internal clock information … Share and […]

  2. Harmen says:

    Hi Maarten,
    thanks for all the work you’ve done! I’ve got a plugwise set here, but all the bytes, except the header/footer are +0x30. That includes the commands, the serial id, function arguments. It’s a brand new system so it could be I have a ref3, if such a thing exists. Feel free to e-mail me if you want more info.

  3. zynga chips says:

    i was beginning to imagine i may perhaps be the only human being whom thought about this, at the very least at this point i acknowledge i’m not weird :) i’ll make sure to see a number various articles right after i get a tad of caffeine in me, it is tough to read with out my coffee, take care :)

  4. Lieven says:

    Hello Maarten,

    very interesting information! Currently I’m using the Plugwise devices with the old firmware in combination with MisterHouse to control some devices in my home.

    Were you able to read out the power consumption history of the Circles with the new version of the firmware? I’d like to be able to get hold of this info so that I can add some monitoring to my automation environment.

    Keep on the good work!

  5. Maarten says:

    Yes, I am/was able to read out the power consumption history (buffers)
    I will post a blog post about that soon!

  6. Olli says:

    Hi. Great work on this.

    Does anyone know if there is a command to get the mac addresses for the plugs in the first place? Or is it always case of manually adding them in from the stickers on the plugs?

  7. Deep says:

    hi Maarten,

    i have analize the protocol deep and have discovered a number of things not documented (or documented as unkown) in your describe.

    by example, you miss ack from stick in pol.py code and yor describe

    Send code
    003E000D6F000055XXXXBF07

    but, you miss ack data
    00000D5200C11699 [len=21]

    0000 in first pkt after send instruction means ACK

    0D52 is pkt sequence #

    00C1 looks like status = OK

    1699 = CRC

    Look next packet…

    003F 0D52 000D6F0000552XXX 13 25 35 04 01 457A 0EFF

    003F = resp code

    0D52 = same as pkt seq above

    So, correct processing is:

    TX CMD:

    003E000D6F000055XXXXBF07

    RX ACK:

    00000D5200C11699

    RX RESP:

    003F0D52000D6F0000552XXX1325350401457A0EFF

    but look at ACK and RESP pkt, 0D52 is common in chars 4..8

    Look at long sniff, you see chars 4..8 increment 1 by one this is packet sequence.

    So protocol is 3 packets:

    Send to stick
    Stick ACK
    Data returns

    can also be OOB datas – valid RX packet is:

    PACKET DATAS

    you can also RX datas without , and these are OOB data’s

    I have pythn script to find this and strip

    ALso, if you send invalid command to stick, you get error response

    do send packet like 004A000D6F000055XXXX

    and you get ack with SEQ number

    then error packet

    000000Ex1699

    where 00Ex is error code of some type – if good request, is 00C1

    I have more infos from dig – maybe you like to pm me and I tell more.

    Oh, I also know how to detect association plugs like Olli wants

    bye

  8. Deep says:

    site formatting screws up lot of my detail in above. send me pm and I send correct datas without fukup reformat

  9. Deep says:

    I have more interesting information about the PowerInfo request.

    If you want this info, reply to me via PM

  10. Olli says:

    How do I PM to deep? I assume need to register with this website but where?

  11. YogiBear75 says:

    Hi Maarten,

    I would like to receive more information on the new protocol version :)
    Can you perhaps e-mail me some code, so I can adjust my Perl scripts ?
    I am using XPL-Perl with plugwise.pm and already made some adjustments.

    Thnx,

    Ronald

  12. JMcL says:

    Further to Deep’s analysis of the send command/ack/response sequence, there’s an additional useful response regarding the packet sequence number

    When a command packet is sent to the stick, the first reponse from the stick is a line in the form:

    PutFifoUnicast 33 : Handle 129 : 000D6F0000xxxxB3

    The ‘129’ in the line above is specific to the command sent. From what I’ve implemented it’s as follows:

    PowerChange (code=0017) : 33
    PowerInfo (code=0012) : 23
    Calibration (code=0026) : 60

    I presume other commands will also follow this pattern.

    The handle returned is the value (in decimal) of the packet sequence Deep refers to and will be used on the subsequent ACK and data packets, so the conversation is now along the lines of (leaving out frame start/ends and inserting spaces for clarity – CCCC represents CRC):

    SEND: 0017 000D6F0000xxxxB3 CCCC
    RECV: PutFifoUnicast 33 : Handle 129 : 000D6F0000xxxxB3
    RECV: 0000 0081 00C1 CCCC (note ‘0081’ = 129)
    RECV: 0000 0081 00D8 00D8000D6F0000xxxxB3 CCCC

    I guess this could be useful to optimise access to plugs. Fire a command, get the handle, and then keep track of responses received, leaving you free to send other commands in the meantime (Note: I haven’t tried this yet, it’s purely speculation!!!)

  13. Roelof says:

    My 0016 string is different (2 bytes added FFFF), probably because the firmware changed.

    After initialisation, just after the 0016 command, I also see an 0029 command, followed by a 003A is a reply/ This 003A reply contains data that is similar to the clock-time data of the 3E reply. I an not sure however, there is also a difference.

    SEND 0016 000D6F0000B1B64B 0B0552FB FFFFFFFF FFFF 12 03 02 07
    RECV 0000 sequ 00D7 000D6F0000B1B64B
    YOUR 0016 000D6F0000551C14 0A021501 FFFFFFFF 11 25 36 04

    SEND 0029 000D6F0000B1B64B

    RECV 003A sequ 000D6F0000B1B64B 02 03 18 07 15 05 11

    SEND 003E 000D6F0000B1B64B
    RECV 003F sequ 000D6F0000B1B967 12 03 00 07 01 45 7A
    YOUR 003F sequ 000D6F0000552XXX 13 25 35 04 01 45 7A

    Te time in my ‘message’ is 20u03[CET]=18u03[UTC] = 12u03 (hex), DoW=7 (sunday)
    The 01 45 7A trailer seems quite constant.

    I am wondering what to do with the FFFFFFFF (and FFFF) part, where you mention it has to do wite the logbuffers.
    The logbuffer formula you mentioned elsewhere seems changed. (both offset and divider), for my firmware. Boundaries are not at 32 bytes anymore but at 8, and the offset is bigger now (not sure how big)

  14. Roelof says:

    Oops, I messed up two responses while copy/pasting, but the timecode is still the same… Noticed it after submitting my comment.

    SEND 003E 000D6F0000B1B64B

    RECV 003F 0161 000D6F0000B1B64B 1203 02 07 01 45 7A

    SEND 003E 000D6F0000B1B967

    RECV 003F 0163 000D6F0000B1B967 1203 00 07 01 45 7A

  15. […] and more details become clear in the plugwise protocol. In Plugwise Unleased Maarten made this post, that describes a timesync between the modules and the computer. There is also a second DateTime […]

  16. Marc Dirix says:

    I’m using 0016 on all plugs to synchronize the internal clock monthly.
    But somehowe changing the plug clock als changes the timebase for the hourly logs.

    Does anyone now how these relate? The windows tool doesn’t seem to be bothered by it.
    Should I only update the circleplus?

    Best regards,

    Marc Dirix

  17. Marc Dirix says:

    Scratch that.

    I’ve found the the hourly logs no longer is in “hours” since date-X but now also is given in the same “year-month-month_minutes” format as in 0024.

Leave a Reply