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 the larpixdaq.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 and send_info is simply to pass the print function (in Python 3; in Python 2 first from __future__ import print_function).

Parameters

  • name – the name of the routine to test

  • controller – the larpix.larpix.Controller object

  • send_data – a function to call to send data down the pipeline. Signature: def send_data(packets_to_send). (optional, default or None results in def 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 or None results in def 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 object

  • send_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.