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 nil followed by a list of the absolute paths to the prefix's direct children.

For instance, if the branch foo.bar contains { x=1, y={z1=2, z2=3}}, a get("foo.bar") will return nil, { "foo.bar.x", "foo.bar.y" }. No value is returned, and the children of y, which are the grand-children of foo.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

  1. the value associated with the path leaf node.

  2. nil + list of direct children paths when path is a non-leaf node.

  3. 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

  1. non-nil upon success;

  2. 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 regvars changes. It receives as parameter a table of variable-name / variable-value pairs; these variables are all the variables listed in regvars which have changed, plus every variables listed in passivevars, 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 regvars can be either FQVN names, or a path which denotes every individual variable below this path.

Variables listed in passivevars must 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 a regvars variable 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 to callback, whether they changed or not.

Return values

  1. a registration id, to be passed to devicetree.unregister in order to unsubscribe.

  2. 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

  1. "ok" on success.

  2. nil + error message otherwise.

devicetree.unregister(userid)

Cancels registration to receive a notification when a variable changes.

Parameter

Return values

  1. "ok" on success.

  2. nil + error string otherwise.