############################################################ # # IOCManager application README # # Auth: Sonya Hoobler # # Mod: # 13-May-2025, A. Le (anle): # Add instructions to add acsws with new firmware # 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 or init_snmp.iocsh (3) Update RELEASE_NOTES, tag and release IOCManager application (4) Add device to appropriate home display (5) Add device to Network Alarm system to make the alarms visible to home and the relevant network main display. (6) Add device to the srcArchive//.sub-arch file. This will generate an archive file at $TOP/archive/.archive. On IOCManager boot, this file will be copied to production server directory $IOC_DATA//archive/ where this file will be processed by a cron job periodically, and the pvs added the archive engine. (7) Check out into production, boot into IOCManager soft ioc (8) 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 an acsw, connect to it using telnet, note the network card firmware version, then enter "exit" to quit. Firmware v7.x.x or vx.x.x.x requires SNMP as existing asyn support is incompatible. An acsw using SNMP does not require a substitutions file entry as its info is set in the ioc's init_snmp.iocsh. Example: $ telnet acsw-in20-nw06 Trying 172.27.5.192... Connected to acsw-in20-nw06. Escape character is '^]'. User Name : (ask for username Password : and password) Schneider Electric Network Management Card AOS ==>v1.5.1.1<== read here (c) Copyright 2021 All Rights Reserved RPDU 2g APP v1.2.0.4 For a crat/acsw (firmware v6.x.x or lower, NOT vx.x.x.x), 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--nw*/init_asyn.cmd or init_snmp.iocsh for the associated area For a crat or acsw (firmware v6.x.x or lower, NOT vx.x.x.x), edit sioc--nw*/init_asyn.cmd 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'.) For an acsw with firmware v7.x.x or vx.x.x.x, edit sioc--nw*/init_snmp.iocsh Add a line initializing the SNMP interface. Load pdu_apc_snmp.iocsh for SNMPv2c or pdu_apc_snmp_v3.iocsh for SNMPv3 (slower but more secure). IMPORTANT: Ask Ken Brobeck to enable the SNMP version you plan to use on the acsw. Example entry: iocshLoad("$(TOP)/iocBoot/common/pdu_apc_snmp_v3.iocsh", "DEV=ACSW:IN20:NW06, HOST=acsw-in20-nw06, LOC=LKG-2724") Commit changes to git. (3) Update RELEASE_NOTES with your changes. Commit it to git, tag, build, and cram push new version. (4) 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. (5) Update the Network Alarm system to add the new device. This will make the new device's alarms visible in the 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. (6) 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. (7) 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 :INFO " ", so that it has a valid value. Or populate INFO with something useful! (8) 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. (9) 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 cd /prod/epics/app/IOCManager cvs -d /afs/slac/g/lcls/cvs checkout -P -d -r epics/ioc/IOCManager cd /configure cp RELEASE_SPEAR RELEASE cd .. cp RELEASE_SITE_SPEAR RELEASE_SITE make cd /prod/epics/app/IOCManager rm prod ln -s 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