Root

class pyrogue.Root(*, name=None, description='', expand=True, timeout=1.0, initRead=False, initWrite=False, pollEn=True, maxLog=1000)[source]

Class which serves as the root of a tree of Nodes. The root is the interface point for tree level access and updates.

Parameters:

name (str | None, default: None) – Root name. Defaults to class name.
description (str, default: '') – Human-readable description.
expand (bool, default: True) – Default GUI expand state.
timeout (float, default: 1.0) – Transaction timeout in seconds.
initRead (bool, default: False) – Perform an initial read on start.
initWrite (bool, default: False) – Perform an initial write on start.
pollEn (bool, default: True) – Enable polling on start.
maxLog (int, default: 1000) – Maximum log entries to retain.

start()[source]

Setup the tree and start background threads for pollQueue and updateQueue. Call Device._start() recursively on child Nodes.

Return type:: None

stop()[source]

Stop background threads. Must be called for clean exit. Call Device._stop() to recursively stop all Devices in the tree.

Return type:: None

property running: bool: Return True if the root is running.

addVarListener(func, *, done=None, incGroups=None, excGroups=None)[source]

Add a variable update listener function. The variable path and value are passed as func(path, varValue).

Parameters:

func (Callable[[str, VariableValue], None]) – Listener callback of the form func(path, varValue) where path is a full variable path and varValue is a pyrogue.VariableValue.
done (Callable[[], None] | None, default: None) – Optional callback of the form done() executed after each update batch.
incGroups (str | list[str] | None, default: None) – Group name or group names to include.
excGroups (str | list[str] | None, default: None) – Group name or group names to exclude.

Return type:

None

updateGroup(period=0)[source]

Get a context manager within which many Variable updates will be broadcast as one.

Functions that operate on and set() more than one Variable should do so within a Root.updateGroup() context. This will reduce the number of update broadcasts that the Root has to make.

The optional ‘period’ parameter will allow broadcasts of the state every ‘period’ seconds, useful for long running functions.

Parameters:: period (float, default: 0) – Maximum update period in seconds.
Return type:: Iterator[None]

pollBlock()[source]

Context manager that blocks poll activity while active.

Return type:: Iterator[None]

waitOnUpdate()[source]

Wait until all update queue items have been processed.

Return type:: None

hardReset()[source]

Generate a hard reset on all devices.

Called recursively on the entire tree.

Return type:: None

getNode(path)[source]

Get a Node of the tree by its path string

Parameters:: path (str) – Node path. Accepts absolute dotted path, root name, or root.
Returns:: Located node object, or None if no node matches.
Return type:: Node

saveAddressMap(fname)[source]

Dump the tree address map to a file

Parameters:: fname (str) – Destination file path.
Return type:: None

saveVariableList(fname, polledOnly=False, incGroups=None)[source]

Save a string representing the entire tree

Parameters:

fname (str) – Destination file path.
polledOnly (bool, default: False) – If True, include only polled variables.
incGroups (str | list[str] | None, default: None) – Group name or group names to include.

Return type:

None

saveYaml(name, readFirst, modes=['RW', 'RO', 'WO'], incGroups=None, excGroups=None, autoPrefix='', autoCompress=False)[source]

Save YAML configuration or status to a file.

Parameters:

name (str | None) – Destination file path. If empty, a timestamped name is generated.
readFirst (bool) – Read values from hardware before exporting.
modes (list[str], default: ['RW', 'RO', 'WO']) – Variable modes to include. Allowed values are 'RW', 'WO', and 'RO'.
incGroups (str | list[str] | None, default: None) – Group name or group names to include.
excGroups (str | list[str] | None, default: None) – Group name or group names to exclude.
autoPrefix (str, default: '') – Prefix for auto-generated filenames.
autoCompress (bool, default: False) – Generate a .zip file when auto-generating names. Default False

Returns:

Returns True when export completes.

Return type:

bool

loadYaml(name, writeEach, modes, incGroups=None, excGroups=None)[source]

Load YAML configuration from files or directories.

Parameters:

name (str | list[str]) – Input file, directory, zip-path, or list of those entries.
writeEach (bool) – Write each variable as it is applied.
modes (list[str]) – Variable modes to include. Allowed values are 'RW', 'WO', and 'RO'.
incGroups (str | list[str] | None, default: None) – Group name or group names to include.
excGroups (str | list[str] | None, default: None) – Group name or group names to exclude.

Returns:

Returns True when load completes.

Return type:

bool

treeDict(modes=['RW', 'RO', 'WO'], incGroups=None, excGroups=None, properties=True)[source]

Return the root tree as a dictionary.

Parameters:

modes (list[str], default: ['RW', 'RO', 'WO']) – Variable modes to include. Allowed values are 'RW', 'WO', and 'RO'.
incGroups (str | list[str] | None, default: None) – Group names to include.
excGroups (str | list[str] | None, default: None) – Group names to exclude.
properties (bool, default: True) – Include variable property fields.

Returns:

Dictionary keyed by root name with tree data.

Return type:

dict[str, Any]

treeYaml(modes=['RW', 'RO', 'WO'], incGroups=None, excGroups=None, properties=None)[source]

Return the root tree as YAML text.

Parameters:

modes (list[str], default: ['RW', 'RO', 'WO']) – Variable modes to include. Allowed values are 'RW', 'WO', and 'RO'.
incGroups (str | list[str] | None, default: None) – Group names to include.
excGroups (str | list[str] | None, default: None) – Group names to exclude.
properties (bool | None, default: None) – Include variable property fields. If None, defaults to True.

Returns:

YAML representation of the root tree.

Return type:

str

setYaml(yml, writeEach, modes, incGroups=None, excGroups=None)[source]

Set variable values from YAML text.

Parameters:

yml (str) – YAML text containing values to apply.
writeEach (bool) – Write each variable as it is applied.
modes (list[str]) – Variable modes to include. Allowed values are 'RW', 'WO', and 'RO'.
incGroups (str | list[str] | None, default: None) – Group name or group names to include.
excGroups (str | list[str] | None, default: None) – Group name or group names to exclude.

Return type:

None

remoteVariableDump(name, modes, readFirst)[source]

Dump remote variable values to a file.

Parameters:

name (str | None) – Destination file path. If empty, a timestamped name is generated.
modes (list[str]) – Variable modes to include. Allowed values are 'RW', 'WO', and 'RO'.
readFirst (bool) – Read values from hardware before dumping.

Returns:

Returns True when dump completes.

Return type:

bool

add(node)

Add a child node to the device.

Return type:: None
Parameters:: node (Any)

addCustomBlock(block)

Add a pre-defined memory block to the device.

Return type:: None
Parameters:: block (Any)

addInterface(*interfaces)

Add stream or memory interfaces to manage.

Parameters:: *interfaces (Any | Iterable[Any]) – One or more interfaces or iterables of interfaces.
Return type:: None

addNode(nodeClass, **kwargs)

Construct and add a node of nodeClass.

Return type:

None

Parameters:

nodeClass (type[Node])
kwargs (Any)

addNodes(nodeClass, number, stride, **kwargs)

Add a series of nodes with indexed names.

Return type:

None

Parameters:

nodeClass (type[Node])
number (int)
stride (int)
kwargs (Any)

addProtocol(*protocols)

Add protocol entities (alias of addInterface).

Return type:: None
Parameters:: protocols (Any)

addRemoteVariables(number, stride, pack=False, **kwargs)

Add a repeating block of remote variables.

Parameters:

number (int) – Number of variables to add.
stride (int) – Byte stride between instances.
pack (bool, default: False) – If True, add a packed link variable for all entries.
**kwargs (Any) – Arguments forwarded to RemoteVariable.

Return type:

None

addToGroup(group)

Add this node to a group and propagate to children.

Parameters:: group (str) – Group name to add.
Return type:: None

property address: Any: Return the device base address.

callRecursive(func, nodeTypes=None, **kwargs)

Call a named method on this node and matching children.

Parameters:

func (str) – Method name to call.
nodeTypes (Iterable[type[Node]] | None, default: None) – Node types to include.
**kwargs (Any) – Arguments forwarded to the method call.

Return type:

None

checkBlocks(*, recurse=True, variable=None, **kwargs)

Check block transactions and notify variable listeners.

Parameters:

recurse (bool, default: True) – If True, recurse into child devices.
variable (Any | None, default: None) – Optional variable to check.
**kwargs (Any) – Additional arguments passed through to the transaction.

Return type:

None

command(**kwargs)

Decorator to add inline methods as commands.

The decorated function is used as LocalCommand(function=...). The command wrapper supplies keyword arguments root, dev, cmd, and arg; the function may accept any subset.

Return type:: Callable[[Callable[..., Any]], Callable[..., Any]]
Parameters:: kwargs (Any)

property commands: OrderedDict[str, BaseCommand]: Return direct child commands.

commandsByGroup(incGroups=None, excGroups=None)

Return commands filtered by group.

Return type:

OrderedDict[str, BaseCommand]

Parameters:

incGroups (str | list[str] | None)
excGroups (str | list[str] | None)

countReset()

Call countReset on all child devices.

Return type:: None

property description: str: Return the node description.

property deviceList: list[Device]: Return a recursive list of devices.

property devices: OrderedDict[str, Device]: Return direct child devices.

devicesByGroup(incGroups=None, excGroups=None)

Return devices filtered by group.

Return type:

OrderedDict[str, Device]

Parameters:

incGroups (str | list[str] | None)
excGroups (str | list[str] | None)

enableChanged(value)

Hook for reacting to enable state changes.

Return type:: None
Parameters:: value (Any)

property expand: bool: Return the expand state.

filterByGroup(incGroups, excGroups)

Return True if the node passes include/exclude filters.

Parameters:

incGroups (str | list[str] | None) – Group name or group names to include.
excGroups (str | list[str] | None) – Group name or group names to exclude.

Return type:

bool

find(*, recurse=True, typ=None, **kwargs)

Find all child nodes that are a base class of ‘typ’ and whose properties match all of the kwargs. For string properties, accepts regexes.

Parameters:

recurse (bool, default: True) – If True, recurse into child nodes.
typ (type[Node] | None, default: None) – Base class type to match.
**kwargs (Any)

Returns:

List of nodes that match the criteria.

Return type:

list[Node]

genDocuments(path, incGroups=None, excGroups=None)

Generate Sphinx documentation pages for this device.

Parameters:

path (str) – Output directory path.
incGroups (str | list[str] | None, default: None) – Group name or group names to include.
excGroups (str | list[str] | None, default: None) – Group name or group names to exclude.

Return type:

None

getNodes(typ, excTyp=None, incGroups=None, excGroups=None)

Get a filtered ordered dictionary of nodes. pass a class to typ to receive a certain type of node exc is a class type to exclude, incGroups is an optional group or list of groups that this node must be part of excGroups is an optional group or list of groups that this node must not be part of

Parameters:

typ (type[Node])
excTyp (type[Node] | None, default: None) – Type to exclude.
incGroups (str | list[str] | None, default: None) – Group name or group names to include.
excGroups (str | list[str] | None, default: None) – Group name or group names to exclude.

Returns:

Ordered dictionary of nodes.

Return type:

OrderedDict[str, Node]

getYaml(readFirst=False, modes=['RW', 'RO', 'WO'], incGroups=None, excGroups=None, recurse=True)

Return current values as YAML text.

Parameters:

readFirst (bool, default: False) – If True, perform a full hardware read before exporting.
modes (list[str], default: ['RW', 'RO', 'WO']) – Variable modes to include. Allowed values are 'RW', 'WO', and 'RO'.
incGroups (str | list[str] | None, default: None) – Group name or group names to include.
excGroups (str | list[str] | None, default: None) – Group name or group names to exclude.
recurse (bool, default: True) – If True, recurse into child devices.

Returns:

YAML-formatted representation of the node subtree.

Return type:

str

property groups: list[str]: Return the node groups.

property guiGroup: str | None: Return the GUI group label.

property hidden: bool: Return True if the node is hidden.

hideVariables(hidden, variables=None)

Hide a list of variables or variable names.

Parameters:

hidden (bool) – True to hide variables, False to show them.
variables (Iterable[Any] | None, default: None) – Iterable of variable names or variables.

Return type:

None

inGroup(group)

Return True if the node is in the provided group or groups.

Parameters:: group (str) – Group name or list of groups to test.
Return type:: bool

initialize()

Call initialize on all child devices.

Return type:: None

property isCommand: bool: Return True if this node is a command.

property isDevice: bool: Return True if this node is a device.

property isVariable: bool: Return True if this node is a variable (excluding commands).

isinstance(typ)

Return True if this node is an instance of typ.

Return type:: bool
Parameters:: typ (type[Node])

linkVariableGet(**kwargs)

Decorator to add inline linkedGet functions.

The decorated function is used as LinkVariable(linkedGet=...). The linked-get wrapper supplies keyword arguments dev, var, read, index, and check; the function may accept any subset.

Return type:: Callable[[Callable[..., Any]], Callable[..., Any]]
Parameters:: kwargs (Any)

makeRecursive(func, nodeTypes=None)

Create a recursive wrapper for a named method.

Parameters:

func (str) – Method name to call.
nodeTypes (Iterable[type[Node]] | None, default: None) – Node types to include.

Return type:

Callable[..., None]

manage(*interfaces)

Manage additional interfaces for start/stop.

Return type:: None
Parameters:: interfaces (Any)

property name: str: Return the node name.

node(name)

Return a direct child node by name.

Parameters:: name (str) – Child node name.
Return type:: Node

property nodeCount: int: Return the total node count.

property nodeList: list[Node]: Return a recursive list of nodes.

nodeMatch(name)

Match a node name, including array-style accessors.

Parameters:: name (str) – Node name or array accessor string.
Returns:: Matching nodes.
Return type:: list[Node]

property nodes: OrderedDict[str, Node]: Return an ordered dictionary of direct child nodes.

property offset: Any: Return the device offset.

property parent: Node: Return the parent node.

property path: str: Return the full node path.

printYaml(readFirst=False, modes=['RW', 'RO', 'WO'], incGroups=None, excGroups=None, recurse=False)

Print the YAML representation to stdout.

Parameters:

readFirst (bool, default: False) – If True, perform a full hardware read before exporting.
modes (list[str], default: ['RW', 'RO', 'WO']) – Variable modes to include. Allowed values are 'RW', 'WO', and 'RO'.
incGroups (str | list[str] | None, default: None) – Group name or group names to include.
excGroups (str | list[str] | None, default: None) – Group name or group names to exclude.
recurse (bool, default: False) – If True, recurse into child devices.

Return type:

None

readAndCheckBlocks(recurse=True, variable=None, checkEach=False)

Read and check all blocks.

Parameters:

recurse (bool, default: True) – If True, recurse into child devices.
variable (Any | None, default: None) – Optional variable to read.
checkEach (bool, default: False) – Perform per-variable verification checks.

Return type:

None

readBlocks(*, recurse=True, variable=None, checkEach=False, index=-1, **kwargs)

Read blocks in the background.

Parameters:

recurse (bool, default: True) – If True, recurse into child devices.
variable (Any | None, default: None) – Optional variable to read.
checkEach (bool, default: False) – Perform per-variable verification checks.
index (int, default: -1) – Optional index for array variables.
**kwargs (Any) – Additional arguments passed through to the transaction.

Return type:

None

removeFromGroup(group)

Remove this node from a group.

Parameters:: group (str) – Group name to remove.
Return type:: None

property root: Root: Return the root node.

setName((Slave)arg1, (str)arg2) → None :

C++ signature :: void setName(rogue::interfaces::memory::Slave {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >)

setPollInterval(interval, variables=None)

Set the poll interval for a group of variables.

Parameters:

interval (float) – Polling interval in seconds.
variables (Iterable[Any] | None, default: None) – Iterable of variable names or variables. If None, all variables with nonzero poll interval are updated.

Return type:

None

property variableList: list[BaseVariable]: Return a recursive list of variables and commands.

property variables: OrderedDict[str, BaseVariable]: Return direct child variables (excluding commands).

variablesByGroup(incGroups=None, excGroups=None)

Return variables filtered by group.

Return type:

OrderedDict[str, BaseVariable]

Parameters:

incGroups (str | list[str] | None)
excGroups (str | list[str] | None)

verifyBlocks(*, recurse=True, variable=None, checkEach=False, **kwargs)

Verify blocks in the background.

Parameters:

recurse (bool, default: True) – If True, recurse into child devices.
variable (Any | None, default: None) – Optional variable to verify.
checkEach (bool, default: False) – Perform per-variable verification checks.
**kwargs (Any) – Additional arguments passed through to the transaction.

Return type:

None

writeAndVerifyBlocks(force=False, recurse=True, variable=None, checkEach=False)

Write, verify, and check all blocks.

Parameters:

force (bool, default: False) – Force the write even if values are unchanged.
recurse (bool, default: True) – If True, recurse into child devices.
variable (Any | None, default: None) – Optional variable to write/verify.
checkEach (bool, default: False) – Perform per-variable verification checks.

Return type:

None

writeBlocks(*, force=False, recurse=True, variable=None, checkEach=False, index=-1, **kwargs)

Write all blocks held by this device.

Parameters:

force (bool, default: False) – Force the write even if values are unchanged.
recurse (bool, default: True) – If True, recurse into child devices.
variable (Any | None, default: None) – Optional variable to write.
checkEach (bool, default: False) – Perform per-variable verification checks.
index (int, default: -1) – Optional index for array variables.
**kwargs (Any) – Additional arguments passed through to the transaction.

Return type:

None