Logic control macros
In Logic Manager macros can be triggered on the list of events, third-party applications or user via LM EI interface or LM API functions.
Macro code is a file written in Python and located in the folder xc/lm/ under the name <macro_id>.py, i.e. test.py for “test” macro. Macro id should be unique within the single LM PLC, full id (group/id) - within the whole installation.
Additionally, each macro is automatically appended with common.py file located in the same folder enabling to quickly assign common functions to several macros without using modules.
Macros are compiled into byte-code each time after macros file or common.py file are changed. Compilation or execution errors can be viewed in the log files of the controller.
Contents
- Logic control macros
- Executing macros
- Debugging macros
- Macros configuration
- Common principles of macros operation
- System macros
- Macros and security
- Macros built-ins
- Variables
- Extending macros functionality
- General functions
- alias - create object alias
- cmd - execute a remote system command
- date - date/time
- decrement_shared - decrement value of the shared variable
- exit - finish macro execution
- increment_shared - increment value of the shared variable
- ls - list files in directory
- mail - send email message
- open_newest - open newest file by mask
- open_oldest - open oldest file by mask
- run - execute another macro
- set_shared - set value of the shared variable
- shared - get value of the shared variable
- sleep - pause operations
- system - execute the command in a subshell
- time - current time in seconds since Epoch
- Item functions
- history - get item state history
- lvar_status - get lvar status
- lvar_value - get lvar value
- sensor_status - get sensor status
- sensor_value - get sensor value
- state - get item state
- status - get item status
- unit_nstatus - get unit nstatus
- unit_nvalue - get unit nvalue
- unit_status - get unit status
- unit_value - get unit value
- value - get item value
- LVar functions
- Unit control
- Rule management
- Scheduled job management
- Devices
- Logic cycles
- Locking functions
- Logging
Executing macros
To execute a macro, use macro run command of eva lm or LM API run function.
Note
If you need to execute or use a single macro function, you may do this directly, adding “@” symbol to function name, e.g. @action_toggle, @start, etc.
Debugging macros
Macro compilation and execution errors are written into the logs of the controller on DEBUG level, the exceptions are also added to err field of the execution result.
To receive information about errors you may run the following command:
eva lm -J run <macro_id> -w 3600 | jq -r .err
Macros configuration
After the macro code is placed into xc/lm/<macro_id>.py file, it should be appended to the controller using create_macro LM API function or with eva lm.
After the macro configuration is created, you may view its params using list_macro_props and change them with set_macro_prop.
Parameters:
- id macros id, can’t be modified after the macro is created
- action_enabled true means macro can be executed (true by default)
- action_exec controller gets the code of the macro from the file <macro_id>.py by default, use this parameter to assign another file
- description macro description
- group macro group (in difference to other objects, macro group can be changed after creation)
- pass_errors if true, in case the function called by macro is completed with an exception, the controller ignores this and continues the code execution (false by default)
- send_critical if true, allows to send critical events to controller core with critical(msg, send_event=True)
Common principles of macros operation
Macros are launched simultaneously: system does not wait for the completion of the macro and launches its next copy or another macro in parallel. If you want only one copy of macro to operate at the certain point of time or to block execution of other macros, use macro lock and unlock functions.
The system architecture does not provide the possibility to stop macro from outside, that is why macros should have minimum internal logic and cycles.
All the logic should be implemented in the decision-making matrix. The working cycles should be implemented with logic variables timers.
System macros
On startup
If defined, macro named system/autoexec is launched automatically at the controller startup. This macro is not always the first one executed, as far as some initial decision-making rules may call assigned macros, or some events may be handled before. In case a macro is launched later than logic variables or other loadable items update their status (e. g. due to slow connection with MQTT server) it’s recommended to use sleep function to do a small delay.
Macros from system group are considered as the local system macros and aren’t synchronized to SFA.
Example of autoexec macro usage:
# both cycle timers are expired
if is_expired('timers/timer1') and is_expired('timers/timer2'):
# launch the first cycle process
action('pumps/pump1', on)
# start the first cycle timer
reset('timers/timer1')
On shutdown
If defined, macro named system/shutdown is launched automatically at the controller shutdown. This macro can, for example, gracefully stop cycles and set/reset required logic variables. The macro should end its work in default controller timeout.
Macros and security
As all Python features are available for macros, including execution of external programs or working with any local files, the code of macros should be edited only by system administrator.
If access permissions to individual macros are configured via API keys, you should take into account the following: if a macro runs other macros using run function, these macros will be executed even if the API key allows to run only the initial macro.
Macros built-ins
Macros can execute any Python functions or use Python modules installed on the local server. In addition, macros have a set of built-in functions and variables.
Built-in functions are included for quick access to the most frequently used Python functions such as LM API and UC API. When calling API function, item id is always transmitted in full. When calling other macros and working with logic variables, it’s possible to use the short ids only.
Variables
Macros have the following built-in variables:
- on alias to integer 1
- off alias to integer 0
- yes alias to boolean True
- no alias to boolean False
- _source item generated the event, used by the system to call the macro. You may directly access the item and e.g. use its internal variables such as _source.item_id, _source.full_id, _source.oid etc.
- _polldelay controller poll delay
- _timeout controller default timeout
- args array list of arguments the macro is being executed with
- kwargs dict of keyword arguments the macro is being executed with
- _0 current macro id (i.e. ‘test’)
- _00 current macro full id (i.e. ‘group1/test’)
- _1, _2, … _9 first 9 arguments the macro is being executed with
- lm_cvars all lm_cvars variables
- out macro may use this variable to output the data which will be set to out field of the execution result
- is_shutdown if defined, contains a function which returns True if macro caller got shutdown/stop event (set by logic cycle)
Note
if macro arguments or lm_cvars are numbers, they are automatically converted to float type
Extending macros functionality
Macros function set can be extended with pre-made or custom macro extensions. As soon as extension is loaded, its functions become available in all macros without a need to restart LM PLC.
Also, macro can import any local Python module. The following modules are pre-imported:
- json JSON processing
- os standard Python OS functions
- requests HTTP functions
- sys standard Python system functions
General functions
alias - create object alias
alias('rpush', 'roboger_local_push')
Parameters:
- alias_obj alias object
- src_obj source object
Returns:
True if alias is set. Doesn’t raise any exceptions, safe to use in common files
cmd - execute a remote system command
Executes a command script on the server where the controller is installed.
r = cmd('uc/mws1-v1', 'test', wait=5)
Parameters:
- controller_id controller id to execute command on
- command name of the command script
Optionally:
- args string of command arguments, separated by spaces (passed to the script)
- wait wait (in seconds) before API call sends a response. This allows to try waiting until command finish
- timeout maximum time of command execution. If the command fails to finish within the specified time (in sec), it will be terminated
Returns:
Serialized command action object (dict)
{
"args": [],
"cmd": "test",
"err": "some text to stderr\n",
"exitcode": 0,
"out": "test script start\nparam 1: ( > 0 will generate \"failed\" status)\nparam 2: \nparam 3: \ndelay 3 sec\nscript finish\n",
"status": "completed",
"time": {
"completed": 1553466937.5606368,
"created": 1553466934.5421243,
"running": 1553466934.5424464
},
"timeout": 5.0
}
Raises:
- ResourceNotFound command script or controller is not found
date - date/time
r = date()
Returns:
Serialized date/time object (dict)
{
"day": 14,
"hour": 0,
"minute": 47,
"month": 5,
"second": 16,
"timestamp": 1557787636.680612,
"weekday": 1,
"year": 2019
}
ls - list files in directory
If recursive is true, the pattern “**” will match any files and zero or more directories and subdirectories.
r = ls('/opt/i/*.jpg')
Parameters:
- mask path and mask (e.g. /opt/data/*.jpg)
- recursive if True, perform a recursive search
Returns:
dict with fields ‘name’ ‘file’, ‘size’ and ‘time’ { ‘c’: created, ‘m’: modified }
[
{
"file": "/opt/i/20170926_004347.jpg",
"name": "20170926_004347.jpg",
"size": 6464873,
"time": {
"c": 1553460493.280853,
"m": 1506379536.0
}
},
{
"file": "/opt/i/20171017_095941.jpg",
"name": "20171017_095941.jpg",
"size": 1650389,
"time": {
"c": 1553460493.2968528,
"m": 1510695841.0
}
},
{
"file": "/opt/i/20171029_194029.jpg",
"name": "20171029_194029.jpg",
"size": 3440296,
"time": {
"c": 1553460493.324853,
"m": 1510695762.0
}
},
{
"file": "/opt/i/20170926_004334.jpg",
"name": "20170926_004334.jpg",
"size": 6523001,
"time": {
"c": 1553460493.1648533,
"m": 1506379526.0
}
}
]
mail - send email message
The function uses [mailer] section of the LM PLC configuration to get sender address and list of the recipients (if not specified).
mail(subject='we have a problem', text='sensor 5 is down')
Optionally:
- subject email subject
- text email text
- rcp recipient or array of the recipients
Raises:
- FunctionFailed mail is not sent
open_newest - open newest file by mask
i = open_newest('/opt/i/*.jpg', 'rb').read()
print(r)
None
Parameters:
- mask path and mask (e.g. /opt/data/*.jpg)
Optionally:
- mode file open mode (default: ‘r’)
Returns:
file descriptor
Raises:
- Exception exceptions equal to Python “open” function
open_oldest - open oldest file by mask
i = open_oldest('/opt/i/*.jpg', 'rb').read()
print(r)
None
Parameters:
- mask path and mask (e.g. /opt/data/*.jpg)
Optionally:
- mode file open mode (default: ‘r’)
Returns:
file descriptor
Raises:
- Exception exceptions equal to Python “open” function
run - execute another macro
Execute a macro with the specified arguments.
r = run('tests/test1', kwargs={'v1': 'test', 'v2': 999}, wait=2)
Parameters:
- macro macro id
Optionally:
- args macro arguments, array or space separated
- kwargs macro keyword arguments, name=value, comma separated or dict
- wait wait for the completion for the specified number of seconds
- uuid action UUID (will be auto generated if none specified)
- priority queue priority (default is 100, lower is better)
Returns:
Serialized macro action object (dict)
{
"args": [],
"err": "",
"exitcode": 0,
"finished": true,
"finished_in": 0.0047829,
"item_group": "tests",
"item_id": "test1",
"item_oid": "lmacro:tests/test1",
"item_type": "lmacro",
"kwargs": {
"v1": "test",
"v2": 999
},
"out": "",
"priority": 100,
"status": "completed",
"time": {
"completed": 1559869087.3697698,
"created": 1559869087.364987,
"pending": 1559869087.3653126,
"queued": 1559869087.3661342,
"running": 1559869087.3669574
},
"uuid": "fc0e8c8e-9c93-49c4-bb30-e7905fedc33f"
}
Raises:
- ResourceNotFound macro is not found
sleep - pause operations
Unlike standard time.sleep(…), breaks pause when controller shutdown event is received.
sleep(0.1)
Parameters:
- t number of seconds to sleep
Optionally:
- safe break on shutdown event (default is True)
Returns:
True if sleep is finished, False if shutdown event is received
system - execute the command in a subshell
r = system('touch /tmp/1.dat')
print(r)
0
Returns:
shell exit code (0 - no error)
time - current time in seconds since Epoch
Return the current time in seconds since the Epoch. Fractions of a second may be present if the system clock provides them.
r = time()
print(r)
1553461581.549374
Item functions
history - get item state history
To use this function, DB or TSDB notifier in LM PLC must be present. (notifier can share DB with SFA in read/only mode).
r = history('lvar:tests/test1', t_start='2019-03-24')
Parameters:
- item_id item ID, or multiple IDs (list or comma separated)
Optionally:
- t_start time frame start, ISO or Unix timestamp
- t_end time frame end, optional (default: current time), ISO or Unix timestamp
- limit limit history records
- prop item property (‘status’ or ‘value’
- time_format time format, ‘iso’ or ‘raw’ (default) for timestamp
- fill fill frame with the specified interval (e.g. 1T - 1 minute, 2H - 2 hours etc.), optional. If specified, t_start is required
- fmt output format, ‘list’ (default) or ‘dict’
- db notifier ID which keeps history for the specified item(s) (default: db_1)
Returns:
list of dicts or dict of lists
{
"status": [
1,
1,
1,
1
],
"t": [
1553461864.9564857,
1553461878.8139935,
1553461883.1168087,
1553461887.6495461
],
"value": [
0.0,
0.0,
1.0,
1.0
]
}
lvar_status - get lvar status
r = lvar_status('tests/test1')
print(r)
1
Parameters:
- lvar_id lvar id
Returns:
lvar status (integer)
Raises:
- ResourceNotFound lvar is not found
lvar_value - get lvar value
r = lvar_value('tests/test1')
print(r)
1.0
Parameters:
- lvar_id lvar id
Returns:
lvar value
sensor_status - get sensor status
r = sensor_status('env/temp_test')
print(r)
1
Parameters:
- sensor_id sensor id
Returns:
sensor status (integer)
Raises:
- ResourceNotFound sensor is not found
sensor_value - get sensor value
r = sensor_value('env/temp_test')
print(r)
191.0
Parameters:
- sensor_id sensor id
Optionally:
- default value if null (default is empty string)
Returns:
sensor value
Raises:
- ResourceNotFound sensor is not found
state - get item state
r = state('sensor:env/temp1')
Parameters:
- item_id item id (oid required)
Returns:
item status/value dict
{
"status": 1,
"value": 55.0
}
Raises:
- ResourceNotFound item is not found
status - get item status
r = status('unit:tests/unit1')
print(r)
0
Parameters:
- item_id item id (oid required)
Returns:
item status (integer)
Raises:
- ResourceNotFound item is not found
unit_nstatus - get unit nstatus
nstatus is the status which is set to unit after the current running action is completed.
the function may be called with an alias “nstatus(…)”
r = unit_nstatus('tests/unit1')
print(r)
0
Parameters:
- unit_id unit id
Returns:
unit nstatus (integer)
Raises:
- ResourceNotFound unit is not found
unit_nvalue - get unit nvalue
nvalue is the value which is set to unit after the current running action is completed.
the function may be called with an alias “nvalue(…)”
r = unit_nvalue('tests/unit1')
print(r)
Parameters:
- unit_id unit id
Returns:
unit nvalue
Raises:
- ResourceNotFound unit is not found
unit_status - get unit status
r = unit_status('tests/unit1')
print(r)
0
Parameters:
- unit_id unit id
Returns:
unit status (integer)
Raises:
- ResourceNotFound unit is not found
unit_value - get unit value
r = unit_value('tests/unit1')
print(r)
Parameters:
- unit_id unit id
Optionally:
- default value if null (default is empty string)
Returns:
unit value
Raises:
- ResourceNotFound unit is not found
value - get item value
r = value('sensor:env/temp_test')
print(r)
191.0
Parameters:
- item_id item id (oid required)
Optionally:
- default value if null (default is empty string)
Returns:
item value
Raises:
- ResourceNotFound item is not found
LVar functions
clear - reset lvar value
Set lvar value to 0 or stop timer lvar (set timer status to 0)
clear('tests/test1')
Parameters:
- lvar_id lvar id
Raises:
- FunctionFailed lvar value set error
- ResourceNotFound lvar is not found
decrement - decrement lvar value
Decrement value of lvar. Initial value should be number
decrement('tests/test1')
Parameters:
- lvar_id lvar id
Raises:
- FunctionFailed lvar value decrement error
- ResourceNotFound lvar is not found
expires - set lvar expiration time
expires('timers/timer1', 30)
Parameters:
- lvar_id lvar id
Optionally:
- etime time (in seconds), default is 0 (never expires)
Raises:
- FunctionFailed lvar expiration set error
- ResourceNotFound lvar is not found
increment - increment lvar value
Increment value of lvar. Initial value should be number
increment('tests/test1')
Parameters:
- lvar_id lvar id
Raises:
- FunctionFailed lvar value increment error
- ResourceNotFound lvar is not found
is_expired - is lvar (timer) expired
r = is_expired('nogroup/timer1')
print(r)
True
Parameters:
- lvar_id lvar id
Returns:
True, if timer is expired
Raises:
- ResourceNotFound lvar is not found
reset - reset lvar value
Set lvar value to 1 or start lvar timer
reset('tests/test1')
Parameters:
- lvar_id lvar id
Raises:
- FunctionFailed lvar value set error
- ResourceNotFound lvar is not found
set - set lvar value
set('tests/test1', value=1)
Parameters:
- lvar_id lvar id
Optionally:
- value lvar value (if not specified, lvar is set to null)
Raises:
- FunctionFailed lvar value set error
- ResourceNotFound lvar is not found
toggle - toggle lvar value
Change lvar value to opposite boolean (0->1, 1->0)
toggle('tests/test1')
Parameters:
- lvar_id lvar id
Raises:
- FunctionFailed lvar value set error
- ResourceNotFound lvar is not found
Unit control
action - unit control action
The call is considered successful when action is put into the action queue of selected unit.
r = action('tests/unit1', status=1, wait=5)
Parameters:
- unit_id unit id
- status desired unit status
Optionally:
- value desired unit value
- wait wait for the completion for the specified number of seconds
- uuid action UUID (will be auto generated if none specified)
- priority queue priority (default is 100, lower is better)
Returns:
Serialized action object (dict)
{
"err": "",
"exitcode": 0,
"finished": true,
"finished_in": 0.0149484,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "completed",
"time": {
"completed": 1559869105.9634602,
"created": 1559869105.9485118,
"pending": 1559869105.9487257,
"queued": 1559869105.9491074,
"running": 1559869105.949467
},
"uuid": "4bce26a6-7203-4a3c-a123-14c144dcc613"
}
Raises:
- FunctionFailed action is “dead”
- ResourceNotFound unit is not found
action_toggle - toggle unit status
Create unit control action to toggle its status (1->0, 0->1). if using OID, you can also call “toggle(..)” with the same effect.
r = action_toggle('tests/unit1', wait=5)
Parameters:
- unit_id unit id
Optionally:
- value desired unit value
- wait wait for the completion for the specified number of seconds
- uuid action UUID (will be auto generated if none specified)
- priority queue priority (default is 100, lower is better)
Returns:
Serialized action object (dict)
{
"err": "",
"exitcode": 0,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 0,
"nvalue": "",
"out": "",
"priority": 100,
"status": "completed",
"time": {
"completed": 1553465690.1327171,
"created": 1553465690.1081843,
"pending": 1553465690.1084123,
"queued": 1553465690.1089923,
"running": 1553465690.1094682
},
"uuid": "0982213a-6c8f-4df3-8581-d1281d0f41dc"
}
Raises:
- FunctionFailed action is “dead”
- ResourceNotFound unit is not found
is_busy - is unit busy
r = is_busy('tests/unit1')
print(r)
False
Parameters:
- unit_id unit id
Returns:
True, if unit is busy (action is executed)
Raises:
- ResourceNotFound unit is not found
kill - kill unit actions
Apart from canceling all queued commands, this function also terminates the current running action.
kill('tests/unit1')
Parameters:
- unit_id unit id
Raises:
- ResourceNotFound unit is not found
q_clean - clean action queue of unit
Cancels all queued actions, keeps the current action running.
q_clean('tests/unit1')
Parameters:
- unit_id unit id
Raises:
- ResourceNotFound unit is not found
result - get action status
Checks the result of the action by its UUID or returns the actions for the specified unit.
r = result(unit_id='tests/unit1')
Parameters:
- unit_id unit id or
- uuid action uuid
Optionally:
- group filter by unit group
- status filter by action status: Q for queued, R for running, F for finished
Returns:
list or single serialized action object
[
{
"err": "",
"exitcode": 0,
"finished": true,
"finished_in": 0.0147429,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 0,
"nvalue": null,
"out": "",
"priority": 100,
"status": "completed",
"time": {
"completed": 1559869099.8924437,
"created": 1559869099.8777008,
"pending": 1559869099.8778677,
"queued": 1559869099.8782423,
"running": 1559869099.8786528
},
"uuid": "d5b82c8c-9a95-482a-9063-e3048addc741"
},
{
"err": "",
"exitcode": 0,
"finished": true,
"finished_in": 0.0149484,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "completed",
"time": {
"completed": 1559869105.9634602,
"created": 1559869105.9485118,
"pending": 1559869105.9487257,
"queued": 1559869105.9491074,
"running": 1559869105.949467
},
"uuid": "4bce26a6-7203-4a3c-a123-14c144dcc613"
}
]
Raises:
- ResourceNotFound unit or action is not found
start - start unit
Create unit control action to set its status to 1
r = start('tests/unit1', wait=5)
Parameters:
- unit_id unit id
Optionally:
- value desired unit value
- wait wait for the completion for the specified number of seconds
- uuid action UUID (will be auto generated if none specified)
- priority queue priority (default is 100, lower is better)
Returns:
Serialized action object (dict)
{
"err": "",
"exitcode": 0,
"finished": true,
"finished_in": 0.0179181,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "completed",
"time": {
"completed": 1559869092.8558156,
"created": 1559869092.8378975,
"pending": 1559869092.838309,
"queued": 1559869092.8390505,
"running": 1559869092.8402033
},
"uuid": "bf74b19c-2af1-40f6-9ec6-5f74bb572558"
}
Raises:
- FunctionFailed action is “dead”
- ResourceNotFound unit is not found
stop - stop unit
Create unit control action to set its status to 0
r = stop('tests/unit1', wait=5)
Parameters:
- unit_id unit id
Optionally:
- value desired unit value
- wait wait for the completion for the specified number of seconds
- uuid action UUID (will be auto generated if none specified)
- priority queue priority (default is 100, lower is better)
Returns:
Serialized action object (dict)
{
"err": "",
"exitcode": 0,
"finished": true,
"finished_in": 0.0147429,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 0,
"nvalue": null,
"out": "",
"priority": 100,
"status": "completed",
"time": {
"completed": 1559869099.8924437,
"created": 1559869099.8777008,
"pending": 1559869099.8778677,
"queued": 1559869099.8782423,
"running": 1559869099.8786528
},
"uuid": "d5b82c8c-9a95-482a-9063-e3048addc741"
}
Raises:
- FunctionFailed action is “dead”
- ResourceNotFound unit is not found
terminate - terminate action execution
Terminates or cancel the action if it is still queued
try:
terminate(unit_id='tests/unit1')
except ResourceNotFound:
print('no action running')
Parameters:
- unit_id action uuid or
- uuid unit id
Raises:
- ResourceNotFound if unit/action is not found or action is already finished
Rule management
set_rule_prop - set rule prop
set_rule_prop('28af95b2-e087-47b3-a6cd-15fe21d06c4a', 'condition', 'x < 5')
Parameters:
- rule_id rule id (uuid)
- prop property to set
- value value to set
Optionally:
- save save rule config after the operation
Raises:
- ResourceNotFound rule is not found
Scheduled job management
set_job_prop - set job prop
set_job_prop('6970e296-5cb4-4448-9f2a-1ab2a14ed7f1', 'enabled', True)
Parameters:
- job_id job id (uuid)
- prop property to set
- value value to set
Optionally:
- save save job config after the operation
Raises:
- ResourceNotFound job is not found
Devices
deploy_device - deploy device items from template
Deploys the device from the specified template.
deploy_device('uc/mws1-v1', 'device1', cfg={ 'ID': 5 })
Parameters:
- controller_id controller id to deploy device on
- device_tpl device template (runtime/tpl/<TEMPLATE>.yml|yaml|json, without extension)
Optionally:
- cfg device config (var=value, comma separated or dict)
- save save items configuration on disk immediately after operation
Raises:
- ResourceNotFound device template or controller is not found
- FunctionFailed device deploy error
undeploy_device - undeploy device items config from template
undeploy_device('uc/mws1-v1', 'device1', cfg={ 'ID': 5 })
Parameters:
- controller_id controller id to deploy device on
- device_tpl device template (runtime/tpl/<TEMPLATE>.yml|yaml|json, without extension)
Optionally:
- cfg device config (var=value, comma separated or dict)
Raises:
- ResourceNotFound device template or controller is not found
update_device - update device items config from template
update_device('uc/mws1-v1', 'device1', cfg={ 'ID': 5 })
Parameters:
- controller_id controller id to deploy device on
- device_tpl device template (runtime/tpl/<TEMPLATE>.yml|yaml|json, without extension)
Optionally:
- cfg device config (var=value, comma separated or dict)
- save save items configuration on disk immediately after operation
Raises:
- ResourceNotFound device template or controller is not found
- FunctionFailed device update error
Logic cycles
get_cycle_info - get cycle information
r = get_cycle_info('tests/cycle1')
Parameters:
- cycle_id cycle id
Returns:
dict with cycle information
{
"avg": 0.01,
"description": "",
"full_id": "tests/cycle1",
"group": "tests",
"ict": 20,
"id": "cycle1",
"interval": 0.01,
"iterations": 0,
"macro": "tests/test",
"oid": "lcycle:tests/cycle1",
"on_error": null,
"status": 0,
"type": "lcycle",
"value": "0,0.0100,"
}
Raises:
- ResourceNotFound cycle is not found
is_cycle_running - get cycle running status
r = is_cycle_running('tests/cycle1')
print(r)
True
Parameters:
- cycle_id cycle id
Returns:
True if cycle is runing
Raises:
- ResourceNotFound cycle is not found
list_cycle_props - list cycle props
r = list_cycle_props('tests/cycle1')
Parameters:
- cycle_id cycle id
Returns:
dict with cycle props
{
"autostart": false,
"description": "",
"ict": 20,
"interval": 0.01,
"macro": "tests/test",
"on_error": null
}
Raises:
- ResourceNotFound cycle is not found
reset_cycle_stats - reset cycle stats
reset_cycle_stats('tests/cycle1')
Parameters:
- cycle_id cycle id
Raises:
- ResourceNotFound cycle is not found
set_cycle_prop - set cycle prop
set_cycle_prop('tests/cycle1', 'ict', 20)
Parameters:
- cycle_id cycle id
- prop property to set
- value value to set
Optionally:
- save save cycle config after the operation
Raises:
- ResourceNotFound cycle is not found
start_cycle - start cycle
start_cycle('tests/cycle1')
Parameters:
- cycle_id cycle id
Raises:
- ResourceNotFound cycle is not found
stop_cycle - stop cycle
stop_cycle('tests/cycle1', wait=True)
Parameters:
- cycle_id cycle id
Optionally:
- wait wait for cycle stop (default is False)
Raises:
- ResourceNotFound cycle is not found
Locking functions
lock - acquire lock
lock('lock1', expires=1)
Parameters:
- lock_id lock id
Optionally:
- timeout max timeout to wait
- expires time after which token is automatically unlocked (if absent, token may be unlocked only via unlock function)
Returns:
True if lock is acquired
Raises:
- FunctionFailed function failed to acquire lock
unlock - release lock
Releases the previously acquired lock.
unlock('lock1')
Parameters:
- l lock id
Returns:
True if lock is released
Raises:
- ResourceNotFound lock is not found
- FunctionFailed function failed to release lock
Logging
debug - put debug message to log file
debug('this is a test debug message')
Parameters:
- msg message text
info - put info message to log file
Additionally, print() function is alias to info()
info('this is a test debug message')
Parameters:
- msg message text
warning - put warning message to log file
info('this is a test debug message')
Parameters:
- msg message text
error - put error message to log file
error('this is a test debug message')
Parameters:
- msg message text
critical - put critical message to log file
critical('this is a test debug message')
Parameters:
- msg message text
Optionally:
- send_event if True, critical event to core is sent (requires send_critical=true in macro props)