pyduofern

.. image:: https://travis-ci.org/gluap/pyduofern.svg?branch=master :target: https://travis-ci.org/gluap/pyduofern .. image:: https://coveralls.io/repos/github/gluap/pyduofern/badge.svg?branch=master :target: https://coveralls.io/github/gluap/pyduofern?branch=master

Disclaimer: this library is not endorsed by the company Rademacher, the manufacturer of home automation products under the label duofern. The name pyduofern was chosen to indicate the function of the library: communicating with duofern devices via python.

These are my efforts in porting the FHEM <http://fhem.de/fhem.html> Duofern USB-Stick <https://wiki.fhem.de/wiki/DUOFERN> based module to Homeassistant <https://home-assistant.io/>_. As of now the port is rather ugly, but it is usable enough to control my Duofern blinds. I did not port the Weather-Station related features of the original module -- Mainly because I do not own the corresponding hardware and have no means to test if it works. I only tested it with the model RolloTron Standard DuoFern 14233011 Funk-Gurtwickler Aufputz.

As reported in #31 <https://github.com/gluap/pyduofern/issues/31>_ 10-Digit codes recently announced by Rademacher are not supported as of now as the handshake/ protocol for these devices was not reverse engineered by anyone as far as I know.

This requires the Duofern USB Stick Art.-Nr.: 70000093 by Rademacher.

I do not provide any guarantees for the usability of this software. Use at your own risk.

License::

python interface for dufoern usb stick Copyright (C) 2017 Paul Görgen Rough python python translation of the FHEM duofern modules by telekatz (also licensed under GPLv2) This re-write does not literally contain contain any verbatim lines of the original code (given it was translated to another language) apart from some comments to facilitate translation of the not-yet translated parts of the original software. Modification dates are documented as submits to the git repository of this code, currently maintained at https://github.com/gluap/pyduofern.git <https://github.com/gluap/pyduofern.git>_

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 should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Getting Started

Install via::

 pip3 install pyduofern

or if you want the development version from github::

 pip3 install git+https://github.com/gluap/pyduofern.git@dev

udev configuration

to make your usb stick easy to identify deploy an udev rules <https://wiki.debian.org/udev>_ file in /etc/udev/rules.d/98-duofern.rules or the equivalent of your distribution. The following worked for my stick::

SUBSYSTEM=="tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", SYMLINK+="duofernstick"

Or, if you use several USB-Serial adapters with vendor 0403 and product 6001 find out the serial number of your stick (assuming it is currently registered as ``/dev/ttyUSB0```)::

user@host:~ > udevadm info -a -n /dev/ttyUSB0 | grep '{serial}' | head -n1
ATTRS{serial}=="WR04ZFP4"

As you can se for me the serial is WR04ZFP4. Use the following udev line (use the serial you found above)::

SUBSYSTEM=="tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", ATTRS{serial}=="WR04ZFP4", SYMLINK+="duofernstick"

Once the rule is deployed your stick should show up as /dev/duofernstick as soon as you plug it in. This helps avoid confusion if you use other usb-serial devices. Also be warned: The line also makes the stick accessible to non-root users. But likely on your system you will be the only user anyhow.

Getting Started

To start using your stick you can use the duofern_cli.py script which should have been installed together with the pyduofern module. Begin by choosing a 4 hex-digit system code. If you have already used the roller shutters with FHEM use the last 4 digits of your FHEM code to preserve pairings. Ideally write it down, if you forget it, you will likely have to chose a new system code and reset your devices in order to be able to pair them again. It is also a security feature which is why no default is provided.

Decide for a system configuration file. By default it will reside as a hidden config file in your home directory in ~/.duofern.json. Pass the config file to duofern_cli.py via the command line option --configfile. The default has the advantage that you do not always have to pass the config file when using the script. Initialize the config file with your system code with the following command::

duofern_cli.py --code <your chosen 4 digit hex code here>

or if you prefer your own configfile location

doufern_cli.py --code <your chosen 4 digit hex code here> --configfile

Now RTFM of the shutter to find out how to start pairing. Set the maximum and minimum positions according to the manual. If you want to experiment with the shutter first, chose the two positions very near each other. The motors shut down after a certain maximum runtime and you could exceed that while experimenting if you move the shutters up and down several times unless the min and max positions are close to each other.

Start out by pairing your first rollershutter::

duofern_cli.py --pair --pairtime 60

now initiate pairing via the buttons on your shutter. Once a shutter is paired it should show up in your config file and you can name it. Say the blind that popped up has the ID 408ea2, run the following to give it the name kitchen::

duofern_cli.py --set_name 408ea2 kitchen
# you can now try to also have it move up or down:
duofern_cli.py --up kitchen
# or try to set the position of a blind (0=down, 100=up)
duofern_cli.py --position 42 kitchen

Hopefully you now have working command line interface that knows how to move up or down your shutters. But the python interface can do more, (which I was so far too lazy to expose via the command line):

Indexing paired blinds

If you have the system code of your system but lost the list of configured blinds you can use the CLI to refresh the config file with all paired blinds.::

# assuming you lost the config file
duofern_cli.py --code <your code> --refresh --refreshtime 60

will start up the stick and listen for connecting blinds for 60 seconds. It will store all the blinds that were found in the default config file.a

Usage with Homeassistant

There is a custom component for homeassistant that can be easily deployed via hacs at <https://github.com/gluap/pyduofern-hacs>_

Usage from python

.. code-block:: python

from pyduofern.duofern_stick import DuofernStickThreaded
import time
stick = DuofernStickThreaded(device="/dev/duofernstick") # by default looks for /dev/duofernstick
stick._initialize() # do some initialization sequence with the stick
stick.start() # start the stick in a thread so it keeps communicating with your blinds
time.sleep(10) # let it settle to be able to talk to your blinds.
# your code here
# this uses internal variables of the duofern parser module and likely I will wrap it in
# the future.

print(stick.duofern_parser.modules['by_code']['1ff1d3']['position'])

command("1ff1d3", "up") # open the blind with code 1ff1d3

stick.command("1ff1d3", "down") # down the blind with code 1ff1d3

stick.command("1ff1d3", "stop") # stop the blind with code 1ff1d3

stick.command("1ff1d3", "position", 30) # set position of the blind with code 1ff1d3 to 30%

Look for an indication of possible commands in pyduofern/definitions.py I just translated them into python and did not explore what might be possible. It looks like a lot of functionality requires a weather station, but you can just as easily automate the stuff using your home automation and having it send the up and down commands instead of buying a weather station.

Changelog

0.36

• add periodic requests for status updates.

0.36

• add rudimentary tracking of successfully sent messages and resending of unacknowledged ones.

0.35.1

• fix issue with crashes when "sets" was not defined because a bogous device type was present in duofern config.

0.35.0

• limit message sending frequency.

0.34.3

• Fix issue with asynchronous code in synchronous part of the code that was breaking homeassistant.

0.34.2

• merged pull request by @realbuxtehuder that adds stop command to cli

0.34.1

• functionally equivalent to 0.34.0, removed shebangs where not required, moved unit tests outside of packaging

0.34.0

• merge callback state updates for covers introduced by @DomiStyle in #21 to master

0.33.0

• add smokedetector introduced by @DomiStyle in #20 to master

0.32.0

• fix case to try and fix #18 for sensorMsg

0.30.0

• breaking change: instead of creating multiple devices for single physical devices with multiple actor channels which was rather buggy add a channel parameter to the respective functions inpyduofern.duofern.Duofern() which allows to handle channels in a consistent manner. See discussion in https://github.com/gluap/pyduofern/pull/9 . For each device available channels are listed in in Duofern().modules['by_code'][code]['channels']. The default channel available for all devices is None, otherwise an int is expected.

0.25.2

• try to fix https://github.com/gluap/pyduofern/issues/2

0.25.1

• changed custom component to fix bug in switch implementation accidentally introduced recently.

0.25

• restarted from 0.23 to get somewhat working auto detection

0.24

• somewhat broken changes for auto detection

0.23.5

• python 3.7 support should enable current hassio version

0.23.3

• added --position to CLI

0.23.2

• renamed README.rst and moved version number from setup.py to __init__.py

0.23.1

• fixed references to repository url
• upped version for pypi release

0.23

• added recordings and increased coverage of unit tests (no result-based tests yet though -- just checking if every replay runs until the end without hanging)

0.22

• Added recording of actions for replay in integration tests
• Improved unit tests
• Enable travis
• Enable coveralls

0.21.1

• fixed bug where device IDs containing cc would be be messed up when inserting channel number.