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:
Image 1: serial port sniffing log after the clock change.
Following after that is the following data:
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
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.
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 🙂
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!
Yes, I am/was able to read out the power consumption history (buffers)
I will post a blog post about that soon!
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?
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
site formatting screws up lot of my detail in above. send me pm and I send correct datas without fukup reformat
I have more interesting information about the PowerInfo request.
If you want this info, reply to me via PM
How do I PM to deep? I assume need to register with this website but where?
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
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!!!)
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)
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
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
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.