Application Note PCI DV C-Link Support for the Redlake (formerly DuncanTech) DT1100, MS2100, M3100, MS4100, DT4000 Multi-Spectral Cameras Engineering Design Team, Inc June 2002 Last updated, June 2003 CONTENTS Overview Required Software Required Firmware Configuration Files Duncantech-Specific Configuration File Directives Data Format Important Notes About 30-Bit Mode Controlling The Camera Serial Communications From The Command-Line Duncantech-Specific PCI DV Library Routines OVERVIEW This application note describes the specifics of Redlake/Duncantech camera support on the PCI DV C-Link, cPCI DV C-Link, and PCI RCI C-Link Camera Link interface systems. The term PCI DV C-Link is used generically in this document; unless otherwise specified it can be assumed everything discussed here applies to all EDT Camera Link products. The term Duncantech is also used generically, to refer to the Duncantech cameras both before and after they were acquired by Redlake. REQUIRED SOFTWARE The discussion assumes you have the latest EDT PCI DV software package, available on EDT's web site at www.edt.com/software.html You should also have a current version of the Duncantech DTControl software, available through Duncantech or Redlake MASD. REQUIRED FIRMWARE The PCI DV C-Link interface is loaded at the factory with firmware that works for standard base-mode CameraLink, including 24-bit Duncantech mode. In order to run with DuncanTech cameras in 30-bit mode, both cameralink cables must be used, and the board's on-board PROM must be re- flashed with Medium mode firmware. To do so, select EDT utilities (or go the EDT\pdv directory [Windows] or /opt/EDTpdv [Solaris/Linux]). Then run pciload pdvcamlk_pir and after if completes, halt and cycle power on the computer. To go back to Base mode firmware, (Duncantech 24-bit mode and most other cameras), reload the standard firmware: pciload pdvcamlk and halt and cycle power. To find out which firmware is presently loaded, run pciload with no arguments. See the PCI DV Family Users Guide for more details about the firmware. CONFIGURATION FILES Versions 3.2.9.8 and later of the PCI DV Software/Driver package include the following Duncantech configuration files in the camera_config subdirectory (see the Duncantech Camera User's Guide for more information on the specific camera modes): dt1100.cfg (DT1100, 24-bits per pixel, freerun) dt1100t.cfg (DT1100, 24-bits per pixel, integrate/dump) dt1100-30.cfg (DT1100, 30-bits per pixel, freerun) dt1100-30t.cfg (DT1100, 30-bits per pixel, integrate/dump) dt2100.cfg (MS2100, 24-bits per pixel, freerun) dt2100t.cfg (MS2100, 24-bits per pixel, integrate/dump, indep.) dt2100-30.cfg (MS2100, 30-bits per pixel, freerun) dt2100-30t.cfg (MS2100, 30-bits per pixel, integrate/dump, indep.) dt3100.cfg (MS3100, 24-bits per pixel, freerun) dt3100t.cfg (MS3100, 24-bits per pixel, integrate/dump, indep.) dt3100-30.cfg (MS3100, 30-bits per pixel, freerun) dt3100-30t.cfg (MS3100, 30-bits per pixel, integrate/dump, indep.) dt4100.cfg (MS4100, 24-bits per pixel, freerun) dt4100t.cfg (MS4100, 24-bits per pixel, integrate/dump, indep.) dt4100-30.cfg (MS4100, 30-bits per pixel, freerun) dt4100-30t.cfg (MS4100, 30-bits per pixel, integrate/dump, indep.) dt4000.cfg (DT4000, 24-bits per pixel, freerun) dt4000t.cfg (DT4000, 24-bits per pixel, integrate/dump) dt4000-30.cfg (DT4000, 30-bits per pixel, freerun) dt4000-30t.cfg (DT4000, 30-bits per pixel, integrate/dump) ms4000.cfg (MS4000, 24-bits per pixel CIR, freerun) ms4000t.cfg (MS4000, 24-bits per pixel CIR, integrate/dump, indep.) ms4000-30.cfg (MS4000, 30-bits per pixel CIR freerun) ms4000-30t.cfg (MS4000, 30-bits per pixel CIR, integrate/dump, indep.) Choices corresponding to the above configuration files will show up in the camera configuration tool, included with the PCI DV software package. You can choose them from there (when running the pdvshow GUI program for example), or initialize from the command line using the initcam program. For example: initcam -f camera_config/dt2100-30.cfg DUNCANTECH-SPECIFIC CONFIGURATION FILE DIRECTIVES For duncantech cameras, the serial_init_duncanf configuration file directive was added to make it easier to send setup commands to the duncantech cameras. This directive takes one argument: a double-quoted character string containing colon-separated ASCII representations of serial binary commands WITHOUT the framing information. Initcam will add the framing (STX and checksum) to each command, and send the resulting command to the camera. For example, to set the integration time on channel 1 to 100 (64 hex), send the proper (DuncanTech defined) bytes to the camera, via the serial_init directive: serial_init_duncanf: "040014016400" After adding the STX 02 and checksum bytes (in this case, 02 and 87 respectively), initcam will send the properly framed command bytes to the camera, via pdv_serial_binary_command: 02 04 00 14 01 64 00 87 The method_serial_format has no effect on the library subroutines such as pdv_serial_binary_command. If you send a command to the camera using a pdv_serial_binary_command or other serial command library routines, you will need to send all of the required bytes, incluing the leading STX and checksum. Initcam and configuration file directives are discussed in detail in the Camera Configuration guide camconfig.pdf, available on the distribution CD ROM and on our web site at www.edt.com/manuals.html. Also see the contents of the specific config file for more examples. DATA FORMAT The data format in 24-bit mode is 3 bytes per pixel, B G R. The data format in 30-bit mode is 4 bytes per pixel, with the first 3 bytes being the high order 8-bits of B, G and R respectively, and the MSbyte containing the low order 2 bits of B, G and R: Byte 0 Byte 1 Byte2 Byte3 8 MS-Blue 8 MS-Green 8 MS-Red 2 LS-B, 2 LS-G, 2 LS-R, 2 0 *** IMPORTANT NOTES ABOUT 30-BIT MODE *** 1) In 30-bit mode, Duncantech cameras require 25% more PCI bandwidth than 24- bit mode, and this can saturate the PCI bus on some systems. If you experience broken frames, slow frame rates, or image timeouts, you may need to upgrade to a system with a 66Mhz or faster PCI or PCI-X bus. For more on bandwidth requirements, see http://www.edt.com/requirements.html 2) Prior to about June 2003, Duncantech cameras had a timing problem that resulted in offset of some bits of the blue channel, yielding erroneous color information on the blue channel when running in 30-bit mode. The easiest way to tell if this problem is present is to load the board with the 30-bit firmware (see REQUIRED FIRMWARE, above) and bring up the board and camera in a 30-bit configuration, then run dtcontrol and switch to one of the monochrome modes. Acquire a single image in pdvshow then move the mouse pointer around over the image. The triplet that shows the RGB values (near the center of the footer bar in the pdvshow window) should be the same for all pixels. The problem will show up as R and G being the same but B varying by a little bit. If you see this, contact Redlake to arrange to have the fix applied to the camera. Alternately you can load the board with a version of the firmware that has a workaround for this condition, by running pciload pdvcamlk_dlylv 3) Duncantech's 30-bit output MUX does not conform to the camera link standard. Because of this, EDT developed an input MUX that matches the Duncantech ordering. Later versions of Duncantech camera firmware may have changed this however. So if in 30-bit mode you're seeing odd colors, try switching the board's MUX by changing the rgb30 flag from 1 to 3 in the config file you're using. CONTROLLING THE CAMERA Serial communication to the camera can be accomplished through either the computer's COM port or the Camera Link serial channel. EDT serial subroutines all go through the Camera Link channel. Duncantech's DTcontrol software on the other hand is not "Camera Link enabled", so to use it you must have the serial cable connected between the camera and the computer's COM port. In practice, both paths are used; the EDT board sends commands via the Camera Link serial channel (primarily set-up commands at initializtion time -- see the serial_init_duncanf config file directive in the Camera Configuration Guide), and Dtcontrol provides a GUI for controlling the camera's shutter speed, gain, etc. using the RS-232 path. Duncantech's DTcontrol software has not been ported to Solaris or Linux. Camera communications on such systems must therefore be sent via the COM port using a terminal program, or through the EDT board's Camera Link serial channel via the provided command line application or pdvlib subroutine calls. SERIAL COMMUNICATIONS FROM THE COMMAND-LINE The EDT utility program serial_cmd can be used to send and receive serial commands and status to and from the DuncanTech camera. The program is described in the PCI DV Family User's guide, and its usage can be output by invoking it with the -h (help) option: serial_cmd -h The -x option can be used to send raw binary commands to the DuncanTech. However, if you do this you will need to calculate and include the required STX and checksum bytes -- a tedious exercise. To make this a little easier, the -D option was added, which handles these framing details. Much like the aforementioned serial_init_duncanf config file directive, the "-D" option results in serial_cmd automatically adding the leading STX (0x03), and checksum byte. So all you need to specify are the size, command and channel bytes (if any). For example, say you wanted to query the camera's channel 1 integration time. The DuncanTech command for this is 0x15, and the size is 2. The two size bytes (LSB then MSB) come first, then the command byte, then the channel number. To do this with serial_command, enter the following on the command line: serial_cmd -D > 02 00 15 01 The program will add the STX and checksum, and send out the bytes 02 02 00 15 01 ea and read back the response, which should be something like resp <02 05 00 15 01 64 00 00 86> Note that framing information is NOT stripped off the response from the camera, whether or not the -D option is used. DUNCANTECH-SPECIFIC PCI DV LIBRARY ROUTINES Several Duncantech-specific functions are available to be called from user applications: pdv_set_exposure_duncan_ch, pdv_set_gain_duncan_ch, pdv_set_offset_duncan_ch. The source code for these is provided in libpdv.c and can be used as examples for for programmers who want to create subroutines for other DuncanTech-specific functions. These routines use the serial channel in the cameralink cable, so it is not necessary to have the RS232/COM port channel set up unless you also wish to use Duncantech's DTcontrol program. It should be noted that the general-purpose convenience routines pdv_set_exposure, pdv_set_gain, and pdv_set_blacklevel are all single- channel routines, which means they will not work with the DuncanTech which has multi-channel control of these parameters. This isn't a big deal, it just means that you won't be able to change the camera parameters using the built-in functionality in some of the EDT-supplied example programs (for example the take '-e', '-g', and '-b' options, and pdvshow's 'camera settings' dialog.) Descriptions of the Duncantech-specific functions follow: ======================================================================= pdv_set_exposure_duncan_ch DESCRIPTION Set the exposure on a specific channel of the Duncan MS2100 camera. Sends the binary serial command, properly formatted, to the camera, and reads the response. SYNTAX int pdv_set_exposure_duncan_ch(PdvDev *pdv_p, int channel, int value) ARGUMENTS pdv_p pointer device struct returned from pdv_open channel channel to set the exposure on -- valid values are 1, 2 or 3 value exposure value -- range is camera-specific RETURNS 0 on success, -1 on failure EXAMPLE /* set channel 1, 2 and 3 exposure */ pdv_set_exposure_duncan_ch(pdv_p, 1, 100); pdv_set_exposure_duncan_ch(pdv_p, 2, 200); pdv_set_exposure_duncan_ch(pdv_p, 3, 200); ======================================================================= pdv_set_gain_duncan_ch DESCRIPTION Set the gain on a specific channel of the Duncan MS2100 camera. Sends the binary serial command, properly formatted, to the camera, and reads the response. SYNTAX int pdv_set_gain_duncan_ch(PdvDev *pdv_p, int channel, int value) ARGUMENTS pdv_p pointer device struct returned from pdv_open channel channel to set the gain on -- valid values are 1, 2 or 3 value gain value -- range is camera-specific RETURNS 0 on success, -1 on failure EXAMPLE /* set channel 1, 2 and 3 gain */ pdv_set_gain_duncan_ch(pdv_p, 1, 100); pdv_set_gain_duncan_ch(pdv_p, 2, 200); pdv_set_gain_duncan_ch(pdv_p, 3, 200); ======================================================================= pdv_set_offset_duncan_ch DESCRIPTION Set the offset (black level) on a specific channel of the Duncan MS2100 camera. Sends the binary serial command, properly formatted, to the camera, and reads the response. SYNTAX int pdv_set_offset_duncan_ch(PdvDev *pdv_p, int channel, int value) ARGUMENTS pdv_p pointer device struct returned from pdv_open channel channel to set the offset on -- valid values are 1, 2 or 3 value offset value -- range is camera-specific RETURNS 0 on success, -1 on failure EXAMPLE /* set channel 1, 2 and 3 offset */ pdv_set_offset_duncan_ch(pdv_p, 1, 100); pdv_set_offset_duncan_ch(pdv_p, 2, 200); pdv_set_offset_duncan_ch(pdv_p, 3, 200); ======================================================================= Two more specialized subroutines were created to help make it easier to program for duncantech cameras -- pdv_send_duncan_frame, and pdv_read_duncan_frame. Both are used, either directly or indrectly, by the above routines. ======================================================================= pdv_send_duncan_frame DESCRIPTION Given a command buffer minus the framing, add the framing information and send the command bytes. Ref. DuncanTech Camera Manual Doc. ID number 9000-0001-05 SYNTAX int pdv_send_duncan_frame(PdvDev * pdv_p, u_char *cmdbuf, int len) ARGUMENTS pdv_p pointer device struct returned from pdv_open cmdbuf DuncanTech command buffer len length in bytes of command buffer RETURNS 0 on success, -1 on failure EXAMPLE Send a GetIntegrationTime command to the camera unsigned char cmdbuf[8]; buf[0] = 0x02; /* LSB size */ buf[1] = 0x00; /* MSB size */ buf[2] = 0x15; /* GetIntegrationTime command */ buf[3] = 0x01; /* channel number */ pdv_send_duncan_frame(pdv_p, cmdbuf, 4); /* pdv_send_duncan_frame adds the */ /* STX and checksum before sending */ /* the frame to the camera */ ======================================================================= pdv_read_duncan_frame DESCRIPTION Read the command response from a DuncanTech camera. This routine is similar to pdv_serial_read, and in fact uses it at a lower level. However it has a little more "smarts" about the format of a DuncanTech command response, and therefore is able to read the length bytes as they come in and determine from those how many more bytes to wait for, thus eliminating some serial "wait" time that would otherwise be needed to make sure all of the response bytes has been returned. Ref. DuncanTech Camera Manual Doc. ID number XXX SYNTAX int pdv_read_duncan_frame(PdvDev * pdv_p, u_char *cmdbuf) ARGUMENTS pdv_p pointer device struct returned from pdv_open cmdbuf DuncanTech command buffer RETURNS number of bytes read EXAMPLE Send a command and read the response pdv_send_duncan_frame(pdv_p, cmdbuf, 4); if ((n = pdv_read_duncan_frame(pdv_p, cmdbuf)) < 1) printf("Error: no response from DuncanTech camera\n"); ======================================================================= For more information refer to the following: - PCI DV Family Users Guide - PCI DV Addenda: Camera Configuration Guide - PCI DV README file - Duncantech camera user manual EDT documentation is available on the EDT CDROM and on our web site, www.edt.com. Duncantech documentation is available on their web site, www.duncantech.com.