Plugwise Bundle

See the download page to obtain this program

This code makes use of only publically available information about the Plugwise protocol. This information is not definitive, so the code should be treated only as indicative. This implementation and the information it is based on are not endorsed by Plugwise.

Description

This is a Java implementation of the Plugwise modules that monitor electricity usage. The code is a a bundle for OSGi (Open Services Gateway initiative). It is therefore not a standard Java application, but the core of the bundle contains everything that would be needed for such an application.

The PlugwiseTransceiver class supports Plugwise Circles connected via a Stick. The Plugwise network should (perhaps) have first been set up using the Source. The following limitations or uncertainties apply:

• Various aspects of the protocol and its format are not yet known (to me or others).
• Sequence numbers from the Circle+/Circle are not used. Instead commands are sent one at a time, waiting for the response.
• It is unclear whether it is sufficient to periodically set the Circle+ clock, or whether all Circle clocks need to be set. This is presumably OK since the Plugwise documentation says that it is the Circle+ that has the clock. It appears that Circles synchronise clocks with the Circle+ on the hour. It appears that clocks follow UTC, and have to be read or written by adjusting local time.
• A Circle sometimes refuses to respond to a valid request for a power buffer, as if the current buffer were locked. This problem goes away after the next buffer is written on the following hour. This may be related to using the Source in between runs of this bundle. The Source successfully reads the buffer even though the bundle does not.

The bundle is not complete because it relies on the CommAccess bundle from the author to provide a serial port service using Sun/Oracle JavaComm 2.0. However, an alternative bundle (e.g. the Knopflerfish one based on RxTx) could be used.

Installation

As this is a standard OSGi bundle, it should be installed in the usual way for the platform. The only unusual feature is that the bundle uses a configuration properties file. The code to handle this assumes that Knopflerfish is in use, so the properties file is expected to be in the Knopflerfish OSGi root directory.

Operation

Circles are periodically polled to perform the following tasks:

• The Circle+ clock is set every 24 hours to the PC clock, starting immediately after the bundle is started.
• The Circle energy consumption for the past hour is retrieved at 1 minute past the first hour after the bundle is started.
• The Circle instantaneous power consumption is retrieved at the configured interval in minutes, starting at this interval after the bundle is started.

OSGi events with the following parameters are supported. The format here is that supported by the Appel policy language:

• device_in(energy,lamp,lounge,14:00:00,70) means 70 watt-hours have been consumed by the lounge lamp in the hour starting at 2PM. The total of all energy readings has the form device_in(energy,,,14:00:00,130).
• device_in(power,lamp,lounge,,110) 110 watts are currently being consumed by the lounge lamp. The total of all power readings has the form device_in(power,,,,650).
• device_out(on,lamp,lounge) switches the lounge lamp on, while "device_out(off,lamp,lounge)" switches it off. Any message type apart from on and off is an error. If the entity name/instance are not defined in the mapping given by the property files, the event is ignored.

Licence

This program is free software. You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation - either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful but without any warranty, without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

You may re-distribute this software provided you preserve this README file. Bug reports should be sent to Ken Turner.

Acknowledgements

The protocol implementation was inspired by information from Maarten Damen and Roheve. Inspiration was also drawn from code by Gonium and by Sven Petai. The CRC calculation was adapted from code by Tiz.

History

• Version 1.0: First version, Ken Turner, 17th May 2011

Up one level to Communications Utilities