diff --git a/doc/item_scripts.rst b/doc/item_scripts.rst new file mode 100644 index 000000000..ea7f35444 --- /dev/null +++ b/doc/item_scripts.rst @@ -0,0 +1,263 @@ +Item scripts +============ + +Item scripts are used to update :doc:`items'` state and execute actions. +Scripts are placed in xc folder (**xc/uc** for `/uc/uc`, **xc/lm** for +`/lm/lm`) and may be either written in any scripting language or be binary +executables. The script file should have exec permissions. + +All the examples provided in this documentation are written in the classic +Bourne shell (bash). It is recommended to use dash or perl in the heavy loaded +production systems to provide better startup speed. Experience has shown that +the modern systems do not require the use of the lower-level languages compiled +into executable files: it complicates the integration and servicing, on the +other hand, the difference in the program operation is only a few milliseconds. + +The script always the max execution time (timeout) specified in the item +configuration (or default controller timeout). After that the system terminates +the script operation: firstly - voluntary, by sending SIGTERM, then - forcibly +by sending SIGKILL (this in-between time may be changed in the item +configuration with param *term_kill_interval*) + +Script or program always gets the environment variables: + +* all variables from the controller var file (:ref:`uc_cvars` or + :ref:`lm_cvars``) +* **PATH** variable with additional EVA bin and xbin subfolders +* **EVA_ITEM_ID** item ID which the script is being executed for +* **EVA_ITEM_TYPE** item type: unit, sensor or lvar, (lvars can also be + updated with a scripts) +* **EVA_ITEM_GROUP** full item group +* **EVA_ITEM_PARENT_GROUP** nearest parent group of the item (i.e. + building1/env/room1/temp1 - room1) +* **EVA_ITEM_FULL_ID** full item ID +* **EVA_ITEM_STATUS** current item status +* **EVA_ITEM_VALUE** current item state value + +The system considers the script to be successful if its exit code is 0. + +Item actions +~~~~~~~~~~~~ + +Item actions are used to control the units. After the :ref:`unit` action +has ben called, the controller executes the appropriate script. By default, +control scripts are placed in xc/uc/ folder and named ID, where ID is a unit +ID, for example, xc/uc/lamp1. This may be changed in the item configuration to +let i.e. one script execute actions for the group of units. + +The startup parameters of the action script include: + +* **param1** unit ID +* **param2** new unit status +* **param3** new unit value + +A simple example script: send toe command to `X10 +`_ controller via `mochad +`_ + +.. code-block:: bash + + #!/bin/sh + [ $2 -eq 0 ] && CMD="off" || CMD="on" + echo "pl $1 $CMD" | nc localhost 1099 + +Such script is actually universal for X10 (in case units are named according to +X10 - a1-aX) + +Another example: activate the third `EG-PM2-LAN +`_ plug. Here we access EG1_IP variable +from :ref:`uc_cvars` + +.. code-block:: bash + + #!/bin/sh + + EG-PM2-LAN $EG1_IP 3 $2 + +Another example: control the relay (4 modules, 1 relay block) by `Denkovi +AE `_ + +.. code-block:: bash + + #!/bin/sh + + ${RELAY1_CMD}.1.4.0 i $2 + +where in :ref:`uc_cvars`: + +.. code-block:: bash + + RELAY1_CMD = snmpset -v1 -c private RELAY_IP_ADDRESS .1.3.6.1.4.1.19865.1.2 + +In the previous examples, we used the same command for turning the units +on/off. Let us review more complex logic. The next example shows how EVA can +shut down the remote server machine and turn it on via Wake on LAN (tip: such +script requires more action_timeout in unit config): + +.. code-block:: bash + + #!/bin/sh + + case $2 in + 0) + ssh eva@${SERVER_IP} "sudo /sbin/poweroff" + ;; + 1) + wakeonlan ${SERVER_MAC} + ;; + esac + +In the :ref:`queue` history script is marked as completed if it +completed independently with 0 code, failed - if the code differs from 0. + +The script or program can display anything on stdout/stderr. This data, as well +the exit code, will be recorded in "out" and "err" fields of the +:ref:`result` dict. + +Sometimes it is useful to catch SIGTERM in the script/program, i.e. if you +operate the motor that must be stopped after the script gets a termination +signal. Warning:, the system does not track/stop child processes executed after +SIGTERM is sent to the script. + +Passive updates of item state +----------------------------- + +Passive updates are used to collect the state of the equipment which doesn't +report its state by itself. By default, scripts for passive updating of the +item state are named **ID_update**, where ID is a unit ID, for example: +*lamp1_update*. + +The status update script is being executed: + +* Every X seconds, if *update_interval* specified in the config is more than 0 +* After the unit action succeeds (if *update_exec_after_action=true* in config) + +The system considers the script was executed successfully if its exit code is +0, otherwise, its new item state is ignored. + +Passive update scripts get the following parameters: + +* **param1** "update" +* **param2** item ID + +Script should print on stdout only the new status and (optionally) value, +separated by space, i.e. + + 0 NEW_VALUE + +For the sensor, it's data should be printed as: + + 1 VALUE + +where 1 means the sensor is working properly. + +Let us analyze an example of a simple script, e. g. state update of the sensor +that monitors the remote machine + +.. code-block:: bash + + #!/bin/sh + + ping -W1 -c1 ${SERVER_IP} > /dev/null 2>&1 && echo "1 1"||echo "1 0" + +Unit status - the third `EG-PM2-LAN `_ +plug + +.. code-block:: bash + + #!/bin/sh + + EG-PM2-LAN evacc-rl5|cut -d, -f3 + +Update state of the relay (4 modules, 1 relay block) by `Denkovi +AE `_ + +.. code-block:: bash + + #!/bin/sh + + ${RELAY1_UPDATE_CMD}.2.0|awk -F\ '{ print $4 + +where in :ref:`uc_cvars`: + +.. code-block:: bash + + RELAY1_UPDATE_CMD = snmpget -v2c -c public RELAY_IP_ADDRESS .1.3.6.1.4.1.42505.6.2.3.1.3 + +Multiupdate scripts +------------------- + +:ref:`Multiupdates` allow updating the state of several items with +the one script which works like a normal passive update script and outputs the +states of the monitored items line-by-line: + +.. code-block:: bash + + item1_status item1_value + item2_status item2_value + ..... + +The order of the output should correspond to the order of the items in the +multiupdate. + +By default, multiupdate scripts are named **ID_update**, where ID is a +multiupdate ID, for example, *xc/uc/temperatures_update* for mu ID = +temperatures. + +For example, let's update all 8 units connected to the relay controlled by +`DS2408 `_ + +.. code-block:: bash + + #!/bin/sh + + w1_ds2408 28-999999999999 || exit 1 + +The script output will be as approximately follows: + +.. code-block:: bash + + 1 + 0 + 1 + 1 + 1 + 1 + 0 + 1 + +where each row contains the status of the unit connected to the corresponding +relay port. + +Commands +-------- + +Commands are used if you need to run some commands remotely on the server where +EVA controller is installed. Commands are executed with :doc:`controller cli +tools`, with SYS API function :`ref`:`cmd` or with :ref:`macro +function`. + +For command scripts: + +* Configurations are absent. Scripts are named as **xc/cmd/SCRIPT_NAME** +* Script timeout is set when it is started + +Example of a command usage: the speaker is connected to the remote machine. we +want to play some sound as an additional feedback after the certain macros or +actions are executed + +**xc/cmd/play_snd** + +.. code-block:: bash + + #!/bin/sh + + GAIN=-7 + + killall play > /dev/null 2>&1 && killall -9 play > /dev/null 2>&1 + play /data/snd/$1.wav gain ${GAIN} + +when you call the command, the sound file_name will be played. If you want to +wait until the playback is over add w=15 to API call i.e. to wait 15 seconds +before continue. + diff --git a/doc/items.rst b/doc/items.rst index d3370150f..70a34bce5 100644 --- a/doc/items.rst +++ b/doc/items.rst @@ -20,23 +20,23 @@ controller should be restarted to reload the configurations. Common item parameters ---------------------- -* id - item ID, i.e. 'lamp1'. Must be unique within one controller. even if +* **id** item ID, i.e. 'lamp1'. Must be unique within one controller, even if items are in the different groups. This makes some complications when designing the whole installation architecture but allows to keep EVA configuration and item scripts organized in a simple way and makes system administration and support much easier. -* group - item group, i.e. 'hall/lamps'. Assigned at the time of the item +* **group** item group, i.e. 'hall/lamps'. Assigned at the time of the item creation, the group can't be changed later to avoid synchronization problems. -* full_id - full item id (i.e. 'hall/lamps/lamp1'), read-only +* **full_id** full item id (i.e. 'hall/lamps/lamp1'), read-only -* oid - object id, unique within the whole installation, same as full_id, but +* **oid** object id, unique within the whole installation, same as full_id, but also contains the item type: 'unit:hall/lamps/lamp1', read-only -* description - item description +* **description** item description -* virtual - boolean (true/false) param which says is the item +* **virtual** boolean (true/false) param which says is the item :doc:`virtual` or real. .. _unit: @@ -105,86 +105,88 @@ most cases, the system itself replaces the blank value with "null". Unit parameters ~~~~~~~~~~~~~~~ -* expires - interger value, time (seconds) after which the item state is +* **expires** interger value, time (seconds) after which the item state is considered "expired". If the item state was not updated during this period, the state automatically is set to -1 (error), value is deleted (set to null). If 'expires' param is set to 0, this feature is disabled. The minimum expiration step is 0.1 sec. -* mqtt_update = "notifier:qos" - if set, the item may receive active state +* **mqtt_update = "notifier:qos"** if set, the item may receive active state updates through the notification from the specified :ref:`MQTT server`. Example: "eva_1:2". -* snmp_trap - if set, the item may receive active state updates via +* **snmp_trap** if set, the item may receive active state updates via :doc:`/snmp_traps`. -* update_exec - a :doc:`script` for passive update of the item +* **update_exec** a :doc:`script` for passive update of the item state, "xc/uc/ITEMID_update" by default. -* update_interval - integer value, time (seconds) interval between the calls +* **update_interval** integer value, time (seconds) interval between the calls for passive update of the item. Set 0 to disable passive updates. Minimum step is 0.1 sec. -* update_delay - interger value, delay (in seconds) before the next call of the - passive update, may be used to avoid multiple update scripts of the different +* **update_delay** interger value, delay (in seconds) before the next call of + the passive update, may be used to avoid multiple update scripts of the + different items run simultaneously. -* update_timeout - integer, value, time (seconds) in which the script of the +* **update_timeout** integer, value, time (seconds) in which the script of the passive update should finish it's work or it will be terminated. -* action_allow_termination - boolean, allow the currect running action +* **action_allow_termination** boolean, allow the currect running action termination by external request. -* action_always_exec - boolean, :doc:`always execute` the +* **action_always_exec** boolean, :doc:`always execute` the actions, even if the intended status is similar to the current one -* action_enabled - boolean, allow or deny new actions queue/execution +* **action_enabled** boolean, allow or deny new actions queue/execution -* action_exec - a :doc:`script` which performs the action, +* **action_exec** a :doc:`script` which performs the action, "xc/uc/ITEMID" by default. -* action_queue={0|1|2} +* **action_queue={0|1|2} - * 0 - action queue is disabled, if the action is running, new actions are not - accepted - * 1 - action queue is enabled, all new actions are put in queue and executed + * **0** action queue is disabled, if the action is running, new actions are + not accepted + * **1** action queue is enabled, all new actions are put in queue and executed in a normal way - * 2 - queue is disabled, new action terminates the current running one and + * **2** queue is disabled, new action terminates the current running one and then is being executed -* action_timeout - integer, value, time (seconds) in which the script of the +* **action_timeout** integer, value, time (seconds) in which the script of the action should finish it's work or it will be terminated. -* auto_off - integer, the simple automation parameter: the command to turn the +* **auto_off** integer, the simple automation parameter: the command to turn the unit off (call an action to set status = 0) will be executed after the indicated period of time (in seconds) after the last action performed for this unit. Set 0 to disable this feature. Minimum step is 0.1 sec. -* mqtt_control = "notifier:qos" - item gets actions through the notifications +* **mqtt_control = "notifier:qos"** item gets actions through the notifications from the specified :ref:`MQTT server`, for example "eva_1:2", actions should be sent to path/to/unit/control (i.e. unit/hall/lamps/lamp1/control) in a form of the text messages "status [value] [priority]". If you want to skip value, but keep priority, set it to null, i.e. "status 0 null 50". -* status_labels - "labels" used to display the unit statuses by the interfaces. - Labels may be changed via :doc:`/uc/uc_api` or :doc:`uc-cmd`, in the - following way: status:number = label, i.e. "status:0" = "stop". By default the - unit has labels "status:0" = "OFF", "status:1" = "ON". +* **status_labels** "labels" used to display the unit statuses by the + interfaces. Labels may be changed via :doc:`/uc/uc_api` or + :doc:`uc-cmd`, in the following way: status:number = label, i.e. + "status:0" = "stop". By default the unit has labels "status:0" = "OFF", + "status:1" = "ON". -* term_kill_interval - integer, difference (in seconds) between stopping and - forceful stopping the action script. Tip: sometimes it is useful to catch - SIGTERM in the script to exit it gracefully. Cannot exceed the value of - timeout - 2, where timeout - default timeout, set in a controller config. +* **term_kill_interval** integer, difference (in seconds) between stopping and + forceful stopping the action or update script. Tip: sometimes it is useful to + catch SIGTERM in the script to exit it gracefully. Cannot exceed the value of + timeout** 2, where timeout** default timeout, set in a controller config. -* update_exec_after_action - boolean, start passive update immediately +* **update_exec_after_action** boolean, start passive update immediately after the action is completed (to ensure the unit state has been changed correctly) -* update_if_action - boolean, allow or deny passive updates while the action is - being executed +* **update_if_action** boolean, allow or deny passive updates while the action + is being executed -* update_state_after_action - boolean, if action completed successfully, the +* **update_state_after_action** boolean, if action completed successfully, the controller assumes that its actual unit state has ben changed correctly and sets it without calling/waiting for the state update. @@ -208,10 +210,10 @@ script). The sensor can have 3 statuses: -* 1 - sensor is working and collecting data -* 0 - sensor is disabled, the value updates are ignored (this status may be set +* **1** sensor is working and collecting data +* **0** sensor is disabled, the value updates are ignored (this status may be set via API or by the user) -* -1 - sensor error ("expires" timer went off, the status was set because the +* **-1** sensor error ("expires" timer went off, the status was set because the connection with a physical sensor got lost during passive or active update etc), when the sensor is in this status, it's value is not sent via the notification system to let the other components work with the last valid data. @@ -242,7 +244,7 @@ Sensor parameters ~~~~~~~~~~~~~~~~~ Sensors have the same parameters as :ref:`units`, except the don't have -action_*, auto_off, mqtt_control, status_labels and term_kill_interval. +action_*, auto_off, mqtt_control and status_labels. .. _lvar: @@ -329,9 +331,9 @@ Multiupdates have the same parameters as :ref:`sensors`, except * items = item1, item2, item3... - the list of items for updating, may be changed via :doc:`/uc/uc_api` and :doc:`uc-cmd` as follows: - * -p "item+" -v "item_id" - add item for update - * -p "item-" -v "item_id" - delete item - * -p "items" -v "item1,item2,item3..." - replace the whole list + * **-p "item+" -v "item_id"** add item for update + * **-p "item-" -v "item_id"** delete item + * **-p "items" -v "item1,item2,item3..."** replace the whole list * update_allow_check - boolean, the multiupdate will be performed only in case the passive state updates are currently allowed for all included items (i.e. diff --git a/doc/uc/uc.rst b/doc/uc/uc.rst index bf42148b1..fbc76ebc5 100644 --- a/doc/uc/uc.rst +++ b/doc/uc/uc.rst @@ -61,6 +61,8 @@ uc.ini - primary configuration file of UC server .. literalinclude:: ../../etc/uc.ini-dist :language: ini +.. _uc_cvars: + runtime/uc_cvars.json variables file ------------------------------------ @@ -131,38 +133,38 @@ priority is 100. The lower means the higher priority of queued action execution. Queued action can have the following statuses: -* created - action has just been created and has not been queued yet -* pending - the action is placed in the global queue. The previous action +* **created** action has just been created and has not been queued yet +* **pending** the action is placed in the global queue. The previous action status, as well as this one, are rarely found because :doc:`uc_api` waits for the command to be placed in the queue of a certain unit and then returns the result -* queued - the action has already passed the global queue and is now waiting to - be executed in the queue of a certain unit -* refused - unit rejected the action execution because the item configuration - value *action_enabled = False* -* dead - API failed to wait until the action is placed to the queue of a +* **queued** the action has already passed the global queue and is now waiting + to be executed in the queue of a certain unit +* **refused** unit rejected the action execution because the item configuration + value *action_enabled=False* +* **dead** API failed to wait until the action is placed to the queue of a certain unit and, therefore, marked it as "dead". Virtually, such status clearly indicates that server is seriously overloaded -* canceled - the command is canceled either from the outside or due to either - unit already running the other action (in case *action_queue = 0* and queue - is disabled) or the unit got new action to execute and *action_queue = 2* +* **canceled** the command is canceled either from the outside or due to either + unit already running the other action (in case *action_queue=0* and queue + is disabled) or the unit got new action to execute and *action_queue=2* (cancel and terminate the pending actions after getting a new one) -* ignored - the unit rejected the action execution, because its status/value are - the same as requested to be changed to, and *action_always_exec = False* -* running - the action is being executed -* failed - the controller failed to execute the command -* terminated - the controller terminated the action execution due to timeout or - by the external request -* completed - the action finished successfully +* **ignored** the unit rejected the action execution, because its status/value + are the same as requested to be changed to, and *action_always_exec=False* +* **running** the action is being executed +* **failed** the controller failed to execute the command +* **terminated** the controller terminated the action execution due to timeout + or by the external request +* **completed** the action finished successfully Startup and shutdown -------------------- To manage UC server use ./sbin/uc-control script with the following options: -* start - start UC server -* stop - stop UC server -* restart - restart UC server -* logrotate - call after log rotatino to restart the logging -* version - display the server version +* **start** start UC server +* **stop** stop UC server +* **restart** restart UC server +* **logrotate** call after log rotatino to restart the logging +* **version** display the server version diff --git a/doc/uc/uc_api.rst b/doc/uc/uc_api.rst index f35156045..7dfa871c2 100644 --- a/doc/uc/uc_api.rst +++ b/doc/uc/uc_api.rst @@ -3,7 +3,7 @@ UC API :doc:`Universal Controller` UC API is called through URL request -*\http:///uc-api/function?parameters* +**\http:///uc-api/function?parameters** If SSL is allowed in the controller configuration file, you can also use https calls. @@ -21,7 +21,7 @@ Test can be executed with any valid :ref:`API KEY` Parameters: -* k - valid API key +* **k** valid API key Returns JSON dict with system info and current API key permissions (for masterkey only 'master':true is returned) @@ -54,24 +54,24 @@ masterkey only 'master':true is returned) Errors: -* 403 Forbidden if the key has no access to the API. +* **403 Forbidden** if the key has no access to the API. .. _state: state - get item state ---------------------- -Status of the :doc:`item` or all items of the specified type can be +State of the :doc:`item` or all items of the specified type can be obtained using *state* command. Parameters: -* k - valid API key -* i=ID - item ID -* p=TYPE - item type (short forms U for unit, S for sensor may be used) -* g - group filter, optional :ref:`mqtt` masks can be used, for +* **k** valid API key +* **i=ID** item ID +* **p=TYPE** item type (short forms U for unit, S for sensor may be used) +* **g** group filter, optional :ref:`mqtt` masks can be used, for example group1/#, group1/+/lamps) -* full=1 - display extended item info, optional (config_changed, description, +* **full=1** display extended item info, optional (config_changed, description, virtual, status_labels and action_enabled for unit) Returns item status in JSON dict or array of dicts: @@ -93,15 +93,15 @@ Returns item status in JSON dict or array of dicts: } ] -where status and value - current item state, nstatus and nvalue (for unit) - +where status and value** current item state, nstatus and nvalue (for unit) - expected status and value. Current and new status and value are different in case the action is executed for the unit at the moment. In all other cases, they are the same. Errors: -* 403 Forbidden - invalid API KEY -* 404 Not Found - item doesn't exist, or the key has no access to the item +* **403 Forbidden** invalid API KEY +* **404 Not Found** item doesn't exist, or the key has no access to the item .. _action: @@ -112,22 +112,22 @@ Create unit control action and put it into the queue of the controller. Parameters: -* k - valid API key -* ID - unique unit ID -* s - new unit status -* v - new unit value +* **k** valid API key +* **ID** unique unit ID +* **s** new unit status +* **v** new unit value optionally: -* p=PRIORITY - action priority in queue (the less value is - the higher priority - is, default is 100) -* u=UUID - unique action ID (use this option only if you know what you do, the +* **p=PRIORITY** action priority in queue (the less value is** the higher + priority is, default is 100) +* **u=UUID** unique action ID (use this option only if you know what you do, the system assigns the unique ID by default) -* w=sec - the API request will wait for the completion of the action for the +* **w=sec** the API request will wait for the completion of the action for the specified number of seconds -* q=sec - timeout for action processing in the public queue +* **q=sec** timeout for action processing in the public queue -Returns JSON dict with the following data (time - UNIX_TIMESTAMP): +Returns JSON dict with the following data (time** UNIX_TIMESTAMP): .. code-block:: json @@ -153,8 +153,8 @@ Returns JSON dict with the following data (time - UNIX_TIMESTAMP): Errors: -* 403 Forbidden - invalid API KEY -* 404 Not Found - item doesn't exist, or the key has no access to the item +* **403 Forbidden** invalid API KEY +* **404 Not Found** item doesn't exist, or the key has no access to the item In case the parameter 'w' is not present or action is not terminated in the specified wait time, it will continue running, and it's status may be checked @@ -172,18 +172,18 @@ simple units. Parameters: -* k - valid API key -* ID - unique unit ID +* **k** valid API key +* **ID** unique unit ID optionally: -* p=PRIORITY - action priority in queue (the less value is - the higher priority - is, default is 100) -* u=UUID - unique action ID (use this option only if you know what you do, the +* **p=PRIORITY** action priority in queue (the less value is** the higher + priority is, default is 100) +* **u=UUID** unique action ID (use this option only if you know what you do, the system assigns the unique ID by default) -* w=sec - the API request will wait for the completion of the action for the +* **w=sec** the API request will wait for the completion of the action for the specified number of seconds -* q=sec - timeout for action processing in the public queue +* **q=sec** timeout for action processing in the public queue Returns and behaviour: @@ -191,8 +191,8 @@ Same as :ref:`action` Errors: -* 403 Forbidden - invalid API KEY -* 404 Not Found - item doesn't exist, or the key has no access to the item +* **403 Forbidden** invalid API KEY +* **404 Not Found** item doesn't exist, or the key has no access to the item .. _result: @@ -204,14 +204,14 @@ specified unit. Parameters: -* k - valid API key -* u - action UUID or -* i - unit ID +* **k** valid API key +* **u** action UUID or +* **i** unit ID Additionally results may be filtered by: -* g=GROUP - unit group -* s=STATE - action status (Q - queued, R - running, F - finished) +* **g=GROUP** unit group +* **s=STATE** action status (Q** queued, R** running, F** finished) Returns: @@ -219,8 +219,8 @@ Same JSON dict as :ref:`action` Errors: -* 403 Forbidden - invalid API KEY -* 404 Not Found - unit doesn't exist, action with the specified UUID doesn't +* **403 Forbidden** invalid API KEY +* **404 Not Found** unit doesn't exist, action with the specified UUID doesn't exist, or the key has no access to them .. _terminate: @@ -232,8 +232,8 @@ Terminate action execution or cancel the action if it's still queued Parameters: -* k - valid API key -* u - action UUID +* **k** valid API key +* **u** action UUID Returns: @@ -243,8 +243,8 @@ termination is disabled in unit configuration. Errors: -* 403 Forbidden - invalid API KEY -* 404 Not Found - action with the specified UUID doesn't exist (or already +* **403 Forbidden** invalid API KEY +* **404 Not Found** action with the specified UUID doesn't exist (or already compelted), or the key has no access to it .. _q_clean: @@ -256,15 +256,15 @@ Cancel all queued actions, keep the current action running Parameters: -* k - valid API key -* i - unit ID +* **k** valid API key +* **i** unit ID Returns JSON dict result="OK", if queue is cleaned. Errors: -* 403 Forbidden - invalid API KEY -* 404 Not Found - unit doesn't exist, or the key has no access to it +* **403 Forbidden** invalid API KEY +* **404 Not Found** unit doesn't exist, or the key has no access to it .. _kill: @@ -276,8 +276,8 @@ current running action. Parameters: -* k - valid API key -* i - unit ID +* **k** valid API key +* **i** unit ID Returns JSON dict result="OK", if the command completed successfully. If the current action of the unit cannot be terminated by configuration, the notice @@ -286,44 +286,46 @@ running) Errors: -* 403 Forbidden - invalid API KEY -* 404 Not Found - unit doesn't exist, or the key has no access to it +* **403 Forbidden** invalid API KEY +* **404 Not Found** unit doesn't exist, or the key has no access to it .. _disable_actions: disable_actions - disable actions for the unit ---------------------------------------------- + Disables unit to run and queue new actions. Parameters: -* k - valid API key -* i - unit ID +* **k** valid API key +* **i** unit ID Returns JSON dict result="OK", if actions are disabled. Errors: -* 403 Forbidden - invalid API KEY -* 404 Not Found - unit doesn't exist, or the key has no access to it +* **403 Forbidden** invalid API KEY +* **404 Not Found** unit doesn't exist, or the key has no access to it .. _enable_actions: enable_actions - enable actions for the unit -------------------------------------------- + Enables unit to run and queue new actions. Parameters: -* k - valid API key -* i - unit ID +* **k** valid API key +* **i** unit ID Returns JSON dict result="OK", if actions are enabled. Errors: -* 403 Forbidden - invalid API KEY -* 404 Not Found - unit doesn't exist, or the key has no access to it +* **403 Forbidden** invalid API KEY +* **404 Not Found** unit doesn't exist, or the key has no access to it .. _update: @@ -335,17 +337,17 @@ of the passive state update, for example with the use of the external controller Parameters: -* k - valid API key -* i - unit ID -* s - unit status (integer, optional) -* v - unit value (optional) +* **k** valid API key +* **i** unit ID +* **s** unit status (integer, optional) +* **v** unit value (optional) Returns JSON dict result="OK", if the state was updated successfully. Errors: -* 403 Forbidden - invalid API KEY -* 404 Not Found - unit doesn't exist, or the key has no access to it +* **403 Forbidden** invalid API KEY +* **404 Not Found** unit doesn't exist, or the key has no access to it .. _groups: @@ -356,7 +358,7 @@ Returns the list of the item groups. Useful i.e. for the custom interfaces. Parameters: -* k - valid API key +* **k** valid API key Returns JSON array: @@ -370,7 +372,7 @@ Returns JSON array: Errors: -* 403 Forbidden - invalid API KEY +* **403 Forbidden** invalid API KEY .. _list: @@ -381,7 +383,7 @@ Returns the list of all items available Parameters: -* k - masterkey +* **k** masterkey Returns JSON array: @@ -399,7 +401,7 @@ Returns JSON array: Errors: -* 403 Forbidden - invalid API KEY +* **403 Forbidden** invalid API KEY .. _get_config: @@ -411,11 +413,11 @@ Returns complete :doc:`item configuration` Parameters: -* k - masterkey +* **k** masterkey Errors: -* 403 Forbidden - invalid API KEY +* **403 Forbidden** invalid API KEY .. _save_config: @@ -426,15 +428,15 @@ Saves item configuration on disk (even if it wasn't changed) Parameters: -* k - masterkey -* i - unit ID +* **k** masterkey +* **i** unit ID Returns JSON dict result="OK", if the configuration was saved successfully. Errors: -* 403 Forbidden - invalid API KEY -* 404 Not Found - unit doesn't exist, or the key has no access to it +* **403 Forbidden** invalid API KEY +* **404 Not Found** unit doesn't exist, or the key has no access to it .. _list_props: @@ -446,13 +448,13 @@ Allows to get all editable parameters of the Parameters: -* k - masterkey -* i - unit ID +* **k** masterkey +* **i** unit ID Errors: -* 403 Forbidden - invalid API KEY -* 404 Not Found - unit doesn't exist, or the key has no access to it +* **403 Forbidden** invalid API KEY +* **404 Not Found** unit doesn't exist, or the key has no access to it .. _set_prop: @@ -463,18 +465,18 @@ Allows to set configuration parameters of the item. Parameters: -* k - masterkey -* i - unit ID -* p - item configuration param -* v - param value +* **k** masterkey +* **i** unit ID +* **p** item configuration param +* **v** param value Returns result="OK if the parameter is set, or result="ERROR", if an error occurs. Errors: -* 403 Forbidden - invalid API KEY -* 404 Not Found - unit doesn't exist, or the key has no access to it +* **403 Forbidden** invalid API KEY +* **404 Not Found** unit doesn't exist, or the key has no access to it .. _create_unit: @@ -485,21 +487,21 @@ Creates new :ref:`unit`. Parameters: -* k - masterkey -* i - unit ID -* g - unit group +* **k** masterkey +* **i** unit ID +* **g** unit group optionally: -* virtual=1 - unit is created as :doc:`virtual` -* save=1 - save unit configuration on the disk immediately after creation +* **virtual=1** unit is created as :doc:`virtual` +* **save=1** save unit configuration on the disk immediately after creation Returns result="OK if the unit was created, or result="ERROR", if the error occurred. Errors: -* 403 Forbidden - invalid API KEY +* **403 Forbidden** invalid API KEY .. _create_sensor: @@ -510,21 +512,21 @@ Creates new :ref:`sensor`. Parameters: -* k - masterkey -* i - sensor ID -* g - sensor group +* **k** masterkey +* **i** sensor ID +* **g** sensor group optionally: -* virtual=1 - sensor is created as :doc:`virtual` -* save=1 - save sensor configuration on the disk immediately after creation +* **virtual=1** sensor is created as :doc:`virtual` +* **save=1** save sensor configuration on the disk immediately after creation Returns result="OK if the sensor was created, or result="ERROR", if the error occurred. Errors: -* 403 Forbidden - invalid API KEY +* **403 Forbidden** invalid API KEY .. _create_mu: @@ -535,21 +537,22 @@ Creates new :ref:`multiupdate`. Parameters: -* k - masterkey -* i - multiupdate ID -* g - multiupdate group +* **k** masterkey +* **i** multiupdate ID +* **g** multiupdate group optionally: -* virtual=1 - multiupdate is created as :doc:`virtual` -* save=1 - save multiupdate configuration on the disk immediately after creation +* **virtual=1** multiupdate is created as :doc:`virtual` +* **save=1** save multiupdate configuration on the disk immediately after + creation Returns result="OK if the multiupdate was created, or result="ERROR", if the error occurred. Errors: -* 403 Forbidden - invalid API KEY +* **403 Forbidden** invalid API KEY .. _clone: @@ -560,21 +563,21 @@ Creates a copy of the :doc:`item`. Parameters: -* k - masterkey -* i - item ID -* n - new item ID -* g - group for the new item +* **k** masterkey +* **i** item ID +* **n** new item ID +* **g** group for the new item optionally: -* save=1 - save item configuration on the disk immediately after creation +* **save=1** save item configuration on the disk immediately after creation Returns result="OK if the item was loned, or result="ERROR", if the error occurred. Errors: -* 403 Forbidden - invalid API KEY +* **403 Forbidden** invalid API KEY .. _clone_group: @@ -585,15 +588,15 @@ Creates a copy of the all items from the group. Parameters: -* k - masterkey -* g - group to clone -* n - new group to clone to -* p - item ID prefix, i.e. device1. for device1.temp1, device1.fan1 -* r - iem ID prefix in the new group, i.e. device2 +* **k** masterkey +* **g** group to clone +* **n** new group to clone to +* **p** item ID prefix, i.e. device1. for device1.temp1, device1.fan1 +* **r** iem ID prefix in the new group, i.e. device2 optionally: -* save=1 - save cloned items configurations on the disk immediately after +* **save=1** save cloned items configurations on the disk immediately after creation. Returns result="OK if the items were cloned, or result="ERROR", if error @@ -601,7 +604,7 @@ occurred. Only items with type unit and sensor are cloned. Errors: -* 403 Forbidden - invalid API KEY +* **403 Forbidden** invalid API KEY .. _destroy: @@ -625,9 +628,9 @@ restarting the server. Errors: -* 403 Forbidden - invalid API KEY +* **403 Forbidden** invalid API KEY -.. _users: +.. _uc-users: User authorization using login/password --------------------------------------- @@ -635,7 +638,7 @@ User authorization using login/password Third-party apps may authorize :doc:`users` using login and password as an alternative for authorization via API key. -.. _login: +.. _uc-login: login - user authorization ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -652,17 +655,17 @@ IP addresses. Parameters: -* u - user name -* p - user password +* **u** user name +* **p** user password Returns JSON dict { "result" "OK", "key": "APIKEY_ID" }, if the user is authorized. Errors: -* 403 Forbidden - invalid user name / password +* **403 Forbidden** invalid user name / password -.. _logout: +.. _uc-logout: logout ~~~~~~ @@ -675,7 +678,7 @@ Returns JSON dict { "result" : "OK" } Errors: -* 403 Forbidden - no session available / session is already finished +* **403 Forbidden** no session available / session is already finished .. _udp_api: @@ -693,14 +696,14 @@ To update the status of the item send the following UDP packet to API port: ID u [value] -(ID - item ID, value - optional parameter). +(ID** item ID, value** optional parameter). To send :ref:`action` for the unit send the following UDP packet to API port: ID [value] [priority] -(value and priority - optional parameters). +(value and priority** optional parameters). If you needs to skip the parameter, set it to 'None'. For example: