Root

The Root class is the fundamental building block of the PyRogue Tree. The tree hierarchy starts with a root node.

The root node is the base of the tree and provides tree wide access methods

These methods are used to manage and update the system tree
In python, the root node class is created the following way:

Root = pyrogue.Root(name='name', description='description')

Root classes should be created a sub-class of Root

class EvalBoard(pyrogue.Root):
   def __init__(self):
      pyrogue.Root.__init__(self,name='evalBoard',description='Evaluation Board')

Hardware interfaces (pgp, rssi, udp) can be created and linked within the Root class pyrogue.Root.init() method
Epics and pyro servers can be started within the root class init() method
Typical top level file utilizing our previously created root class:

if __name__ == "__main__":
   evalBoard = EvalBoard()
   appTop = PyQt4.QtGui.QApplication(sys.argv)
   guiTop = pyrogue.gui.GuiTop(group='rogueTest')
   guiTop.addTree(evalBoard)
   appTop.exec_()
   evalboard.stop()

Key Attributes

Along with all other Node class parameters, the following are also included:

running: True/False flag indicating if the Root class is running pyrogue.Root.start() has been called

Key Methods

pyrogue.Root.start()
pyrogue.Root.stop()
- Stop the root class and all of its associated background threads
pyrogue.Root.addVarListener()
- Add a system level variable listener. See more in Variable
pyrogue.Root.getNode()
- Return a node at the full path. Ex: evalBoard.AxiVersion.ScratchPad

Yaml File Configuration

Saving and Restoring Configurations

System wide configurations and be saved to or restored from yaml strings using provided methods.

pyrogue.Node.getYaml() (Note: inherited from pyrogue.Node class.)
pyrogue.Root.setYaml()

Configuration Array Matching

In some cases there will be devices or variable that are part of an array, such as:

AmcCard[0] - DacEnable[0], DacEnable[1]
AmcCard[1] - DacEnable[0], DacEnable[1]
AmcCard[2] - DacEnable[0], DacEnable[1]

In cases like this, Yaml configuration file can be setup to apply settings to multiple elements. Python list slicing indexes are used, as well as additional wildcards.

To Enable Dac channel 0 in both AMCS:
- AmcCard:DacEnable[0]: True
To Enable both DAC channels in AMC cards 1 and 2:
- AmcCard[1:3]: DacEnable: True
Example list splicing:
- AmcCard[1:3] accesses AmcCards 1 & 2
- AmcCard[:2] accesses AmcCards 0 & 1
- AmcCard[:] accesses all AmcCards
Example wildcard features:
- AmcCard = all cards
- AmcCard[*] = all cards

Included Command Objects

The following pyrogue.LocalCommand objects are all created when the Root node is created.

WriteAll: Write every variable value to hardware (hidden from the GUI).
ReadAll: Read every variable value from hardware.
SaveState: Save state to file in yaml format.
SaveConfig: Save configuration to file. Data is saved in YAML format.
LoadConfig: Read configuration from file. Data is read in YAML format.
RemoteVariableDump: Save a dump of the remote variable state.
RemoteConfigDump: Save a dump of the remote configuration state.
Initialize: Generate a soft reset to each device in the tree.
HardReset: Generate a hard reset to each device in the tree.
CountReset: Generate a count reset to each device in the tree.
ClearLog: Clear the message log contained in the SystemLog variable.
SetYamlConfig: Set configuration from YAML string.
GetYamlConfig: Get configuration in YAML string.
GetYamlState: Get current state as YAML string.

Included Variable Objects

The following pyrogue.LocalVariable objects are all created when the Root node is created.

RogueVersion: Rogue version string.
RogueDirectory: Rogue Library Directory.
SystemLog: String containing newline separated system logic entries. Allows remote management interfaces to know when an error has occurred. This string contains a summary of the error while the full trace method is dumped to the console.
SystemLogLast: String containing last system log entry.
ForceWrite: Controls how system level writes are handled. Configuration flag to always write non stale blocks for WriteAll, LoadConfig and setYaml.
InitAfterConfig: Configuration flag to execute initialize after LoadConfig or setYaml.
Time: Current time in seconds since EPOCH UTC.
LocalTime: Local time.
PollEn: Polling worker.

Below is an example of creating a root device in C++.

#include <rogue/interfaces/memory/Constants.h>
#include <boost/thread.hpp>

// Create a subclass of a root
class MyRoot : public rogue:: ... {
   public:

   protected:

};

A few notes on the above examples …

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. The root is a stream master which generates frames containing tree configuration and status values. This allows configuration and status to be stored in data files.

Variables:: rogue.interfaces.stream.Master

pr.Device :

start()[source]: Setup the tree. Start the polling thread.

stop()[source]: Stop the polling thread. Must be called for clean exit.

property running

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

Add a variable update listener function. The variable and value structure will be passed as args: func(path,varValue)

Parameters:

func
done
incGroups
excGroups

updateGroup(period=0)[source]

Parameters:: period – (Default value = 0)

pollBlock()[source]

waitOnUpdate()[source]: Wait until all update queue items have been processed.

hardReset()[source]: Generate a hard reset on all devices

getNode(path)[source]

Parameters:: path

saveAddressMap(fname)[source]

Parameters:

fname
headerEn – (Default value = False)

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

Parameters:

fname
polledOnly (bool) – (Default value = False)
incGroups – (Default value = None)

saveYaml(name, readFirst, modes, incGroups, excGroups, autoPrefix, autoCompress)[source]

Save YAML configuration/status to a file. Called from command

Parameters:

name
readFirst
modes
incGroups
excGroups
autoPrefix
autoCompress

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

Load YAML configuration from a file. Called from command

Parameters:

name
writeEach
modes
incGroups
excGroups

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

Set variable values from a yaml file modes is a list of variable modes to act on. writeEach is set to true if accessing a single variable at a time. Writes will be performed as each variable is updated. If set to false a bulk write will be performed after all of the variable updates are completed. Bulk writes provide better performance when updating a large quantity of variables.

Parameters:

yml
writeEach
modes
incGroups
excGroups

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

Dump remote variable values to a file.

Parameters:

name
modes
readFirst

add(node)

Parameters:: node

addCustomBlock(block)

Parameters:: block

addInterface(*interfaces)

Add one or more rogue.interfaces.stream.Master or rogue.interfaces.memory.Master Also accepts iterables for adding multiple at once

Parameters:: *interfaces

addNode(nodeClass, **kwargs)

Parameters:

nodeClass
**kwargs

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

Parameters:

nodeClass
number
stride
**kwargs

addProtocol(*protocols)

Add a protocol entity. Also accepts iterables for adding multiple at once

Parameters:: *protocols

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

Parameters:

number
stride
pack (bool) – (Default value = False)
**kwargs

addToGroup(group)

Add this node to the passed group, recursive to children

Parameters:: group – variable denoting a node that has not been passed

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

Parameters:

func
nodeTypes – (Default value = None)
**kwargs

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

Check errors in all blocks and generate variable update notifications

Parameters:: *

recursebool: (Default value = True)
variablestr: (Default value = None)

**kwargs :

command(**kwargs)

A Decorator to add inline constructor functions as commands

Parameters:: **kwargs

commandsByGroup(incGroups=None, excGroups=None)

Parameters:

incGroups – (Default value = None)
excGroups – (Default value = None)

Returns:

Pass list of include and / or exclude groups

Return type:

type

property description: assigns and returns description attribute to class variable

property deviceList: Get a recursive list of devices

devicesByGroup(incGroups=None, excGroups=None)

Parameters:

incGroups – (Default value = None)
excGroups – (Default value = None)

Returns:

Pass list of include and / or exclude groups

Return type:

type

enableChanged(value)

Parameters:: value

filterByGroup(incGroups, excGroups)

Filter by the passed list of inclusion and exclusion groups

Parameters:

incGroups – list of passed inclusion groups
excGroups – list of passed exclusion groups

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 – (Default value = True)
typ – (Default value = None)
**kwargs

genDocuments(path, incGroups, excGroups)

Parameters:

path
incGroups
excGroups

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

Get a filtered ordered dictionary of nodes. pass a class type to receive a certain type of node class type may be a string when called over Pyro4 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
excTyp – (Default value = None)
incGroups – (Default value = None)
excGroups – (Default value = None)

Return type:

ordered dictionary of nodes

getYaml(readFirst=False, modes=['RW', 'RO', 'WO'], incGroups=None, excGroups=['Hidden'], recurse=True): Get current values as yaml data. modes is a list of variable modes to include. If readFirst=True a full read from hardware is performed.

property groups: assigns and returns groups attribute to class variable

property hidden: assigns and returns hidden attribute to class variable

hideVariables(hidden, variables=None)

Hide a list of Variables (or Variable names)

Parameters:

hidden
variables (str) – (Default value = None)

inGroup(group)

Parameters:: group

isinstance(typ)

Parameters:: typ

linkVariableGet(**kwargs)

Decorator to add inline constructor functions as LinkVariable.linkedGet functions

Parameters:: **kwargs

makeRecursive(func, nodeTypes=None)

Parameters:

func
nodeTypes – (Default value = None)

manage(*interfaces)

Parameters:: *interfaces

property name: assigns and returns name attribute to class variable

node(name)

Parameters:: name

property nodeList: Get a recursive list of nodes.

nodeMatch(name)

Parameters:: name
Returns:: be a single value or a list accessor: value value[9] value[0:1] value[*] value[:] Variables will only match if their depth matches the passed lookup and wildcard: value[*] will match a variable named value[1] but not a variable named value[2][3] value[*][*] will match a variable named value[2][3]. The second return field will contain the array information if the base name matches an item in the non list array.
Return type:: type

property nodes: Get a ordered dictionary of all nodes.

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

Perform a read and check.

Parameters:

recurse (bool) – (Default value = True)
variable (str) – (Default value = None)
checkEach (bool) – (Default value = False)

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

Perform background reads

Parameters:: *

recursebool: (Default value = True)
variablestr: (Default value = None)
checkEachbool: (Default value = False)
indexint: (Default value = -1)

**kwargs :

removeFromGroup(group)

Remove this node from the passed group, not recursive

Parameters:: group – variable denoting a node that is in the passed group
Return type:: if in group, remove from group

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. The variables param is an Iterable of strings If variables=None, set interval for all variables that currently have nonzero pollInterval

Parameters:

interval
variables (str) – (Default value = None)

property variableList: Get a recursive list of variables and commands.

variablesByGroup(incGroups=None, excGroups=None)

Parameters:

incGroups – (Default value = None)
excGroups – (Default value = None)

Returns:

Pass list of include and / or exclude groups

Return type:

type

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

Perform background verify

Parameters:: *

recursebool: (Default value = True)
variablestr: (Default value = None)
checkEachbool: (Default value = False)

**kwargs :

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

Perform a write, verify and check. Useful for committing any stale variables

Parameters:

force (bool) – (Default value = False)
recurse (bool) – (Default value = True)
variable (str) – (Default value = None)
checkEach (bool) – (Default value = False)

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

Write all of the blocks held by this Device to memory

Parameters:

*
force (bool) – (Default value = False)
recurse (bool) – (Default value = True)
variable (str) – (Default value = None)
checkEach (bool) – (Default value = False)
index (int) – (Default value = -1)
**kwargs