# Guide: Configuring uopi for ITER CS-Studio

This guide explains how to configure **uopi** to work within the **ITER CODAC (Control System Studio / Phoebus)** environment. Since uopi is a single portable binary, it can be deployed alongside or as a lightweight web-based alternative to standard CS-Studio screens.

---

## 1. Prerequisite Information

To connect uopi to the ITER control system, you need three pieces of information usually found in your standard CODAC environment or terminal:

| Info Needed | Purpose | Where to find it in ITER |
| :--- | :--- | :--- |
| **CA Addr List** | PV Discovery via UDP | Run `echo $EPICS_CA_ADDR_LIST` in a terminal. |
| **Archiver URL** | Historical Trends | Check your CS-Studio preferences under *Archive Appliance* (usually `http://arch-mgmt:17665/`). |
| **CFS URL** | Automatic PV Search | Check CS-Studio preferences under *Channel Finder* (usually `http://cf-service:8080/ChannelFinder`). |

---

## 2. Configuration (`uopi.toml`)

Create a file named `uopi.toml` in the directory where you will run uopi. Use the values found above:

```toml
[server]
listen      = ":8080"           # The port uopi will serve the web HMI on
storage_dir = "./interfaces"    # Where your XML screens will be saved

[datasource.epics]
enabled            = true
# Paste the output of 'echo $EPICS_CA_ADDR_LIST' here
ca_addr_list       = "10.0.x.x 10.0.x.255" 
# ITER Archive Appliance URL
archive_url        = "http://arch-mgmt:17665/"
# ITER Channel Finder URL
channel_finder_url = "http://cf-service:8080/ChannelFinder"

# Automatic discovery on startup
auto_sync_from_archiver = true
auto_sync_filter        = "tags=production" 
```

---

## 3. Deployment in the ITER Environment

### A. Running via Terminal
If you are on a CODAC workstation or a server with network access to the Plant System:
1. Copy the `uopi` binary to the machine.
2. Run it pointing to your config:
   ```bash
   ./uopi -config uopi.toml
   ```
3. Open a browser and navigate to `http://<machine-ip>:8080`.

### B. Offline Usage (No Internet)
uopi is built with **zero external dependencies**. All scripts and the favicon are embedded. No `npm` or `curl` calls are made at runtime. It will function perfectly on isolated ITER networks.

---

## 4. Discovering ITER PVs

Once uopi is running:

1.  **Automatic Discovery:** If `auto_sync_from_archiver` is set to `true`, the sidebar will be pre-populated with thousands of ITER PVs on boot.
2.  **Smart Grouping:** Click the **"Group By"** dropdown in the sidebar. Select **"Area"** or **"System"**. uopi will use the metadata from the ITER Channel Finder to organize PVs into folders (e.g., `Vacuum`, `Cryogenics`, `PowerSupply`).
3.  **Advanced Search:** 
    *   Click the **🔍 (Advanced Search)** icon in the sidebar.
    *   Use the **Channel Finder** tab to find signals by tags (e.g., `interlock`) or properties (e.g., `iocName`).
    *   Use the **Archive Appliance** tab to perform a glob search (e.g., `*TEMP*`) directly against the ITER Archiver database.

---

## 5. Transitioning from CS-Studio (`.bob` / `.opi`)

uopi uses a custom XML format for its screens, but the layout logic is similar to Phoebus/CS-Studio.

*   **Signals:** Just like in CS-Studio, you can drag PVs from the sidebar directly onto the canvas to create widgets.
*   **Historical Data:** Any PV discovered via the Archiver tab or configured with the Archiver URL will automatically show historical data when added to a **Plot Widget**.
*   **Synthetic Signals:** You can create complex ITER-specific calculations (e.g., `R = V/I`) by clicking the **Σ** icon and combining multiple EPICS PVs into a single virtual signal.

---

## 6. Troubleshooting

*   **Timeout Error:** If `caget` times out in uopi, verify that `ca_addr_list` includes the correct broadcast address for your ITER subnet (e.g., ends in `.255`).
*   **Metadata Missing:** If PVs show up but have no units/descriptions, ensure the `channel_finder_url` is reachable from the uopi binary.