This is an EPICS areaDetector 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.
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.
This driver inherits from ADDriver. It implements many of the parameters in asynNDArrayDriver.h and in ADArrayDriver.h. It also implements a number of parameters that are specific to the Firewire cameras. The firewireWinDCAM class documentation describes this class in detail.
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 asynNDArrayDriver.h and ADDriver.hh. Note that to reduce the width of this table
the parameter index variable 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 | ||||||
Parameter index variable | asyn interface | Access | Description | drvInfo 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 |
Readout time parameters. In firewireDCAM.template. | ||||||
FDC_ READOUT_TIME |
asynFloat64 | r/w | The readout time in seconds. This value is added to the AcquireTime to determine how long to wait before a frame timeout is reported. It should be set to a value slightly larger than the actual readout time of the camera in the current mode. | FDC_READOUT_TIME |
$(P)$(R)READOUT_TIME $(P)$(R)READOUT_TIME_RBV |
ao
ai |
The firewireWinDCAM driver is created with the WinFDC_Config command, either from C/C++ or from the EPICS IOC shell.
WinFDC_Config(const char *portName, const char* camid, int maxBuffers, size_t maxMemory, int priority, int stackSize)
For details on the meaning of the parameters to this function refer to the detailed documentation on the WinFDC_Config function in the firewireWinDCAM.cpp documentation and in the documentation for the constructor for the FirewireWinDCAM class.
There an example IOC boot directory and startup script (iocBoot/iocFirewire/st.cmd) provided with areaDetector.
The following show the MEDM screens that are used to control the Firewire detectors.
firewire.adl
is the main screen used to control Firewire 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.