This module allows to access the ReadyAgent tree.
This tree is local to the ReadyAgent, and contains a set of variables identified by their paths. These variables can be read, and for some of them written, to determine or change the device's state. Applications can also register to be notified whenever the value of a variable--or of a set of variables--changes.

The list of all variables and their meaning is partially device-dependent, and is given in a separate document.

Type devicetree

devicetree.get(path)	Retrieves a variable value from the ReadyAgent variable tree.
devicetree.init()	Initialize the module.
devicetree.register(regvars, callback, passivevars)	Registers to receive a notification when one or multiple variables change.
devicetree.set(path, value)	Sets a variable value into the ReadyAgent 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 value from the ReadyAgent variable tree.
The retrieval is not recursive. Returns the retrieved value if is not a table. If the value is a table, returns nil followed by a list of paths to each child.

Parameter

• path : is a string 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.

Usage:

• `devicetree.get("config.monitoring.activate")` may return `true`.

• `devicetree.get("config.monitoring")` may return 
     `nil, {"config.monitoring.activate", "config.monitoring.debug"}`.

devicetree.init()

Initialize 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 multiple 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 and passivevars can be either FQVN names, or a path which denotes every individual variable below this path.

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. Callback signature: callback([table] varmap).
• 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 ReadyAgent variable tree.

Example: to activate the monitoring, you could send:

Parameters

• path : defining the path of the variable to set.
• value :

  is the value of the variable (can be a table, in which case

  it will actually set a whole sub tree (several variables at once)).

Return values

1. "ok" on success.
2. nil followed by an 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.register

  call to be cancelled.

Return values

1. "ok" on success.
2. nil + error string otherwise.