Clone wiki

python-plugwise / Home

Welcome

python-plugwise is a Python library for communicating with Plugwise smartplugs (Circle & Circle+). Currently it's known to work only with the devices with firmwares from the year 2010 and later.

Disclaimer

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

I suggest never using this or any other wireless controlled switches for anything that can cause real damage if randomly and/or unexpectedly switched on/off.

Installation

You can install the library simply by issuing the following commands assuming you are on a Unix system and have python >= 2.6, mercurial and python-setuptools installed:

hg clone https://bitbucket.org/hadara/python-plugwise
cd python-plugwise
sudo python setup.py install

Usage

Besides the library the install command also installs a simple command line utility that can be used to try out basic the functionality:

$ plugwise_util -h
Usage: plugwise_util [options]

Options:
  -h, --help            show this help message and exit
  -m MAC, --mac=MAC     MAC address
  -d DEVICE, --device=DEVICE
                        Serial port device
  -p, --power           Get current power usage
  -t TIME, --time=TIME  Set circle's internal clock to given time.  Format is
                        'YYYY-MM-DD hh:mm:ss' use the special value 'sync' if
                        you want to set Circles clock to the same time as your
                        computer
  -C, --counter         Print out values of the pulse counters
  -c CONTINUOUS, --continuous=CONTINUOUS
                        Perform the requested action in an endless loop,
                        sleeping for the given number of seconds in between.
  -s SWITCH, --switch=SWITCH
                        Switch power on/off. Possible values: 1,on,0,off
  -l LOG, --log=LOG     Read power usage history from the log buffers of the
                        Circle.      Argument should be 'cur' or 'current' if
                        you want to read the log buffer that is currently
                        being written.     It can also be a numeric log buffer
                        index if you want to read an arbitrary log buffer.
  -i, --info            Perform the info request
  -q QUERY, --query=QUERY
                        Query data. Possible values are: time, pulses,
                        last_logaddr, relay_state
  -v VERBOSE, --verbose=VERBOSE
                        Verbose mode. Argument should be a number represeting
                        verboseness.      Currently all the debug is logged at
                        the same level so it doesn't really matter which
                        numbre you use.

$ python plugwise_util -d /dev/ttyUSB1 -m 000D6F00009966D5 -p
power usage: 1534.37W
$ python plugwise_util -d /dev/ttyUSB1 -m 000D6F00009966D5 -s off
$ python plugwise_util -d /dev/ttyUSB1 -m 000D6F00009966D5 -s on
$ plugwise_util -d /dev/ttyUSB1 -m 000D6F00009966D5 -l current
power usage log:
        2010-11-21 12 822.001342 Wh
        2010-11-21 13 675.205478 Wh
        2010-11-21 14 474.646599 Wh
        2010-11-21 15 419.697459 Wh

$ /usr/local/bin/plugwise_util -d /dev/ttyUSB1 -m 000D6F00009966D5 -q time
22:28:58
$ /usr/local/bin/plugwise_util -d /dev/ttyUSB1 -m 000D6F00009966D5 -q relay_state
0

Documentation

We haven't yet generated a documentation page, but the documentation is available in the docstrings so you can read it directly from the Python shell for now:

>>> import plugwise
>>> help(plugwise)
...
>>> help(plugwise.api)
...

Updated