README for EPICS Knob User Software This software supports using hardware knobs to control EPICS devices. Each instance of this software supports 1 line with up to 15 knob boxes (1-15). (In theory it could support box 0 as well but this is not done in practice.) ================================================================= Configuration: ----------------------------------------------------------------- EPICS databases, knobUserEpicsApp/Db: - Instantiate one instance of knobUserBox.db for each box. Example: # Macros: # LOCA: System location name. For LCLS, use SYS0 # BOX: Box number to be used in PV names, user interfaces # Combination of LOCA and BOX must be unique globally # INST: Box instance, between 1 and 15. # Matches box hardware address and is index into box data structures. # #===================================================================== # file knobUserBox.db{ pattern { LOCA, BOX, INST } { SYS0, 1, 1 } { SYS0, 2, 2 } { SYS0, 3, 3 } { SYS0, 4, 4 } { SYS0, 5, 5 } { SYS0, 6, 6 } { SYS0, 7, 7 } { SYS0, 8, 8 } { SYS0, 9, 9 } { SYS0, 10, 10 } { SYS0, 11, 11 } { SYS0, 12, 12 } { SYS0, 13, 13 } { SYS0, 14, 14 } { SYS0, 15, 15 } } ----------------------------------------------------------------- st.cmd: - Load EPICS Knob User database, for example SIOC-SYS0-KN00.db: dbLoadRecords("db/SIOC-SYS0-KN00") - Initialize knob user software before iocInit. Example for development system: # Initalize EPICS knob user software # knobUserEpicsInit(ctrlcb, devcb, ctrlio, ctrlparm, line) # ctrlcb - Name of callbacks for comm with knob controller # devcb - Name of callbacks for comm with EPICS devices being controlled # ctrlio - Comm handle for knob controller (typically name of node where controller runs) # ctrlparm - Comm parameter for knob controller (typically port number controller listens on) # knobUserEpicsInit("knobUserCtrlCommUdpCb", "knobDevCommCaCb", "lcls-dev1", 2001) ================================================================= Source code description: (all code in knobUserApp/src) ----------------------------------------------------------------- Main program files: knobUserEpics.c/.h Main program for EPICS knob user software Tasks: - Initialize communication with knob controller - Initialize access to EPICS devices - Process requests from EPICS to attach/detach EPICS devices to/from knobs - Process messages from knob controller: when updated turn count, calculate and set new value for device - Maintain connection to attached devices, if their values change, send updated knob legends Program flow: - Program runs in infinite loop - Read and process messages from knob controller - Loop through knobs - If new attach request, attach device - If new detach request, detach device - If device is attached, check for new value. If new value, update legend. If not and device's connection state has changed, update local connection state and message on user display. Data structures (see knobUserEpics.h): - knobdevice_ts contains data for device attached to knob. Only the driver has access to this. One per knob. - knobshr_ts contains knob data that must be shared between driver and device support. One per knob. - kuserglobal_ts contains the above structs, function pointers for passing data to device support, and other variables of global interest Callbacks (see knobUserEpics.h for functional description of callbacks): - kuserctrlcb_ts is the callback structure used for communication with the knob controller. It is required and must be passed as argument to knobUserEpicsInit. - kuserdevcb_ts is the callback structure used for accessing devices attached to knobs. It is required and must be passed as argument to knobUserEpicsInit. - kuserfaccb_ts is the callback structure that may set the legend and sensitivity, using facility-specific conventions, when a device is attached. It is optional and may be set using knobSetFacCallbacks before iocInit Routines called by other software: There are several routines called from device support to set/read data from the driver. These are listed in knobUserEpics.h ----------------------------------------------------------------- Device support: devKnobUserEpics.c/.h Tasks: - Provide user input to EPICS knob support: attach, detach, save value, restore value, adjust knob sensitivity - Provide status from EPICS knob support: status message, device value, units Data structures: -knobdevsup_ts contains data private to device support, stored in DPVT Note that there are a couple EPICS records that need to be modified by both the user interface (device support) and the driver. Thus these are handled a little differently: we do not use scanIoRequest because that requires SCAN=I/O Intr and that would not allow changes from the user interface. Instead when the driver initiates a change, device support uses dbScanLock and scanOnce to update and process. See knobUserEpics.h for more details ----------------------------------------------------------------- Communication with knob boxes: knobCtrlApp/src/knobCtrlComm.c/.h knobCommonApp/src/knobCtrlUserDef.h Tasks: - Intialize communication with knobs - Use callbacks to receive send messages supported by our msg protocol: request turns, update legend, etc. ----------------------------------------------------------------- Callbacks for communication with knob users - UDP knobCtrlUserUdp/knobCtrlUserUdp.c Implements kusercb_ts to communicate with users via UDP. See knobCommonApp/src/knobCtrlUserDef.h for functional description of callbacks Tasks: - Initialize UDP server - Initialize data structures - Copy/compare knob user socket info - Send UDP messages - Receive UDP messages ----------------------------------------------------------------- Callbacks for communication with knob boxes - TCP knobCtrlBoxTcp/knobCtrlBoxTcp.c Implements knobcb_ts to communicate with knob boxes via TCP. See knobCommonApp/src/knobCtrlBoxDef.h for functional description of callbacks Tasks: - Initialize TCP clients - Initialize data structures - Send TCP messages - Receive TCP messages ----------------------------------------------------------------- =================================================================