=============
REST /cmd
=============

The **/cmd** entry in REST is used by User Interfaces to send commands to devices. The url is a direct link to a command

The translation is done based on the db and the json plugin file.

Flow
====
.. actdiag::

	actdiag {
		get -> decode -> lookup -> gxpl -> precv -> psend -> stats -> lookup2 -> event -> encode -> http -> result

		lane ui {
              		label = "User"
			get [label = "http get /cmd"];
			result [label = "http 200"];
		}
		lane rest {
			label = "Rest"
			decode [label = "Decode /cmd"];
			gxpl [label = "generate xpl-cmd"]
			encode [label = "receive event"];
			http [label = "generate http response"];
		}
		lane stat {
			label = "Statsmanager"
			stats [label = "lookup sensor and device"];
			event [label = "generate device event"];
		}
		lane db {
			label = "Database"
                        lookup [label = "get command params from db"];
			lookup2 [label = "get sensor params from db"];
		}
		lane plugin {
			label = "Plugin"
			precv [label = "receive xpl-cmd"];
			psend [label = "send out xpl stats"];
		}
	}

Developper notes 
================
Url description
---------------
.. code-block:: none

    http://ip:port/cmd/<command id>/<param 1>/<value 1>/.../<param n>/<value n>

The goal is to be able to generate a xpl message based on a simple url.

The url is formatted like this :

* the first param is command id, this is a defined command in the DB
* the folowing parts are the parameters (key=value), these also need to be defined in the db

Example
-------
The folowiong data is in the DB:

Device
++++++
.. code-block:: none
    
    id = 1
    name = test
    usage = ventilation
    type = x10.relay

Commands
++++++++
.. code-block:: none
    
    id = 10
    name = command1
    xpl_command_id = 12

Command params
++++++++++++++
.. code-block:: none
    
    id = 11
    key = level

Xpl command
+++++++++++
.. code-block:: none
    
    id = 12
    device = 1
    schema = lighting.device

Xpl command param 
+++++++++++++++++
.. code-block:: none

    command = 12
    key = address
    value = 12

Now if we call the '/cmd/10/level/100 we will generate the folowing xpl command:
.. code-block:: none
	
	lighting.device {
		level = 100
		address = 12
	}

This example demonstrates how the url can generate any type of xpl message, the number of command params or xpl command params is unlimited.

The commands are dynamic parameters and need to be sent via the url, the xpl command params are staticly defined, these definitions are done during device creation and are not changeable afterwards.

How REST gets xpl-trig for a /command 
=====================================

* REST start
* REST do some init stuff
* REST try to get QUEUE_COMMAND_* values from database. If not get default values 
* REST create a queue for /command
* REST get a /command call
* REST create a thread for /command (like all others /foo)
* REST create and send XPL message 
* REST start counting for timeout (see QUEUE_COMMAND_TIMEOUT)
* while timeout not reached, REST read queue to get xpl-trig
* if timeout reached, REST send timeout message
* else :
    * REST transform xpl-trig in json data
    * REST send data

How UI will get status of device ?
==================================

REST only send a OK/KO response with the xpl-trig xPL message received when a /command is successfull. 
To get (for example), the level of a dimmable device after a "+10" increasing command, UI will use **/stats** or **/events** REST feature to get info from this device.