Commands, Blocks, And Groups

Build Your First Rogue Application used variables to read and write registers. That covers state, but not actions — and it says nothing about how Rogue batches register access or how bulk operations decide what to include.

This tutorial covers three mechanisms that work together in every real application:

  • Commands perform actions rather than holding values.

  • Blocks decide how many memory transactions your variables actually cost.

  • Groups label nodes so bulk operations can skip them.

Note

No hardware required. Everything here runs against rogue.interfaces.memory.Emulate, the same software memory space used in Build Your First Rogue Application.

Prerequisites

Finish Build Your First Rogue Application. All examples below attach to one emulated memory space:

class TutorialRoot(pr.Root):
    """Hosts every Device above against one emulated memory space."""

    def __init__(self, **kwargs):
        super().__init__(description='Commands, Blocks and Groups',
                         timeout=2.0, **kwargs)

        self._sim = rogue.interfaces.memory.Emulate(4, 0x10000)
        self._sim.setName('SimSlave')
        self.addInterface(self._sim)

        self.add(CommandDevice(name='Cmds', memBase=self._sim, offset=0x0000))
        self.add(PackedDevice(name='Packed', memBase=self._sim, offset=0x1000))
        self.add(SpreadDevice(name='Spread', memBase=self._sim, offset=0x2000))
        self.add(GroupDevice(name='Groups', memBase=self._sim, offset=0x3000))

Part 1: Commands

A Command is a node you invoke. Rogue offers three kinds, and picking the wrong one is a common source of awkward code:

class CommandDevice(pr.Device):
    """All three command flavours on one Device.

    ``RemoteCommand`` writes to hardware, the ``@self.command`` decorator runs
    arbitrary Python, and ``LocalCommand`` wraps a plain callable that returns
    a value.
    """

    def __init__(self, **kwargs):
        super().__init__(description='Commands demonstration', **kwargs)

        self.add(pr.RemoteVariable(
            name        = 'Control',
            description = 'Control register written by commands',
            offset      = 0x00,
            bitSize     = 32,
            base        = pr.UInt,
            mode        = 'RW',
            disp        = '{:#010x}'))

        # A RemoteCommand writes a value to an address. ``post()`` fires the
        # write without waiting for a response, which is what you want for a
        # self-clearing trigger bit.
        self.add(pr.RemoteCommand(
            name        = 'Pulse',
            description = 'Strobe a self-clearing trigger bit',
            offset      = 0x10,
            bitSize     = 1,
            base        = pr.UInt,
            function    = lambda cmd: cmd.post(1)))

        # The decorator form is the shortest way to attach a procedure that
        # touches several Variables. ``arg`` carries the caller's value.
        @self.command(value=0, description='Write an arbitrary Control value')
        def SetControl(arg):
            self.Control.set(int(arg))

        # A LocalCommand touches no registers at all. Use it for host-side
        # helpers that report something back.
        self.add(pr.LocalCommand(
            name        = 'Describe',
            description = 'Return a host-side summary string',
            function    = lambda: 'CommandDevice ready',
            retValue    = ''))

RemoteCommand writes a value to an address. The function argument says what writing means: cmd.post(1) fires a write without waiting for a response, which is right for a self-clearing trigger bit where the hardware resets the bit itself and reading it back is pointless.

The @self.command decorator is the shortest form when the action is Python rather than a single register write — sequencing several variables, validating an argument, computing a value. The arg parameter carries whatever the caller passed.

LocalCommand touches no registers. Use it for host-side helpers, and set retValue when the caller should get something back.

Invoke all three the same way:

root.Cmds.Pulse()                 # RemoteCommand
root.Cmds.SetControl(0x55)        # decorator form, takes an argument
print(root.Cmds.Describe())       # LocalCommand, returns a value
Control after SetControl : 0x00000055
Describe returned        : CommandDevice ready

Part 2: Blocks

This is the part that surprises people. A Block is the unit Rogue actually reads and writes. Variables do not map one-to-one onto transactions — Rogue coalesces variables that share a register into a single Block, so one transaction serves all of them.

Three fields packed into one 32-bit register at the same offset, differing only in bitOffset:

class PackedDevice(pr.Device):
    """Three fields sharing one 32-bit register.

    Because all three use ``offset=0x00`` and differ only in ``bitOffset``,
    PyRogue coalesces them into a single ``Block`` -- so setting all three
    costs one memory transaction, not three.
    """

    def __init__(self, **kwargs):
        super().__init__(description='Three fields, one register', **kwargs)

        for name, bitOffset in (('Low', 0), ('Middle', 8), ('High', 16)):
            self.add(pr.RemoteVariable(
                name      = name,
                offset    = 0x00,
                bitSize   = 8,
                bitOffset = bitOffset,
                base      = pr.UInt,
                mode      = 'RW',
                disp      = '{:#04x}'))

The same three fields given addresses of their own:

class SpreadDevice(pr.Device):
    """The same three fields at separate addresses, for contrast.

    Identical API, but each Variable now owns a Block of its own, so the same
    three writes become three transactions.
    """

    def __init__(self, **kwargs):
        super().__init__(description='Three fields, three registers', **kwargs)

        for index, name in enumerate(('Low', 'Middle', 'High')):
            self.add(pr.RemoteVariable(
                name    = name,
                offset  = index * 4,
                bitSize = 8,
                base    = pr.UInt,
                mode    = 'RW',
                disp    = '{:#04x}'))

Identical API from the caller’s side, but the cost differs:

Blocks used by Packed (offset 0x00 x3) : 1
Blocks used by Spread (0x00/0x04/0x08) : 3

Writing all three packed fields is one transaction; writing the spread fields is three. Over a high-latency link, or across a register map with hundreds of fields, that ratio decides whether a tree scan takes milliseconds or seconds.

The fields remain independent — setting one does not disturb its neighbours, because Rogue performs a read-modify-write on the shared Block:

root.Packed.Middle.set(0x00)
assert root.Packed.Low.get() == 0xAA    # untouched
assert root.Packed.High.get() == 0xCC   # untouched

You rarely construct Blocks yourself. What matters is knowing they exist, since they explain why bit-packed register maps are worth the effort. See Blocks and Device Block Operations for the full model.

Part 3: Groups

A large tree contains values that should not be treated uniformly. Counters should not be written back from a saved configuration. Diagnostics need not be served to EPICS. Groups are labels that let bulk operations make those distinctions:

class GroupDevice(pr.Device):
    """Variables tagged with Groups so bulk operations can skip them.

    Groups are labels, not access control. Bulk operations such as
    ``getYaml()`` accept ``incGroups``/``excGroups`` and honour them; nothing
    stops a direct ``.get()`` on a tagged Variable.
    """

    def __init__(self, **kwargs):
        super().__init__(description='Groups demonstration', **kwargs)

        self.add(pr.RemoteVariable(
            name='Saved', offset=0x00, bitSize=32,
            base=pr.UInt, mode='RW'))

        # 'NoConfig' is the convention for values that should not be captured
        # in a saved configuration -- counters, status, scratch registers.
        volatile = pr.RemoteVariable(
            name='Volatile', offset=0x04, bitSize=32,
            base=pr.UInt, mode='RW')
        self.add(volatile)
        volatile.addToGroup('NoConfig')

        # 'NoServe' keeps a value out of EPICS and other servers by default.
        private = pr.RemoteVariable(
            name='Private', offset=0x08, bitSize=32,
            base=pr.UInt, mode='RW')
        self.add(private)
        private.addToGroup('NoServe')

Two conventional names appear here. NoConfig marks values that should not be captured in a saved configuration; NoServe keeps a value out of EPICS and similar servers by default.

Groups take effect when a bulk operation filters on them:

everything = root.getYaml(readFirst=False, modes=['RW'],
                          incGroups=None, excGroups=None)
config     = root.getYaml(readFirst=False, modes=['RW'],
                          incGroups=None, excGroups=['NoConfig'])
Volatile in full dump   : True
Volatile in saved config: False
Volatile groups         : ['NoConfig']

Important

Groups are labels, not access control. A variable tagged NoServe is still fully readable and writable through .get() and .set() — the tag only affects operations that choose to honour it. Do not use Groups to protect dangerous registers.

Running It

python3 commands_and_groups.py
--- Commands
   Control after SetControl : 0x00000055
   Describe returned        : CommandDevice ready
--- Blocks
   packed values  : 0xaa 0xbb 0xcc
   Blocks used by Packed (offset 0x00 x3) : 1
   Blocks used by Spread (0x00/0x04/0x08) : 3
--- Groups
   Saved in full dump      : True
   Volatile in full dump   : True
   Volatile in saved config: False
   Volatile groups         : ['NoConfig']

Where To Go Next