Getting started (installation)
This section should help with getting started with the Dogma DAQ system. Enjoy! (hopefully :-) )
tl;dr : The fastest way to get started :-)
To just use the dogma command type the following:
git clone https://git.gsi.de/ee-dig/dogma/soft/dogma.git
cd dogma
pip install --break-system-packages .
Please contact the developers to get an access token, needeed to pull the software.
The command to access the hardware is called dog. Executing:
dog
will give you the available commands.
For autocompletion of the available commands of dog in the shell (zsh in this case),
type (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) autocomplete (<TAB>-<TAB>) will work.
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
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.
Installation
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/-/profile/keys and add your ssh-public key there.
Then you can clone the project in your environment via:
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 username and git-lab password, so e.g. as username “j.doe”)
Install it to your system:
pip install --break-system-packages --user ./dogma
(the ./ in ./dogma is very important, as there is already a “dogma”
project in the global repository for pip)
From now on you can use the tool in any place in your computer.
If you want to install a development version beside the main branch, or you anyhow are used to work in python-venv (recommended!), then you install it like this:
python3 -m venv dogma_dev1
. ./dogma_dev1/bin/activate
cd ./dogma_dev1/
git clone git@git.gsi.de:ee-dig/dogma/soft/dogma.git
cd dogma
git checkout
pip install --editable .
hash -r
dog -h
If you want to install it in your system without the virtual environment,
so directy access to dog as a command, and you don’t have git access, you
can execute anywhere:
git clone https://dogma:glpat-nKKS4uy-YFWHsXUbmu_M@git.gsi.de/ee-dig/dogma/soft/dogma.git
cd dogma
pip install --break-system-packages --editable .
you can then even work on the source code, while still using the “global”
command dog.
Usage
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
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.