Groups

PyRogue groups are string tags attached to Node objects such as Device, Variable, and Command. They are used to filter bulk operations, logging, streaming, remote exposure, and other workflows that need to act on one subset of the tree but not another.

The group model is intentionally open-ended. PyRogue defines a few names with framework meaning, but applications are free to add project-specific group names for their own workflows.

What Groups Are For

Groups let a tree carry workflow policy directly on the Nodes it exposes.

That is useful when the same tree needs to support different views or actions, for example:

  • Configuration save and load versus live runtime state

  • Stream or SQL logging versus local-only values

  • Operator-facing views versus internal helper Nodes

  • Project-specific subsets such as commissioning-only or debug-only controls

This is why groups appear throughout PyRogue APIs as incGroups and excGroups filters. Instead of hard-coding per-Node rules in every bulk operation, the operation can ask the tree which Nodes belong in the requested workflow.

How Group Filtering Works

Most tree APIs that accept incGroups and excGroups use the same basic rule:

  • If incGroups is empty, the include check passes by default.

  • If incGroups is set, the Node must be in at least one of those groups.

  • If excGroups is empty, the exclude check passes by default.

  • If excGroups is set, the Node must be in none of those groups.

A Node is processed only if both checks pass.

In the implementation, group membership is simple set-style string matching. There is no special hierarchy inside the group names themselves.

Built-In Group Names

A small set of group names have established framework meaning in the current implementation.

Hidden

Added automatically when a Node is constructed with hidden=True.

This is the main presentation-oriented group. GUI and helper defaults commonly exclude Hidden Nodes unless the user explicitly asks to include them.

NoConfig

Used for Nodes that should be excluded from configuration save and load workflows.

In practice, Root-level configuration commands such as SaveConfig, LoadConfig, SetYamlConfig, and GetYamlConfig exclude this group by default. Use it for runtime-only or status-oriented values that should not be persisted as configuration.

NoState

Used for Nodes that should be excluded from state snapshots or state-export workflows.

In practice, Root-level state-export commands such as SaveState and GetYamlState exclude this group by default. Use it for values that are transient, local-only, or otherwise not meaningful to capture in a saved state image.

NoStream

Used by Variable streaming workflows to suppress Nodes from the default stream output.

In practice, Variable streaming interfaces exclude this group by default. Use it when a Node should remain in the tree but should not be emitted through the normal Variable stream path.

This is commonly used to prevent internal or low-value Variables from being sent to stream-based logging or recording paths.

NoSql

Used by SQL logging workflows to suppress Nodes from default SQL logging.

Use it for values that would add noise, have little long-term value, or should not be recorded in that logging path.

NoServe

Used for Nodes that should not be exposed through served remote views such as ZMQ or virtual-tree interfaces.

In practice, served remote-node lists exclude this group by default. Use it for local-only controls or internal Nodes that should remain present in the process but not be published outward.

Enable

Used by the built-in enable-variable pattern as a semantic label. It is better treated as a framework convention than as a general-purpose workflow filter, and it should not be reused for unrelated meanings.

This is a convention used by framework components, not a hard filter category by itself.

Custom Groups In Practice

Application-specific groups are often the most useful ones day to day.

import pyrogue as pr

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

        self.add(pr.RemoteVariable(
            name='BiasTrim',
            mode='RW',
            offset=0x00,
            bitSize=16,
            groups=['Commissioning'],
        ))

        self.add(pr.RemoteVariable(
            name='DebugCounter',
            mode='RO',
            offset=0x04,
            bitSize=32,
            groups=['Debug', 'NoConfig', 'NoState'],
        ))

With that structure, bulk workflows can include or exclude those Nodes without hard-coding special cases into every command or script.

Group Assignment Notes

Groups are stored directly on each Node as strings.

Two practical details matter:

  • Passing groups=... during construction assigns the initial group list.

  • Calling addToGroup() on a Node propagates that group to its children.

That propagation behavior is useful when an entire subtree should participate in one workflow policy.

Other Names You May See

NoAlarm appears in some examples and project code, but there is no core framework behavior tied to that name in this repository. Treat it as a project-level convention unless your application defines logic for it.

Design Guidance

Good group usage is usually straightforward:

  • Keep the built-in names aligned with their established semantics.

  • Add project-specific groups when they clearly represent a real workflow or view.

  • Document custom groups near the Root or Device definitions that rely on them.

  • Prefer incGroups and excGroups over ad hoc per-Node conditionals in bulk operations.

What To Explore Next

  • Root workflows that use group filters: Root

  • Variable presentation and group metadata: Variable

  • YAML configuration and state export filters: YAML Configuration

API Reference

See Node for generated API details on Node group properties and helpers.