Getting Started
This page will tell you how to clone this repository, start your Docker container, and open your GUI.
git clone --recurse-submodules https://github.com/OSU-CMS/Ph2_ACF_GUI.git
cd Ph2_ACF_GUI #Working directory
Pull the latest changes while inside the Ph2_ACF_GUI directory:
git submodule update --recursive --remote
git pull --recurse-submodules
First, install docker on your machine, which is an involved process you'll need to look up. A tutorial for AlmaLinux machines is below.
After installing docker to your system make sure that you have enabled the docker service. To check the status of the docker service, you can run:
sudo systemctl status docker
To enable the service run:
sudo systemctl enable --now docker
Also ensure that your user has been added to the docker user group so that docker can be ran without the use of root privileges. You can check this by running:
id $USER
This should show docker listed in your groups. To add a user to a group, run
sudo usermod -aG docker $USER
Start the docker container:
cd Ph2_ACF_GUI
bash run_Docker.sh
At this point the GUI should be open and ready to use.
RHEL insists that users of Alma use a program called podman. They claim that podman is a drop in replacement for docker, however, this does not seem to be the case. As such, there are special instructions that need to be followed in order to run "normal" docker. You can run the following commands to remove podman and install docker. Instructions for this process were obtained here.
- Update system
sudo dnf --refresh update
sudo dnf upgrade
- Install yum-utils so we can add the repository that contains docker
sudo dnf install yum-utils
- Add the docker repository
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
- Install necessary docker packages
sudo dnf install docker-ce docker-ce-cli containerd.io docker-compose-plugin
- Enable and start docker service
sudo systemctl enable --now docker
- Add user to docker user group to enable to the use of docker
sudo usermod -aG docker $USER
- Reboot for user group to take affect
reboot
cd Ph2_ACF_GUI/Gui
Open the file siteConfig.py in your favorite text editor and go to the "Icicle variables" section. Here you can specify which JSON file you are currently using, set the FC7 ips, and set up the cable mapping (simplified only). The chosen JSON file is specified in line 61 of SiteConfig.py:
with open('jsonFiles/instruments_osu_adcboardsldo.json', 'r') as file:
^ In this example, the selected JSON is instruments_osu_adcboardsldo.json, but this should be changed to whatever JSON file you require.
In the JSON file, you can set the model of LV/HV devices, specify USB ports, etc. You should only include instruments that you have connected. For example, if you do not have a relay board or a digital multimeter, you should not list those in the JSON.
Tip
We highly suggest setting up udev rules for your hardware devices (tutorial). This provides two benefits. One is that you will be able to easily refer to each of your devices in the json file. The second, is that linux does not guarantee that your devices are always mounted to the same path upon reboot without the use of udev rules. This means that without udev rules after a computer reboot, the GUI is liable to stop working and will require a manual change of your hardware pathing. For a guide on how to setup udev rules for your hardware, please see the following tutorial given at one of our IT-DAQ collaborations: udev rules. NOTE: The alias needs to begin with ttyUSB in order to work with the GUI correctly.
For every instrument you wish to connect, you must make a separate entry in the 'instrument_dict' section of the JSON. In the example below, there is is one LV power supply, one HV power supply, a relay board, and a multimeter. Each of these has a corresponding entry in 'instrument_dict' detailing its model (listed as "class"), resource, default voltage, and default current. There is another attribute, "sim," which represents whether the device is simulated or not. This should be false for nearly all use cases. Devices that do not have a voltage or current, such as a relay board, multimeter, or adc board, should be set to 0 as a default.
The next section in the JSON is titled 'channels_dict.' This category is responsible for linking your power supply channels to the GUI. For each LV/HV pair, you need one entry in this section. For each entry, you need to specify the LV and the HV contained in it. To do this, you set up the dictionary with two keys, one for your LV and the other for the corresponding HV. You then associate that with an 'instrument' and a 'channel.' The 'instrument' tag corresponds to the physical instrument listed in 'instrument_dict.' For example, the LV in our instrument dict is titled "lv_1," so we name our instrument in 'channels_dict' "lv_1." The channel then corresponds the which specific channel on that instrument you are interested in using.
Now, to set up multile LV power supplies, you can simply create another entry in 'instrument_dict' for your new instrument. Next, you must update the channels_dict section with this new power supply. You will need to create a second entry with the new LV power supply. Each key in channels_dict should be an integer, indexed at 0, as shown below. The trick here is that you still need a LV/HV pair, so you can simply reuse the HV power supply you entered before. Below is an example of this JSON fully written out.
In Gui/jsonFiles, there are example files written that may be modified to suit your purposes.
Returning to Gui/siteConfig.py, you should also scroll down to the "FC7List" and edit the fc7.board.* listed there to match the IP addresses of your FC7 device(s).
If you scroll down a little further, you will see a dictionary titled "CableMapping." This serves as a mapping of the cable ID you see when adding modules in the simplified GUI to a physical port on your FC7(s). Each cable ID is associated with a dictionary detailing the path to a port. The first key, "FC7," specifies which FC7 that you want that cable ID to be connected to. The FC7 you list should be in the FC7List above. Next, you can name the "FMCID," representing which FMC on the FC7 you wish to use. The possible values for this are "L8" if the FMC is on the left or "L12" if the FMC is on the right. Finally, you can specify which port on that FMC you want to connect to. The leftmost port is "0" and the rightmost port is "3."
