DAQ Routines¶
Defines routines for LArPix DAQ components.
Routines allow a DAQ operator to execute a predefined sequence of
operations. Routines are Python functions wrapped in a Routine
object that stores metadata such as documentation and argument lists.
Using routines¶
Existing routines can be loaded by importing this module and calling
init_routines()
. The optional argument can provide a custom location
for routine files. The default is larpixdaq/routines
, i.e. within
this Python package. init_routines
modifies the global ROUTINES
dict, which maps routine names to Routine
objects. The routine’s
function can be accessed at ROUTINES[name].func
, and called with the
appropriate parameters.
Routines all take 3 arguments as part of the routines interface, plus
any other positional arguments that are part of the routine’s
implementation. The 3 required arguments allow the routine to interact
with the DAQ system. See the documentation for the Routine
class for
details.
Routines all return a 2-tuple as part of the routines interface. The
first element is the larpix.larpix.Controller
object containing
up-to-date configurations, IO, and Logger objects. The second element is
the “return value” or result of the routine, which must be
JSON-encodable (numbers, strings, booleans, or None
literals, or dicts or lists
of those literals).
Writing routines¶
When new routines are being written, they can be tested using the
test_routine
convenience method. A test session might look like
>>> from larpixdaq.routines import init_routines, test_routine
>>> init_routines('.') # assuming you have routines in the current directory
>>> from larpix.larpix import Controller
>>> controller = Controller()
>>> # ... then set up the controller
>>> test_routine('my_routine', controller, print, print, (arg1, arg2, arg3))
(<larpix.larpix.Controller at 0x7f3bf6d5c8d0>, <routine return value>)
Sharing and finding routines¶
A global repository of LArPix DAQ routines is being set up at <https://github.com/larpix/larpix-daq-routines>. Contact the LBNL LArPix contacts for help, and/or file an issue or pull request.
-
larpixdaq.routines.
init_routines
(location=None)[source]¶ Collect and register routines.
- Parameters
location – The directory to look for routines files. (optional. If absent or
None
then look inside thelarpixdaq.routines
package directory.)
-
larpixdaq.routines.
test_routine
(name, controller, send_data=None, send_info=None, args=())[source]¶ Run the given routine in a test or custom environment.
This is useful during development, where a routine can be executed without loading up the entire DAQ system.
A reasonable way to mock up
send_data
andsend_info
is simply to pass theprint
function (in Python 3; in Python 2 firstfrom __future__ import print_function
).- Parameters
name – the name of the routine to test
controller – the
larpix.larpix.Controller
objectsend_data – a function to call to send data down the pipeline. Signature:
def send_data(packets_to_send)
. (optional, default orNone
results indef send_data(to_send): return None
)send_info – a function to call to send info messages down the pipeline. Signature:
def send_info(str_to_send)
. (optional, default orNone
results indef send_data(to_send): return None
)args – the arguments to pass to the routine, as an iterable. If there’s only one argument, it’s recommended to use a list (
[arg1]
) since a 1-tuple requires a comma which is easy to forget ((arg1,)
). (optional, default:()
)
- Returns
the return value of the routine
-
class
larpixdaq.routines.
Routine
(name, func, params=None)[source]¶ Represents a routine run using the LArPix Control board.
Routine functions are passed three arguments for the purpose of interacting with the LArPix-control and DAQ systems, so they should have the following signature:
` def func(controller, send_data, send_info, [...]) `
controller
is the current instance of the LArPix-control Controller objectsend_data
is a function which sends data to the DAQ pipeline. The first argument is the data, in bytes. The second is optional and is a dict with metadata. Default metadata of Unix timestamp and component name is automatically added to the supplied dict.send_info
is a function which sends an informational message to the DAQ pipeline. The first and only argument is the message as a string.Any other arguments must be listed in order in self.params.