+ FirewireFeatures.adl
+
+ This is a driver for Firewire (IEEE 1394) cameras that follow the + IIDC/DCAM specification. + This industry standard allows a single driver to control cameras from any manufacturer, using any of + the supported video formats and features. + It inherits from ADDriver and implements many of the parameters in ADStdDriverParams.h. + It also implements a number of parameters that are specific to the Firewire cameras.
++ This driver runs only on Windows. It uses the + Carnegie Mellon 1394 camera driver and library. There is also an + areaDetector Firewire driver for Linux available from the + + Diamond Light Source. +
+The IIDC/DCAM specification defines standard ways that manufacturers must implement features like shutter time, + white balance, frame sizes, frame rates, etc. There is a standard way to determine whether or not a particular + camera supports a particular feature. If it does then there is a standard way of querying the allowed + range of values for that feature. This makes it quite easy to write a driver that can support + cameras with any capabilities from any manufacturer.
+The DCAM specification defines standard video frame sizes, color modes and frames rates. The following tables lists + these standard formats and mode. Video format 7 is special. It allows defining an ROI on the camera to read out. + The pixel resolution with which the size and position of this ROI can be defined can be queried, and is not + necessarily a single pixel. In Format 7 the frame rate settings do not apply, and the frame rate is determined + by the size of the Fireware data packets.
+| + Standard IIDC/DCAM Video Formats and Video Modes | +|||
| + Format Number | ++ Format Description | ++ Mode Number | ++ Mode Description | +
|---|---|---|---|
| + 0 | ++ VGA | +||
| + 0 | ++ 160x120 YUV444 | +||
| + 1 | ++ 320x240 YUV422 | +||
| + 2 | ++ 640x480 YUV411 | +||
| + 3 | ++ 640X480 YUV422 | +||
| + 4 | ++ 640x480 RGB | +||
| + 5 | ++ 640x480 Mono8 | +||
| + 6 | ++ 640x480 Mono16 | +||
| + 7 | ++ Reserved | +||
| + 1 | ++ Super-VGA1 | +||
| + 0 | ++ 800x600 YUV422 | +||
| + 1 | ++ 800x600 RGB | +||
| + 2 | ++ 800x600 Mono8 | +||
| + 3 | ++ 1024x768 YUV422 | +||
| + 4 | ++ 1024x768 RGB | +||
| + 5 | ++ 1024x768 Mono8 | +||
| + 6 | ++ 800x600 Mono16 | +||
| + 7 | ++ 1024x768 Mono16 | +||
| + 2 | ++ Super-VGA2 | +||
| + 0 | ++ 1280x960 YUV422 | +||
| + 1 | ++ 1280x960 RGB | +||
| + 2 | ++ 1280x960 Mono8 | +||
| + 3 | ++ 1600x1200 YUV422 | +||
| + 4 | ++ 1600x1200 RGB | +||
| + 5 | ++ 1600x1200 Mono8 | +||
| + 6 | ++ 1280x960 Mono16 | +||
| + 7 | ++ 1600x1200 Mono16 | +||
| + 3-5 | ++ Reserved | +||
| + 0-7 | ++ Reserved | +||
| + 6 | ++ Still image | +||
| + 0 | ++ Exif | +||
| + 1-7 | ++ Reserved | +||
| + 7 | ++ Partial Image (user-defineable ROI) | +||
| + 0-7 | ++ Vendor-defined | +||
The following tables lists the standard frame rates for formats 0, 1 and 2. Note that not all frame rates are supported + by the IIDC standard for every format and mode, and even when a frame rate is supported by the standard it may not + be implemented for a particular camera. + In Format 7 the frame rate settings do not apply, and the frame rate is determined by the size of + the Fireware data packets. The areaDetector driver currently sets the Format 7 packet size to the vendor recommended + size, which typically results in the maximum possible frame rate.
+| + Standard IIDC/DCAM Video Frame Rates | +|
| + Frame Rate Number | ++ Frame Rate (Frames/second) | +
|---|---|
| + 0 | ++ 1.875 | +
| + 1 | ++ 3.75 | +
| + 2 | ++ 7.5 | +
| + 3 | ++ 15 | +
| + 4 | ++ 30 | +
| + 5 | ++ 60 | +
| + 6 | ++ 120 | +
| + 7 | ++ 240 | +
The DCAM specification defines 22 standard features, which control things such as the brightness, white balance, + shutter time, etc.. For each feature the standard defines + control in both device units (12-bit integers) and absolute units (floating point). For example shutter time + may support absolute seconds, as well as device units. A feature may or may not + be supported on a particular camera. If it is supported it may or may not permit control in absolute units. + Each feature may support both manual control and automatic control (e.g. automatic gain control). + The following tables lists these standard features.
+| + Standard IIDC/DCAM Features | +||
| + Feature Number | ++ Feature Description | ++ EPICS record string for firewireFeature.template | +
|---|---|---|
| + 0 | ++ Brightness | ++ BRIGHTNESS | +
| + 1 | ++ Auto exposure | ++ EXPOSURE | +
| + 2 | ++ Sharpness | ++ SHARPNESS | +
| + 3 | ++ White balance (color tint) | ++ WHITEB | +
| + 4 | ++ Hue (color tint) | ++ HUE | +
| + 5 | ++ Saturation (color saturation) | ++ SATURATION | +
| + 6 | ++ Gamma (response curve) | ++ GAMMA | +
| + 7 | ++ Shutter (exposure time) | ++ SHUTTER | +
| + 8 | ++ Gain (amplification) | ++ GAIN | +
| + 9 | ++ Iris | ++ IRIS | +
| + 10 | ++ Focus | ++ FOCUS | +
| + 11 | ++ Temperature | ++ TEMP | +
| + 12 | ++ Trigger mode | ++ TRIGGER | +
| + 13 | ++ Trigger delay | ++ TRIGDLY | +
| + 14 | ++ White shading | ++ WHITES | +
| + 15 | ++ Frame rate | ++ FRAMERATE | +
| + 16 | ++ Zoom | ++ ZOOM | +
| + 17 | ++ Pan | ++ PAN | +
| + 18 | ++ Tilt | ++ TILT | +
| + 19 | ++ Optical filter | ++ FILTER | +
| + 20 | ++ Capture size | ++ CAPTSIZE | +
| + 21 | ++ Capture quality | ++ QUALITY | +
+ The firewireWinDCAM driver implements the following parameters in addition to those in ADStdDriverParams.h.
+ Note that to reduce the width of this table the enum names have been split into
+ 2 lines, but these are just a single name, for example mar345ScanSize.
+
| + Parameter Definitions in firewireWinDCAM.cpp and EPICS Record Definitions | +||||||
| + Enum name | ++ asyn interface | ++ Access | ++ Description | ++ drvUser string | ++ EPICS record name | ++ EPICS record type | +
|---|---|---|---|---|---|---|
| + Video format parameters. In firewireDCAM.template and firewireVideoModes.template. | +||||||
|
+ FDC_ + format |
+ + asynInt32 | ++ r/w | ++ The video format. The allowed choices are 0="VGA", 1="Super VGA 1", 2="Super VGA 2", 6="Still image", 7="User-defined". + The FDC_has_format and FDC_valid_format parameters described below indicate whether a particular format is actually supported + by the camera. | ++ FDC_FORMAT | +
+ $(P)$(R)FORMAT + $(P)$(R)FORMAT_RBV |
+
+ mbbo + mbbi |
+
|
+ FDC_ + has_format |
+ + asynInt32 | ++ r/o | ++ A flag indicating whether a particular format (0-7) is supported by the camera. | ++ FDC_HAS_FORMAT | ++ $(P)$(R)HAS_FORMAT_$(N) (N=0-7) | ++ bi | +
|
+ FDC_ + valid_format |
+ + asynOctet | ++ r/o | ++ A string describing each of the formats (0-7) supported by the camera. The string is "N.A." if the format is not supported. | ++ FDC_VALID_FORMAT | ++ $(P)$(R)VALID_FORMAT_$(N) (N=0-7) | ++ stringin | +
|
+ FDC_ + current_format |
+ + asynOctet | ++ r/o | ++ A string describing the currently selected video format. | ++ FDC_CURRENT_FORMAT | ++ $(P)$(R)CURRENT_FORMAT | ++ stringin | +
| + Video mode parameters. In firewireDCAM.template and firewireVideoModes.template. | +||||||
|
+ FDC_ + mode |
+ + asynInt32 | ++ r/w | ++ The video mode. The allowed choices are 0-7. + The FDC_has_mode and FDC_valid_mode parameters described below indicate whether a particular mode is actually supported + by the camera in the currently selected video format. | ++ FDC_MODE | +
+ $(P)$(R)MODE + $(P)$(R)MODE_RBV |
+
+ mbbo + mbbi |
+
|
+ FDC_ + has_mode |
+ + asynInt32 | ++ r/o | ++ A flag indicating whether a particular mode (0-7) is supported by the camera in the currently selected format. | ++ FDC_HAS_MODE | ++ $(P)$(R)HAS_MODE_$(N) (N=0-7) | ++ bi | +
|
+ FDC_ + valid_mode |
+ + asynOctet | ++ r/o | ++ A string describing each of the modes (0-7) supported by the camera in the currently selected video format. + The string is "N.A." if the mode is not supported in this format. | ++ FDC_VALID_MODE | ++ $(P)$(R)VALID_MODE_$(N) (N=0-7) | ++ stringin | +
|
+ FDC_ + current_mode |
+ + asynOctet | ++ r/o | ++ A string describing the currently selected video mode. | ++ FDC_CURRENT_MODE | ++ $(P)$(R)CURRENT_MODE | ++ stringin | +
| + Video frame rate parameters. These parameters do not apply when the video format=7. + In firewireDCAM.template and firewireVideoModes.template. | +||||||
|
+ FDC_ + framerate |
+ + asynInt32 | ++ r/w | ++ The frame rate in frames/second. The allowed choices are 0="1.875", 1="3.75", 2="7.5", 3="15", 4="30", 5="60", 6="120", 7="240". + FDC_has_framerate and FDC_valid_framerate parameters described below indicate whether a particular frame rate is actually supported + by the camera in the currently selected video format and mode. | ++ FDC_FRAMERATE | +
+ $(P)$(R)FR + $(P)$(R)FR_RBV |
+
+ mbbo + mbbi |
+
|
+ FDC_ + has_framerate |
+ + asynInt32 | ++ r/o | ++ A flag indicating whether a particular frame rate (0-7) is supported by the camera in the currently selected video format and mode. | ++ FDC_HAS_FRAMERATE | ++ $(P)$(R)HAS_RATE_$(N) (N=0-7) | ++ bi | +
|
+ FDC_ + valid_framerate |
+ + asynOctet | ++ r/o | ++ A string describing each of the frame rates (0-7) supported by the camera in the currently selected video format and mode. + The string is "N.A." if the frame rate is not supported in this format and mode. | ++ FDC_VALID_FRAMERATE | ++ $(P)$(R)VALID_RATE_$(N) (N=0-7) | ++ stringin | +
|
+ FDC_ + current_framerate |
+ + asynOctet | ++ r/o | ++ A string describing the currently selected video frame rate. | ++ FDC_CURRENT_FRAMERATE | ++ $(P)$(R)CURRENT_RATE | ++ stringin | +
| + Video color code parameters. These parameters only apply when the video format=7. + In firewireDCAM.template and firewireColorCodes.template. | +||||||
|
+ FDC_ + colorcode |
+ + asynInt32 | ++ r/w | ++ The color code. The allowed choices are 0-10. + FDC_has_colorcode and FDC_valid_colorcode parameters described below indicate whether a particular color code is actually supported + by the camera in the currently selected video format (7) and mode. | ++ FDC_COLORCODE | +
+ $(P)$(R)COLORCODE + $(P)$(R)COLORCODE_RBV |
+
+ mbbo + mbbi |
+
|
+ FDC_ + has_colorcode |
+ + asynInt32 | ++ r/o | ++ A flag indicating whether a particular color code (0-10) is supported by the camera in the currently selected video format (7) and mode. | ++ FDC_HAS_COLORCODE | ++ $(P)$(R)HAS_COLORCODE_$(N) (N=0-10) | ++ bi | +
|
+ FDC_ + valid_colorcode |
+ + asynOctet | ++ r/o | ++ A string describing each of the color codes (0-10) supported by the camera in the currently selected video format (7) and mode. + The string is "N.A." if the color code is not supported in this format and mode. | ++ FDC_VALID_COLORCODE | ++ $(P)$(R)VALID_COLORCODE_$(N) (N=0-10) | ++ stringin | +
|
+ FDC_ + current_colorcode |
+ + asynOctet | ++ r/o | ++ A string describing the currently selected color code. | ++ FDC_CURRENT_COLORCODE | ++ $(P)$(R)CURRENT_COLORCODE | ++ stringin | +
| + Video feature parameters. These parameters apply to each of the 22 DCAM features listed above. In firewireFeature.template. | +||||||
|
+ FDC_ + feat_val |
+ + asynInt32 | ++ r/w | ++ The feature value in device units. | ++ FDC_FEAT_VAL | +
+ $(P)$(R)$(FEATURE) + $(P)$(R)$(FEATURE)_RBV |
+
+ ao + ai |
+
|
+ FDC_ + feat_val_abs |
+ + asynFloat64 | ++ r/w | ++ The feature value in absolute units. | ++ FDC_FEAT_VAL_ABS | +
+ $(P)$(R)$(FEATURE)_ABS + $(P)$(R)$(FEATURE)_ABS_RBV |
+
+ ao + ai |
+
|
+ FDC_ + feat_available |
+ + asynInt32 | ++ r/o | ++ A flag indicating if the feature is available. | ++ FDC_FEAT_AVL | ++ $(P)$(R)$(FEATURE)_AVL | ++ bi | +
|
+ FDC_ + feat_absolute |
+ + asynInt32 | ++ r/o | ++ A flag indicating if absolute control of the feature is available. | ++ FDC_FEAT_ABSOLUTE | ++ $(P)$(R)$(FEATURE)_ABS_AVL | ++ bi | +
|
+ FDC_ + feat_mode |
+ + asynInt32 | ++ r/o | ++ Selects manual (0) or automatic (1) control of the feature. | ++ FDC_FEAT_MODE | +
+ $(P)$(R)$(FEATURE)_CTRL + $(P)$(R)$(FEATURE)_CTRL_RBV |
+
+ bo + bi |
+
|
+ FDC_ + feat_val_min |
+ + asynInt32 | ++ r/o | ++ The minimum allowed value of the feature in device units. The database copies this value to the LOPR and DRVL fields + of the $(P)$(R)$(FEATURE) record. | ++ FDC_FEAT_VAL_MIN | ++ $(P)$(R)$(FEATURE)_MIN | ++ ai | +
|
+ FDC_ + feat_val_max |
+ + asynInt32 | ++ r/o | ++ The maximum allowed value of the feature in device units. The database copies this value to the HOPR and DRVH fields + of the $(P)$(R)$(FEATURE) record. | ++ FDC_FEAT_VAL_MAX | ++ $(P)$(R)$(FEATURE)_MAX | ++ ai | +
|
+ FDC_ + feat_val_abs_min |
+ + asynInt32 | ++ r/o | ++ The minimum allowed value of the feature in absolute units. The database copies this value to the LOPR and DRVL fields + of the $(P)$(R)$(FEATURE)_ABS record. | ++ FDC_FEAT_VAL_ABS_MIN | ++ $(P)$(R)$(FEATURE)_ABS_MIN | ++ ai | +
|
+ FDC_ + feat_val_abs_max |
+ + asynFloat64 | ++ r/o | ++ The maximum allowed value of the feature in absolute units. The database copies this value to the HOPR and DRVH fields + of the $(P)$(R)$(FEATURE)_ABS record. | ++ FDC_FEAT_VAL_ABS_MAX | ++ $(P)$(R)$(FEATURE)_ABS_MAX | ++ ai | +
+ The following table describes how the Firewire driver implements some of the standard + driver parameters. +
++ It is useful to use NDPluginROI to define an ROI containing the entire mar345 detector. + The MaxValue_RBV PV in this ROI can be monitored to make sure that the 16-bit limit + of 65,535 is not being approached in any pixel. +
+| + Implementation of Parameters in ADStdDriverParams.h and EPICS Record Definitions + in ADBase.template and NDFile.template | +||
| + Enum name | ++ EPICS record name | ++ Description | +
|---|---|---|
| + ADNumImages | ++ $(P$(R)NumImages | ++ Controls the number of images to acquire when ADImageMode is ADImageMultiple. | +
| + ADAcquirePeriod | ++ $(P$(R)AcquirePeriod | ++ Controls the period between images when ADImageMode is ADImageMultiple or ADImageContinuous. + If this is greater than the acquisition time plus readout overhead then the driver + will wait until the period has elapsed before starting the next acquisition. | +
| + ADGain | ++ $(P)$(R)Gain | ++ Maps onto the gain features. If camera supports absolute ... + | +
+ The mar345 driver does not support the following standard driver parameters because + they are not supported in the mar345dtb program:
++ The mar345 driver is created with the following command, either from C/C++ or from + the EPICS IOC shell. +
++mar345Config(const char *portName, const char *mar345Port, + int maxBuffers, size_t maxMemory); ++
| + Argument | ++ Description | +
|---|---|
+ portName |
+ + The name of the asyn port for this detector. + | +
+ mar345Port |
+
+ The name of the asyn TCP/IP port to communicate with mar345dtb. This
+ must have been previously created with drvAsynIPPortConfig(),
+ |
+
+ maxBuffers |
+ + Maximum number of buffers to be created for plugin callbacks. Passed to the constructor + for the ADDriver base class. | +
+ maxMemory |
+ + Maximum number of bytes of memory to be allocated for plugin callbacks. Passed to + the constructor for the ADDriver base class. | +
+ The following is an example st.cmd startup script: +
+< < envPaths
+errlogInit(20000)
+
+dbLoadDatabase("$(AREA_DETECTOR)/dbd/mar345App.dbd")
+mar345App_registerRecordDeviceDriver(pdbbase)
+
+###
+# Create the asyn port to talk to the MAR on port 5001
+drvAsynIPPortConfigure("marServer","gse-marip2.cars.aps.anl.gov:5001")
+# Set the input and output terminators.
+asynOctetSetInputEos("marServer", 0, "\n")
+asynOctetSetOutputEos("marServer", 0, "\n")
+asynSetTraceIOMask("marServer",0,2)
+#asynSetTraceMask("marServer",0,255)
+
+mar345Config("MAR", "marServer", 20, 200000000)
+asynSetTraceIOMask("MAR",0,2)
+#asynSetTraceMask("MAR",0,255)
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/ADBase.template", "P=13MAR345_1:,R=cam1:,PORT=MAR,ADDR=0,TIMEOUT=1")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDFile.template","P=13MAR345_1:,R=cam1:,PORT=MAR,ADDR=0,TIMEOUT=1")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/mar345.template","P=13MAR345_1:,R=cam1:,PORT=MAR,ADDR=0,TIMEOUT=1,MARSERVER_PORT=marServer")
+
+# Create a standard arrays plugin
+drvNDStdArraysConfigure("MARImage", 5, 0, "MAR", 0, -1)
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDPluginBase.template","P=13MAR345_1:,R=image1:,PORT=MARImage,ADDR=0,TIMEOUT=1,NDARRAY_PORT=MAR,NDARRAY_ADDR=0")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDStdArrays.template", "P=13MAR345_1:,R=image1:,PORT=MARImage,ADDR=0,TIMEOUT=1,SIZE=16,FTVL=SHORT,NELEMENTS=12000000")
+
+# Create an ROI plugin
+drvNDROIConfigure("MARROI", 5, 0, "MAR", 0, 4, 20, -1)
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDPluginBase.template","P=13MAR345_1:,R=ROI1:, PORT=MARROI,ADDR=0,TIMEOUT=1,NDARRAY_PORT=MAR,NDARRAY_ADDR=0")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDROI.template", "P=13MAR345_1:,R=ROI1:, PORT=MARROI,ADDR=0,TIMEOUT=1")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDROIN.template", "P=13MAR345_1:,R=ROI1:0:,PORT=MARROI,ADDR=0,TIMEOUT=1,HIST_SIZE=256")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDROIN.template", "P=13MAR345_1:,R=ROI1:1:,PORT=MARROI,ADDR=1,TIMEOUT=1,HIST_SIZE=256")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDROIN.template", "P=13MAR345_1:,R=ROI1:2:,PORT=MARROI,ADDR=2,TIMEOUT=1,HIST_SIZE=256")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDROIN.template", "P=13MAR345_1:,R=ROI1:3:,PORT=MARROI,ADDR=3,TIMEOUT=1,HIST_SIZE=256")
+
+#asynSetTraceMask("MARROI",0,3)
+#asynSetTraceIOMask("MARROI",0,4)
+
+# Load scan records
+dbLoadRecords("$(SSCAN)/sscanApp/Db/scan.db", "P=13MAR345_1:,MAXPTS1=2000,MAXPTS2=200,MAXPTS3=20,MAXPTS4=10,MAXPTSH=10")
+
+set_requestfile_path("./")
+set_savefile_path("./autosave")
+set_requestfile_path("$(AREA_DETECTOR)/ADApp/Db")
+set_requestfile_path("$(SSCAN)/sscanApp/Db")
+set_pass0_restoreFile("auto_settings.sav")
+set_pass1_restoreFile("auto_settings.sav")
+save_restoreSet_status_prefix("13MAR345_1:")
+dbLoadRecords("$(AUTOSAVE)/asApp/Db/save_restoreStatus.db", "P=13MAR345_1:")
+
+iocInit()
+
+# save things every thirty seconds
+create_monitor_set("auto_settings.req", 30,"P=13MAR345_1:,D=cam1:")
+
+
+ + The following show the MEDM screens that are used to control the Firewire detectors. + Note that the general purpose screen ADBase.adl can be used, but it exposes some + controls that are not applicable to Firewire cameras, and lacks many fields that are important + for such cameras.
+
+ FirewireFeatures.adl is the screen used to control the features of Firewire cameras.
+
+ FirewireVideoFormats.adl is the screen used to control the video formats and modes of Firewire cameras.
+ This is a screen shot when the camera is not in Format 7.
+
+ FirewireVideoFormats.adl is the screen used to control the video formats and modes of Firewire cameras.
+ This is a screen shot when the camera is in Format 7, in which case the video rate menu is not displayed.
+
+ The mar345 is definitely not a fast detector! + The following measurements show the time to perform various erase and scan operations. Note that because the + mar345 file format is compressed the file sizes are typically much less than the image sizes listed.
+| + Scan diameter | ++ Pixel size | ++ Image dimensions | ++ Image size (MB) | ++ Time to scan | ++ Time to erase | +
|---|---|---|---|---|---|
| + 180 mm + | ++ 0.15 mm + | ++ 1200x1200 + | ++ 2.7 + | ++ 38.6 + | ++ 37.8 + | +
| + 240 mm + | ++ 0.15 mm + | ++ 1600x1600 + | ++ 4.9 + | ++ 50.4 + | ++ 50.8 + | +
| + 300 mm + | ++ 0.15 mm + | ++ 2000x2000 + | ++ 7.6 + | ++ 74.7 + | ++ 66.9 + | +
| + 345 mm + | ++ 0.15 mm + | ++ 2300x2300 + | ++ 10.1 + | ++ 88.6 + | ++ 82.7 + | +
| + 180 mm + | ++ 0.10 mm + | ++ 1800x1800 + | ++ 6.2 + | ++ 46.4 + | ++ 45.9 + | +
| + 240 mm + | ++ 0.10 mm + | ++ 2400x2400 + | ++ 11.0 + | ++ 71.9 + | ++ 63.8 + | +
| + 300 mm + | ++ 0.10 mm + | ++ 3000x3000 + | ++ 17.2 + | ++ 89.1 + | ++ 87.0 + | +
| + 345 mm + | ++ 0.10 mm + | ++ 3450x3450 + | ++ 22.7 + | ++ 107.5 + | ++ 107.1 + | +
+ The following are some current restrictions of the mar345 driver:
+