View
7
Download
0
Category
Preview:
Citation preview
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
Recommended