Domogik (v0.1.0) USB Mail notifer plugin

As I'm currently managing to get my apartment automated, I was looking for a opensource way to do it my self so as to learn thing and hack a bit. I decided to start my home automation on the Domogik opensource project that presents a lot advantage quickly scanned after the break. But before coding something useful to switch on/off light and opens/shut roller blind I decided to make something useless like porting my Usb Mail Notifer python package on this project! This package is designed to light a cheap ($6) usb device that can be coloured by seven different colours(red, green, lightblue, darkblue, yellow, purple, white)

Summary

PART 1 - Home Automation? Domogik? Huuu?

PART 2 - Usb mail notifer plugin

    I - Why Domogik v0.1 and not Domogik v0.2
   II - The Plugin content

1. mlntf.xml 
   
2. bin/mlntf.py
   
3. lib/mlntf.py
   
4. url2xpl/mailnotifier_tech/<command_name>.xml
   
5. stats/mailnotifier_tech/sensor.basic-mlntf.xml

  III - The installation Process

1. Dependency
2. Installation
   a - Complete installation with fancy Screen Shots
   b - Summary installation:
3. Documentation

Conclusion

  I - The Domogik Home Automation project
 II - The USB Mail Notifier Domogik Plugin

PART 1 - Home Automation? Domogik? Huuu?

I found a very impressive project named Domogik, that is mostly written in python (Love It), is html5 compliant, is using standards as XPL network so as to communicate (Love it), and it's a French initiative (love it). But most of all the project got a great documentation and a huge community making it always enhancing and updating regarding to needs and feedbacks.
The project already got a second version v0.2 more modular and separating more atomically all elements simplifying enhancement and update of every parts (Web UI, android App, Rest server, plugins, xpl-network, database...).

The project work out of the box on every linux distributions and comes with an open source Android Apps !!! Awesome!

The biggest advantage to use this kind of project compare to home made solution is the community that publish a lot of hacks and DIY around this project making it living and giving you chance to profit features from each others project freely. A lot of plugins have already been developed to support common technologies like chacon appliances, telldus sticks, usbrelayboards, onewire, miror RFID, Karotz, etc...

PART 2 - Usb mail notifer plugin

I - Why Domogik v0.1 and not Domogik v0.2

I first choose to make my plugin compliant with the domogik v0.1 mainly because:

• I read somewhere that only a few things change between plugin designed for domogik v0.1 and v0.2 (xml files changes to json files... but seems that python code doesn't need to be changed) so not really painful evolution.
• v0.1 was all in one tarball(v0.2 is working with plugin repository and separated WebGui part), less changeable but the only thing I wanted for a first approach is something the simplest possible, to toy with it and dissect it.
• For me, v0.1 was more stable than v0.2, but but right now I can't say that it is false, both are stables and I will for sure evolve my plugin to v0.2 soon!

II - The Plugin content

I will not explain the way plugin are made (or a just bit), I reserve that for a future post that will explain way to code, and way plugin are working in Domogik.
In this post I will only make a brief overview on bunch of file that compose what is called a "plugin":

1. mlntf.xml 

   This file will contain all necessaries information for domogik to find the plugin other files, to characterise and get information about what does the plugin.

2. bin/mlntf.py

   This file is the entry point to the XPL network, this handle getting the plugin user configuration from the Data base, and filtering XPL messages that arrive on the XPL network.

3. lib/mlntf.py

   This file implement the desired plugin's behaviour. In our example it is just an interface to the UsbMailNotifier package.

4. url2xpl/mailnotifier_tech/<command_name>.xml

   This files will be used as "translator" to traduce url accessed by GUI widgets on the web GUI to XPL message sent on the XPL network.

5. stats/mailnotifier_tech/sensor.basic-mlntf.xml

   This will determine what information Domogik should "log" about the plugin. For example a plugin sent temperature you will inform domogik that you want it to "log" temperature by giving it this file.

III - The installation Process

Like Domogik v0.1 has not been designed to accept hot plugging plugins, so the way to install new plugin is to reinstall Domogik from sources after copying the desired plugin sources at the right place in Domogik sources. Every thing is made to not have to scratch already made configuration.
So first you should install once Domogik v0.1 and configure all the stuff around it(creation of domogik user, python => 2.6, mysql DB, domogik config file)

As I said if you want to reinstall on an already installed domogik you don't need to scratch every config you made, so reinstalling will not erase your configs.

1. Dependency 

   The plugin depends on a python package I made, so first if it is not done, you must download it and install it:
   See my previous post here

2. Installation

   a - Complete installation with fancy Screen Shots
   As I made a good "install & config" explanation in the doxygen documentation given in plugin tarball.
   1. So download USBMailNotifier_Plugin-v0.0.1.tar.gz
   2. tar -xzf plugin_tarball_name .
   3. In root plugin folder launch it by:
   $ firefox doxygen/html/index.html &
   
   b - Summary installation:
   Stop domogik:
   
   $ sudo /etc/init.d/domogik stop
   
   
   So as to really install the plugin, I made an "plugin_install_script" that copy all sources files correctly by just giving the Domogik root sources path.
   do it by placing you in the plugin root folder and type:
   $ ./install_MailNotifier_plugin.sh -c cp -p <path to domogik 0.1>
   
   Once plugin sources installed, you can just reinstall domogik and answer you don't want to scratch any configs(by default if you just press enter on each question it select the answer that doesn't scratch your preciouuus config).
   $ cd ../domogik-0.1.0 (or domogik source folder)
   $ sudo ./install.sh
   You need to enable the plugin by adding "mlntf= enable" in /home/domogik/.domogik/domogik.cfg
   
   $ sudo dmgenplug mlntf
   (or $ echo "mlntf= enable" >> /home/domogik/.domogik/domogik.cfg)
   
   Restart domogik:
   
   $ sudo /etc/init.d/domogik start
   
   That's all, plugin is now installed and ready to be configured. the configuration is done from the Domogik's Webui, I recommend you to use the doxygen documentation section configuration.

3. Documentation

   Addtionnal documentation on sources, installation, configuration can be found in the doxygen doc, in plugin root folder type:
   
   $ firefox doxygen/html/index.html &

Conclusion

I - The Domogik Home Automation project:  

Domogik is a very cool project and it is very easy to add a new feature, you just need to get the minimum knowledge about how does it work. Once done only a reduced bunch of files are required, and two steps needed to enable the plugin.
The plugin integration in Domogik is instantly made (thanks to the XPL network), and the User interface is already done (even the Android App is usable directly to act on your plugin)

II - The USB Mail Notifier Domogik Plugin:

The Plugin can be used by acting on UI buttons, but it can also be used to display event interesting event notifications appearing on Domogik or in a plugin (by sending a well formatted XPL message):
* Temperature too cold/hot in the bedroom making the plugin light red on the device
* Somebody came during home absent and rang the doorbell make the plugin light on yellow on the device


Any comments, feedbacks or questions are welcome.
Do not hesitate to contact me!
Cheers,

Sheda