Module devicetree
This module provides read/write access to system parameters and settings, as well as the ability to receive notifications when they change.
System parameters and settings are addressed based on a predefined tree (the "Device Tree") that organizes them based on functionality. This tree will continue to be developed and expanded as the Application Framework evolves.
Description / documentation of the tree is available in the "Device Param Access" technical article.
Type devicetree
| devicetree.get(path) |
Retrieves a variable's value from the device tree. |
| devicetree.init() |
Initializes the module. |
| devicetree.register(regvars, callback, passivevars) |
Registers to receive a notification when one or several variables change. |
| devicetree.set(path, value) |
Sets a variable value into the variable tree. |
| devicetree.unregister(userid) |
Cancels registration to receive a notification when a variable changes. |
Type devicetree
Field(s)
- devicetree.get(path)
-
Retrieves a variable's value from the device tree.
The retrieval is not recursive: asking for a path prefix will not return every key/value pairs sharing this prefix. Instead, it will return
nilfollowed by a list of the absolute paths to the prefix's direct children.For instance, if the branch
foo.barcontains{ x=1, y={z1=2, z2=3}}, aget("foo.bar")will returnnil, { "foo.bar.x", "foo.bar.y" }. No value is returned, and the children ofy, which are the grand-children offoo.bar, are not enumerated.Several variables can also be retrieved in a single request, by passing a list of paths rather than a single path string. In this case, a record of path/value pairs is returned. If some of the paths are non-leaf nodes, a second list, of all direct children of all non-leaf paths, is also returned.
Parameter
-
#string path: is a string, or list of strings, defining the path of the variable to retrieve.
Return values
-
the value associated with the
pathleaf node. -
nil+ list of direct children paths whenpathis a non-leaf node. -
nil+ error string otherwise.
Usages:
`devicetree.get("system.sw_info.fw_ver")` may return `"4.2.5"`.`devicetree.get("system.sw_info")` may return `nil, {"system.sw_info.fw_ver", "system.sw_info.boot_ver"}`.`devicetree.get({"system.sw_info", "system.sw_info.boot_ver"})` may return `{["system.sw_info.boot_ver"]="4.2.5"}, {"system.sw_info.fw_ver", "system.sw_info.boot_ver"}`.
-
- devicetree.init()
-
Initializes the module.
Return values
-
non-
nilupon success; -
nil+ error message upon failure.
-
- devicetree.register(regvars, callback, passivevars)
-
Registers to receive a notification when one or several variables change.
The callback is triggered everytime one or some of the variables listed in
regvarschanges. It receives as parameter a table of variable-name / variable-value pairs; these variables are all the variables listed inregvarswhich have changed, plus every variables listed inpassivevars, whether their values changed or not.Please note that the callback can be called with table param containing niltoken#niltoken value(s) to indicate variable(s) deletion.
Variables listed in
regvarscan be either FQVN names, or a path which denotes every individual variable below this path.Variables listed in
passivevarsmust be path to variables: non-leaf paths will be silently ignored.Parameters
-
regvars: list of variables which must be monitored for change. -
callback: the function triggered everytime aregvarsvariable changes. The callback is called with a table containing all the changes, paths as keys and values as values. -
passivevars: optional variables to always pass tocallback, whether they changed or not.
Return values
-
a registration id, to be passed to devicetree.unregister in order to unsubscribe.
-
nil+ error message in case of error.
-
- devicetree.set(path, value)
-
Sets a variable value into the variable tree.
Example
To activate the monitoring, you could send:
devicetree.set ("config.monitoring.activate", true).Parameters
-
#string path: defining the path of the variable to set. -
value: is the value of the variable. It can also be a table of key/value pairs, allowing to set several variables in a single operation. it will actually set a whole sub tree (several variables at once)).
Return values
-
"ok"on success. -
nil+ error message otherwise.
-
- devicetree.unregister(userid)
-
Cancels registration to receive a notification when a variable changes.
Parameter
-
userid: is the id returned by previous devicetree.registercall to be cancelled.
Return values
-
"ok" on success.
-
nil + error string otherwise.
-