Firewire IIDC (CDAM) Windows driver

Table of Contents

• Introduction
• Firewire specific parameters
• Implementation of standard driver parameters
• Unsupported standard driver parameters
• Configuration
• MEDM screens
• Performance measurements
• Restrictions

Introduction

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.

Video formats, modes, and frame rates

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.

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.

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.

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.

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 standard driver parameters

Unsupported standard driver parameters

The mar345 driver does not support the following standard driver parameters because they are not supported in the mar345dtb program:

• Number of exposures per image (ADNumExposures)
• Trigger mode (ADTriggerMode)
• Gain (ADGain)
• Region to read out (ADMinX, ADMinY, ADSizeX, ADSizeY, ADReverseX, ADReverseY)
• Binning (ADBinX, ADBinY)
• Frame type (ADFrameType)
• Data type (ADDataType)
• Reading previous files (ADReadFile)
• Capture or stream file saving (ADFileWriteMode, ADFileCapture, ADNumCapture, ADNumCaptured)

Configuration

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);
  

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:")

MEDM screens

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.

FirewireFeatures.adl

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.

FirewireFeatures.adl

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.

FirewireFeatures.adl

Performance measurements

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.

Restrictions

The following are some current restrictions of the mar345 driver:

• The areaDetector driver can in principle be run on machines other than the Linux machine running mar345dtb, since the connection is via a socket. It has only been tested on Linux.
• The following items are hardcoded in the driver. They can be changed by recompiling compiling if necessary.
  • MAX_MESSAGE_SIZE=256 The maximum size of message to/from mar345dtb server.
  • MAX_FILENAME_LEN=256 The maximum size of a complete file name including path and extension.
  • MAR345_COMMAND_TIMEOUT=180.0 Timeout for a complete erase or scan command to complete.