==============
Plugin helpers
==============

Purpose
=======
In Domogik a helper is a little tool linked to a plugin that helps users to get information about hardware linked to a plugin.
For example helpers can help you to find your *IPX800 relayboard* on the network, display its status (which relay is on, etc.), list all *1wire*components...
But helpers are right now restricted : you can't use at the same time a plugin and its helper. 
Keep in mind that actual helpers format will totally change in following releases.

Using helpers
=============
Helpers page is a command line tool which is used from the web UI. So right now all helpers are a command with optional parameters.

To access this command line tool, go to **Administration > Tools > Helpers**. You should see the command line interface : 

.. image:: plugin_helper.png

Screen description 
------------------

On the top, there is the **command line entry**. On the right of this entry, you will find 2 buttons : 

* **Send** which will send the helper a command (you can also directly hit **enter**).
* **Clear** which will clean the output zone.

On the bottom, there is the **output zone** in which will display the output of the helper.

Which helpers are available?
----------------------------
See the corresponding plugin page to get available helpers (if no helper is mentionned, it is because there is no helper for this plugin).

You can also use the **help** command: ::

    $ help
    List of available helpers :
    - cidmodem
    - ipx800
    - mirror
    - onewire
    - plcbus
    - teleinfo
    Type 'foo help' to get help on foo helper

This command list all available helpers.

In addition to know which commands are available for one of these plugins, you can again use **help** like this: ::

    $ onewire help
    ds18s20 : Show detail for all DS18S20 devices
      Usage : ds18s20 <adaptator device>
    all : Show all devices found on onewire network
     Usage : all <adaptator device>
    detail : Show detail for a device.
      Usage : detail <adaptator device> <device id>
    ds2401 : Show detail for all DS2401 devices
      Usage : ds2401 <adaptator device>
    ds18b20 : Show detail for all DS18B20 devices
      Usage : ds18b20 <adaptator device>

Use a helper
------------
Example:

* helper : ipx800
* command : find

First, shut down the associated plugin : **Administration > Plugins > ipx800**. Click **Stop plugin**. Wait for plugin shutdown.

Next, launch the helper: ::

    $ ipx800 find
    List of all IPX800 boards found :
    192.168.0.150 : IPX800

Then, restart the associated plugin : **Administration > Plugins > ipx800**. Click **Start plugin**.

Helpers errors 
--------------
Plugin not shut down
^^^^^^^^^^^^^^^^^^^^

Example: ::

    $ ipx800 find
    warning: Plugin 'ipx800' is currently running. Actually, helpers usage are not allowed while associated plugin is running : you should stop the plugin to use the helper.
    In next releases, helpers will be implemented in a different way, so that they can be used while associated plugin is running

Missing parameter(s)
^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

    $ onewire all
    Missing parameters.
    Usage : all <adaptator device>

Helpers in the future
=====================
Following things should change in next releases :

* Helpers will really be included in plugins (no need anymore to shut down the plugin in order to use associated helper).
* We want to implement auto discovery for most plugins and integrate this feature in the web UI.

There are also other ideas :) ...