RemoteVariable

class pyrogue.RemoteVariable(*, name, description='', mode='RW', value=None, disp=None, enum=None, units=None, hidden=False, groups=None, minimum=None, maximum=None, lowWarning=None, lowAlarm=None, highWarning=None, highAlarm=None, base=<class 'pyrogue._Model.UInt'>, offset, numValues=0, valueBits=0, valueStride=0, bitSize=32, bitOffset=0, pollInterval=0, updateNotify=True, overlapEn=False, bulkOpEn=True, verify=True, retryCount=0, guiGroup=None, **kwargs)

Remote variable backed by a memory-mapped interface.

Parameters:

• name (str) – Variable name.

• description (str, default: '') – Human-readable description.

• mode (str, default: 'RW') – Access mode: RW, RO, or WO.

• value (Any, default: None) – Default value.

• disp (Any | None, default: None) – Display formatter or mapping.

• enum (dict[object, str] | None, default: None) – Mapping from object values to display strings.

• units (str | None, default: None) – Engineering units.

• hidden (bool, default: False) – If True, add the variable to the Hidden group.

• groups (list[str] | None, default: None) – Groups to assign.

• minimum (Any | None, default: None) – Minimum allowed value.

• maximum (Any | None, default: None) – Maximum allowed value.

• lowWarning (Any | None, default: None) – Low warning threshold.

• lowAlarm (Any | None, default: None) – Low alarm threshold.

• highWarning (Any | None, default: None) – High warning threshold.

• highAlarm (Any | None, default: None) – High alarm threshold.

• base (Model | Callable[[int], Model], default: <class 'pyrogue._Model.UInt'>) – Base model instance or model factory.

• offset (int | list[int]) – Memory offset or list of offsets.

• numValues (int, default: 0) – Number of values for array variables.

• valueBits (int, default: 0) – Bits per value for array variables.

• valueStride (int, default: 0) – Bit stride between values.

• bitSize (int | list[int], default: 32) – Bit size of the variable.

• bitOffset (int | list[int], default: 0) – Bit offset of the variable.

• pollInterval (Any, default: 0) – Polling interval.

• updateNotify (bool, default: True) – Enable update notifications.

• overlapEn (bool, default: False) – Allow overlapping variables.

• bulkOpEn (bool, default: True) – Enable bulk operations.

• verify (bool, default: True) – Enable verify on write.

• retryCount (int, default: 0) – Retry count for transactions.

• guiGroup (str | None, default: None) – GUI grouping label.

• **kwargs (Any) – Additional arguments forwarded to BaseVariable.

property address: int

Return the absolute address of the variable.

property numValues: int

Return the configured number of values for array variables.

property valueBits: int

Return number of valid bits per array value.

property valueStride: int

Return bit-stride between adjacent array values.

property retryCount: int

Return transaction retry count for this variable.

property varBytes: int

Return the byte size of the variable.

property offset: int

Return the memory offset.

property overlapEn: bool

Return True if overlap is enabled.

property bitSize: int

Return the bit size.

property bitOffset: int

Return the bit offset.

property verifyEn: bool

Return True if verify is enabled.

property base: Model

Return the base model or type.

property bulkEn: bool

Return True if bulk operations are enabled.

set(value, *, index=-1, write=True, verify=True, check=True)

Set the value and write to hardware if applicable Writes to hardware are blocking if check=True, otherwise non-blocking. A verify will be performed according to self.verifyEn if verify=True A verify will not be performed if verify=False An error will result in a logged exception.

Parameters:

• value (Any) – Value to set.

• index (int, default: -1) – Optional index for array variables.

• write (bool, default: True) – If True, perform a write transaction.

• verify (bool, default: True) – If True, verify after write.

• check (bool, default: True) – If True, check transaction completion.

Return type:

None

post(value, *, index=-1)

Set the value and write to hardware if applicable using a posted write. This method does not call through parent.writeBlocks(), but rather calls on self._block directly.

Parameters:

• value (Any) – Value to set.

• index (int, default: -1) – Optional index for array variables.

Return type:

None

get(*, index=-1, read=True, check=True)

Return the value, optionally reading from hardware.

Hardware read is blocking if check=True, otherwise non-blocking. An error will result in a logged exception. Listeners will be informed of the update.

Parameters:

• index (int, default: -1) – Optional index for array variables.

• read (bool, default: True) – If True, perform a read transaction.

• check (bool, default: True) – If True, check transaction completion.

Return type:

Any

write(*, verify=True, check=True)

Force a write of the variable. Hardware write is blocking if check=True. A verify will be performed according to self.verifyEn if verify=True A verify will not be performed if verify=False An error will result in a logged exception

Parameters:

• verify (bool, default: True) – If True, verify after write.

• check (bool, default: True) – If True, check transaction completion.

Return type:

None

add(node)

Add a node as a child.

Return type:

None

Parameters:

node (Node | Iterable[Node])

addDependency(dep)

Add a dependency variable. When this variable changes, the dependency variable will be notified.

Parameters:

dep (BaseVariable) – The dependency variable to add.

Return type:

None

addListener(listener)

Add a listener Variable or function to call when variable changes. This is useful when chaining variables together. (ADC conversions, etc) The variable and value class are passed as an arg: func(path,varValue)

Parameters:

listener (BaseVariable | Callable[[str, VariableValue], None]) – Variable or callback function to notify.

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)

addToGroup(group)

Add this node to a group and propagate to children.

Parameters:

group (str) – Group name to add.

Return type:

None

property alarmSeverity: str

Return the current alarm severity.

property alarmStatus: str

Return the current alarm status.

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

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)

delListener(listener)

Remove a listener Variable or function

Parameters:

listener (BaseVariable | Callable[[str, VariableValue], None]) – Variable or callback function to remove.

Return type:

None

property dependencies: list[BaseVariable]

Return registered dependency variables.

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)

property disp: str

Return the display formatter.

property enum: dict[object, str] | None

Return the enum mapping, if any.

property enumYaml: str

Return the enum mapping as YAML.

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]

genDisp(value, *, useDisp=None)

Generate a display string for a value.

Parameters:

• value (Any) – Value to format for display.

• useDisp (str | None, default: None) – Display formatter override. If None, use the variable’s disp formatter.

Return type:

str

getDisp(read=True, index=-1)

Perform a get() and return the display string for the value.

Parameters:

• read (bool, default: True) – If True, perform a read transaction.

• index (int, default: -1) – Optional index for array variables.

Return type:

str

getExtraAttribute(name)

Return an extra attribute by name, if present.

Parameters:

name (str) – Attribute name to look up.

Return type:

Any | 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]

getVariableValue(read=True, index=-1)

Return the value after performing a read from hardware if applicable. Hardware read is blocking. An error will result in a logged exception. Listeners will be informed of the update.

Parameters:

• read (bool, default: True) – If True, perform a read transaction.

• index (int, default: -1) – Optional index for array variables.

Return type:

VariableValue

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 hasAlarm: bool

Return True if any alarm thresholds are configured.

property hidden: bool

Return True if the node is hidden.

property highAlarm: Any | None

Return the high alarm threshold.

property highWarning: Any | None

Return the high warning threshold.

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

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])

property lock: threading.Lock | None

Return the underlying lock, if available.

property lowAlarm: Any | None

Return the low alarm threshold.

property lowWarning: Any | None

Return the low warning threshold.

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]

property maximum: Any | None

Return the maximum allowed value.

property minimum: Any | None

Return the minimum allowed value.

property mode: str

Return the access mode (RW, RO, WO).

property name: str

Return the node name.

property nativeType: Type[object]

Return the native Python type.

property ndType: Type[dtype]

Return the numpy dtype for array variables.

property ndTypeStr: str

Return the numpy dtype as a string.

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 parent: Node

Return the parent node.

parseDisp(sValue)

Parse a string representation of a value into a Python object.

Parameters:

sValue (str) – Display-formatted value to parse.

Return type:

object

property path: str

Return the full node path.

property pollInterval: float

Return the poll interval.

property precision: int

Return the display precision for float-like values.

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

properties()

Return a dictionary of properties and current value.

Return type:

dict[str, Any]

removeFromGroup(group)

Remove this node from a group.

Parameters:

group (str) – Group name to remove.

Return type:

None

property revEnum: dict[str, object] | None

Return the reverse enum mapping, if available.

property root: Root

Return the root node.

setDisp(sValue, write=True, index=-1)

Set the value of the variable using a string representation of the value.

Parameters:

• sValue (str) – Display-formatted value to set.

• write (bool, default: True) – If True, write the value to the hardware.

• index (int, default: -1) – Optional index for array variables.

Return type:

None

setPollInterval(interval)

Set the poll interval.

Parameters:

interval (float) – Poll interval to use.

Return type:

None

property typeStr: str

Return the type string for this variable.

property units: str | None

Return the engineering units.

property updateNotify: bool

Return True if update notifications are enabled.

value(index=-1)

Return the current value without reading.

Parameters:

index (int, default: -1) – Optional index for array variables.

Return type:

Any

valueDisp(index=-1)

Return a display string for the current value without reading.

Parameters:

index (int, default: -1) – Optional index for array variables.

Return type:

str

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)