# Project Description
This documentation describes the general way the run control program works, and what the main thread and the modules do at each state.

## Project Structure
This documentation provides a short explanation of the different folders and files in this repository. Below is the 
structure of this repository:
```
.
├── README.md
├── config.json
├── dependencies
│   ├── ArduinoSketches
│   │   ├── README.md
│   │   ├── clock/
│   │   ├── ln2autofill_rtd/
│   │   ├── ln2autofill_scale/
│   │   ├── position/
│   │   ├── trigger/
│   │   └── uti-docs/
│   ├── NI_USB6501/
│   └── conda_rc.yml
├── docs
│   ├── api.rst
│   ├── conf.py
│   ├── data_format.md
│   ├── dependencies.md
│   ├── images/
│   ├── index.md
│   ├── program_behavior.md
│   ├── project_structure.md
│   ├── requirements.txt
│   └── usage.rst
├── init.sh
├── rc.py
├── resources/
├── src
│   ├── acoustics.py
│   ├── arduinos.py
│   ├── caen.py
│   ├── cameras.py
│   ├── config.py
│   ├── niusb.py
│   ├── sipm_amp.py
│   ├── sql.py
│   ├── ui_loader.py
│   └── writer.py
└── ui
    ├── custom_widgets.py
    ├── logwindow.ui
    ├── mainwindow.ui
    ├── quitdialog.ui
    └── settingswindow.ui
```

## Run States
The run control program uses multithreading to avoid freezing the GUI when things are happening in the background. Specifically, it has one main thread and a thread for each module. For the secondary threads, there is one worker per thread. The threads communicate with each other via `Signal` and `Slot`.  
At the Start of a run, the main thread will send out a `run_starting` signal. This signal is connected to the `start_run` method of each module worker. (TODO: then the main thread waits for all modules to return a signal that they are ready to go active.) A similar process happens at every state transition.
There are seven states, which are `preparing`, `idle`. `starting_run`, `stopping_run`, `starting_event`, `stopping_event`, `active`. 

### Preparing
When the run control program starts, it will first enter the `preparing` state. In this state it will instantiate all the secondary threads and workers, and load the GUI with initial information.
- Arduinos: Flash sketch to board?
- SiPM amp: run IV curve if no data for today?

### Idle
After the `preparing` state ends, it will enter the `idle` state. The "Start Run" button will be available to start a new run, and any changes to the configuration can be applied immediately.

### Starting Run
After the "Start Run" button is pressed, the program will enter this state. When all modules are ready, it will enter into `starting_event` state.
- GUI: set run ID, event ID, event livetime, run livetime
- Writer: create run folder. Save current config file. Create log file and add to logger. Initialize run_data variable.
- SiPM amp: bias SiPMs
- Config: save current config to run folder.

### Stopping Run
This is the state then the run is stopping.
- SiPM amp: unbias SiPM
- Write run data into SQL RunData table.

### Starting Event
When the `starting_run` state ends, or then `stopping_event` state ends, and neither "Stop Run" button is pressed, or maximum number of events is reached, the program will start a new event. It will send out a `Signal` to all modules. When all modules are ready, it will enter `active` state.
- GUI: set event ID and event livetime display.
- Writer: Create folder for the event.
- Camera: Send config file. Start `imdaq` script.
- NIUSB: set input/output pins. Sends out `trig_reset` signal. Set outputs to camera.
- CAEN: save config file. Start data acquisition.
- Acoustics: save config file. Start data acquisition.

### Stopping Event
This is the state when the event is stopping. A `Signal` is sent to all modules to save data for the event. After the state is finished, it will enter into either `starting_event` to start a new event, or `stopping_run` to end the run. That decision will depend on if the "Stop Run" button is pressed, or maximum number of events is reached.
- Writer: save event binary data.
- Cameras: Take remaining images. Save images, info table and log into event folder.
- CAEN: stop data acquisition, save data to event folder.
- Acoustics: save data to event folder.

### Active
All modules in this state will be actively taking data in buffer, and waiting for a trigger. When a trigger is received by run control, it will enter into `stopping_event` state.
GUI: Start event timer. Update event livetime and run livetime. Check for max event time to send out trigger.

## Modules
The run control program is organized in modules. The main module is responsible for the graphical interface. All other modules are launched in their own threads. Each module is defined by a python script in the `src/` folder, and one or more instances of a module may be created. For example, there are three camera threads, each controlling a camera RPi. A thread is created at the start of the program for each module, and the module class is instantiated into a worker inside that thread. The communication between modules and the main thread is handled by PySide6 signals and threads, and there is also limited number of communication between modules directly. The threads live across events and runs, and are only killed when run control is closed.

### UI Loader
This modules contains the classes for settings window and log window, as well as helper classes. The settings window is the central place where the user can set configuration for both run control and all modules. Every field in `config.json` can be edited from here. The log window display all logs generated by run control. Note that logs produced by child processes run from run control will not be included here, even they may appear in the terminal. These include camera RPi logs and SiPM amp outputs.

### Config
The main job of the config module is to translate between the fields in the settings window, the config dictionary in python, and the `config.json` file. When run control starts, it reads configuration from `config.json` and stores it in a dictionary. When settings window is opened, it fills all of the fields in the GUI from the dictionary. When "Apply" button is clicked in settings window, the dictioanry is updated using the fields in the GUI. When "Save" button is clicked, the dictionary is updated using the GUI, and then the `config.json` is also overwritten using the new dictionary.  
When a run starts, it saves a copy of the config dictionary for the run, so any subsequent changes in the settings window when the run is active won't affect the current run. It then saves the run config into a `config.json` in the run data folder, and then updates the config files for cameras and arduinos.

### NI USB
Using the third party custom driver, this modules handles all digitital input/output requests from run control to the NI USB6501 device. It defines a name and direction for each of the pins, and handles reading from and writing to the pins. Specifically, it handles communication to and from the trigger arduino and the camera RPis. 

### Arduinos
At the start of each run, the Arduinos module checks that the build on the Arduino is up to date. It generates a zip file containing the `.ino` C++ file as well as wll supporting files, including the `.json` configuration file. Then it compares the zip file to the existing zip file in the build folder. If that zip file doesn't exist, or if they are different, the module will compile the code and upload to the corresponding Arduino, while overwriting the zip file with the newer version. If the two zip files are the same, then nothing will happen to prevent unnecessary writes to the EEPROM.

### Writer

### SQL

### Cameras

### CAEN

### SiPM Amp

### Acoustics