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
Command — command reference, including argument and return-value handling.
Blocks — the Block model in detail.
Groups — group semantics and framework conventions.
YAML Configuration — saving and loading configuration, where
NoConfigearns its place.Capture Data To Disk And Replay It — continue with capturing data to disk.