Getting started (installation)
This section should help with getting started with the Dogma DAQ system. Enjoy! (hopefully :-) )
Prerequisites
As long as we are in development, there is no public release of the software. The fastest way to install it and also be able to contribute in a convenient way is to clone the repository. First, you have to be able to access the GSI-Gitlab without password. This is provided by ssh-public keys. So, please go to: https://git.gsi.de/-/user_settings/ssh_keys and add your ssh-public key there.
Then you can clone the project in your environment via (do not clone it now, this step will be part of the installation procedure below):
git clone git@git.gsi.de:ee-dig/dogma/soft/dogma.git
If you don’t want ssh-key authentication, you can also clone it via username and password:
git clone https://git.gsi.de/ee-dig/dogma/soft/dogma.git
(here you have to type in your GSI git-lab username and password, so e.g. as username “j.doe”)
If you do not have access to the GSI git server, please contact the developers to get an access token, needeed to pull the software.
Installation by script
If you trust us and just want the software installed on an OpenSuSE Tumbleweed system, the fastest way is the following:
wget https://eecloud.goip.de/dogma/misc/install_packages_for_dogma_and_dabcgo4_opensuse_tw.sh
Look into this file and if you are happy that no bad things happen in there (only “zypper installs” are executed), then run the script as root:
sudo bash ./install_packages_for_dogma_and_dabcgo4_opensuse_tw.sh
After that you can install the whole dogma and dabc software also by script:
curl https://eecloud.goip.de/dogma/misc/dogma_jumpstart.sh | zsh
Attention: This script runs the compiler for root 16 times in parallel. This
will only work with machines with at least 32GB of memory.
If your machine is smaller (less cores and less memory), change the following
line in the script before executing:
make -j16
to:
make -j8
That is it!
Dogma and DABC and Go4 are quite fast installations, but the compilation of the root-package takes quite a while (30 minutes even on fast computers):
After the script has finished, you can directly use everything by setting the environment variables. For shells in which you want to use the dog/thres/spi/etc. commands, use:
source ~/dogsoft/.venv/bin/activate
For shells in which you want to use the dabc/go4/etc. commands, use:
source ~/dogsoft/dabcgo4/build/dabcgo4login
The dog command will be usable in new shells, or in the current shell via:
source ~/.zshrc
Manual Installation
The recommended way to install the software is to install it in a python virtual environment (python venv) to avoid conflicts with other packages and possible confusion. You can install the dogma tools in a python venv called dogma like this:
python3 -m venv dogma # create the dogma venv
source ~/dogma/bin/activate # activate the dogma venv
cd ~/dogma/
git clone git@git.gsi.de:ee-dig/dogma/soft/dogma.git # clone the dogma software repository (see above)
cd dogma/
pip install --editable . # install dogma software
dog # test dog command
pip install h2o-wave # install h2o-wave package for dogma web interface
The advantage of this method is that you can easily create multiple virtual environments with different or even modified versions of the dogma software.
Shell auto completion
For auto completion of the available commands of dog in the shell (zsh in this case),
execute the following commands (you can exchange zsh with bash):
_DOG_COMPLETE=zsh_source dog > ~/.dog_complete.zsh
echo "source ~/.dog_complete.zsh" >> ~/.zshrc
After opening a new shell (or source ~/.zshrc) auto complete (<TAB>-<TAB>) will work.
Command line usage
If you followed the installation manual and installed the dogma software in a python virtual environment, you first need to activate that venv to make the dog command available:
source ~/dogma/bin/activate # activate the dogma venv (your path may vary...)
Then you can just enter the command:
dog
This should explain everything. E.g., if you want to learn more about read access, then type:
dog read -h
Each “dog” (Dogma endpoint) has to be assigned an IP address via DHCP (e.g. dnsmasq). To be able to use IP broadcasts to several dogs (Dogma endpoints), you have to know the broadcast address of the network you use where the dogs are registered:
dog discover # can be abbreviated to dog d
will also find that for you, but you are encouraged to write the broadcast address to your .zshrc/bashrc. E.g:
echo 'export DOGMA_BROADCAST_ADDRESS="192.168.50.255"' >> ~/.zshrc
A standard dog access to a register looks like this:
DOGMA_IP=192.168.50.101 dog w 0xff000000 0x0 0x10
which will access all (0xff => broadcast) dogs on IP 192.168.50.101 and write a 0x10 to the control register 0x0, which will cause the FPGA to reload its configuration from the on-board flash memory.
Multi-cast access:
dog --broadcast read --access-length=2 0xfd00d5d2 0x10
or:
dog -b r -l2 0xfd00d5d2 0x10
These commands will access via IP broadcast all dogs in the network and address via dogma-multicast all dogs with the multicast-address 0x00d5d2 and read from each dog which has this mutlicast address two registers, 0x10 and 0x11, which are the registers of the 64-bit unique ids of the boards.
Web interface
To start the dogma web interface, navigate to:
~/dogma/dogma/src/dogma_web/
if you followed the installation manual precisely.
If you chose to use a different name for the python venv or placed the dogma software repository in a different place, navigate to:
<your_dogma_repo_path>/src/dogma_web/
Make sure your virtual environment is activated in the current session:
source ~/dogma/bin/activate # activate the dogma venv (your path may vary...)
Then execute:
H2O_WAVE_NO_LOG=True wave run dogma_web.py
After successful startup of the application, you find the dogma web interface at:
http://localhost:10101/dogma
Support
Just talk to the people who wrote the software.
Roadmap
Missing features have to be added and bugs have to be removed. -:)
License
GPL-3 licensed. Also the “Borg license” applies :-)