############################################################
#
#	IOCManager application README
#
#	Auth: Sonya Hoobler
#
# Mod:
#       14-Jul-2020, K. Luchini (luchini):
#         describe LCLS iocs
#       16-Apr-2018, K. Luchini (luchini):
#         modify instructions for archiving data
#	Last updated: 2 June 2017 Sonya Hoobler
#         Updated for SPEAR: 12 Sep 2012 by saa
#
############################################################

Contents
========

1. Overview of IOCManager

2. Request a device to be added to IOCManager

3. Add a production device to the IOCManager application

4. Add a development device to the IOCManager application

** Note, after adding the device to IOCManager, please also add it to Network Alarms.

-------------------------------------------------------------

1. Overview of IOCManager

The IOCManager application allows remote monitoring/control
of networked devices. The devices it currently interfaces
with are:

IOCs
----
soft iocs (sioc)
VME iocs (ioc)
coldfire embedded iocs (eioc)

VME Crates (crat)
----------
21-slot Wiener
7-slot Wiener
4-slot Elma
8-slot Elma
4-slot Hybricon
8-slot Hybricon

AC switches (acsw)
------------------
4-port WTI (deprecated but some still in use)
8-port WTI (deprecated but some still in use)
8-port APC
16-port APC
24-port APC

MicroTCA crates
---------------
Using NAT MCH
Using Vadatech MCH (though may need testing)

ATCA crates
-----------

Rack-mounted External PCs
-------------------------
Supermicro PC
Advantech PC

========================
IOC Definitions
========================
The IOCManager application supports devices for LCLS, FACET, XTA, ASTA and SPEAR
and the development environment.

LCLS has many soft iocs:
--------------------------
sioc-sys0-nw01  - interfaces to devices for IN20 thru DMPH, including FEEH, NEH1, XRT and FEH1,and global (sys0)
                  with the exception of soft-line and ipmi communications (IPC and ATCA)
sioc-sys0-nw02  - interfaces to devices for LTUH thru hard photon lines,
                  with the exception of soft-line and ipmi communications (IPC and ATCA)
sioc-sys0-nw03  - interfaces to devices for soft-line LTUS thru DMPS, including FEES, with the exception of ipmi communications (IPC and ATCA)
sioc-sys0-nw04  - interfaces to devices for GUNB thru BYP + DASEL, with the exception of ipmi communications (IPC and ATCA)

sioc-sys0-nw10   - IPMI and ATCA interfaces to devices for IN20 thru LI30
sioc-sys0-nw11   - IPMI and ATCA interfaces to devices for BSY and global (sys0)
sioc-sys0-nw12   - IPMI and ATCA interfaces to devices for LTUH
sioc-sys0-nw13   - IPMI and ATCA interfaces to devices for UNDH,DMPH, NEH1 and FEEH
sioc-sys0-nw14   - IPMI and ATCA interfaces to devices for LTUS
sioc-sys0-nw15   - IPMI and ATCA interfaces to devices for UNDS, DMPS and FEES
sioc-sys0-nw16   - IPMI and ATCA interfaces to devices for GUNB thru BC1B + SC-Global
sioc-sys0-nw17   - IPMI and ATCA interfaces to devices for L2B thru BC2B
sioc-sys0-nw18   - IPMI and ATCA interfaces to devices for L3B thru Dogleg
sioc-sys0-nw19   - IPMI and ATCA interfaces to devices for Superconducting Bypass
sioc-sys0-nw20   - IPMI and ATCA interfaces to devices for Superconducting Spreader + BSY Dump + DASEL

FACET has 3 soft iocs:
----------------------
sioc-sys1-nw01   - interfaces to devices for S10 thru S19
sioc-sys1-nw02   - IPMI and ATCA interfaces to devices for S10 thru S20
sioc-sys1-nw03   - interfaces to devices for S20

XTA has 1 soft ioc:
-------------------
sioc-sys6-nw01

ASTA has 1 soft ioc:
-------------------
sioc-sys7-nw01

Klytron Test Lab (KTL) soct ioc:
---------------------------------
sioc-sys8-nw01

SLAC Site ioc: (inclues site radiation monitors, he-cryo storage)
----------------
sioc-sys9-nw01

SPEAR has 2 soft iocs:
----------------------
soft-iocmgr - production
iocmgrdev - development

The development environment has 2 soft iocs:
------------------------------------------------
sioc-sys0-nwdev  - for IPMI development
sioc-b34-nw01    - for IPMI development
sioc-xfel-nw01   - for Pohang Accelerator IOC Management
sioc-sys2-nwlerf - for LERF test-stand at JLAB

-------------------------------------------------------------

2. Request a device to be added to IOCManager


To have your device added to the IOCManager application,
the software developer will need gather the following information:

(1) Device type (crat/ioc/acsw)
(2) Device node name (ex: ioc-in20-mg01, acsw-li21-nw02)
(3) Model (manufacturer, number of slots or plugs)
(4) Location (building, rack, elevation)
(5) For an ioc/eioc/sioc, name of primary contact
                          node name of crate it is going into
                          crate slot number it is going into
                          for an eioc, the cpu node name and model
(6) For a crate, slot number(s) and node name(s) of ioc(s) in crate
(7) Optional: slot number(s) and module types in the rest of the crate

-------------------------------------------------------------

3. Add a PRODUCTION device to the IOCManager application

Instructions to add production device to IOCManager:

Overview of Steps:

(1) Add device to area-specific database substitutions file
(2) If it is a crate, acsw, or external pc/server, add device to the ioc's init_asyn.cmd
(4) Update RELEASE_NOTES, tag and release IOCManager application
(5) Add device to appropriate home display
(6) Add device to Network Alarm system to make the alarms visible to <acc>home and the relevant network main display.
(7) Add device to the srcArchive/<facility>/<ioc>.sub-arch file.  This will generate an archive file at
     $TOP/archive/<ioc>.archive.
     On IOCManager boot, this file will be copied to production server directory $IOC_DATA/<ioc>/archive/
     where this file will be processed by a cron job periodically, and the pvs added the archive engine.
(8) Check out into production, boot into IOCManager soft ioc
(9) If it is an acsw, program device name in per plug

Detailed Steps:

Note: Most of these examples are for LCLS and use LCLS directory, file, and node names.

(1) Add device to database substitutions file in IOCManagerApp/Db/lcls.

	In IOCManagerApp/Db/lcls, there is one ioc and one crate substitutions file per area,
	with file names like:

	ioc_in20.substitutions
	crat_li25.substitutions
	ioc_mcc0.substitutions, etc.

	For a ioc/eioc/sioc, add a line to the ioc substitutions file for that area,
	imitating the other entries in the file. Example entry of eioc:

   	pattern { ioc             , slcname          , location   , eng                              }
	   	{ EIOC:IN20:BP221 , ""               , LKG-2222  , "Sonya Hoobler (sonya)"           }

	For a crat/acsw, add a line to the crat substitutions file for that area,
	imitating the other area entries in the file. If this is the first device of this
	type in the file (for example first 8-slot Elma in that sector), copy
	an example from another crat substitutions file that has that device type.
	Example entry of 4-slot ELMA crate:

   	pattern { dev            , link           , location   , slot1         , slot2          , slot3 , slot4 }
           	{ CRAT:LTU0:BP01 , crat-ltu0-bp01 , B105-0138  , IOC:LTU0:BP01 , ""             , ""    , ""    }

	Supermicro and Advantech PCs use the same database template. Example for either:

	file server_pc_lcls.db
	{
  	pattern { dev          	, link          	, location      }
           	{ CPU:LI28:SP02 , cpu-li28-sp02 	, KF28-2C40     }
	}


	Commit changes to git.

(2) If it is a crate or acsw, add device to sioc-<area>-nw*/init_asyn.cmd for the associated area

	For a crat or acsw, add a line defining the serial port. Wiener crates use port 80.
	All other devices that we support use port 23.

	Example entry for Wiener crate:

	drvAsynIPPortConfigure ("crat-li24-mg01","crat-li24-mg01:80",0,0,0)

	Example entry for other device:

	drvAsynIPPortConfigure ("acsw-in20-nw08","acsw-in20-nw08:23",0,0,0)

	For a MicroTCA/ATCA/PC system (IPMI-interfaced device), an additional command is needed.
	This command must come after drvAsynIPPortConfigure for the corresponding device. Example:

	mchInit("cpu-li28-sp02","cpu-li28-sp02-mgt:623 udp",0,0,0)
	(The first argument should match the 'link' macro from the database file in
	 step 1. The second argument is the management interface node name of the new
	 device. IPMI devices use port 623 and the 'udp' qualifier'.)

	Commit changes to git.

(3) Update RELEASE_NOTES with your changes. Commit it to git, tag, build, and cram push new version.

(5) The easiest way to add the device to the display is to copy the widgets for a similar
	device and edit them for your new device. Most often it is a ioc/crate pair or ioc/acsw pair.

(6) Update the Network Alarm system to add the new device.  This will make the new device's alarms
    visible in the <acc>home display and the relevant Network main display.  See Alarm System documentation for details.

	See existing alarm trees for where to put the new IOC.

(7) Send the archive maintainer an email, asking him to add the new PVs to the appropriate archiver
        (LCLS for LCLS PVs, FACET for FACET PVs, etc.)

	To get a list of PVs and their archiver configuration, in the working directory, edit
	IOCManagerApp/srcArchive/ARCHIVE_REQUEST.cwsubstitutions, adding one line for each type of
	device. (Remove the old devices to avoid sending duplicates to Patrick.)

	In the srcArchive directory, make clean, then make. Copy contents of restore/ARCHIVE_REQUEST.cwConfig
   	into an email or CATER task and send this to Patrick Pacual.

(8) Check out into production, boot into soft iocs

	From your tagged directory in development, build your application.
	Next use cram to deploy the new version and upgrade the appropriate soft ioc to the new version.

	In production, restart your soft ioc.

	For any new iocs you've added to IOCManager, caput <IOC>:INFO " ", so that it has a valid value.
	Or populate INFO with something  useful!

(9) If it is an acsw, program device name in per plug

	Go to the acsw display. Usually via: lclshome > Network > area > ioc name... > acsw name...

	Go to Expert...

	For the plug of interest, use Set Name field to enter node name of device in that plug.

(10) Additional instructions for SPEAR:

     * No ChannelWatcher.
     * No Archiver (use Clemens history system instead).
     * Do all builds on connie or beldar (currently RHEL6-64).
     * All crate temps are in C instead of F.
     * Common IOC startup files are $IOC/soft-iocmgr and $IOC/iocmgrdev.
       They should never need to be changed.
     * iocmgrdev runs out of AFS and soft-iocmgr runs out of NFS.
     * EDM display are in $EDM/spear (AFS) and /prod/epics/app/edm/display/spear (NFS).
       spearhome -> Network/Computers -> Global, Glob Inj or Glob Spr
     * RELEASE_SITE_SPEAR and configure/RELEASE_SPEAR are release files for SPEAR and
       must be copied to the appropriate name before a build.
     * For a production release:

        ssh -l spear <connie or beldar>
	cd /prod/epics/app/IOCManager
	cvs -d /afs/slac/g/lcls/cvs checkout -P -d <new_tag> -r <new_tag> epics/ioc/IOCManager
	cd <new_tag>/configure
	cp RELEASE_SPEAR RELEASE
	cd ..
	cp RELEASE_SITE_SPEAR RELEASE_SITE
	make
	cd /prod/epics/app/IOCManager
	rm prod
	ln -s <new_tag> prod

	To restart the IOC, type "iocmgr" (production) or "iocmgrdev" (development) to get to
        the console prompt and type "exit".
	To stop and restart the IOC from scratch, log into the machine running the IOC (currently beldar):

	ssh -l spear beldar
	Production:
	/etc/init.d/st.soft-iocmgr stop
	/etc/init.d/st.soft-iocmgr start
	Development:
	/etc/init.d/st.iocmgrdev stop
	/etc/init.d/st.iocmgrdev start

-------------------------------------------------------------

4. Add a DEVELOPMENT device to the IOCManager application

There is a development version of the IOCManager soft ioc running on lcls-dev1. It is used
to support development systems, test-stands, etc. The soft ioc name is sioc-sys0-nwdev and it
boots from /afs/slac/g/lcls/epics/iocTop/IOCManager/Dev

It only loads crat_dev.db and ioc_dev.db, so add any new devices to crat_dev.substitutions and ioc_dev.substitutions.

To add a device to the development IOCManager, follow the steps from the previous section
with these changes:

-Edit IOCManagerApp/Db/dev/crat_dev.substitutions and/or IOCManagerApp/Db/dev/ioc_dev.substitutions

-Edit iocBoot/sioc-sys0-nwdev/st.cmd

-After committing changes to CVS

	Go to: /afs/slac/g/lcls/epics/iocTop/IOCManager/Dev/
	Perform CVS update
	Rebuild
	Reboot sioc-sys0-nwdev, using iocConsole

