Plugwise

Protocol, set up guide and programming examples

Ilche Georgievskiilche.georgievski@iaas.uni-stuttgart.de

Room: IAAS 0.353

2017/2018Spring

Requisites

• Raspberry Pi set

• Plugwise USB Stick

• Plugwise Circle+

• Plugwise Source Application

• Basic python and Scala/Java skills

Plugwise System

StickCircle+ Circle

What can it do?

• Get status of appliances

• Switch circles on and off

• Measure electricity consumption

• Get historical electricity consumption

• Get circles‘s clock information

• Measure electricity generation

Photos by unknown authors licensed under CC BY-SA

Circle Dissected

High power relay (HF115FD)

Supercapacitor (4.7μF 400V)

Low power relay

Energy meter

(MCP3909)Clock

(LNK304DN)

SMD Resistor (1004)

ZigBee chip, controller and memory

(EM250)

Photos taken from http://domoticx.com/plugwise-stretch-hardware-van-circle-modules/

Plugwise System

StickCircle+ Circle

Main controllerNetwork controller

• Connection between the ZigBee network and the server

• Uses a serial protocol• Communicates directly to the Network

controller

• Controls and organises thenetwork

• Communicates with other nodesof the mesh network

Zigbee Mesh Network

Photos by unknown authors, licensed under CC BY-SA

Zigbee

• Wireless communication protocol

• Reliable and self-healing mesh network

• Looks for the quickest path

• Suitable when needed:– Low data transmission rates– Long battery life– Secure networking (128-bit AES encryption)

• Every device has its own MAC address

• Highly resistant to external inferences of other wireless systems

COMMUNICATION PROTOCOL

Plugwise

About

• All communication data is ASCII– Messages we deal with are hexadecimal values– When hexadecimal values are converted to floats, the results will be the same as in the

PlugwiseData.MDB

• Circle’s clock is set to UTC– 16-bit integer for minutes counts from midnight of the first day of the month

• Uses calibration to get the right power information

• Each circle holds an internal buffer with information about historical electricity consumption

• Stick needs to be initialized once a connection has been made

• Uses a CRC16 checksum– Calculated over full data strings– Added to each command

Steps

• The protocol uses the following steps for all commands handled by the stick

– Client sends a request to the stick

– Stick sends an acknowledgement upon receiving the request

– Stick sends a response with the result

Request (1)

Request code Command

000A Stick initialisation

0012 Circle’s current electricity consumption

0023 General information about a circle

0026 Circle calibration

003E Circle clock information

0048 Circle’s historical electricity consumption

RRRRMMMMMMMMMMMMMMMMCCCC

Request code

Circle’s MAC address CRC checksum

RRRRMMMMMMMMMMMMMMMMCCCC

Request code

Request (2)

• MAC address format– 000D6F000XXXXXXX

• Stick initialization command doesn’t take a MAC address as an argument

• Stick initialization command always has the same checksum

?

Acknowledgement

Ack code Explanation

00C1 Stick ack code

00E1 Stick negative ack code

00D7 Circle set clock ack code

00D8 Circle turned on ack code

00DE Circle turned off ack code

00F8 Circle interval ack code (energy generation)

00C2 Circle negative ack code

Sequence number

CRC checksum value

0000SSSSAAAACCCC

Indication code

Ack code

Response

Response code Command

0011 Stick initialisation

0013 Circle’s current electricity consumption

0024 Circle’s general information

0027 Circle calibration

003F Circle’s clock information

0049 Circle’s historical electricity consumption

RRRRSSSSMMMMMM…MMMMMMCCCC

Response code

Command-specific content CRC checksum value

Sequence number

Example response

Data Data type Explanation

0013 Integer Command response code

24BD Integer Sequence number associated with the request

000D6F0000C3ACE5 Unsigned 64bit integer Circle’s MAC address

0002 16bit integer Number of pulses based on consumption at 1s interval

0013 16bit integer Number of pulses based on consumption at 8s interval

000000AD 32bit integer Number of pulses based on consumption at 1h interval

0000 Unsigned 16bit integer

Related to electricity generation (probably)0000 Unsigned 16bit integer

000A Unsigned 16bit integer

032B Integer CRC16 checksum

001324BD000D6F0000C3ACE500020013000000AD00000000000AXXXX

PLUGWISE NETWORKHow to establish a Plugwise network?

Set up a network

1. Install the Source software (Windows)1. Get free license for non-commercial use2. Don‘t need Smile

2. Configure the devices (follow the ConfigurationWizzard)

1. Insert the stick into the computer and wait for it tobe configured

2. Enter the MAC of the circle+ and wait for it to beconfigured

3. Enter the Mac of the circle and wait for it to beconfigured

Remember the missing digit?

4. Get the missing digit

– MACs get automatically extended

– MAC address format

• 000D6F000XXXXXXX

• 000D6F0004B1E8C0

Finish and test

5. Fill in whatever in the next two steps in the Configuration Wizard

– Naming and pricing have no meaning for us

– Use this info only for testing using the Source

6. Test the circles

– Try switching them on and off

– Plug in some appliance and observe the electricity consumption

Troubleshooting (1)

• Circle not properly configured – reset it– Unplug the circle

– Plug in the circle for 2 seconds and unplug it again (2 times)

– Plug in the circle for 8 seconds and unplug it again

– Wait for 2 seconds before plugging in the circle

• If circle reset, all circle’s network details are deleted

Troubleshooting (2)

• After resetting, the circle will switch on after a fewseconds

• After switching on, the circle will automaticallyadd itself to the network

• If circle+ is reset, all other circles and the stick must be reset too– All network information is deleted– Network has to be recreated– Recreating the network takes longer (up to half an

hour)

PLUGWISE AND PYTHONSet up and examples

Installation

• Two options– python-plugwise: a simple Python library for Plugwise (Circle and

Circle+)– Plugwise-2-py: an extension of python-plugwise with various interfaces

(Web, MQTT, OpenHAB, Domoticz, Homey and Home Assistant)

1. Make sure that the following packages have been installed– setuptools

– python-dev

– git

2. Get the simple Python library code– git clone https://github.com/aequitas/python-plugwise

3. Install the library– python setup.py install (might need sudo)

Testing

• Default port is /dev/ttyUSB0

• Use plugwise_util to test the Circles

– Get the current electricity consumption• plugwise_util –m 000D5F0004B1E8C0 –p

• Output: power usage: 10.81W

– Turn off a Circle• plugwise_util –m 000D5F0004B1E8C0 –s 0

API

• Stick– class Stick(SerialPort)– init()

• sends the initalisation command to the stick• Invoked upon instantiating the classs

• Circle– class Circle(mac, stick)– get_power_usage()

– get_power_usage_history()

– get_info()

– get_clock()

– set_clock(dt)

– switch_on()

– switch_off()

– calibrate()

Examples

• Get the current electricity consumption

• Turn off a circle

from plugwise.api import *

DEFAULT_PORT = "/dev/ttyUSB0"

mac = "000D6F0004B1E8C0"

stick = Stick(DEFAULT_PORT)

circle = Circle(mac, stick)

print("Current electricity consumption in W: %.2f" % (circle.get_power_usage(),))

from plugwise.api import *

DEFAULT_PORT = "/dev/ttyUSB0"

mac = "000D6F0004B1E8C0"

stick = Stick(DEFAULT_PORT)

circle = Circle(mac, stick)

circle.switch_on()

print("The Circle has been turned off successfully.")

PLUGWISE AND SCALASet up and examples

Installation

• Make sure that the following tools have been installed– JDK8– Sbt

• Get the Scala code*– git clone git@github.com:BrianSetz/plugwise-standalone.git

– Switch to the with-assembly branch

• Based on– Futures– Akka Streams (Reactive Streams)– jSerialComm

*Thanks to Brian Setz for the implementation and making it standalone

Testing

• Plug in the Stick into the computer

• Open the project with IntellijIdea

• Go to the Main class in the test folder

– We want to establish a connection with the Stick

• Right click and Run Main

• Observe the output of the Run window

08:54:48.672 [main] INFO de.uni_stuttgart.serial.Serial$ - Opening serial port. comPort: COM3, baudRate: 115200, dataBits: 8, stopBits: 1, parity: 0, flowControl: 0, timeoutMode: 1, timeout: 40008:54:50.449 [plugwise-actor-system-akka.actor.default-dispatcher-2] DEBUG de.uni_stuttgart.plugwise.Plugwise - Response Code: 0011, Sequence Number: 0001, Parsing Packet: 00110001000D6F00029008120101300D6F0005AA0A998C30FF08:54:50.450 [plugwise-actor-system-akka.actor.default-dispatcher-4] DEBUG de.uni_stuttgart.plugwise.Plugwise - Sequence Number: 0001 completed08:54:50.451 [plugwise-actor-system-akka.actor.default-dispatcher-2] DEBUG de.uni_stuttgart.plugwise.Plugwise - STICK INIT Mac: 000D6F0002900812 Network: 300D6F0005AA0A99 (8C30) Connected: true08:54:50.454 [scala-execution-context-global-28] INFO de.uni_stuttgart.plugwise.main.Main$ - Plugwise USB connection opened successfully

API

• class Plugwise(port: String)– open()

– stickInit()

– circleOn(mac: String)

– circleOff(mac: String)

– circleInfo(mac: String)

– circleClockInfo(mac: String)

– circleSetClock(mac: String, dt: DateTime)

– circleCalibration(mac: String)

– circlePower(mac: String)

– circleInterval(mac: String, consInterval: Int, genInterval: Int)

– circleBuffer(mac: String, logAddress: Int)

– circleConsumption(mac: String)

– circleConsumption(mac: String, calibration: CircleCalibration, bufferInterval: Int)

– circleHistoricalConsumption(mac: String, bufferInterval: Int)

– circleHistoricalConsumption(mac: String, calibration: CircleCalibration, bufferInterval: Int)

Examples (1)

• Get the current electricity consumption

package de.uni_stuttgart.plugwise.main

import de.uni_stuttgart.plugwise.Plugwise

import grizzled.slf4j.Logging

import scala.util.{Failure, Success}

import scala.concurrent.ExecutionContext.Implicits.global

object Main extends App with Logging {

val plugwise = new Plugwise("COM3")

val openFuture = plugwise.open()

val mac = "000D6F0004B1E8C0"

openFuture.onComplete {

case Success(result) =>

info("Plugwise USB connection opened successfully")

plugwise.circleConsumption(mac).onComplete {

case Success(consumption) => info(s"Current electricity consumption in W: ${consumption.watt1s}")

case Failure(e) => error(e)

}

case Failure(exception) =>

error("Failed to open Plugwise USB connection", exception)

}

}

Examples (2)

• Turn off a circlepackage de.uni_stuttgart.plugwise.main

import de.uni_stuttgart.plugwise.Plugwise

import grizzled.slf4j.Logging

import scala.util.{Failure, Success}

import scala.concurrent.ExecutionContext.Implicits.global

object Main extends App with Logging {

val plugwise = new Plugwise("COM3")

val openFuture = plugwise.open()

val mac = "000D6F0004B1E8C0"

openFuture.onComplete {

case Success(result) =>

info("Plugwise USB connection opened successfully")

plugwise.circleOff(mac).onComplete {

case Success(r) => info("Circles has been turned off.")

case Failure(e) => error(e)

}

case Failure(exception) =>

error("Failed to open Plugwise USB connection", exception)

}

}

Create a JAR

• Run sbt assembly in the command line– It automatically detects the main class

– It compiles the project

– Packs class files and all dependencies into a single JAR file

– Location: target/scala_X.X.X/projectname-assembly-X.X.X.jar

• Specify manually a main class– Modify build.sbt so that it looks something like this:

lazy val commonSettings = Seq(

version := "0.1",

organization := "de.uni_stuttgart",

scalaVersion := "2.12.6"

)

lazy val app = (project in file("plugwise-standalone")).

settings(commonSettings: _*).

settings(

mainClass in assembly := Some("de.uni_stuttgart.app.Main"),

// more settings here ...

)

References

• M. Damen, Plugwise unleashed: A document explaining theprotocol used by Plugwise products. 2010.

• Roel‘s technical notepad. Plugwise Protocol Analysis. 2011.• Python Plugwise, python implementation,

https://bitbucket.org/hadara/python-plugwise/wiki/Home• Plugwise Standalone, Scala implementation,

https://github.com/BrianSetz/plugwise-standalone• Energy Saving with Plugwise,

https://www.slideshare.net/mdda/energy-saving-with-plugwise-apl2010-martine

• B. Vande Meerssche, G. Van Ham, G. Deconinck, J. Reynders, M. Spelier, and N. Maes. Practical use of energy management systems. In Proc. AmiEs'11, Chania, Crete, Greece, Sept. 2011.

• Plugwise FAQ, https://www.plugwise.com/en_US/frequently-asked-questions