Skip to content

Forgot to update landing page for docs #90

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gwm17 merged 1 commit into from
Apr 14, 2025
Merged

Forgot to update landing page for docs #90

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 63 additions & 39 deletions src/main.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,58 +1,82 @@
//! # attpc_envoy
//!
//! attpc_envoy is a Data Acquisition Hub for the Active Target Time Projection Chamber written in Rust. It provides an async framework for querying the various DAQ elements of the AT-TPC with a clean user interface. The primary goal is to provide an error-safe system from which to run and manage the data aqcuistion, without sacrificing performance.
//! attpc_envoy is a Data Acquisition Hub for the Active Target Time Projection Chamber
//! written in Rust. It provides an async framework for querying the various DAQ elements
//! of the AT-TPC with a clean user interface. The primary goal is to provide an error-safe
//! system from which to run and manage the data aqcuistion, without sacrificing
//! performance.
//!
//! ## Download and Installation
//!
//! To download attpc_envoy simply run `git clone https://github.com/gwm17/attpc_envoy.git`. With the project downloaded, the build process is relatively simple as well.
//! attpc_envoy is written using Rust; if you have never used Rust before you will need to download the Rust toolchain, which is provided by the Rust team [here](https://www.rust-lang.org).
//! With the toolchain installed, navigate to the attpc_envoy repository, and from the top level repository directory run the command `cargo run --release` to build and run attpc_envoy.
//! To build attpc_envoy you need a rust compiler which can be installed using instructions
//! from the Rust [website](https://www.rust-lang.org).
//!
//! ### Platform Support
//! To download attpc_envoy use the command:
//!
//! At the time of writting, the AT-TPC DAQ is mostly run through Apple Mac systems (MacMinis and iMacs). As such this has been the primary target during development.
//! However, attpc_envoy has aimed to be cross-platform, to stay ahead of any potential changes to the DAQ system. attpc_envoy has been tested and successfully builds on Windows 11 and Ubuntu 22.04.
//! For MacOS, it has been tested primarily on MacOS Ventura (13).
//! ```bash
//! git clone https://github.com/gwm17/attpc_envoy.git
//! ```
//!
//! ## Configuration
//!
//! attpc_envoy requires several pieces of information to run effectively. Here we'll outline the big ones:
//!
//! - Experiment Name: this is a unqiue identifier for this experiment. This name should match the name used to identify the ECC configuration files given to the CoBo/Mutant ECC servers.
//! - Description: Currently unused. Potentially used in a automatic experiment log feature in the future.
//! - Run Number: The number associated with the current data-taking run. This number *must* be unique for each run.
//! To build the project and run it, enter the repository and use the following command
//!
//! Configurations can be saved using the File->Save menu. Configurations can then be loaded using File->Open. Configurations are serialized to YAML
//! files using the [serde](https://serde.rs) library.
//! ```bash
//! cargo run -r
//! ```
//!
//! ## About
//! attpc_envoy aims to be cross platform and supports Mac, Windows, and Linux. However,
//! since the AT-TPC group primarily uses MacOS for DAQ machines, attpc_envoy is only
//! guaranteed to run on MacOS. Other platforms are supported as best-effort only.
//!
//! ### Async Envoys
//! ## What is attpc_envoy exactly?
//!
//! At the heart of attpc_envoy is the Envoy task object. Upon starting the attpc_envoy application, a new [tokio](https://tokio.rs) async runtime is created and then handed
//! off to the user interface (which is made using the awesome [egui](https://www.egui.rs) library). When the user clicks the Connect button in the UI the async runtime spawns a bunch of
//! Envoy tasks. The Envoys are more-or-less communication channels which query or command the ECC server and Data Router systems of the AT-TPC data acquisition. Communication
//! is managed through the Embassy structure, which provides a bridge between the synchronous UI and the asynchronous Envoys. The reason for async is clear: most of the
//! time the Envoys don't do anything! They're either waiting for a commmand from the UI or they're waiting until a timer goes off to check the status of the server. Creating a OS thread
//! for each of these objects would be incredibly heavy. Instead, the tokio runtime manages these tasks efficiently for us, reducing the cost of having so much of the program sleeping.
//! Under the hood, each Envoy is really just an HTTP request machine (using the [reqwest](https://crates.io/crates/reqwest) library), either posting or getting data as specified by it's task type.
//! attpc_envoy is essentially a control panel that communicates to the distributed DAQ
//! services used to run the AT-TPC. There are a few key assumptions made by the envoy
//! system that you should be aware of:
//!
//! ### User Interface
//! - attpc_envoy assumes that you are using the AT-TPC network infrastructure, including
//! the expected IP address assignments for DAQ machines.
//! - Each DAQ machine is expected to be running three programs: `getECCServer`,
//! `dataRouter` or `DataExporter`, and `attpc_sentry`
//! - There are the typical number of DAQ machines (at time of writting, 11)
//! - GETDAQ configuration files are located in the expected AT-TPC directory structure
//!
//! The user interface provides the functionality to command the ECC servers to configure themeselves using the Progress/Regress buttons. Each ECC Envoy has it's own Progress/Regress buttons
//! as well as a status. Additionally there is a system Progress/Regress set of buttons as well as a system status. The system progress/regress can be used when the *entire* ECC Envoy system
//! is at the same status. That is, when every envoy is at the same point in the configuration process, you can progress the system as a whole rather than individually pressing each button for
//! each envoy. However, if one of the envoys is at a different status, you will not be able to modify the system as a whole (the system status should say Inconsistent in this case).
//! In general, where possible it is best to use the system Progress/Regress and only use individual options when the system options are not available.
//! If you do not meet these requirements, or are unsure, you can checkout the
//! [constants](https://attpc.github.io/attpc_envoy/attpc_envoy/envoy/constants/index.html)
//! docs to view some of them.
//!
//! Once the project is stable, a more comprehensive description of the user interface will be provided.
//!
//! ### Logging
//! ## Configuration
//!
//! If issues begin to occur, the User Interface will attempt to display appropriate status messages that indicate where something went wrong. However, due to the async nature of the tasks,
//! it can be difficult to express this in a clear way. To help with this, the [tracing](https://tokio.rs/tokio/topics/tracing) library is used; tracing allows logging of async type systems
//! in a way that aims to be expressive about where information is coming from. Tracing logs data to the terminal, so if things seem to not be working, check the terminal from which you spawned
//! attpc_envoy and see if anything was reported.
//! It is not recommended to create a configuration by hand. Instead, it is best to use the
//! UI to set configuration parameters and then use the File->Save, and File->Load menus to
//! handle configuration saving and loading. However, we will outline the format here for
//! clarity.
//!
//! attpc_envoy uses YAML to define its configuration. Below is an example configuration
//! file:
//!
//! ```yaml
//! experiment: Exp
//! run_number: 0
//! description: Write here
//! fields:
//! B-Field (T): ''
//! Beam: ''
//! E-Drift (V): ''
//! E-Trans (V): ''
//! Energy (MeV/U): ''
//! GET Freq. (MHz): ''
//! Pressure (Torr): ''
//! Target Gas: ''
//! V_Cathode (kV): ''
//! V_MM (V): ''
//! V_THGEM (V): ''
//! ```
//!
//! `experiment` is the experiment identifier, and should match the identifier used for the
//! GET configuration files. `run_number` is the current run number. `description` is a
//! brief discription of the run. `fields` is an extensible list of run logged info. All
//! `fields` values are stored as strings even if they are more naturally a numeric type to
//! avoid boxing.

mod envoy;
mod ui;
Expand Down
Loading