From CVS repository

doc/README.camserver_commands

+Camserver is a completely freestanding program that controls an x-ray camera and provides a simple user interface for "atomic" (single function) commands.  It is intended to provide a spartan, but fully functional, low level interface to camera hardware.
+
+Camserver takes a single command-line argument, the path to the resource file.  Camserver will also use the same path to open its debugging file, 'camdbg.out', if debugging is enabled.
+
+A major function is to accept socket connections from a high level controller (e.g., tvx), which can provide high level services to this or other cameras.  The interface is a simple text-based message passing system.  Images - the ultimate product of a working area x-ray detector - do not pass thru the interface, but are written to a configurable location (e.g., an nfs mount) where either program can access them.
+
+Because of the socket connection protocol, the camera hardware and server can reside on a different machine form the high level controller.
+
+Camserver implements a token mechanism (controllingProcess) to prevent more than one outside process from having control over the hardware.  The camserver window has full control at all times.
+
+Commands in camserver that are also present in the tvx main window must have different names to prevent collisions between the enum's in camclient.c and in tvx.c.  I have chosen to distinguish them by upper-casing the last letter (e.g., Run in tvx.c, RuN in camserver.c), and re-lower the case of the last letter in menu_print to make it look better.  This is generally poor prctice in C, but since these commands have the same function in the two places, I see no harm.  Alternatives would be leading or trailing underscores, all upper-case in one window, or slightly respelling commands.
+
+To permit all processes to enquire as to the state of the camera system, I implemented a /proc-like file system which at all times has the camera status, and which can be queried by any process (just 'cat' from the command line will work, too).  Alternatives would have been: use of threads (__clone) rather than fork, so that all child processes share memory; use of shared memory (shmop, etc.); or use of pipes.  Of course, programmers must see to it that these values are always updated.
+
+--- Organization:
+
+cam_config.h - locations of configuration files & names of configurable vars
+
+camrc - camera resource file read at startup
+~/.camrc - your customized copy of camrc, read after the system file.
+    These can be used to configure the camera status reporting system and
+    the location of the camera definition.  
+    
+./camrc - project-specific camera resource file in your project directory
+    This is read after ~/.camrc, and overwrites previous global settings
+
+These various "camrc" files are read and interpreted by code in
+    ./camserver/util/cam_config.c, which may be extended with new items as
+     needed.
+
+camera.def - the camera hardware definition
+    The camera definition file is specified in the 'camrc' file and is read and
+    interpreted by code in, e.g., ./camserver/sls42/util/cam_tbl.c, that is, in
+    the camera-specific directory.  As above, this may be extended with new
+    items as needed.  New camera definition files can be reread/replaced
+    from the command line during camera operation.
+
+cam_config.c - the configuration reader (see above)
+camserver.c - main program
+camserver.h - declarations for the server.  Needed also by the client (tvx)
+sls42cam.pkg - a package of commands specific to one equipment.
+    The reading of, e.g., sls_05_16_1.def is compiled into the sls42 
+    directory tree.  
+
+--- Paths:
+
+camstat_path - path to the /proc-like filesystem that tracks camera status
+cam_data_path - default path for camera data
+cam_image_path - place to put images for stand-alone operation
+    Note that the image path is normally provided by the client in the 
+    'exposure' command.
+
+--- Files:
+
+cam_definition_file - hardware-specific configuration of camera containing
+    values of camera variables, e.g. width, height, bits-per-pixel
+cam_startup_file - camera-specific commands to executed at startup.  Note that
+    this function could equally well be accomplished in the tvx startup file.
+
+--- Initialization:
+
+Each camera type should be configured in its own directory, following the model of the sls42 directory.  The concept is (though it may fail in practice) that camserver, and its 'utils' are fairly generic, and that the personality of particular camera is brought about by the association with a camera-specific directory.  This is all controlled by reasonably straight-forward changes in ./camserver/Makefile (and only there).  Of course, you have to write the camera code for your camera.
+
+Summary - (sls42 setup)
+1. camserver calls cam_config_initialize(path) in util/cam_config.c
+     which calls camera_read_setup(filename) in sls42/util/interface.c
+        which calls read_camera_setup(filename) in sls42/util/interface.c
+           which calls read_detector_info(filename) in sls42/progi2c/signals.c
+2. camserver calls camera_initialize(void) in sls42/util/interface.c
+     which currently is a no-op
+3. camserver command 'read_setup filename' calls camera_read_setup (filename)
+     which repeats the steps above.
+
+In more detail - 
+camserver.c invokes cam_config_initialize (in cam_config.c) supplying the path to the resource file (camrc) supplied in the invocation line.
+
+cam_config_initialize reads (1) the system config file (/usr/local/etc/camrc); (2) the local config file (./camrc); and then (3) the user config file ($HOME/.camrc).  These overwrite previous data in that order.  Thus, the user can have differing configurations in each of several experiment-related directories, or simply a single configuration in his personal .camrc.  It is probably a bad idea to rely on the system default - it will normally point to /tmp, which is guaranteed writable by everyone, but wherein data is insecure.
+
+If a 'camera_definition_file' is specified in the config file, read_camera_setup (in hardware-specific directory sls42/util/cam_tbl.c) is invoked to read camera-specific parameters.  This action may be repeated from the command line by the Read_setup command.  The camera table contains operational parameters for the camera such as image height, width, bpp, bin-factor, etc.  This may be extended to include parameters specific for one kind of hardware, or those variables may be read separately in an application specific package (see next).
+
+camserver.c then invokes read_detector_info (in signals.c, an application specific package).  This reads the camera hardware definition from a file in the cam_data_path directory (default is ./cam_data; the file is specified in 'pix_detector.h' ). 
+
+camserver.c finally reads and executes the cam_startup_file specified in the resource file, if any.
+
+--- To implement a new camera:
+
+Camserver is now organized to make configuring for a new camera fairly easy.  The concept is that camserver and its associated utilities are fairly generic, and the real personality of a detector is carried in a subdirectory devoted to the camera.  Camserver isssues calls to, e.g., camera_start(), which is defined in interface.c, in the util directory of the specific camera.  The avoids most of the messy conditional compilation that could arise.  
+
+The steps to create a new camera are:
+(1) create a new directory for the camera by copying demo_cam in its entirety:
+    cd ./tvx/camera/camserver
+    cp -a demo_cam new_cam
+(2) in ./new_cam, change the name of the package to "new_cam.pkg"
+(3) in ./camserver/Makefile, add CAMERA = NEW_CAM, and comment out all cameras
+(4) in ./camserver/Makefile, add an 'ifeq' case for NEW_CAM, and list your
+          directories (just follow the existing cases)
+(5) in ./camserver/Makefile, add your new directory to the list CAMDIRS
+(6) in ./camserver/util/Makefile, add CAMERA = NEW_CAM
+(7) change ./camserver/util/cam_config.c to suit your needs
+(8) change ./camserver/new_cam/util/inteface.c to suit your needs
+(9) edit ./camserver/camrc to point to your configuration data
+(10) issue 'make' in the ./camserver directory
+That should do it.  Of course now you must build all your hardware specific code.
+
+Step (5) is so that 'make distclean' can clean up non-selected directories.
+
+Step (6) isn't strictly necessary if you do all your 'make's from the ./camserver directory, as the defines will propagate into the subsidiary directories.  But, just to be safe, it is better to do it.
+
+To use 'make' in the individual directories (convenient for debugging), it is necessary to use the same order as in the Makefile in ./camserver, namely:
+    ./camserver/misc
+    ./camserver/util
+    ./camserver/new_camera/util
+    ./camserver/new_camera/(other directories)
+if you use 'make distclean' in any directory, it erases the library, so you must repeat these steps.
+
+----- DEBUGGING:
+
+Many errors may be displayed until the configuration is correct, and these will scroll out of the window, or worse exit, before you can read them.  To debug the startup, cd to the camserver directory, and in a large window invoke the camserver directly (not from 'runtvx') giving as argument the (optional) path to the resource file (camrc) you are using; e.g.:
+    cd ./tvx/camera/camserver
+    ./camserver /home/efe/testtvx
+My directory testtvx has a 'camrc' file in it (also a 'tvxrc' file).
+
+Or, look at camdbg.out where initialization steps and errors are displayed clearly.
+
+----- COMMANDS:
+
+These are the commands in the base module, without camera-specific packages.
+Please do not change the format below, as it is used by the on-line help.
+
+~keystart=CamCmd
+CamCmd  - a general client entry to interpreter - used in tvx to send
+commands to camserver (that camserver understands) without programming tvx.
+This instruction  is not needed if you are writing your own client.
+
+Socket connection return code: 1
+Socket connection return text: none
+~keyend
+
+~keystart=CamSetup
+CamSetup  - report cmaera setup
+
+Socket connection return code: 2
+Socket connection return text: camera setup
+~keyend
+
+~keystart=CamWait
+CamWait  - wait for an exposure to end, or program a wait state
+
+Socket connection return code: 15
+Socket connection return text: none
+~keyend
+
+~keystart=DataPath
+DataPath - set or show cam_data_path.  Usage:
+
+        datapath path_to_directory
+
+    1) path_to_directory should already exist & have write permission
+    2) path should be either a full path, or begin with '~'.
+    3) normally should point to the cam_data directory
+
+This is the path to camera setup data (not the image path) and 
+generally should not be changed.
+
+Socket connection return code: 15
+Socket connection return text: full data path
+~keyend
+
+~keystart=Df
+Df  - show the number of 1024 KB blocks available on ImgPath
+
+Socket connection return code: 5
+Socket connection return text: number of 1K blocks available
+~keyend
+
+~keystart=ExpEnd
+ExpEnd - end an exposure
+
+Socket connection return code: 6
+Socket connection return text:  full path name of last image
+~keyend
+
+~keystart=Exposure
+Exposure  - make an exposure
+Usage:  exposure [filename]
+
+ExpTime and ShutterEnable should be preset.  The image is written to the
+specified filename relative to ImgPath, or to an absolute path if given.
+The format of the image is derived from the filename extension if given
+(tif, cbf or edf); otherwise a raw iamge is written.
+If a camera-specific exposure series is set up, an image number is inserted
+before the extension.
+If the camserver shutter control is being used, this command starts either
+a background or an exposure depending on the shutter state.
+
+Do 'help ExposureNaming' to see the exposure file naming convention
+
+Socket connection return code: 
+    15 at the start of the exposure or exposure series
+    7 after completion.
+Socket connection return text: 
+    at start: starting xxx second background <date & time>  -or-
+              starting xxx second exposure <date & time>
+    at end: full path name of last image
+~keyend                
+
+~keystart=ExpTime            
+ExpTime  - query or set the exposure time.
+
+Socket connection return code: 15
+Socket connection return text: Exposure time set to: xxx sec.
+~keyend
+
+~keystart=HeaderString            
+HeaderString  - give a string to be included in the image header
+Usage:  HeaderString text
+
+    1) The maximum length is 68 characters, no formatting permitted
+	2) Enclose the text in quotes to transmit non-alpha characters
+
+Socket connection return code: 15
+Socket connection return text: none
+~keyend
+
+~keystart=ImgPath
+ImgPath - query or change cam_image_path.  Usage:
+
+        imgpath [path_to_directory]
+
+    1) if path_to_directory does not exist, it will be created if
+       it is possible to do so with write permission
+    2) path may be a full path, or begin with '~'.
+    3) A path relative to the current path is accepted; '..' is accepted
+    4) E.g., if 'imgpath test' is given, and the current directory is
+        name 'test', a new directroy is NOT created.  If such a new
+        directory is desired, it may be specified by 'test/test'.
+    5) E.g., if 'imgpath test1/test2' is given, and the current path
+        is '.../test1/test2', a new directroy is NOT created.
+
+Socket connection return code: 10
+Socket connection return text: the path
+~keyend
+
+~keystart=LdCmndFile
+LdCmndFile  - load a file of camera commands and execute them
+
+Socket connection return code: 11
+Socket connection return text: none
+~keyend
+
+~keystart=Read_setup
+Read_setup  - (re)read a hardware-specific camera setup from a file, 
+e.g. camera.def
+Usage:  read_setup pathname
+
+Socket connection return code: 12
+Socket connection return text: the setup
+~keyend
+
+~keystart=K
+K  - stop an exposure in progress
+
+Socket connection return code: 
+    13 if an exposure is in progress
+    15 if no exposure in progress
+Socket connection return text: 
+    image name if there was an exposure in progress
+    none if no exposure in progress
+~keyend
+
+~keystart=ResetCam
+ResetCam  - synonym for 'K'
+~keyend
+
+~keystart=Send
+Send  - send a message to the client (tvx)
+
+Socket connection return code: 15
+Socket connection return text: message text
+~keyend
+
+~keystart=ShowPID
+ShowPID - show the PID of the process receiving the command
+
+Socket connection return code: 16
+Socket connection return text: the pid
+~keyend
+
+~keystart=ShutterEnable
+ShutterEnable  - enable/disable shutter control
+
+Socket connection return code: 15
+Socket connection return text: none
+~keyend
+
+~keystart=Telemetry
+Telemetry  - report camera telemetry
+
+Socket connection return code: 18
+Socket connection return text: telemetry text
+~keyend
+
+~keystart=Exit
+Exit  - exit the program
+
+Socket connection return code: N/A
+Socket connection return text: none
+~keyend
+
+~keystart=Quit
+Quit  - synonym for 'exit'
+~keyend
+
+~keystart=Menu
+Menu  - type the menu of all commands, including camera specific commands
+
+Socket connection return code: none
+Socket connection return text: none (prints only to the camserver window)
+~keyend
+
+~keystart=Status
+Status - return the camera status word as text
+
+Socket connection return code: 22
+Socket connection return text: status word
+~keyend
+
+~keystart=CamStatus
+CamStatus - synonym for Status, q.v.
+~keyend
+
+~keystart=Version
+Version - print the version (code release)
+
+Socket connection return code: 24
+Socket connection return text: version
+~keyend
+
+~keystart=CamNoop
+CamNoop - echo the argument to this command
+
+Socket connection return code: none
+Socket connection return text: none (prints only to the camserver window)
+~keyend
+
+~keystart=DbglvL
+Dbglvl  - print or set the debugging level 
+
+Socket connection return code: none
+Socket connection return text: none (prints only to the camserver window)
+~keyend
+
+~keystart=EndOfHelpText  **** THIS INDICATES THE END OF THE HELP FILE TEXT. 
+                TEXT AFTER THIS WILL NOT BE READ! ****

doc/new_camserver.txt

+ExtMTrigger - make exposures using multiple external triggers.  Usage:
+		extmtrigger file_base_name
+
+	1) Set NImages, ExpTime in advance.
+	2) Set delay in advance; default is 0
+	3) The time between triggers must be < 15 sec.
+	4) Images are trigged by the external trigger, but use the internal
+		timer for the exposure time.
+
+Do 'help ExpNaming' to see the exposure file naming convention
+
+
+DiscardMultiIm - discard multiple images
+Usage:
+		discardmultiim [n]
+	where n=0 to turn off this feature, or n!=0 to turn on
+	1) if n is omitted, the current state is printed
+	2) n may also be the word 'yes' or 'no' or 'y' or 'n
+
+DacOffset - query or set the state of dac offset compensation
+Usage: 
+		dacoffset [n]
+	where n=0 to turn off this feature, or n!=0 to turn on
+	1) if n is omitted, the current state is printed
+	2) n can be 0 or !0 or 'on' or 'off'
+	3) the default state is off; turn on for trim calculations
+
+
+MXsettings - query or set crystallography parameters
+Usage:
+		mxsettings [parm_name [value] [parm_name value] ...]
+
+	Parameter names:
+		Wavelength
+		Threshold_setting
+		Detector_distance
+		Detector_Voffset
+		Beam_xy
+		Flux
+		Filter_transmission
+		Start_angle
+		Angle_increment
+		Detector_2theta
+		Kappa
+		Phi
+		Chi
+		N_oscillations
+		
+	1) The parameter 'beam xy' accepts 2 values.
+	2) These paramters are included in CBF and TIFF image headers as comments.
+	3) More than 1 parameter may be specified in each command and they
+can be in any order.
+	4) With no parameters, prints the entire current list
+	5) With a parameter name only, print just that parameter's value
+	6) All parameters may be abbreviated with the shortest unambiguous string
+	7) In an automatic sequence, Start_angle is automatically incremented by
+Angle_increment after each recorded image.
+
+
+CalibFile - show or change the detector calibration file
+Usage:
+		calibfile [path]
+	1) if path not given, the current calibration file is printed
+	2) if path is given, it will be interpreted relative to the current
+		cam_data_path, unless an absolute path is given.
+
+
+SetThreshold - set gain (energy range) and threshold energy
+Usage:
+		setthreshold [[gain] threshold]
+	1) if parameters are omitted, the current settings are shown
+	2) gain is 'uhighG', 'highG', 'midG' (standard) or 'lowG'
+	3) if gain is omitted, the previous setting is retained
+	4) threshold is in eV
+	5) this command builds a script in "/tmp/setthreshold.dat" and 
+		then loads it.  The data for building the script are read, e.g.,
+		from p2_1mod/config/cam_data/m169_calibration.def.
+
+
+SetAckInt - set the interval for acknowledgements over the socket
+Usage:
+		setackint [N]
+	1) if N is omitted, the current value is shown
+	2) N=0 (default) - only the last exposure of a series is acknowledged.
+	   The initiating command is always acknowledged, so for 1 or more
+	   images, there is an acknowldgement before the start and at the end
+	   of a series.
+	3) N=n - acknowledge every nth image.  There are some restrictions at
+	   high frame rate: n cannot be too low.
+
+
+DMA_hold - set or query the dma holdoff time: the time until DMA is enabled
+Usage:
+		dma_hold [time]
+	1) If a time (in seconds) is not given, print the current setting
+	2) enter "dma_hold 0" to turn off the facility
+	3) This is useable only in the ExtEnable, ExtTrigger, and ExtMTrigger
+		modes.
+	4) The minimum useable holdoff is 5 sec.
+	5) Be very careful - wrong values will cause data loss
+
+
+LdBadPixMap - load a mask image giving bad pixels to be flagged
+Usage:
+		ldbadpixmap [filename]
+	1) if filename is not given, the current setting is shown
+	2) if filename is '0' or "off", the pixel flagging function is turned off
+	3) filename must be a full pathname
+	4) the maximum number of bad pixels and the flag value are in detsys.h
+
+
+LdFlatField - load or query flat-field correction file
+Usage:
+		ldflatfield [filename]
+	1) if filename is not given, the current setting is shown
+	2) if filename is '0' or "off", the flat field function is turned off
+	3) filename must be a full pathname
+	4) filename must be a 32-bit floating-point image
+	5) the image is pixel-wise multiplied by the correction file
+
+
+GapFill - query or set the value to be used in pixels between modules
+Usage:
+		gapfill [n]
+	where n is 0 or -1.
+	1) if n is omitted, the current value is printed
+
+
+
+
+
+
+
+
+