config directions

Directions for v0.3.5 of fauxmo config.json drawn from various sources

Configuration
-------------

Copy config-sample.json to config.json
Edit config.json

The minimal configuration settings are:

  "FAUXMO": General Fauxmo settings
    - "ip_address": Server’s IP address or "auto"

  "DEVICES": 
  
  "PLUGINS: Top level key for your plugins, values should be a
  dictionary of (likely CamelCase) class names, spelled identically to
  the plugin class, with each plugin’s settings as a subdictionary.

    - "ExamplePlugin": Your plugin class name here, case sensitive.

      -  ``path``: The absolute path to the Python file in which the
         plugin class is defined (please see the section on user plugins
         above). Required for user plugins / plugins not pre-installed
         in the ``fauxmo.plugins`` subpackage.
      -  ``example_var1``: For convenience and to avoid redundancy, your
         plugin class can *optionally* use config variables at this
         level that will be shared for all ``DEVICES`` listed in the
         next section (e.g. an api key that would be shared for all
         devices of this plugin type). If provided, your plugin class
         must consume this variable in a custom ``__init__``.
      -  ``DEVICES``: List of devices that will employ ``ExamplePlugin``

         -  ``name``: Optional[str] – Name for this device. Optional in
            the sense that you can leave it out of the config as long as
            you set it in your plugin code as the ``_name`` attribute,
            but it does need to be set somewhere. If you omit it from
            config you will also need to override the ``__init__``
            method, which expects a ``name`` kwarg.
         -  ``port``: Optional[int] – Port that Echo will use connect to
            device. Should be different for each device, Fauxmo will
            attempt to set automatically if absent from config. NB: Like
            ``name``, you can choose to set manually in your plugin code
            by overriding the ``_port`` attribute (and the ``__init__``
            method, which expects a ``port`` kwarg otherwise).
         -  ``example_var2``: Config variables for individual Fauxmo
            devices can go here if needed (e.g. the URL that should be
            triggered when a device is activated). Again, your plugin
            class will need to consume them in a custom ``__init__``.

Each user plugin should describe its required configuration in its
module-level docstring. The only required config variables for all
plugins is ``DEVICES``, which is a ``List[dict]`` of configuration
variables for each device of that plugin type. Under ``DEVICES`` it is a
good idea to set a fixed, high, free ``port`` for each device, but if
you don’t set one, Fauxmo will try to pick a reasonable port
automatically (though it will change for each run).

Please see
```config-sample`` <https://github.com/n8henrie/fauxmo/blob/master/config-sample.json>`__
for a more concrete idea of the structure of the config file, using the
built-in ``SimpleHTTPPlugin`` for demonstration purposes. Below is a
description of the kwargs that ``SimpleHTTPPlugin`` accepts.

-  ``name``: What you want to call the device (how to activate by Echo)
-  ``port``: Port the Fauxmo device will run on
-  ``on_cmd``: str – URL that should be requested to turn device on.
-  ``off_cmd``: str – URL that should be requested to turn device off.
-  ``state_cmd``: str – URL that should be requested to query device
   state
-  ``method`` / ``state_method``: Optional[str] = GET – GET, POST, PUT,
   etc.
-  ``headers``: Optional[dict] – Extra headers
-  ``on_data`` / ``off_data`` / ``state_data``: Optional[dict] – POST
   data
-  ``state_response_on`` / ``state_response_off``: str – If this string
   is in contained in the response from ``state_cmd``, then the devices
   is ``on`` or ``off``, respectively
-  ``user`` / ``password``: Optional[str] – Enables HTTP authentication
   (basic or digest only)