uopi/docs/ITER_GUIDE.md

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:

[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:

   ./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.