Plugins development

Note

If you think something is not clear or is missing in this documentation, please send an email to our developers mailing list : domogik-developers@lists.labs.libre-entreprise.org and explain us clearly what is not clear or what could be added.

General informations

• What is new in 0.4 about Domogik plugins format ?
• Changelog of plugins format since Domogik 0.4
• Release numbers rules

First, create a repository and write some specifications

• Create the plugin repository on GitHub
• Write specifications

Branches management

• What is a branch in git ?
• The branches management is detailed in the workflow of a plugin development

Plugin name

Choose a name that describes the plugin as good as possible. Notice that a plugin can not use more than 8 characters and they should be all lower case. This restriction is linked to xPL and is not a Domogik limitation.

Prepare the plugin

See workflow, step 1

Now, you will have to create a few files for your plugin on the master branch.

• Plugin file tree
• Readme and changelog files
• .gitignore file

Before coding : branching to ‘develop’

See workflow, step 2

• Switch to the *develop* branch before starting your developments : follow the step 2 of the workflow
• If you want, you can create in one shot the main folders and files

Json file

See workflow, step 3

The info.json file it surely the most important part of a plugin. It will describe the configuration of the plugins, the features, the xPL messages to send and to listen, ... You should first read all this chapter, then make sure that you already defined the following part in your specifications :

• configuration parameters
• devices features, splitted in sensors and commands
• xPL messages used by these features
• the data to store in database

Starting to create the json file without being clear on these elements is useless!

Note

To help you to understand the way to create a json file, you can look on already existing plugins to see real examples.

• Json file overview
• Sample json file
• Convert the json file from Domogik 0.2/0.3 format to the new Domogik 0.4 format
• Identity part
• Configuration part
• Device types part
• Sensors part
• Xpl stats part
• Commands part
• Xpl commands part
• Resources :
  • Data types
  • Field types
  • Conversion files

Python part

See workflow, step 3

After creating a start script (used only by the developers), you will now create the python part of your plugin.

• start.sh file
• Python part
  • __init__.py files
  • Bin part
  • Library part
  • How to ...
    • Make the detected devices available in the user interface
    • ...

Dedicated administration page

See workflow, step 3

Some plugin may need some advanced configuration capabilities or some helpers feature that can be used from the administration interface. This is not mandatory.

• Add dedicated administration pages

Icon

See workflow, step 3

Your plugin should have an icon.

• Add an icon

Udev rules

See workflow, step 3

If needed, you can add some sample udev rules files for your plugin.

• Add some udev rules files

Documentation

See workflow, step 3

The documentation is a part important of a plugin! If it is not enough clear, the user may have some difficulties to use the plugin.

• Overview of the documentation process
• Doc tree
• How to write the documentation in *ReST* format (which is used by *sphinx*)
• What should contain the documentation ?
• The developers part
• Make your documentation published on ReadTheDocs.org

Tests

See workflow, step 3

Preparing some automated tests is something really important for a plugin. It will help you to test automatically the plugin after each commit and will help you to easily validate some contributions (pull requests).

• Tests
  • The testrunner tool
  • Travis CI (continuous integration)

Your plugin is ready ? Make some users test it

See workflow, step 4

Now, your plugin may be functional, documented and the tests are automated. It is time to release a version! But before, you should make some people test your plugin!

• Release your plugin by following the step 4 of the workflow

Release a version of your plugin

See workflow, step 5

• Release your plugin by following the step 5 of the workflow

..todo ::

• switch to develop
• create a branch per version for readthedoc ????
• update info.json version number
• update docs/conf.py version number
• do the dev/doc/tests
• switch to master when version is ready (see previous chapter)

Some other points

• Helpers
  • ...

• Data files