How to run dune-artdaq in a Virtual Machine on your own computer


dune-artdaq is a complex piece of software, in that many different groups on protoDUNE have contributed to its codebase, as well as supplied external packages which dune-artdaq depends on in order for their code to run. As such, installing it on a new host outside the protoDUNE cluster is not a simple manner, since among other things it involves copying over numerous packages from the cluster. A workaround is to provide dune-artdaq developers with a VM (Virtual Machine), in our context a single file which mimics a full Scientific Linux environment with dune-artdaq and all the packages it depends on already installed. At Fermilab, we've created such a file, designed to be run in the VirtualBox program (website here).

Installation of the Virtual Machine

In this developer's experience, VirtualBox was very easy to install on a MacBook (if you click on the VirtualBox link just above, you'll see there's a big green button near the top of the VirtualBox page labeled "Download VirtualBox 6.0" which I clicked on; the page I was brought to had an "OS X" link where VirtualBox began immediately downloading onto my MacBook when I clicked on it). Please note that VirtualBox is supported on Linux and Windows as well, though I can't speak to the ease of installation on those platforms.

Once you have VirtualBox installed, you'll want to get your hands on the file which VirtualBox needs to load in in order to recreate the Linux environment. The way to do this is to copy it from my public area on CERN's lxplus nodes; on Linux, after you cd into a directory you think would be appropriate, this would look like:

scp -p .
On a MacBook, once you've copied the file over, you can just double click on this file in your directory folder, and in the VirtualBox window that opens up entitled "Appliance settings" click on the "Import" button at the bottom. Wait a minute or two for the import to complete, and then in the window called "Oracle VM VirtualBox Manager", on the left side, double click on the bottom tab (if there's more than one) which starts with "SL7 Base". The VM may launch after a moment or two; if it doesn't, then click on the big green arrow with "Start" below it, and wait for the VM to launch. One the VM launches you will find yourself at the login after ~20-30 seconds; just click on "artdaq user" without entering any password, wait a moment, and then you should find yourself in a window with a highlighted region which says "artdaq User" (possibly obscured by a subwindow or two, which you can close by clicking on the X).

Getting started

Click on the "artdaq User" and you'll find yourself at a prompt. If the font's very small (as it was in my case), hitting Ctrl-+ repeatedly made it larger. Try to not to resize the window - in my experience, when this is attempted the screen goes black and I lose any work that I didn't snapshot (see below for the definition of "snapshot" in this context). If you have to resize it, do so slowly and in increments.

You can immediately start running a ToySimulator (a front end software component unconnected to hardware which generates "ADC" counts drawn from a monte carlo distribution) by executing the following commands:

cd ~/DAQInterface
source source_me
DAQInterface & ./boot.txt 20 --config "ToyComponent_EBwriting00026" --comps "toysimulator01" 
For the full set of instructions on DAQInterface you can read its manual (, but to break down what's happening here: you cd into the DAQInterface working directory, source its environment, launch it, and then tell it to run for 20 seconds. While it runs for those 20 seconds it will configure the artdaq processes it launched using the FHiCL documents found in the directory structure whose base is the $HOME/configs/ToyComponent_EBwriting00026 directory. In particular, with the "comps" argument list we tell DAQInterface that we want just one front-end artdaq process (this type of artdaq process is known as a "boardreader"), and that we want to configure it with a file called toysimulator01_hw_cfg.fcl which can be found in the $HOME/configs/ToyComponent_EBwriting00026/ directory structure. Note that the "_hw_cfg" part of the filename is there for historical reasons; DAQInterface would also be able to figure out that a file called toysimulator01.fcl is the one needed for the boardreader if such a file existed.

A record of the run you've taken can be found in the most recent subdirectory of /run_records .

Where to develop

In the "Getting started" section above, the actual dune-artdaq installation you're using gets set up using the file specified at the top of the boot file; if you take a look at the boot file's contents ("cat boot.txt"), you'll see at the top:

DAQ setup script: $HOME/dune-artdaq-base/setupDUNEARTDAQ
i.e., a specification to DAQInterface that it should source this script before launching artdaq processes.

The actual dune-artdaq git repository which you can develop in is in a subdirectory of $HOME/dune-artdaq-base/: $HOME/dune-artdaq-base/srcs/dune_artdaq. In particular, "fragment generators" - i.e., the user-supplied front end code which is embedded in the boardreader - are developed in $HOME/dune-artdaq-base/srcs/dune_artdaq/dune-artdaq/Generators. For details on how to build the code you edit, you can refer to the Building section of this TWiki. Just be aware that there are a couple of differences from the standard instructions: since you're developing in a virtual machine and not the CERN protoDUNE cluster, instead of executing "mrb install -j8" as described in those instructions, you'll want to execute "mrb install -j1; you can also disregard the instructions on logging in to np04-srv-023 and cd'ing into a subdirectory of "/scratch" at the top of the page since you're already on the node (the VM) you want to develop in. The "setupDUNEARTDAQ_forBuilding" script can be found in $HOME/dune-artdaq-base.

If you're completely new to fragment generator development, aside from the obvious advice that your protoDUNE coworkers will be very useful to consult, you can also take a look at Fermilab's artdaq-demo instructions here; this basically describes a "toy" artdaq-based DAQ system, analogous to dune-artdaq, as well as how one can add code to it.

Testing your fragment generator

If you've added a fragment generator to $HOME/dune-artdaq-base/srcs/dune_artdaq/dune-artdaq/Generators and rebuilt dune-artdaq, the next step is to run it. This will involve a couple of steps:

Create a configuration which supports your fragment generator

The ToyComponent_EBwriting00026 configuration only supports fragment generators which have been used on the protoDUNE cluster as of the date of this writing (Jul-18-2019), including the fake data generator you ran in the "Getting started" section. If you've created a new fragment generator, you'll need to add it. What you'll want to do is copy that directory to something more appropriately named than "ToyComponent_EBwriting00026", e.g.:

cd $HOME/configs
cp -r ToyComponent_EBwriting00026 new_configuration_name_you_decided_on
and then in the new directory, create a FHiCL file whose stub name is the name you want to give your fragment generator, e.g. your_fragment_generator_name.fcl. It's recommended that you copy a pre-existing FHiCL file (e.g., toysimulator01_hw_cfg.fcl) to your_fragment_generator_name.fcl rather than editing it from scratch; then you can just make modifications to get it to work with your fragment generator and not a ToySimulator.

Tell DAQInterface there's a new fragment generator available

You'll also want to add an entry for fragment generator to the file referred to by $DAQINTERFACE_KNOWN_BOARDREADERS_LIST once you've set up the DAQInterface environment, i.e., add something like:

your_fragment_generator_name localhost -1 1
where you'd want to kill and restart DAQInterface to pick up the change (how to do this is described in its manual,

Use the appropriate arguments when running

Namely, something like this: ./boot.txt 20 --config "new_configuration_name_you_decided_on" --comps "your_fragment_generator_name" 

For information on how to examine the results of your run, refer to the DAQInterface manual.

Saving your work

VirtualBox supports a concept called a "snapshot", which is a snapshot in time of the complete state of the virtual machine you're working on. It's a good idea to take a snapshot to save your work, or before testing something potentially destructive. At least on my Mac, there's an option in the "Machine" tab at the top of the screen called "Take Snapshot"; if you're using a different host OS (e.g., Linux) the instructions may be different, but section 1.11 of the VirtualBox user manual found on their site covers this topic.

How to get data from your host machine into the VM

If you've opened up your VM, a simple example of getting data into your VM terminal from the VM's host machine (i.e., your computer) can be done in the following manner - assuming your host machine runs some sort of Linux, and has the netcat utility:

  • In the VirtualBox window titled "Oracle VM VirtualBox Manager" (as opposed to the window the VM is running in), select "Settings" at the top (yellow gear icon), "Network" at the top of the window that pops up (two-blue-screens icon), click on "Advanced" at the bottom of the window, click on "Port Forwarding" at the bottom of the window, eliminate the four rules I added for testing purposes by clicking on the tiny orange "X" four times, and then click on the tiny green "+" to add a rule.

  • The rule should have the following values: "Name" -> "Rule 1", "Protocol" -> "TCP", "Host IP" -> "", "Host Port" -> "15060", "Guest IP" -> "", "Guest Port" -> "15060". Note that this assumes that on your host computer, port 15060 isn't already being used for something. Click "OK" at the bottom.

  • From the VM's terminal, type "firewall-cmd --add-port 15060/tcp" and then "nc -l -p 15060", where the second command translates to "Listen for arbitrary TCP data on port 15060"

  • From a terminal on your host computer, type "echo test | nc localhost 15060". You should see "test" appear on the terminal in your VM.

-- JohnChristianFreeman - 2020-04-01

Edit | Attach | Watch | Print version | History: r15 < r14 < r13 < r12 < r11 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r15 - 2020-04-01 - JohnChristianFreeman
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    CENF All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2022 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback