Table Of Content¶

Domoweb¶

Installation¶

Install Domoweb

Technical Documentation¶

Packs¶

Before creating a pack
Packs types :
- Iconsets
- Themes

Installation¶

Get the packages¶

Two components are needed to install Domoweb :

domogik-mq : the message queue component used by all components which want/need to use the message queue (Domogik, Domoweb, ...)
domoweb

You have to install Domogik-mq only if you don’t install Domoweb on the same server as Domogik. Please do as you did for Domogik-mq installation during installing Domogik and just set the install as client instead of master.

Note

The following commands assume that you are using the /opt/dmg/ folder as the root folder for Domoweb. And so Domoweb will be installed in the /opt/dmg/domoweb/ folder.

Download Domoweb :

$ cd /opt/dmg
$ wget --content-disposition https://github.com/domogik/domoweb/archive/0.4.0.tar.gz
$ tar xvzf domoweb-0.4.0.tar.gz
$ ln -s domoweb-0.4.0 domoweb
$ cd domoweb

Launch the installation script¶

Run the install script. If needed the install script provide options:

$ sudo python install.py -h
Usage: install.py [options]

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  --uninstall           Uninstall Domoweb
  --simul               Simulation mode for Uninstall
  --nodeps              Do not install dependencies
  -u USER, --user=USER  User that will run Domoweb (default: domoweb)
  --libdir=LIBDIR       Folder for domoweb lib files (default:
                        /var/lib/domoweb)
  --logdir=LOGDIR       Folder for domoweb log files (default:
                        /var/log/domoweb)
  --piddir=PIDDIR       Folder for domoweb pid files (default:
                        /var/run/domoweb)
  --noconfig            Do not install Init and /etc files
  --nodbupdate          Do not update the Domoweb DB
  --notest              Do not test Domoweb Installation

If you are ready launch it:

$ sudo ./install.py

The first step will install all required dependencies.

 [ Installing setuptools... ]
Setuptools version 0.6c11 or greater has been installed.
(Run "ez_setup.py -U setuptools" to reinstall or upgrade.)
 [ Installing dependencies... ]
Searching for django==1.4
Best match: Django 1.4
Processing Django-1.4-py2.7.egg
Django 1.4 is already the active version in easy-install.pth
Installing django-admin.py script to /usr/bin

Using /usr/lib/python2.7/site-packages/Django-1.4-py2.7.egg
Processing dependencies for django==1.4
Finished processing dependencies for django==1.4
...

System user that will launch DomoWeb. You should keep the default choice.

[ Checking user ]

Which user will run domogik (default : domoweb)?

[ Looking for user domoweb ] ==> User domoweb found

The script will now create the required folders, and assign them to the domoweb user.

[ Checking /var/lib/domoweb folder ]
[ Updating rights for user domoweb[1000] ]
[ Checking /var/log/domoweb folder ]
[ Updating rights for user domoweb[1000] ]
[ Checking /var/run/domoweb folder ]
[ Updating rights for user domoweb[1000] ]

If you already have DomoWeb configuration files, you will be asked for keeping them or not.

 [ Installing /etc/domoweb.cfg ]
You already have Domoweb configuration files. Do you want to keep them ? [Y/n] Y

The script will next install the system files.

[ Installing /etc/default/domoweb ]
[ Configuring /etc/default/domoweb ]
[ Installing /etc/rc.d/domoweb ]
[ Installing /etc/logrotate/domoweb ]

Database creation or update if already exist.

[ Updating Domoweb DB... ]
Syncing...
Creating tables ...
Installing custom SQL ...
Installing indexes ...
Installed 0 object(s) from 0 fixture(s)

Synced:
 > django.contrib.auth
 > django.contrib.contenttypes
 > django.contrib.sessions
 > django.contrib.messages
 > django.contrib.sites
 > django.contrib.admin
 > south

Not synced (use migrations):
 - domoweb
(use ./manage.py migrate to migrate these)

 domoweb
  (*) 0001_initial
  (*) 0002_auto__add_page__add_pagetheme
  (*) 0003_auto__del_field_page_theme_id__add_field_page_left__add_field_page_rig
  (*) 0004_root_page
  (*) 0005_auto__chg_field_page_right__del_unique_page_right__chg_field_page_id__


 [ Apply DB migration script ]
Running migrations for domoweb:
- Nothing to migrate.
 - Loading initial data for domoweb.
Installed 0 object(s) from 0 fixture(s)

The final test to check the Domoweb installation.

 ==> Everything seems to be good, DomoWeb should be installed correctly.
 ==> Testing installation
Please press Enter when ready.

[ Test imports ]
==> Imports are good
[ Checking global config file ]
==> Global config file exists and contains right stuff
[ Test user / config file ]
==> Domogik's user exists and has a config file
[ Check user config file contents ]
==> Config file correctly loaded
[ Checking init.d / rc.d ]
==> /etc/init.d/domoweb or /etc/rc.d/domoweb found with good permissions
[ Checking Domoweb DB ]
==> /var/lib/domoweb/domoweb.db found

==> ================================================== <==
==>  Everything seems ok, you should be able to start  <==
==>       DomoWeb with /etc/init.d/domoweb start       <==
==>             or /etc/rc.d/domoweb start             <==
==>  DomoWeb UI is available on                        <==
==>                            http://127.0.0.1:40404/ <==
==> ================================================== <==

Make Domoweb start with your computer¶

For Debian or Ubuntu systems:

$ sudo update-rc.d domoweb defaults

Start Domoweb¶

sudo /etc/init.d/domoweb start

Now, you can access UI on this url : http://127.0.0.1:40404/

Uninstall¶

$ sudo python install.py --uninstall

General description¶

Django and CherryPy¶

Django is the core of Domoweb. Django is a high-level Python Web framework with a very flexible template system. Unfortunately the web server provided with Django is not multitasks and not suitable for production environment. Instead of having the user to install himself Apache or other web server, we decided to use the CherryPy web server in order to provided a easy and quick solution.

RINOR direct and AJAX connections¶

For easy configuration, all RINOR request are processed through Django.

For the view generations, the pipe.py library is directly used to connect RINOR and retreive the data.
For AJAX requests from the browser, Django provides a mini REST service using the Tastypie library.
- http://django-tastypie.readthedocs.org

How Widgets are working¶

On Page Load¶

On page load, each widget JS file is loaded.

Create_widget() is called for each.
For each widget a jQuery class is created as a subclass of ui.widget_core.
The widget is registred on a list, sorted by sensor/actuator type.

On Page Ready¶

On page ready each widget/feature association is placed and configured.

On page ready, the initAssociation is called by the DOM event.
An AJAX fonction contact the RINOR server and retreive the associations list.
Each feature is identified and ready to be initialised with the linked widget element.
The _init fonction of the feature/widget is called.
...
The widget is bind to the event channel to receive all event notifications.
The widget try to get his last value state.
The RINOR server is connected to get the value. If the value exist in the database, the value is sent to the widget using the event channel. (Asynchrone)
When the event is receved. The state handler fonction is called, and display the widget state.

On State Event received¶

When a state event is receved (via RINOR). The state handler fonction is called on each widget.
If the feature matches the event identifier, the state handler process the data.
The new state is displayed.

On Command sent¶

A widget action is detected (click).
The widget prepare the command value to be send.
The command is send (AJAX) to the RINOR server, and the widget place himself in a waiting state.
If the command is received and ack by the plugin...
The widget leave the waiting state.
When the confirmation state event changed is receved (via RINOR). The state handler fonction is called on the widget.
If the feature matches the event identifier, the state handler process the data.
The new state is displayed.

How i18n is implemented¶

Django Internationalization¶

Domoweb translation is based on Django translation process: https://docs.djangoproject.com/en/1.4/topics/i18n/translation/

The translation process is based on gettext. The translations has to be implemented on three sections:

in Python view code
in Template code
in Javascript code

Python views¶

On each file:

from django.utils.translation import ugettext as _

Then for each string:

def my_view(request):
    output = _("Welcome to my site.")
    return HttpResponse(output)

Django templates¶

On each page:

{% load i18n %}

Then for each string:

<title>{% trans "This is the title." %}</title>

Javascript¶

First we need to create the translation catalog:

js_info_dict = {
    'packages': ('domoweb',),
}

urlpatterns = patterns('',
    (r'^jsi18n/$', 'django.views.i18n.javascript_catalog', js_info_dict),
)

And on main template:

<script type="text/javascript" src="{% url django.views.i18n.javascript_catalog %}"></script>

Then for each string:

string = gettext('this is to be translated')

Language files generation¶

The message file for each language needs to be created separately (with ‘-d djangojs’ option for the JS files):

$ django-admin.py makemessages -l en
$ django-admin.py makemessages -d djangojs -l en
$ django-admin.py makemessages -l fr
$ django-admin.py makemessages -d djangojs -l fr
$ django-admin.py makemessages -l it
$ django-admin.py makemessages -d djangojs -l it
...

After translation, re-adding the .po to the locale, the files are compiled to .mo files:

$ django-admin.py compilemessages

Note

If you use OSX remove before the bloody Apple files with:

find . -name ".AppleDouble" -depth -exec rm -Rf {} \;

Transifex¶

The Transifex service is used for the translation: https://www.transifex.net/projects/p/domoweb/

Before creating a pack¶

What are Domoweb packs ?¶

Packs are the first step to downloadable packages. For now each modulable code of domoweb are separated from Domoweb main code to a separated ‘packs’ subfolder and will sligtly move to downloadable packages along Domoweb versions.

Types of packs¶

Iconsets of pages icons

IconSet pack¶

Each iconset are specifically created for a different section of Domoweb (page, usage, etc ...) But one type is available so far in Domoweb 0.3: ‘iconset_page’

Pack structure¶

The iconset root folder name should be identical to the iconset id:

/var/lib/domoweb/packs/iconsets/page/< id >/...

or in dev. mode:

../src/packs/iconsets/page/< id >/...

Naming convention¶

Each icon should be named according to the info.json section:

< id >_< size >.png

(ex. myicon_16.png)

info.json¶

The info.json file declare all icons available in the set.

{
    json_version: 1,
    identity: {
        type: 'iconset_page',
        id: 'myicons',
        version: 0.1,
        name: 'My iconset',
        description: 'Description for iconset..',
        creator: 'Domogik',
        creator_email: 'xx@xxx.xx',
        ...
    },
    images: {...},
    icons: [
        {
            id: 'myicon',
            label: 'My Icon',
            sizes: [16, 32, 64],
        },
        {...},
    ],
}

version : (see Domogik info.json documentation page)
type : the type id for the widget element is ‘iconset_page’.
identity : (see Domogik info.json documentation page)
images : (see Domogik info.json documentation page)
icons : list of icons

Internal processing and data¶

Registration¶

When Domoweb starts the packs/iconsets/ folder is parsed
If the json version is supported:
- Each icon of the iconset is registered into the domoweb ‘PageIcon’ database. (Visible in Domoweb Admin > Core > Domoweb Data)

Todo

If not available the CSS file is generated .icon64-iconsetid-iconid { background-image:url(images/iconid_64.png);} .icon32-iconsetid-iconid { background-image:url(images/iconid_32.png);} .icon16-iconsetid-iconid { background-image:url(images/iconid_16.png);}

Icon association¶

The couple iconsetid-iconid is attribued to the page item on the Domogik table ui_page.

Applied icon style¶

To apply an icon to a HTML element, we attribute the icon css class:

class='icon<size>-iconsetid-iconid'

None

Table Of Content¶

Domoweb¶

Installation¶

Technical Documentation¶

Packs¶

Installation¶

Get the packages¶

Launch the installation script¶

Make Domoweb start with your computer¶

Start Domoweb¶

Uninstall¶

General description¶

Django and CherryPy¶

RINOR direct and AJAX connections¶

How Widgets are working¶

On Page Load¶

On Page Ready¶

On State Event received¶

On Command sent¶

How i18n is implemented¶

Django Internationalization¶

Python views¶

Django templates¶

Javascript¶

Language files generation¶

Transifex¶

Before creating a pack¶

What are Domoweb packs ?¶

Types of packs¶

IconSet pack¶

Pack structure¶

Naming convention¶

info.json¶

Internal processing and data¶

Registration¶

Icon association¶

Applied icon style¶