This document states workflows to develop a OPI to be integrated into a EPIK8S deploy.

Architecture

Each beamline in EPIK8S has a GIT project associated. This GIT project has a opi directory that point to a OPI git project that contains the interface of the given beamline.

├── README.md
├── config
│   ├── applications
│   ├── iocs
│   └── services
├── deploy
│   ├── Chart.yaml
│   ├── templates
│   └── values.yaml
├── opi                          <--- This is the OPI git submodule (this case https://baltig.infn.it/lnf-da-control/sparc-epics-opi.git)
│   ├── Launcher.bob             <--- OPI entry point
│   ├── README.md
│   ├── deploy
│   ├── env.sh
│   ├── phoebus_mrf_interface
│   ├── ptts
│   ├── rp-opi
│   ├── settings.ini				<--- phoebus initialization (see beamline info i.e https://confluence.infn.it/display/SCS/EPIK8s+Sparc) 
│   ├── settings_template.ini
│   └── start.sh                    <--- phoebus start (generally works on EPIK8s, Linux and MAC) 
└── sparc-deploy.yaml

This structure allows:

1. separate development of OPIs and IOCs
2. update control room OPIs accessing just the GIT repository of the OPI.

OPI GIT project

Every OPI MUST have a GIT repository associated. A project for an internal facility  must be created or exist under https://baltig.infn.it/lnf-da-control.

For instance the OPI git project for SPARC is: https://baltig.infn.it/lnf-da-control/sparc-epics-opi.git while for dafne is https://baltig.infn.it/lnf-da-control/dafne-epics-opi.git.

Pay attention to not set the project private otherwise will not be possible to load it into the EPIK8S.

Setup Phoebus

Please refer to this guide: Phoebus. Particular sensitive is the settings.ini. This file must exists and initialised as EPIK8s information page suggests (i.e EPIK8s Sparc ).

For Linux and MAC system the start.sh can be used to launch phoebus and initialise correctly with the settings.ini. 

.

Setup environment

Depending on the target beamline (i.e. sparc environ EPIK8s Sparc). 

1. Setup EPICS_CA_ADDR_LIST
2. Identify your target EPIK8s information page (i.e EPIK8s Sparc ) retrieving "GIT Control Source" URL, clone it.
3. This project includes a opi directories that is a git submodule that points to a GIT project intended to include all the CSS/phoebus interfaces that compose the Control System interfaces of the EPIK8S beamline. The entry point to the beamline control interface is Launcher.bob. The settings.ini is built by start.sh depending on the environment variables:
   1. EPICS_CA_ADDR_LIST that must include the addresses of the IOC you want to access or the address of the ca-gateway listed on the target ECS information page
   2. OPIHOME the directory where the OPIs are.

   3. EPICS_ARCHIVER the Entry point of the archiver.

   4. PHOEBUS_SAVE_AND_RESTORE service of save and restore

   5. PHOEBUS_SCAN_SERVER service

4. Test your environment trying to open Launcher.bob and open some control interface.

Develop your OPI and deploy

The development flow depends on you. You may have your OPI in a git project (very suggested way) or you may have developed something really custom for the beamline so that you may include it directly in  the OPI beamline project.

If you developed your OPI and resides in a GIT repository you should include your repository into the Beamline OPI as submodule:

cd opi
git pull --recurse-submodules ## to update remote changes
git submodule update --init ## to update eventually new submodules
## here add your new submodule
git submodule add <your repository_URL> [<submodule_path>]
git commit -m "your comment Add submodule <submodule_name>"
git push origin <your remote branch i.e main/master>

In case you want add your OPI to the Beamline OPI, so your files we'll be part of the Beamline OPI just use:

cd opi
git pull --recurse-submodules ## to update remote changes
git submodule update --init ## to update eventually new submodules
## here add your folder/files
git add <your files/folder>
git commit -m "your comment " .
git push origin <your remote branch i.e main/master>

Update an existing OPI submodule:

cd /<your git directory>/epik8-<beamline name>
git pull --recurse-submodules ## to update remote changes
git submodule update --init ## to update eventually new submodules
cd opi/<OPI TYPE>/<submodule name> ## fro example RF/sparc-rf-opi
git pull ## to update the submodule
cd ..
git add <submodule name>
git commit -m "<your message>"
git push origin ## add HEAD:main to this command line if you are in a detached HEAD
cd ../.. ## to go in the master repository
git add opi/
git commit -m "<your message>"
git push origin

If, in any moment in the update procedure, git says that you are not in a branch you can type:

git branch ## to verify the available branches (typically "main" for the submodule and "master" for the main repository)
git switch <name of the branch>

to enter in the correct branch.