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.
So what is plugwise anyway?
Plugwise is a smart way of measuring power usage using a device called the Circle.
It’s basically a plug between your device and the power socket.
The device can be used to keep track of the following:
– Current power usage;
– historic power usage, using buffers in the device itself;
– you can also use it to power on/power off a device;
– you can also use it as standby killer (using a schema).
For more information visit: http://www.plugwise.com
General information
Before we can dive deep into the plugwise protocol, we are first going through some basics of the protocol in part one of this series.
Plugwise uses the zigbee protocol to communicatie over the air.
Once all of your devices have been setup using Plugwise source (the default Plugwise software) you can control your devices using the plugwise stick (this is a little USB stick)
Image 1: the plugwise stick
To send commands to the Plugwise stick, plugwise uses a serial communication protocol.
Actually the Plugwise stick has a FTDI FT232 UART aboard. The following information shows up when plugged into a Linux machine:
Bus 006 Device 003: ID 0403:6001 Future Technology Devices International, Ltd FT232 USB-Serial (UART) IC
The serial communication takes place with the following settings:
- Baud rate: 115200
- Data bits: 8
- Stop bits: 1
- Parity: none
Plugwise data packet
The Plugwise data packet looks like this:
Image 2: the Plugwise protocol frame.
The start frame must be sent before sending any other data, the hexadecimal presentation of the start frame looks like this:
\x05\x05\x03\x03
The data formats varies, an example might look like this:
0017000D6F0000236XXX01
This actually is an example of the power change command (switch a device on or off, in this case a device on command)
0017 is the command, 00D6F0000236XXX the mac address and 01 the power code (power on)
Followed by the data, is the CRC checksum.
The used CRC checksum by Plugwise is a CRC16 checksum (often reffered to as ymodem or zmodem), it has the following properties:
- Polynomial: 0x11021
- Seed value: 0x00000
- Xor mask: 0x00000
- Width: 16
The checksum is generated over the data piece of the packet.
Last part of the packet is the end frame, this is basically a control feed followed by a linefeed. Which looks the following way, in hexadecimal:
\x0d\x0a
This concludes the first part of the Plugwise protocol unleashed series. If you have any specific protocol questions, please leave them in the comments so I can talk about it in the next part of this serie.
Nice work!
I’ve used your protocol descriptions for the old plugs to write my own software in C that logs data to MySQL every 5 minutes. And I really like it and are hoping that version 2 will bring more accuracy to low power measures. I’m really looking forward for the next parts to come on this BLOG.
Thank you for the hard work.
Thanks for your feedback.
Version 2 has really accurate readings.. it even reads below 1 watt.
I am trying to make a crc16 calculation in java but this is kinda new for me. Right now I do not get how a polynominal could have 5 bytes (11021 as you suggest) is this a typo or do you know of some backgroundreading I can do to understand more of checksums?
Btw, I really like whst you have done so far.
That was my typo. I meant I thought crc16 needed a 2 byte polynom. So I do not get 0x11021
Ok, I have made a hugh mistake that took too many hours of troubleshooting. So I thought I would share this in case anyone else encounters the same problem. (Although probably it is due to my lack of software background / experience)
I programmed my method and as a test I calculated the checksum for 000A because I knew this had to be B43C. However, I thought 000A was a HEX value already (“A” being the value 10). In fact, 000A is a String that has to be converted to bytes before you can calculate the checksum. After it was found, I easily corrected of course.
Most of you might be loughing out loud and I am happy to have amused you :-). For the others: I hope I prevented unnecesary troubleshooting.
Hi guys, im currently working on a paper where i refer to Plugwise more than often and im trying to get around as to how each component works. I have a basic home 5 package with a stick a circle+ and 4 normal circle modules.
What i basically want to know is exactly how the data gets transferred between the stick and the modules. You seem to have explained just that but in a way that i cant exactly figure out some stuff since im not an expert in the field.
What i want to know is why the Circle+ is the one that sends the data to the stick and if any of the regular circle modules can send data too and the Circle+ is only there because it has a battery and 6-9 hours of clock operating time without power supply whereas the normal ones dont.
Thanks in advance and thanks for posting this
Does it only sends timestamps to each one of the nodes in the network just to see if they are alive?
Hello everyone.
That’s a really awesome work everybody has done. I currently got a Circle+/Circle Home Start from Plugwise for my master thesis research and I wanted to write a program in Java for retrieving power consumption from the Circle. I’ve read almost all the articles but I can’t understand how should I send the msg to the serial port. Here is a simple code I use:
serialPort = (SerialPort) portId.open(this.getClass().getName(), TIME_OUT);
serialPort.setSerialPortParams(DATA_RATE, SerialPort.DATABITS_8, SerialPort.STOPBITS_1, SerialPort.PARITY_NONE);
// Open the Streams
input = serialPort.getInputStream();
output = serialPort.getOutputStream();
// Add event Listeners
serialPort.addEventListener(this);
serialPort.notifyOnDataAvailable(true);
String text = “003E000D6F0000AF6414”;
String crc16 = Checksum.getCRC16_String(text);
String packet = text + crc16;
byte[] sentPacket = HexBin.decode(packet);
output.write(sentPacket);
But I can’t get any msg at all. I’m not very used to serial programming.
For the CRC16 I used the code here http://domoticaforum.eu/viewtopic.php?f=39&t=5803&p=45093&hilit=java+plugwise#p45093 (by Tiz).
I hope anyone can help me, thanks.
Hello, can anyone help me please.
I am trying to write a program in Java for comunicating with the Plugwise Circle.
I wrote a simple program which opens the port and writes to its OutputStream. I tried the following:
byte[] text = {0x05, 0x05, 0x03, 0x03, 0x30, 0x30, 0x30, 0x41, 0x42, 0x34, 0x33, 0x43, 0x0D, 0x0A};
output.write(text);
but it doesn’t work. I receive nothing. I have tried the RealTerm software with which I can send data (ASCII) to the serial port.
When I send this string:
\x05\x05\x03\x03\x30\x30\x30\x41\x42\x34\x33\x43\x0D\x0A
I get back the same string i captured with portmon software.
So i thought the java code I wrote might be wrong, the way I am trying to send “Hexadecimal” data.
Can anyone help me please…