Detail configuration key and goal of a controller

This update brings more detailled JSON object key description and try to improve what is the
main goal of a controller.

Change-Id: I2a4a7a3c6bf17c8e12f4bb56c8cba0d2ec048154
Signed-off-by: Romain Forlot <romain.forlot@iot.bzh>

2 files changed, 26 insertions, 11 deletions

diff --git a/docs/controller.md b/docs/controller.md
index 4012455..bf0a3c2 100644
--- a/docs/controller.md
+++ b/docs/controller.md
@@ -8,7 +8,10 @@
 ## Features
 
 * Create a controller application from a JSON config file
-* Each control (eg: navigation, multimedia, ...) is a suite of actions. When all actions succeed control is granted, if one fails control access is denied.
+* Create a controller application from a JSON config file.
+* A controller could be considered as a collection of actions that could be
+  mapped to a dynamically created verb or when receiving an event from any other
+  API.
 * Actions can either be:
   * Invocation of an other binding API, either internal or external (eg: a policy service, Alsa UCM, ...)
   * C routines from a user provided plugin (eg: policy routine, proprietary code, ...)
diff --git a/docs/controllerConfig.md b/docs/controllerConfig.md
index 6a21fd2..cf3c007 100644
--- a/docs/controllerConfig.md
+++ b/docs/controllerConfig.md
@@ -37,7 +37,8 @@ Each block in the configuration file is defined with
 ## Config is organised in sections
 
 * **metadata**: describes the configuration
-* **plugins or resources**: defines the set of functions provided by the plugins allowing to load additionnal resources (compiled C or lua)
+* **plugins or resources**: defines the plugins to be loaded as additionnal
+  resources (compiled C or lua).
 * **onload**: a collection of actions meant to be executed at startup time
 * **control**: sets the controls with a collection of actions, in dynamic api it could also specify the verbs of the api
 * **event**: a collection of actions meant to be executed when receiving a given signal
@@ -66,8 +67,9 @@ You can define the following keys or arrays of the following keys:
 
 * **uid**: mandatory.
 * **info**: optional
-* **action**: mandatory
-* **args**: optionnal
+* **action**: mandatory, an object or array of object describing an action and
+ explained in the later [Action Elements](<#Action Elements>) chapter.
+* **args**: optionnal, action's arguments.
 
 ## Control section
 
@@ -76,9 +78,11 @@ Control section defines a list of controls that are accessible.
 You can define the following keys or arrays of the following keys, moreover
 this section could be verb api:
 
-* **uid**: mandatory
+* **uid**: mandatory, used as the verb's name.
 * **info**: optional
-* **action**: the list of actions is mandatory
+* **action**: mandatory, an object or array of object describing an action and
+ explained in the later [Action Elements](<#Action Elements>) chapter.
+* **args**: optionnal, action's arguments.
 
 ## Event section
 
@@ -89,9 +93,12 @@ master-volume to speed.
 
 You can define the following keys or arrays of the following keys, moreover you can define an event from an another API with the following syntax "API/event".
 
-* **uid**: mandatory
+* **uid**: mandatory must match an event name with format **api/event_name**,
+ i.e: **low-can/messages.engine.speed**
 * **info**: optional
-* **action**: the list of actions  is mandatory
+* **action**: mandatory, an object or array of object describing an action and
+ explained in the later [Action Elements](<#Action Elements>) chapter.
+* **args**: optionnal, action's arguments.
 
 ## Plugin section
 
@@ -105,13 +112,18 @@ You can define the following keys or arrays of the following keys:
 * **info**: optionnal
 * **spath**: optionnal, semicolon separated paths where to find the plugin. This could be a compiled shared library or LUA scripts. Could be specified using CONTROL_PLUGIN_PATH environment variable also.
 * **libs**: mandatory, Plugin file or LUA scripts to load
-* **lua**: optionnal, C functions that could be called from a LUA script
+* **lua**: optionnal, a JSON object listing C functions that could be called
+ from a LUA script and could prefixed.
+  * **function**: string or array of string of C functions
+  * **prefix**: a prefix to be used with the listed C functions
 
 ## Personnal sections
 
 * **uid**: mandatory
 * **info**: optionnal
-* **action**: mandatory
+* **action**: mandatory, an object or array of object describing an action and
+ explained in the later [Action Elements](<#Action Elements>) chapter.
+* **args**: optionnal, action's arguments.
 * **any keys wanted**: optionnal
 
 You can define your own sections and add your own callbacks into the
@@ -238,4 +250,4 @@ afb-daemon --name=yourname --port=1234 --workdir=. --roothttp=./htdocs --tracere
 Afb-Daemon only loads controller bindings without searching for the other
 binding. In this case, the controller binding will search for a configuration file
 name '(prefix-)bindermiddlename*.json'. This model can be used to implement for testing
-purpose or simply to act as the glue between a UI and other binder/services.
\ No newline at end of file
+purpose or simply to act as the glue between a UI and other binder/services.