Getting started with module development
Chris Mills
haven't seen it, the LightwaveRF range includes a 'WiFi Link' which,
despite its name, doesn't actually provide WiFi connectivity but does
allow ones iPhone or Android phone to control the product range.
The LightwaveRF forum has documented part of the UDP protocol used to
signal to the WiFi link to transmit messages to the devices and it
strikes me that this should be easy to integrate into FHEM.
I have been doing some reading, but not speaking German, I am finding
it challenging to get started with developing a module. I have put a
Perl script called 99_LWRF.pm into the /usr/share/fhem/FHEM directory
(on Ubuntu) and FHEM appears to be loading it, but what is the minimum
I need to define in that script in order to build a working system?
I have read about Interfaces and figure I need to implement dimmer and
switch, but how?
What other functions do I need as a minimum to implement?
I do not want to re-invent the wheel (or indeed bits of FHEM) so is
there a list of pre-defined functions that I should be using to for
example send out the UDP packets to a defined address (LightwaveRF
WiFi link listens for broadcast UDP packets).
I am relatively content with my ability to write Perl.
Would it be worth putting together a dummy module which does nothing
other than log but would show new developers like myself what they
need to implement as a minimum in order to get something up and
running?
Many thanks
Chris
Rudolf Koenig
> working system?
There are two models in fhem:
- one-level, where fhem is controlling a single device like a directly attached
heating controller. A barebone starting point would be the 00_TAHR.pm, which I
just checked in into the fhem/contrib directory.
Complete fhem example is the KM271, attached via a serial line to the fhem
box.
- two-level: fhem controls over a phyiscal device like the CUL a large number
of logical devices (like FS20 actors, S300 sensors, etc). Another example is
the TCM physical device and EnOcean logical devices.
I think in your case you'll need the latter one, so I would start with copying,
renaming and stripping down 00_TCM.pm and implement all the functions specified
in the Initialize function. This module would implement the functions for the
physical device (IODevice) attached directly to the fhem box.
The second module (copy,rename, adapt 10_EnOcean.pm) would implement the
logical devices like the dimmers (this is the client in fhem speak)
These two modules are connected by the iodevice calling the Dispatch function,
which is selecting with the help of the $iomodule->{MatchList},
$iomodule->{Clients} and $clientmodule->{Match} the correct client for a
certain type of message.
Chris Mills
I have successfully written some code to control my LightwaveRF
devices. Currently I can switch an appliance module on and off and I
can select an absolute level for my dimmers:
Example:
"define bed_light LWRF dimmer 2 2" defines a dimmer type device on
room 2 device code 2, then:
"set bed_light 100" brings it up to full brightness or:
"set bed_light 50" sets it to half brightness or:
"set bed_light 0" switches it off.
For the appliance module I can:
"define table_lamp LWRF switch 3 1" defines a switch type device on
room 3 device code 1, then:
"set table_lamp on" switches it on and:
"set table_lamp off" switches it off again.
At present, I have used the one-level approach as control of the
LightwaveRF devices is via a network attached 'WiFi link' which
receives UDP broadcasts and relays them using the proprietary radio
protocol. It is very fast - changes occur almost instantly.
However, I think that for the long term, the two level model would be
better. At present, the system does not support two way communication
but there is a lot of pressure on the developers to echo, via UDP
broadcasts, any remote RF the WiFi link hears. Obviously I can only
create one socket to listen on, so the system needs to be two level.
It looks like DevIO_OpenDev does not currently support UDP broadcast
sockets so should I create my own code to listen/send using this
method? If so, is it possible to connect this to the underlying code
so that I can use existing functions to actually send some data out
through the socket or receive incoming packets?
Secondly, I would like my devices to appear in the various pre-built
web/iPhone interfaces as if they were proper switches or lamps. Is
this possible at present by implementing certain functions or do the
developers of those interfaces need to write specific code for the
LightwaveRF device types? I am currently using Fhemobile on iPhone.
I feel that I am 50% complete but I want to be 100% complete. I have
been reading the code for things like the X10 and FS20 dimmers etc and
I can see that there are commands like on-for-timer etc, should I
implement these or are they specific to the X10 and FS20 devices?
Finally, would anyone be willing to assist in tidying my code and
would it be possible to integrate it into the FHEM source tree so
others may make use of it?
Chris
Rudolf Koenig
> better.
From the user point the two level approach has the advantage of being able to
use FHEM2FHEM in RAW mode, i.e. the remote fhem will be able to send commands
and to use autocreate. And it is easier to add different USB devices to handle
the same protocol.
> It looks like DevIO_OpenDev does not currently support UDP broadcast
> sockets so should I create my own code to listen/send using this
> method? If so, is it possible to connect this to the underlying code
> so that I can use existing functions to actually send some data out
> through the socket or receive incoming packets?
I haven't used UDP with perl yet, but I think from the programming point of
view it will be very much like TCP, up to sysread, which will be replaced with
somethink like rcv .
> should I implement these or are they specific to the X10 and FS20 devices?
What you should implement:
- "set <dev> ?" should return a space separated list of possible commands, with
the same prefix like the other modules.
- If you implement set on and off, then at least the FHEMWEB frontend will
allow to directly switch the device, without the need of a webCmd attribute.
- As the two main families (FS20 and HM) implement dim<Num>, a future dimmer
widget will more likely use these commands
> Finally, would anyone be willing to assist in tidying my code and
> would it be possible to integrate it into the FHEM source tree so
> others may make use of it?
I have no problems in giving you SVN access, but since my own TODO list is
quite long atm. I won't assist you much. Putting a module into the FHEM
directory is only allowed, if there is a proper documentation in the
commandref.html and if it is reasonably tested. Until then the contrib
directory is the correct choice.