PyRogue Tree Components And Concepts

A PyRogue tree is defined by the object model and runtime behavior of Root, Device, Variable, and Command Nodes, with Block and Model providing memory transaction grouping and typed value conversion.

A typical hierarchy starts at one Root and fans into multiple Device subtrees. Each Device can contain child Device Nodes, Variable Nodes, and Command Nodes. At runtime, the Root coordinates startup, background polling, and system-wide read/write operations across that hierarchy.

This subsection is intentionally split into foundational pages first and more specialized mechanics later. Most readers should understand Root, Device, Variable, and Command before diving into Block, Model, polling internals, YAML bulk configuration, or stream adapters.

Minimal Tree Example

import pyrogue as pr
import pyrogue.interfaces

class DemoDevice(pr.Device):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)

        self.add(pr.LocalVariable(
            name='Enable',
            mode='RW',
            value=False,
        ))

        self.add(pr.LocalCommand(
            name='Reset',
            function=lambda: print('Reset requested'),
        ))

class DemoRoot(pr.Root):
    def __init__(self):
        super().__init__(name='DemoRoot', pollEn=False)

        self.add(DemoDevice(name='App'))

        # Optional: expose the running tree to remote clients.
        self.addInterface(pyrogue.interfaces.ZmqServer(
            root=self,
            addr='127.0.0.1',
            port=0,
        ))

This composition pattern is the foundation for most PyRogue applications: Root owns lifecycle, Device organizes hardware/application structure, and Variable/Command Nodes expose state and actions.

How To Read This Subsection

Use the core pages in this order:

Root for lifecycle, startup, and whole-tree control behavior.
Device for composition, interface ownership, and block traversal.
Variable and Command for the two main leaf-node interaction models.
The subtype pages for local, remote, and link variants.
The more advanced mechanics pages once the tree model itself is familiar.

That ordering keeps the conceptual model stable before introducing the details of memory grouping, typed encoding, polling internals, and YAML bulk configuration.

Core Node Model

Node is the common base class for the full tree object model. Every Root, Device, Variable, and Command inherits shared identity and hierarchy behavior (name/path/root/parent relationships).

The shared responsibilities of Node-derived types include:

Stable hierarchical addressing and lookup
Group tagging/filtering support
Lifecycle attachment to a Root context
Shared logging/path conventions across all subclasses

Concrete Node Categories

Common Design Workflow

Define one Root for lifecycle, top-level interfaces, and system actions.
Partition the design into Device subtrees by hardware/function boundary.
Add Variable and Command Nodes for control and telemetry procedures.
Choose local, remote, or linked Node subtypes as needed.
Confirm memory mapping and typed conversion behavior through Block and Model.
Expose remote access patterns for GUIs, scripts, notebooks, and clients.

Advanced Topics And Why They Are Separate

Some pages in this subsection are deliberately separated because they describe mechanics that matter a lot in real systems, but are usually not the right starting point:

Block is about transaction grouping and memory access flow.
Device Block Operations is about recursive Device traversal and sequencing of the *Blocks methods.
Model is about typed byte conversion and custom encodings.
Fixed-Point Models is a focused companion page for Fixed and UFixed usage.
Poll Queue is about background scheduling behavior.
YAML Configuration is about YAML save/load workflows, matching rules, and configuration file structure.
Memory Variable Stream is about bridging variable updates into stream processing paths.
Groups is about filtering and bulk-operation scoping.

Those topics belong in core because they define how the tree behaves, but they are advanced enough that they read better as focused pages rather than as long detours inside the introductory Root/Device/Variable docs.

What To Explore Next

Root lifecycle and orchestration: Root
Device composition and managed interfaces: Device
Variable behavior and types: Variable
Command behavior and invocation patterns: Command
Block transaction behavior: Blocks
Device block traversal and sequencing: Device Block Operations
Model conversion behavior: Model
Fixed-point model details: Fixed-Point Models
Poll scheduling behavior: PollQueue
YAML save/load behavior: YAML Configuration
Variable-to-stream adapter behavior: Variable Update Stream

API Reference

Python: Root, Device, BaseVariable, BaseCommand, Model

Core: