Build Your First Rogue Application
Build a complete, working Rogue application from an empty file, run it, and read and write registers from it.
Note
No hardware required. This guide uses Rogue’s built-in memory emulator and PRBS data generator, so everything here runs on a laptop with nothing attached. For board-level walkthroughs that do use real hardware, see Hardware-Based Walkthroughs at the end of this page.
By the end you will have a single Python file, about 45 lines, containing a
Root with an emulated register space, a custom Device with registers you
can read and write, and a self-testing data stream.
Prerequisites
A working Rogue installation is the only requirement. If you do not have one yet, Installing & Compiling Rogue covers the options; the Miniforge route in Installing Rogue With Miniforge is the quickest. Verify it before continuing:
python3 -c "import pyrogue; print(pyrogue.__version__)"
This should print a version such as 6.15.0. If it raises
ImportError, Rogue is not on your PYTHONPATH yet — return to
Installing & Compiling Rogue.
Some familiarity with Python classes is assumed. No C++ is needed.
Step 1: A Root That Runs
Every Rogue application is a tree with a Root
at the top. Create my_app.py:
import pyrogue as pr
class MyRoot(pr.Root):
def __init__(self, **kwargs):
super().__init__(description='Minimal example root',
timeout=2.0, pollEn=True, **kwargs)
if __name__ == '__main__':
with MyRoot() as root:
print('Tree is running')
Run it with python3 my_app.py. The with block is what starts and cleanly
stops the tree, so always use it rather than constructing MyRoot() bare.
This tree is empty but functional. The next step gives it something to talk to.
Step 2: An Emulated Register Space
Normally a Root reaches hardware over PCIe, Ethernet, or similar. Instead we
attach a memory emulator — a software
stand-in that behaves like a register space, which is what makes this guide
hardware-free.
Add the import and the three highlighted lines:
import pyrogue as pr
import rogue.interfaces.memory
class MyRoot(pr.Root):
def __init__(self, **kwargs):
super().__init__(description='Minimal example root',
timeout=2.0, pollEn=True, **kwargs)
sim = rogue.interfaces.memory.Emulate(4, 0x1000)
sim.setName('SimSlave')
self.addInterface(sim)
The arguments are the word size in bytes (4) and the size of the emulated space
(0x1000, so 4 KiB). addInterface hands ownership to the Root so the
emulator is started and stopped with the tree.
Step 3: A Device With Registers
A Device groups registers. Each RemoteVariable maps to an address in the memory space; a LocalVariable is computed in Python and touches no hardware at all.
Add this class above MyRoot:
class MyDevice(pr.Device):
def __init__(self, **kwargs):
super().__init__(description='Minimal register map', **kwargs)
self.add(pr.RemoteVariable(
name = 'ScratchPad',
description = 'Read/write test register',
offset = 0x04,
bitSize = 32,
base = pr.UInt,
mode = 'RW',
disp = '{:#010x}'))
self.add(pr.LocalVariable(
name = 'Doubled',
mode = 'RO',
value = 0,
localGet = lambda: self.ScratchPad.value() * 2))
offset is the byte address within the device, bitSize the register
width, mode the access policy ('RW' or 'RO'), and disp the
display format — '{:#010x}' renders values as 0x1234abcd.
Doubled reads no register. Its localGet callback runs on demand, which is
the normal way to expose a derived quantity.
Then add the device inside MyRoot.__init__, after the emulator:
self.add(MyDevice(name='MyDevice', memBase=sim, offset=0x0))
memBase=sim points the device at the emulator, and offset=0x0 places it
at the base of that space. A register’s final address is the device offset
plus the variable offset — so ScratchPad lands at 0x04.
Step 4: A Self-Testing Data Stream
Rogue’s other half is the stream interface, for bulk data rather than registers. A PRBS transmitter generates test frames and a matching receiver validates them, so you get a working data path with no hardware and no custom code.
Add the import and, at the end of MyRoot.__init__:
import pyrogue.utilities.prbs
self._prbsTx = pr.utilities.prbs.PrbsTx(name='PrbsTx')
self._prbsRx = pr.utilities.prbs.PrbsRx(name='PrbsRx')
self._prbsTx >> self._prbsRx
self.add(self._prbsTx)
self.add(self._prbsRx)
The >> operator connects a stream source to a destination — covered further
in Connecting Streams.
Step 5: Drive It
Replace the __main__ block so it writes a register, reads it back, and runs
the stream for one second:
if __name__ == '__main__':
with MyRoot() as root:
root.MyDevice.ScratchPad.set(0x1234ABCD)
print('ScratchPad =', root.MyDevice.ScratchPad.valueDisp())
print('Doubled =', root.MyDevice.Doubled.get())
root.PrbsTx.txEnable.set(True)
time.sleep(1.0)
root.PrbsTx.txEnable.set(False)
print('Frames sent =', root.PrbsTx.txCount.get())
print('Frames received =', root.PrbsRx.rxCount.get())
print('Errors =', root.PrbsRx.rxErrors.get())
Nodes are reached by name as plain attributes, so MyDevice becomes
root.MyDevice. Use .set() to write, .get() to read, and
.valueDisp() to get the value formatted through disp.
Running It
python3 my_app.py
Output, with the frame counts depending on your machine’s speed:
ScratchPad = 0x1234abcd
Doubled = 610883482
Frames sent = 30254
Frames received = 30254
Errors = 0
Three things worth noting. ScratchPad reads back what was written, so the
emulated register space works. Doubled is exactly twice 0x1234ABCD
(305441741 × 2), confirming the computed variable. Sent and received counts
match at zero errors, so the stream path is intact.
Complete Listing
The whole application:
import time
import pyrogue as pr
import pyrogue.utilities.prbs
import rogue.interfaces.memory
class MyDevice(pr.Device):
def __init__(self, **kwargs):
super().__init__(description='Minimal register map', **kwargs)
self.add(pr.RemoteVariable(
name = 'ScratchPad',
description = 'Read/write test register',
offset = 0x04,
bitSize = 32,
base = pr.UInt,
mode = 'RW',
disp = '{:#010x}'))
self.add(pr.LocalVariable(
name = 'Doubled',
mode = 'RO',
value = 0,
localGet = lambda: self.ScratchPad.value() * 2))
class MyRoot(pr.Root):
def __init__(self, **kwargs):
super().__init__(description='Minimal example root',
timeout=2.0, pollEn=True, **kwargs)
sim = rogue.interfaces.memory.Emulate(4, 0x1000)
sim.setName('SimSlave')
self.addInterface(sim)
self.add(MyDevice(name='MyDevice', memBase=sim, offset=0x0))
self._prbsTx = pr.utilities.prbs.PrbsTx(name='PrbsTx')
self._prbsRx = pr.utilities.prbs.PrbsRx(name='PrbsRx')
self._prbsTx >> self._prbsRx
self.add(self._prbsTx)
self.add(self._prbsRx)
if __name__ == '__main__':
with MyRoot() as root:
root.MyDevice.ScratchPad.set(0x1234ABCD)
print('ScratchPad =', root.MyDevice.ScratchPad.valueDisp())
print('Doubled =', root.MyDevice.Doubled.get())
root.PrbsTx.txEnable.set(True)
time.sleep(1.0)
root.PrbsTx.txEnable.set(False)
print('Frames sent =', root.PrbsTx.txCount.get())
print('Frames received =', root.PrbsRx.rxCount.get())
print('Errors =', root.PrbsRx.rxErrors.get())
Adding A GUI
External tools such as the PyDM GUI attach over a ZMQ control server. A
Root does not start one by default, so two changes are needed.
First, add the server inside MyRoot.__init__ (this also needs
import pyrogue.interfaces at the top of the file):
self.zmqServer = pr.interfaces.ZmqServer(root=self, addr='127.0.0.1', port=9103)
self.addInterface(self.zmqServer)
All three arguments are keyword-only and required. Passing port=0 lets the
operating system choose a free port instead, which avoids collisions when
several applications run at once — but then the port is not known in advance, so
read it back from root.zmqServer.address rather than assuming 9103.
Second, the tree must stay alive for a client to connect to it. As written, the
script exits after one second. Replace time.sleep(1.0) with:
pr.waitCntrlC()
Start the application. It now prints the server details on startup:
Start: Started zmqServer on ports 9103-9105
To start a gui: python -m pyrogue gui --server='localhost:9103'
To use a virtual client: client = pyrogue.interfaces.VirtualClient(addr='localhost', port=9103)
Then, in a second terminal, run the command from that banner:
python -m pyrogue gui --server='localhost:9103'
Your device and variables appear in a tree you can edit live. Press Ctrl-C
in the first terminal to shut down.
Note
A ConnectionError mentioning Failed to connect almost always means
one of three things: no ZmqServer was added to the Root, the
application already exited (so nothing is listening), or the port does not
match the one the server actually chose. Use the exact command from the
startup banner, since with port=0 the ports vary between runs.
See Using The PyDM GUI for the GUI itself, and Client Interfaces for scripted access instead of a GUI.
A Larger Worked Example
Rogue ships a much fuller version of this application, adding a realistic AXI-Lite register map, a file writer, run control, EPICS support, and live plotting. Run it directly:
python -m pyrogue.examples --gui
The source is at python/pyrogue/examples/ in the Rogue repository. The pages
below walk through it, and follow naturally from what you just built:
Build Your First PyRogue Root — the same
Rootpattern with production components attached.Create A Custom PyRogue Device — a full
AxiVersiondevice usingRemoteCommandand indexed register arrays.Review The Complete Root Example — that example assembled in one listing.
Where To Go Next
PyRogue Tree — the tree model in depth: devices, variables, commands, and lifecycle.
RemoteVariable — register addressing, bit packing, and access modes beyond the basics.
Stream Interface — the data path: frames, sources, sinks, and the built-in stream modules.
Memory Interface — how register transactions work below the
Devicelayer.Cookbook — task-oriented recipes for common patterns.
Tutorials — longer guided workflows.
Hardware-Based Walkthroughs
Everything above is deliberately hardware-free. When you are ready to drive a real board, these external examples replace the emulator with actual transports:
Tutorial page: Simple-PGPv4-KCU105 Example
Source repository: slaclab/Simple-PGPv4-KCU105-Example
Within this documentation, Hardware covers the driver-backed endpoints (AXI, DMA, raw memory maps) that take the emulator’s place, and Protocols covers network transports such as UDP, RSSI, and SRP.