Äîêóìåíò âçÿò èç êýøà ïîèñêîâîé ìàøèíû. Àäðåñ îðèãèíàëüíîãî äîêóìåíòà : http://www.astro.louisville.edu/software/sbig/archive/xmccd-4.1/xmccd-4.1e/docs/apogee/ApSpec40.pdf Äàòà èçìåíåíèÿ: Thu Oct 2 23:15:07 2008 Äàòà èíäåêñèðîâàíèÿ: Thu Feb 27 22:37:01 2014 Êîäèðîâêà:

DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

Apogee Camera Control Development Specification
Applicable to

AP, KX, LISAA, and SPH Series Imaging Cameras Using Xilinx 4000 and Spartan series FPGA Engines Supporting Parallel Port, ISA and PCI Interfaces

Also compatible with some AM (QRX firmware), AX (Q firmware) series cameras

Specification Version 4.0
Revision Date: September, 2001

1


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

Disclaimer
Apogee Instruments Inc. assumes no liability for the use of the information contained in this document or the software which it describes. The user assumes all risks. There is no warranty of fitness for a particular purpose, either express or implied. The information contained in this document is assumed to be correct, but in no event shall Apogee Instruments Inc. be held responsible for typographical errors or changes in the software not reflected in this document. The specifications contained in this document are subject to change without notice.

Support
The Apogee Camera Control development specification is provided as a courtesy to our customers, and comes without warranty of fitness for any purpose or application. The user assumes all risk for the use of the information contained in this document and the software it describes.

Copyright © 1997 ­ 2001 Apogee Instruments Inc. All rights reserved. All trademarks mentioned in this document are the property of their respective owners are used herein solely for informational purposes only.

Apogee Instruments, Inc. 11760 Atwood Road, Suite #4 Auburn, CA 95603 (530) 888-0500 (530) 888-0540 FAX

2


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

1 2

Introduction _____________________________________________________________________ 4 Hardware Interface _______________________________________________________________ 4
2.1 Firmware Behavior__________________________________________________________________ 4
Imaging Geometry _______________________________________________________________________ 4 Temperature Calculations _________________________________________________________________ 7 Register Summary _______________________________________________________________________ 8 Reg_Command __________________________________________________________________________ 9 Reg_Timer ____________________________________________________________________________ 11 Reg_VBinning _________________________________________________________________________ 12 Reg_AICCounter _______________________________________________________________________ 13 Reg_TempSetPoint _____________________________________________________________________ 14 Reg_PixelCounter ______________________________________________________________________ 15 Reg_LineCounter _______________________________________________________________________ 16 Reg_BICCounter _______________________________________________________________________ 17 Reg_ImageData ________________________________________________________________________ 18 Reg_TempData ________________________________________________________________________ 19 Reg_Status ____________________________________________________________________________ 20 Reg_CommandReadback _________________________________________________________________ 21 2.1.1 2.1.2

2.2

Register Descriptions ________________________________________________________________ 7

2.2.1 2.2.2 2.2.3 2.2.4 2.2.5 2.2.6 2.2.7 2.2.8 2.2.9 2.2.10 2.2.11 2.2.12 2.2.13

3

Camera Initialization Files ________________________________________________________ 22
3.1 3.2 Parameters________________________________________________________________________ 22 Ranges and Defaults ________________________________________________________________ 23 ActiveX Driver ____________________________________________________________________ 24
Properties _____________________________________________________________________________ Methods ______________________________________________________________________________ Usage from Visual Basic _________________________________________________________________ Usage from Visual C++ __________________________________________________________________ Usage from LabVIEW ___________________________________________________________________ 25 27 28 30 31

4

Software Interface _______________________________________________________________ 24
4.1
4.1.1 4.1.2 4.1.3 4.1.4 4.1.5

4.2 4.3

Generic Class Interface _____________________________________________________________ 32 Architectural Notes _________________________________________________________________ 34
Read/Write Substitutions for Parallel Port Operation ___________________________________________ 34

4.3.1

3


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

1 Introduction
This specification outlines the hardware and software functionality of the Apogee imaging cameras. The specification is broken into three major sections: the Hardware Interface, Initialization Files, and the Software Interface. The Hardware Interface details the firmware engine used to control Apogee camera systems. This includes an overview of the register set and associated bit descriptions of registers. Behavioral models of the hardware are also discussed in this section. For example, temperature control is now discussed in detail, and a more thorough description of the geometry variables used during image readout is provided. Initialization files are key to providing the bridge between the Hardware and Software components of the camera. It is important to always properly configure the camera device to known safe state, before attempting any imaging operation. The initialization files provide a list of parameters to set on the camera before using the device for the first time. The section on the Software Interface explains the Apogee software architecture. A key component of this architecture is an API library that is packaged as an ActiveX (COM) component. Apogee Instruments does provide source code support for the camera systems. However, wherever possible, third party vendors are encouraged to the use the ActiveX DLL. The ActiveX DLL provides probably the fastest method to producing a new imaging application. Furthermore, third party applications using the DLL will find it easy to support any changes or updates that might occur in the future, because while the internal implementation of the DLL functionality may change, the external interface will remain the same.

2 Hardw are Interface
2.1 Firmware Behavior
2.1.1 Imaging Geometry
Pixels are processed and digitized according to specified geometry parameters. In order to discuss these rules and algorithms, we will use the following definitions: Parameter Columns Rows Image Columns (ImgCols) Image Rows (ImgRows) B IC AIC BIR AIR SkipC SkipR Definition Total physical count of columns on CCD device Total physical count of rows on CCD device Number of columns within the Image Area (in unbinned pixels) Number of rows within the Imaging Area (in unbinned pixels) Before Imaging Columns (BIC) count. Number of columns before Image Area. Specified in .INI file. After Imaging Columns (AIC) count. Number of columns after Image Area. Internally calculated value. Before Imaging Rows (BIR) count. Number of rows before Image Area. Specified in .INI file. After Imaging Rows (AIR) count. Number of rows after Imag Area. Internally calculated value. Skip Columns. Number of columns to be digitized in the Image Area, but not actually part of the Region of Interest (ROI). Specified in .INI file. Skip Rows. Number of rows to be digitized in the Image Area, but not actually part of the Region of Interest (ROI). Specified in .INI file.

4


DEVELOPMENT SPECIFICATION The following picture may be useful for visualizing the geometry:

APOGEE INSTRUMENTS INC

Columns

BIR

SkipR ImgRows SkipC Rows

ROI Digitized Imaging Area
AIR

Physical CCD Device

BIC

ImgCols

AIC

Note in the image above that even though SkipC and SkipR are digitized pixels, they are not included as part of the final image that is presented to an application by the driver. Also note that SkipC and SkipR are purely conventions used within the driver. The hardware firmware has no knowledge of these parameters.

2.1.1.1 Horizontal Geometry Rules
BIC Digitized Imaging Area AIC

Horizontally, the firmware automatically processes an entire CCD row. Each row is comprised of three sections which vary in size depending on the subframe location chosen. The first section is known as the "Before Imaging Columns" (BIC) and represents the column offset leading to the digitized area of interest. The BIC is counted on a 1:1 basis regardless of other binning parameters. For a full frame, the BIC value from the .INI file is used. The second section is the actual digitized imaging area "pixel count". The value loaded in the counter is based on groups of binned pixels. So if 100 columns within the imaging area are being binned by a factor of 4, then a value of 100/4 = 25 would be loaded into the Pixel_count variable. The third section is the "After Imaging Columns" (AIC) and represents the remaining columns of the physical CCD that still require clocking. It is calculated using the "Columns" value from the .INI file as follows: AIC = Columns (Specified in .INI) ­ BIC ­ "Unbinned (physical) Digitized Imaging Area pixels"

2.1.1.2 Horizontal Geometry examples:
INI files settings: [geometry] columns=530 imgcols=512 bic=4 a. For a full frame image binned 1:1, the values of BIC_count, Pixel_count and AIC_count are as follows; BIC_count = 4 (from ini file) 5


DEVELOPMENT SPECIFICATION Pixel_count AIC_count = 512 (from ini file) = 530 ­ 4 ­ 512 = 14

APOGEE INSTRUMENTS INC

b. For a sub-frame image 50 pixels wide located at a column offset= 100 ccd columns, binned 2:2: BIC_count = 4 (from ini file) + 100 = 104 Pixel_count = 50 / 2 = 25 AIC_count = 530 ­ 104 ­ 50 = 376 That having been said, the horizontal and vertical binning factors loaded during the Expose method are based on the .INI file setting "hflush=" and not the binning factors desired for the region of interest data. The Hflush and Vflush parameters were designed to provide a different (higher) value of binning for flushing so that faster flush cycles were possible.

2.1.1.3 Vertical Geometry Rules
Row Offset Initiated by Expose Digitized Rows Processed by GetImage Remaining Rows Processed by Flush

Since the Expose method causes the firmware to automatically skip (clock) to the region of interest after the exposure is complete, the geometry and vertical binning for this skipped region (row offset) must be considered. The factors to be considered are BIR and vflush binning in order to determine the proper value for line_count. In addition, a residual line_count number is generated and passed to GetImage. This is explained below. Line_count is based on unbinned rows, hence with a row offset of 4 with a vertical binning of 2 would result in a value of 4 being written to line_count. However, the complication comes apparent if the vertical binning used for the row offset exceeds the row offset itself, or if the number of skipped rows is not evenly divisible by the vertical binning factor. These two cases will be described as follows. 1. The vertical binning used for the row offset exceeds the row offset

The default vertical binning usedby the Expose method is based on "vflush=" from the INI file. If the number of offset rows (BIR) is less then vflush, then the value of BIR should be used for binning and a value of BIR written to the line_counter. 2. If the number of skipped rows is not evenly divisible by the vertical binning factor

This will occur most of the time. In this case, the greatest possible number of binned rows are assigned to line_count, and the remainder (m_ExposureRemainingLines) is passed to GetImage. GetImage will first skip the remainder before it does it's normal processing by setting the vertical binning = remainder and calling next_line one time.

2.1.1.4 Vertical Geometry Examples
INI files settings: [geometry] bir=4 vflush=8 a. For a full frame image, the values of vertical_binning and line_count are; Vertical_binning Line_count =4 =1 6


DEVELOPMENT SPECIFICATION Value of remaining_lines returned =0

APOGEE INSTRUMENTS INC

b. For a sub-frame image with a row offset of 150, the values of vertical_binning and line_count are; Vertical_binning Line_count Value of remaining_lines returned = 8 (from vflush INI setting) = ((bir of 4) + (row offset of 150)) / 8 = 19 (rounded down) =2

2.1.2 Temperature Calculations
The correct temperature setting values are derived from proper programming of the temperature setting registers. See the register descriptions for specific details on calculating the correct register values. Proper cooler operation involves setting the desired temperature, and then enabling the cooler operation. Once the set temperature has been reached, R11.7 (At-temp) will go high. From this point forward, assuming no other changes to the settings, the cooler can safely be assumed to be at the desired temperature setting. Some fluctuation may exist beyond this point, which an application can take into account by conducting a rolling average of the temperature value. Again, please note that there should be no expectation that once the set temperature has been reached, R11.7 will remain high consistently-- it is only to be used as an indication of the first time the set temperature was reached. As noted above, because of temperature fluctuations, the temperature readings should be taken once or twice a second, with a rolling average of 15 to 20 values used to derive the current temperature. An application can take the temperature reading more frequently, but should not attempt more than eight readings per second (the number of times the temperature reading is updated within the firmware itself). The following table lists various states for the cooling system. CommandReadback and Status Register Bits R11.4 R11.5 R11.6 R11.7 R12.8 R12.15 X X X X X 0 0 0 0 0 0 1 0 0 0 0* 0 1 X X 0 X 1 1 X X 1 X 1 1 0 1 0 X 0 1 1 0 0 X 0 1 0 0 0 1 0 1

Status String Cooler off Ramping to temp Correcting Ramping to ambient Ramp-up Complete Max cooling limit Min cooling limit At temp

* Correcting can be assumed if R11.7 (at-temp bit) was once a one but now a zero. After temperature ramp down, keep track of this bit in order to derive the "correcting" status. When first determining temp status following the opening of a camera, "correcting" can be assumed, if no other status can be derived.

2.2 Register Descriptions
Apogee cameras are line-readout devices, not frame-capture cameras. No interrupts or DMA operations are used. This means that the CCD data is read from the camera one line at a time, with polling to determine the camera states. Internal state control logic in the camera head and/or the interface card handles camera status, exposure timing, row and column counting, flushing, and temperature control. The driver is responsible for reading the correct number of rows from the camera and organizing the resulting data for display and processing.

7


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

2.2.1 Register Summary
The firmware is organized as a group of twelve 16 bit registers. Eight registers can be written to with the following (note that these registers can also be read from on PCI-based systems): · · · · · · Exposure time Horizontal and vertical binning Geometry information such as column offsets, #pixels per ROI, row offsets Desired Temperature Command bits which when toggled begin image acquisition, start/stop flushing, reset the system, or digitize and store entire rows of image data. Misc. control bits

Four 16 bit registers can be read from and contain the following data: · · · · Image data CCD Temperature Status bits used for temperature control and image readout Mirror of command register

Register 1 2 3 4 5 6 7 8 9 10 11 12

Mnemonic Reg_Command Reg_Timer Reg_Vbinning Reg_AICCounter Reg_TempSetPoint Reg_PixelCounter Reg_LineCounter Reg_BICCounter Reg_ImageData Reg_TempData Reg_Status Reg_CommandReadback

Function Command bits Timer bits 0-15 Timer bits 16-20, Vertical Binning After Imaging Column (AIC), Test2 bits Desired Temperature, Digital port Pixel Counter, Horizontal binning Line Counter, Mode bits Before Imaging Column (BIC), Test bits 16 bit Image Data CCD Temperature Status Register Command bits (Register 1) mirror

8


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

2.2.2 Reg_Command
Register Number: 1 Access:
ISA/PPI Write Only PCI Read/Write

Location (Offset from Base Address):
Interface ISA/PPI PCI Read N/A 0x20 0x0 0x0 Write

Programming Notes:
None.

Register Description:
15 Cooler Enable 14 Cable Length 13 Focus Mode 12 Start Flushing 11 Start Next Line 10 Timer Load Enable 9 Done Reading Bits 8 7 6 5 Cooler Shutter Stop Trigger ShutEnable Flushing Enable down 4 FIFO Cache 3 Reset System 2 Shutter Override 1 Start Timer 0 TDI Mode

Bit 0 1 2

Function TDI Mode Start Timer with Offset Shutter Override

3 4 5 6 7

Reset System FIFO Cache Trigger Enable Stop Flushing Shutter Enable

8 9 10

Cooler Shutdown Done Reading Timer Load Enable

11 12

Start Next Line Start Flushing

13

Focus Mode

Usage Enables drift scan operation (if camera firmware supports). If the firmware does not support Drift Scan, this bit has no effect on camera operation. Transition this bit (1 to 0) to begin exposure, skip lines according to image row offset, and digitize and store the first line of data in FIFO buffer. Enabling this bit forces the shutter open. Disabling this bit has no effect on shutter control. Note that the Shutter Override bit is not used in normal operation. Normal operation should use bit 7 (Shutter Enable) to control shutter operation during an exposure. Transition this bit (1 to 0) to reset firmware. Enable this bit during readout of an image line from the camera. Enables the start of an exposure from an external hardware trigger source. Disable this bit when not using an external hardware trigger. Transition this bit (1 to 0) to discontinue flushing. 0 = Dark Frame or Bias; 1 = Shuttered Exposure. Controls whether or not shutter is open while timer is active. Used to differentiate Dark and Bias frames from Images and Flat Fields. Setting this bit will ramp the cooler to Ambient temperature at a controlled rate. Transition this bit (1 to 0) to indicate that the current line has been read. Enable this bit while writing timer values to Reg2 and Reg3. After values are written, transition this bit back to 0 in order to use the timer. (Timer does not function when the Timer Load Enable bit is set.) Transition this bit (1 to 0) to initiate next line acquisition. Used after initial Start Timer command to read each successive line. Transition this bit (1 to 0) to initiate flushing. Flushing causes the CCD to continuous readout pixels, as if an image were being generated. This keeps the charge on the pixels to a minimum. Enabling this bit allows faster "lower quality" subframing. Use when speed is preferred over image quality. 9


DEVELOPMENT SPECIFICATION 14 15 Cable Length Cooler Enable

APOGEE INSTRUMENTS INC

0 = Short Cable; 1 = Long Cable. The following indicates appropriate values for cable length: Enables cooler operation. When enabled, the internal cooler control system will seek desired temperature defined by Reg5. Disabling this bit causes the hardware to stop regulating temperature control. The camera will eventually reach Ambient temperature. Note that this is not the recommended method of turning off the cooler. For controller cooler shutdown, use the "Cooler Shutdown" bit.

10


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

2.2.3 Reg_Timer
Register Number: 2 Access:
ISA/PPI Write Only PCI Read/Write

Location (Offset from Base Address):
Interface ISA/PPI PCI Read N/A 0x24 0x2 0x4 Write

Programming Notes:
The camera timer is a hardware timer, capable of measuring exposure duration to 0.01 second increments. The full timer is 20 bits wide, yielding a maximum exposure time of approximately 10,485.75 seconds or roughly 2.9 hours. A camera reset is suggested before using the internal camera timer. The reset operation will insure that the camera is not already running or in an unknown state when the timer values are loaded. The timer is set by enabling bit 10 (Timer Load Enable) of the Command register (Reg_Command). The 20 bit timer value is then written to Reg_Timer (lower 16 bits) and Reg_VBinning (upper four bits). Once those values are written, the Timer Load Enable bit should be brought low. The timer will not function with the Timer Load Enable bit set high. Also, the Timer will not be loaded with the correct timing value if the Timer Load Enable bit is not set before writing to the Reg_Timer and Reg_VBinning registers. For PCI camera operation, note that a read from this register will return the current value of the timer. If the timer is currently in operation,it should not be assumed that the current value of the timer register is the original (set) value of the timer.

Register Description:
Bits 15 : 0 Timer [15 : 0]

Bits 15:0

Function Timer

Usage The lower 16 bits of the camera's internal 20 bit timer.

11


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

2.2.4 Reg_VBinning
Register Number: 3 Access:
ISA/PPI Write Only PCI Read/Write

Location (Offset from Base Address):
Interface ISA/PPI PCI Read N/A 0x28 0x4 0x8 Write

Programming Notes:
None.

Register Description:
Bits 15 : 14 Reserved 13 : 8 Vertical Binning [5 : 0] 7:4 Reserved 3:0 Timer [19 : 16]

Bits 3:0 7:4 13:8 15:14

Function Timer Reserved Vertical Binning Reserved

Usage The upper four bits of the camera's internal 20 bit timer. Reserved for future use. Sets the Vertical Binning count to a value in the range 0-63. Reserved for future use. (These bits may be used to set an 8 bit vertical binning value in future products and/or firmware.)

12


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

2.2.5 Reg_AICCounter
Register Number: 4 Access:
ISA/PPI Write Only PCI Read/Write

Location (Offset from Base Address):
Interface ISA/PPI PCI Read N/A 0x2C 0x6 0xC Write

Programming Notes:
None.

Register Description:
Bits 15 : 12 Test2 11 : 0 AIC Counter [11 : 0]

Bits 11:0 15:12

Function AIC Counter Test2

Usage Defines the number of columns to be skipped after the imaging columns in a subframe have been digitized. The valid range of values is 1-4096, inclusive. Defines special camera functions or configurations. Specified via .INI file, and loaded when the device is initialized. Test2 bits are used for camera settings set at the Factory.

13


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

2.2.6 Reg_TempSetPoint
Register Number: 5 Access:
ISA/PPI Write Only PCI Read/Write

Location (Offset from Base Address):
Interface ISA/PPI PCI Read N/A 0x30 0x8 0x10 Write

Programming Notes:
This register is used for writing temperature data to the device. A conversion must be applied in order to write the correct value, given a certain temperature specified in degrees Celsius. This conversion is determined by using a zero-point and scale factor from the configuration file. Given the following variables: ZP = Zero-Point (Specified in .INI file) T = Temperature in degrees Celcius (Desired temperature to set) SF = Scale Factor (Specified in .INI file) Value = Raw Temperature (Value we will write to the device) We can determine the temperature in degrees Celsius using the following formula: Value = ZP + (T * SF) So, supposing we want to set a temperature of ­10 degrees Celsius, and have specified a zero-point of 0x115 and a scale factor of 2.5 in the .INI file, we get Value = 0x115 + (-10 * 2.5) = 0x90

Register Description:
Bits 15 : 8 Relay Control 7:0 Temperature Value

Bits 7:0 15:8

Function Temperature Value Relay Control

Usage Current temperature value, as determined from a set zero-point and scaling factor. An application must convert this value into degrees Celsius. Relay control.

14


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

2.2.7 Reg_PixelCounter
Register Number: 6 Access:
ISA/PPI Write Only PCI Read/Write

Location (Offset from Base Address):
Interface ISA/PPI PCI Read N/A 0x34 0xA 0x14 Write

Programming Notes:
The pixel counter is a 12 bit counter. This defines the limit (4096) to the number of pixels which can be digitized by the Apogee camera. Note that this does not include AIC or BIC pixels, only those pixels to be digitized. See the previous section on hardware geometry parameters for more information.

Register Description:
Bits 15 Reserved 14 : 12 Horizontal Binning 11 : 0 Pixel Counter

Bits 11:0 14:12 15

Function Pixel Counter Horizontal Binning Reserved

Usage Denotes the number of pixels to be digitized on a given line of the CCD. Sets the Horizontal Binning count to a value in the range 1-8. (A value of "000" in these bits is treated as a binning value of "1") Reserved for future use.

15


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

2.2.8 Reg_LineCounter
Register Number: 7 Access:
ISA/PPI Write Only PCI Read/Write

Location (Offset from Base Address):
Interface ISA/PPI PCI Read N/A 0x38 0xC 0x18 Write

Programming Notes:
None.

Register Description:
Bits 15 : 12 Mode 11 : 0 Line Counter

Bits 11:0 15:12

Function Line Counter Mode

Usage The number of rows to be flushed before the Frame Done Status (Reg11.11) goes high. Defines special camera functions or configurations. Specified via .INI file, and loaded when the device is initialized. Mode bits are used for camera settings set at the Factory

16


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

2.2.9 Reg_BICCounter
Register Number: 8 Access:
ISA/PPI Write Only PCI Read/Write

Location (Offset from Base Address):
Interface ISA/PPI PCI Read N/A 0x3C 0xE 0x1C Write

Programming Notes:
The BIC count is always given in terms of unbinned pixels..

Register Description:
Bits 15 : 12 Test 11 : 0 BIC Counter

Bits 11:0 15:12

Function BIC Counter Test

Usage Defines the number of columns to be skipped before the imaging columns in a subframe have been digitized. The valid range of values is 1-4096, inclusive. Defines special camera functions or configurations. Specified via .INI file, and loaded when the device is initialized. Test bits are used for camera settings set at the Factory

17


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

2.2.10

Reg_ImageData

Register Number: 9 Access:
ISA/PPI Read Only PCI Read Only

Location (Offset from Base Address):
Interface ISA/PPI PCI Read 0x0 0x0 N/A N/A Write

Programming Notes:
None.

Register Description:
Bits 15 : 0 16 bit Image Data

Bits 15:0

Function Image Data

Usage 16 bit image data from a single pixel.

18


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

2.2.11

Reg_TempData

Register Number: 10 Access:
ISA/PPI Read Only PCI Read Only

Location (Offset from Base Address):
Interface ISA/PPI PCI Read 0x2 0x4 N/A N/A Write

Programming Notes:
This register is used for reading temperature data from the device. A conversion must be applied in order to convert the value into degrees Celsius. This conversion is determined by using a zero-point and scale factor from the configuration file. Given the following variables: ZP = Zero-Point (Specified in .INI file) T = Temperature in degrees Celcius (Unknown) SF = Scale Factor (Specified in .INI file) Value = Raw Temperature (Read from lower byte of this register) We can determine the temperature in degrees Celsius using the following formula: T = (Value ­ ZP) / SF So, supposing we read a value of 0x90 from this register, and have specified a zero-point of 0x115 and a scale factor of 2.5 in the .INI file, we get T = (0x90 ­ 0x115) / 2.5 = -10 degrees Celsius

Register Description:
Bits 15 : 8 Reserved 7:0 Temperature Value

Bits 7:0 15:8

Function Temperature Value Reserved

Usage Current temperature value, as determined from a set zero-point and scaling factor. An application must convert this value into degrees Celsius. Reserved for future use.

19


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

2.2.12

Reg_Status

Register Number: 11 Access:
ISA/PPI Read Only PCI Read Only

Location (Offset from Base Address):
Interface ISA/PPI PCI Read 0x6 0x8 N/A N/A Write

Programming Notes:
None.

Register Description:
Bits 15 : 12 Reserved 11 Frame Done 10 Got Trigger 9 Rsvd 8 Rsvd 7 At Temp 6 Shutdown Done 5 Temp Max 4 Temp Min 3 Rsvd 2 Cache Read OK 1 Line Done 0 Expose In Progress

Bit 0 1 2 3 4 5 6 7

Function Expose In Progress Line Done Cache Read OK Reserved Temp Min Temp Max Shutdown Done At Temp

8 9 10 11 15:12

Reserved Reserved Got Trigger Frame Done Reserved

Usage Bit is set to indicate that an exposure is in progress. While high, poll the Frame Done bit (Reg11.11) to determine when the image is complete. Bit is set when imaging line has been processed and is ready for readout. Unused in driver. Goes high when cached FIFOs will allow reading to begin on the next line. Reserved for future use. Bit is set when the temperature cannot be driven more positive. Bit is set when the temperature cannot be driven more negative. Bit is set to indicates that a controlled cooler shutdown has finished. This is in response to the "Cooler Shutdown" bit being set in the Command register (Reg1.8). Indicates the point when the cooler has reached the desired temperature. Temperature can be assumed to reach the set point the first time "At Temp" goes high (even if the bit subsequently goes low). Reserved for future use. Reserved for future use. Bit is set when an external trigger has been received. Bit is set when the number of rows indicated by the line counter (Reg_LineCounter (Reg7)) have been flushed. Reserved for future use.

20


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

2.2.13

Reg_CommandReadback

Register Number: 12 Access:
ISA/PPI Read Only PCI Read Only

Location (Offset from Base Address):
Interface ISA/PPI PCI Read 0x8 0x10 N/A N/A Write

Programming Notes:
None.

Register Description:
15 Cooler Enable 14 Cable Length 13 Focus Mode 12 Start Flushing 11 Start Next Line 10 Timer Load Enable 9 Done Reading Bits 8 7 6 5 Cooler Shutter Stop Trigger ShutEnable Flushing Enable down 4 FIFO Cache 3 Reset System 2 Shutter Override 1 Start Timer 0 TDI Mode

The description and usage of these bits is the same as for the Command (Reg_Command) register. Please see that register for a detailed explanation of the bit fields.

21


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

3 Camera Initialization Files
The API uses a configuration file to identify all characteristics unique to a camera. This eliminates the need to change driver or application software for each camera type. The industry standard .INI file format is used. It is assumed that the API or application will never write over the .INI file. Any changes to .INI settings within an application using the API will be saved elsewhere as defined by the application. The initialization file settings are not case sensitive. White space is allowed between tokens. Values of "off/0/false" or "on/1/true" are equivalent. A complete list of all .INI parameters and their descriptions is presented below.

3.1 Parameters
[system] Interface Base Reg_Offset PP_Repeat Cable High_Priority Data_Bits Sensor Mode Test Test2 Shutter_Speed Shutter_Bits MaxBinX MaxBinY Guider_Relays Timeout [geometry] Columns Rows ImgCols ImgRows BIC BIR SkipC SkipR HFlush VFlush [temp] Control Target Cal Scale [ccd] Sensor Color Noise Gain PixelXSize PixelYSize Type of camera interface used CCD Controller card base address Camera offset used for parallel port systems Delay used for parallel port systems Cable length Thread set to high priority when dowlonding image Digitization resolution Type of sensor (CCD/CMOS) for future use. Mode bits in decimal, determined by factory Test bits in decimal, determined by factory Test2 bits in decimal, determined by factory Shutter time resolution (0.01 sec, 0.001 sec, dual) Mode and Test bits to toggle for dual speed shutters. The Mode mask is the low nibble, the Test mask is the high nibble. Maximum horizontal binning factor Maximum vertical binning factor Camera can output to guider relays Maximum length of time the Frame Done bit is polled Total columns on CCD (physical) Total rows on CCD (physical) Unbinned columns in imaging area Unbinned rows count in imaging area Before image column count (dark, non-imaging pixels) Before image row count Deleted data columns Deleted data rows Horizontal flush binning Vertical flush binning CCD temperature can be controlled CCD temperature set point Temperature calibration factor Temperature scaling factor Type of sensor CCD sensor has Typical readout Typical camera Size of pixels Size of pixels installed in camera color dyes noise in e- units gain in e-/ADU units in horizontal diraction (in micrometers) in vertical diraction (in micrometers)

22


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

3.2 Ranges and Defaults
N.B. Parameters prefixed by 0x or sufixed by an H are assumed to be hexadecimal. Parameters suffixed by .0 are assumed to be floating point numbers. Decimal integer parameters can be used in their place. Parameter [system] Interface Base Reg_Offset PP_Repeat Cable Data_Bits High_Priority Sensor Mode Test Test2 Shutter_Speed Shutter_Bits MaxBinX MaxBinY Guider_Relays Timeout [geometry] Columns Rows ImgCols ImgRows BIC BIR SkipC SkipR HFlush VFlush [temp] Control Target Cal Scale [ccd] Sensor Color Noise Gain PixelXSize PixelYSize Range ISA, PPI, PCI 0x000 - 0xFFF 0x0 - 0xF0 1 - 1000 short/long 8 - 18 true/false CCD/CMOS 0x0 ­ 0xF 0x0 ­ 0xF 0x0 ­ 0xF normal, fast, dual 0x0 - 0xFF 1-8 1 - 255 true/false 0.0 - 10000.0 Default required Required for PPI/ISA; Ignored for PCI cameras 0x0 1 short 16 true CCD 0x0 0x0 0x0 normal 0x0 8 63 false 2.0

1 1 1 1 1 1 0 0

- 65536 - 65536 - 4096 - 4096 - 4096 - 4096 - 4096 - 4096 1-8 1 - 255

required required Columns ­ BIR - SkipR Rows ­ BIC - SkipC 4 4 0 0 1 1

true/false -60 - +40 1 - 255 1.0 - 10.0

true -10 160 2.1

Any Any Any Any

Any text string true/false floating point numb floating point numb floating point numb floating point numb

er er er er

false 0 .0 0 .0 0 .0 0 .0

23


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

4 Softw are Interface
The Apogee camera drivers provide access to all camera functions through a straightforward ActiveX (COM Automation) API. ActiveX is accessible from virtually any Windows programming or scripting language. The ActiveX driver resides in the file Apogee.dll, which can be installed anywhere on the user's system. Note, though, that the DLL must be registered with the operating system (this is done by software installers automatically, or can be done manually via the command line interface). Please see the installation README file for appropriate instruction on hardware and software installation of the Apogee system. For applications where it is desirable to directly compile the driver into the program, to modify the driver for custom applications, or to use it under a different operating system, C++ source code has also been included. The interface for the C++ version is similar to the ActiveX interface described in this document, but is not identical. Please see the section Generic Class Interface for more information. Please note that the kernel-level driver must still be installed under Windows NT/2000.

4.1 ActiveX Driver
The ActiveX DLL can supply multiple Camera objects with an ICamera interface to any Windows application that can access COM objects. This includes applications written in Visual Basic, Visual C++, Delphi, Visual Java, Visual Interdev and other COM-aware languages, and scripting hosts such as Visual Basic for Applications, VBScript, JScript, PerlScript, Python etc. The Apogee software stack for the ActiveX driver is illustrated below:

Apogee ActiveX/COM Software Stack
Camera Control Application

ActiveX/COM Interface (Apogee.DLL) Windows NT 4.0/2000 ISA/PPI Driver and Windows NT 4.0 PCI Driver (ApogeeIO.sys)

Windows 98/ME/2000 PCI Driver (ApPCI.sys)

Windows 98/ME ISA/PPI Driver (Apogee.DLL)

Apogee Camera Firmware/Hardware

Note that PCI is only supported on Windows 98, Windows Millennium (ME), Windows NT 4.0, and Windows 2000. Apogee PCI controller cards are not supported on Windows 95. As stated previously, the ActiveX/COM interface provides a level of indirection for the software and driver components lower in the stack. This allows the underlying Apogee architecture to change and grow, while still supporting previous products. For example, an application written using the ActiveX interface for ISA or Parallel Port (PPI) designs does not require changes or additions to support Apogee PCI controller cards. Any API should be able to handle the requirements of a typical camera control application. A typical imaging session helps show the required, basic components, and might be structured as follows: 24


DEVELOPMENT SPECIFICATION · · · · · ·

APOGEE INSTRUMENTS INC

Initialize the camera with an .INI file Load desired geometry, temperature and configuration data using various the camera properties Call the Expose method Poll camera Status property When ready call the GetImage method Poll temperature and cooler status periodically

The Apogee ActiveX/COM architecture supports this functionality, plus additional features, via the ICamera interface. The ICamera interface supports the following methods and properties.

4.1.1 Properties
The following table details the properties supported by the Apogee ActiveX driver. Camera Settings Variable Status

R/W Read Only

Data Type Short

Present Shutter ForceShutterOpen Long Cable PPRepeat Mode TestBits Test2Bits DataBits SensorType

Read Only Read Only R/W R/W R/W R/W R/W R/W Read Only Read Only

Boolean Boolean Boolean Boolean Short Short Short Short Short Short

FastReadout Use Trigger T DI MaxExposure MinExposure MaxBinX MaxBinY GuiderRelays

R/W R/W R/W Read Read Read Read Read

O O O O O

nly nly nly nly nly

Boolean Boolean Boolean Double Double Short Short Boolean

Notes Returns current camera state <0: Error codes 0: Idle 1: W aiting for trigger 2: Exposing 3: Downloading 4: Line ready 5: Image ready 6: Flushing BIR Returns TRUE if camera present; FALSE otherwise Returns TRUE if shutter is open; FALSE if closed TRUE forces shutter to open; FALSE allows normal shutter operation Returns/Sets long cable mode Delay used on PPI camera systems Lower four bits map to Mode bits used for special camera functions or configurations Lower four bits map to Test bits used for camera troubleshooting Lower four bits map to Test2 bits used for special camera functions or configurations Digitization Resolution (8-18) Returns type of sensor used 0 or CCD: Charge Coupled Device 1 or CMOS: Complementary Metal-Oxide-Silicon Returns/Sets fast readout mode for focusing Returns/Sets triggered exposure mode Returns/Sets drift scan integration mode Returns the maximum exposure duration Returns the minimum exposure duration Returns the maximum horizontal binning factor Returns the maximum vertical binning factor Returns TRUE if camera can output to guider relays; FALSE otherwise

25


DEVELOPMENT SPECIFICATION Timeout Cooler Settings Variable CoolerControl CoolerSetPoint CoolerStatus R/W Double

APOGEE INSTRUMENTS INC Returns/Sets the maximum length of time the camera Frame Done bit is polled Notes Returns TRUE if CCD temperature can be controlled; FALSE otherwise Returns/Sets the cooler set point temperature in degrees Celcius Returns the current cooler status 0: Off 1: Ramp to set point 2: Correcting 3: Ramping to ambient 4: At ambient 5: Maximum cooling limit 6: Minimum cooling limit 7: At set point Returns/Sets the current cooler operation mode 0: Off (Shutdown immediately) 1: On (Enable Cooler; Go to set point temperature) 2: Shutdown (Ramp to Ambient, then Shutdown) Returns the current temperature in degrees Celcius Returns/Sets the temperature calibration factor (TempCelcius = (DAC units - Tcalibration) / Tscale) Returns/Sets the temperature scaling factor (TempCelcius = (DAC units - Tcalibration) / Tscale) Notes Returns/Sets the horizontal and vertical binning parameters Returns/Sets the subframe start position in terms of unbinned pixels Returns/Sets the subframe size in binned pixels Notes Returns the total number of physical columns or rows on the CCD Returns/Sets the number of deleted data columns that are not to be displayed Returns/Sets the horizontal and vertical flush binning parameters Returns/Sets the Before Imaging Columns/Rows (dark non-imaging pixels) Notes Returns the sensor model installed in the camera (I.e. "SITe 502) Returns TRUE is CCD sensor has color dyes; FALSE otherwise 26

R/W Read Only R/W Read Only

Data Type Boolean Double Short

CoolerMode

R/W

Short

Temperature TempCalibration TempScale Exposure Settings Variable BinX, BinY StartX, StartY NumX, NumY Geometry Settings Variable Columns, Rows SkipC, SkipR Hflush, Vflush BIC, BIR CCD Settings Variable Sensor Color

Read Only R/W R/W

Double Short Double

R/W R/W R/W R/W R/W Read Only R/W R/W R/W

Data Type Short Short Short Data Type Short Short Short Short

R/W Read Only Read Only

Data Type String Boolean


DEVELOPMENT SPECIFICATION Noise Gain PixelXSize, PixelYSize Other Variable Image R/W Read Only Data Type Variant Read Only Read Only Read Only Double Double Double

APOGEE INSTRUMENTS INC Returns the read-out noise in e-. Returns the gain in e-/ADU units Returns the size (X and Y) of the pixels in micrometers Notes Returns a 2D SAFEARRAY of type LONG (4 bytes per element) or Integer (2 bytes per element) which contains the image data. The type of data (LONG or INT) returned is controlled by the associated property of ConvertShortToLong Returns a 1D SAFEARRAY of type LONG (4 bytes per element) or Integer (2 bytes per element) which contains the image data. The type of data (LONG or INT) returned is controlled by the associated property of ConvertShortToLong Combination of the Expose Method and Image Property. Blocks the calling thread for the duration of the exposure and readout. Allows conversion of unsigned short (2 bytes per element) image data to long (4 bytes per element) when using the Image and Snap properties Returns/Sets the array base index for the Image and Snap properties. TRUE sets the base index to 1; FALSE sets the base index to 0. Returns/Sets whether the DLL thread is given high priority during image download (I.e. GetImage, Image and Snap).

Line

Read Only

Variant

Snap Read Only (Duration as Double, Light as Boolean) ConvertShortToLong R/W

Variant

Boolean

OptionBase

R/W

Boolean

HighPriority

R/W

Boolean

4.1.2 Methods
The following table details the methods supported by the Apogee ActiveX driver. System Function Init (String iniFile, Short BaseAddress = -1, [Optional] Short RegOffset = -1, [Optional]) Notes Initializes internal variables to their default value and reads the parameters in the specified INI file. If BaseAddress and RegOffset parmeters are non-negative, then these values are used instead of the INI settings for the BaseAddress and RegOffset properties. Note that PCI operation does not depend on a BaseAddress being specified. For PCI adapters, both the BaseAddress value in the INI file, as well as the BaseAddress parameter passed into this function, are ignored. An exception is thrown if the camera cannot be initialized. The error codes are: 0: No error detected 1: No config file (INI file) specified 2: Config missing or Config file missing required data 3: Loopback test failed; No camera detected 4: Memory allocation failed; System Error 5: NT I/O Driver not present

27


DEVELOPMENT SPECIFICATION Reset()

APOGEE INSTRUMENTS INC Resets the camera to an idle state. Terminates current exposure, if exposure is in progress. Does not initiate flushing (use the Flush() method). Starts flushing the camera (the camera should be in an idle state). If Rows is a non-negative number, only the specified number of rows will be flushed. In this case, the method will return only when the flushing operation is complete Outputs "Value" to an auxillary output port (e.g. for driving guider relays) W rites "Value" to the specified "Register". Registers 1-8 may be written to by the application. Reads from the specified "Register". The result of the read operation is placed into the "Value" variable. Returns/Sets drift scan integration mode Move the filterwheel to the home position. Failure indicates that no filterwheel is attached or the filterwheel is broken. Move the filterwheel to the position denoted by "Slot"

Flush (Short Rows = -1 [Optional])

AuxOutput (Byte Value) RegW rite (Short Register, Short Value) RegRead (Short Register, Short Value) FilterHome() FilterSlot (Short Slot) Normal Exposure Function Expose (Double Duration, (Boolean Light)

GetImage (Long pImageData) Drift Scan Function DigitizeLine()

Notes Takes an exposure of a specified Duration (in seconds). The Light parameter controls the state of the shutter during the exposure. If Light is TRUE, the shutter opens. If Light is FALSE, the shutter will close. This method returns immediately after invocation. Poll the CameraStatus property to determine the start time of a triggered exposure, and the end of an exposure. Returns a pointer (pImageData) to unsigned short data in memory. The data will have (NumX * NumY) elements. Notes Begins clocking and digitization of a single line of data. Poll the CameraStatus property to determine when the data is ready for download. Returns a pointer (pImageData) to unsigned short data in memory. The data will have NumX elements.

GetLine (Long pImageData)

4.1.3 Usage from Visual Basic
Accessing an ActiveX object from Visual Basic is very easy. Start Visual Basic and open the Project menu References command. In the list you will see "Apogee Camera Control Library". Turn on the check box and click OK. Now in the appropriate code section of a Form or Module enter the following:

4.1.3.1 Declaration and Initialization
Dim cam as Camera Set cam = New Camera cam.Init "lisaa.ini" `Declare camera object `Create camera object `Initialize camera

`Now you can then access all Apogee camera functions directly; for example:

28


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

4.1.3.2 Managing Temperature Control
`Initializing the temperature control subsystem cam.SetPoint = 10 cam.CoolerMode = 1 `Set target temperature in degrees C `Turn on cooler

`Updating temperature status (polling) stat = cam.CoolerStatus temp = cam.Temperature `Poll temperature and status. Space polls at least 1 second `apart. Establish rolling average of temperature reads (16 `samples) to reduce read noise.

`Shutting down temperature control subsystem (controlled ramp-up) cam.CoolerMode = 2 `When ramp-up complete (by polling cam.Coolerstatus): cam.CoolerMode = 0 `Turn controller off Only when really necessary.

`Shutting down temperature control subsystem (hard shutdown). cam.CoolerMode = 0

4.1.3.3 Take a normal exposure
cam.Expose 10, true `10 sec exposure with shutter open

do loop until cam.Status = Camera_Status_ImageReady Dim ImageData as Variant ImageData = cam.Image `Can now access image data as a 2D array (i.e. ImageData(100, 100) )

4.1.3.4 Take a dark frame
cam.Expose 10, false '10 sec exposure with shutter closed

do loop until cam.Status = Camera_Status_ImageReady Dim ImageData as Variant ImageData = cam.Image `Can now access image data as a 2D array (i.e. ImageData(100, 100) )

4.1.3.5 Take a TDI (drift scan) exposure
Dim LineData( 1 to NumLines ) as Variant cam.TDI = true cam.Expose drift_rate, true `specify drift_rate in seconds

for i = 1 to NumLines cam.DigitizeLine do loop until cam.Status = Camera_Status_LineReady LineData(i) = cam.Line Next

29


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

4.1.3.6 Take an externally triggered exposure
cam.UseTrigger = true cam.Expose 10, true '10 sec exposure with shutter open

do loop while cam.Status = Camera_Status_Waiting Print "Got Trigger" do loop until cam.Status = Camera_Status_ImageReady Dim ImageData as Variant ImageData = cam.Image `Can now access image data as a 2D array (i.e. ImageData(100, 100) )

4.1.4 Usage from Visual C++
An ActiveX object can be accessed from Visual C++ in many ways. The following example is perhaps the simplest way, taking advantage of VC++ wrapper classes.
// Import the type library to create an easy to use wrapper class #import "apogee.dll" no_namespace ICameraPtr HRESULT cam; hr; // Declare a smart pointer to the camera interface // Return code from ActiveX methods // Initialize COM library

CoInitialize(NULL);

// Create the ActiveX object from the universally unique identifier hr = cam.CreateInstance( __uuidof( Camera ) ); if ( FAILED( hr ) ) return ErrorCode; // ErrorCode must be defined by the application // Open the camera using an ini file _bstr_t inifile( "lisaa.ini" ); hr = cam->Init( inifile, -1, -1 ); if ( FAILED( hr ) ) { cam = NULL; return hr & 0xFF; } // Access properties short CameraXSize = cam->ImgColumns; short CameraYSize = cam->ImgRows; unsigned short* pBuffer = new unsigned short[ CameraXSize * CameraYSize ]; if (pBuffer == NULL ) { cam = NULL; return ErrorCode; } // Take a 10 if ( FAILED( { delete cam = return } sec exposure with the shutter open cam->Expose( 10, true ) ) ) [] pBuffer; NULL; ErrorCode;

while ( true ) { // Wait until the exposure is done and the image is ready if ( cam->Status == Camera_Status_ImageReady ) break; }

30


DEVELOPMENT SPECIFICATION
// Get the image if ( FAILED( cam->GetImage( (long) pBuffer ) ) ) { delete [] pBuffer; cam = NULL; return ErrorCode; } delete [] pBuffer; cam = NULL; CoUninitialize();

APOGEE INSTRUMENTS INC

// This will automatically release the ActiveX object // Close the COM library

4.1.5 Usage from LabVIEW
The Apogee ActiveX DLL can be used within LabVIEW, a graphical programming environment from National Instruments. LabVIEW allows the user to control the camera system through the ActiveX DLL. Apogee does not provide an instrument driver for LabVIEW beyond the Apogee ActiveX DLL. The easiest way to invoke the ActiveX capabilities within LabVIEW is to use LabView as an Automation Client. In this mode, LabVIEW acts as a client, and requests information from the Apogee ActiveX DLL, which is the automation server. First, using your LabVIEW documentation, create an Automation Open Reference. This will allow the ActiveX DLL to be opened. The Automation Reference requires the user to select an ActiveX class in order to operate properly. Choose the option to "Select ActiveX Class" and look at the list of available ActiveX components on the machine. Note that it is not usual for many components to be registered. Select the component labeled "Apogee Camera Control Library." If the "Apogee Camera Control Library" is not present or shown as an ActiveX Class, then the Apogee.DLL has not been installed properly. Please see your installation instructions for proper installation before continuing. Once the reference has been opened, LabVIEW will refer to it in a shortened form, i.e. APOGEELib.ICamera. The partial diagram below shows the Automation Open Reference for an ActiveX control, along with the selection of the Apogee Camera Control Library (APOGEELib.ICamera).

Once the Automation Reference has been opened with the Apogee ActiveX camera control, you can use the Properties and Methods available from the Automation Property Nodes and Automation Invoke Nodes. These Nodes also require an associated ActiveX Class, which should also be set to the Apogee Control (APOGEELib.ICamera). Once this is done, select the appropriate Method or Property you wish to use, and connect to the node to other LabVIEW components as appropriate. The partial diagram below shows a Property Node (Present).

When finished with the Apogee ActiveX Control, make sure to complete operation with an Automation Close Reference. The following diagram is a very simple LabVIEW virtual instrument, which opens an Automation Reference, initializes the camera with the Init method, and then uses the Icamera interfaces to display Before Image Columns/Rows (BIC/BIR) and the X and Y Binning values (BinX and BinY).

31


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

AP O G E ELib . I C a m e r a

e r ro r in ( n o e r ro r)

I C am er a In it in if ile -1 -1 B a s e A ddr es s R e g O ffs e t

I C am er a BI C BI C

I C am er a BI R c : \ a pdr iv er \ i ni\ a c t iv ex \ p c i\ k x 1 e _pc i. in i BI R

I C am er a Bin X Bin X

I C am er a Bin Y Bin Y

For more information regarding LabVIEW usage, as well as specifics of how to use LabVIEW as an Automation Client, please see the documentation provided from National Instruments.

4.2 Generic Class Interface
Normally it is recommended that the included ActiveX driver be used. In cases where custom modification is required to the driver, or ActiveX cannot be used (e.g. non-Microsoft operating systems), the source code can be compiled directly into your application. The "Apogee Driver Source" directory contains the source code. It has been developed under Microsoft Visual C++, but should be portable to other environments with minimal modification. Instead of an ActiveX interface, a set of C++ classes are available: Interface ISA Parallel Port PCI Windows 95/98/ME CCameraIO_ISA_9x CCameraIO_PPI_9x CCameraIO_PCI Windows NT/2000 CCameraIO_ISA_NT CCameraIO_PPI_NT CCameraIO_PCI

These classes are all derived from the base class CCameraIO, which contains code that is common to all cameras. This is a virtual class and cannot be created directly. Also note that the PCI control interface is not supported on Windows 95. 32


DEVELOPMENT SPECIFICATION The following diagram illustrates the software stack for the C++ class interfaces:

APOGEE INSTRUMENTS INC

Apogee Class Library Software Stack
Camera Control Application CCameraIO (Abstract Base Class) CCameraIO_PCI CCameraIO_ISA CCameraIO_PPI (Derived from CCameraIO) (Derived from CCameraIO) (Derived from CCameraIO)
Windows 98/ME/2000 PCI Driver (ApPCI.sys) Windows NT 4.0 PCI Driver (ApogeeIO.sys) Windows 98/ME ISA Driver (Apogee.DLL) Windows NT 4.0/2000 ISA/PPI Driver (ApogeeIO.sys) Windows 98/ME PPI Driver (Apogee.DLL)

Apogee Camera Firmware/Hardware

The class interface is very similar but not identical to the ActiveX interface. Please review the CCameraIO.h header file for a detailed explanation of the interface. The ActiveX Init method is not part of the class interface since it instantiates the derived classes. A generic replacement routine for the Init method, called InitCam is provided along with the actual helper functions (config_load, CfgGet, hextoi and trimstr) called by the Init method to read from the INI file and set the camera default values. These routines can be found in the Camera_Example.cpp file in the Apogee Driver Source directory.

33


DEVELOPMENT SPECIFICATION

APOGEE INSTRUMENTS INC

4.3 Architectural Notes
4.3.1 Read/Write Substitutions for Parallel Port Operation
4.3.1.1 Settings
Parallel ports have particular settings, defined within the .INI initialization files. 4.3.1.1.1 Parallel port type (ECP verses standard Bi-directional) For ECP ports, an additional port setup must be done in order to place the ECP port in standard bi-directional mode. It is suggested to perform this step every time, since it will not hurt a bi-directional port. Prior to communication with the port, the I/O must be converted to bi-directional mode by writing the following value to the port address (defined by .INI file): base + 0x402h, 0x034h. 4.3.1.1.2 PP_Repeat parameter The "pp_repeat" function was created as a .INI file setting to allow for signal settling on long parallel port cables. This function is used in the detailed sequences below to place a time space at critical points.

4.3.1.2 Usage
This API specification assumes that reads and writes are done to a single address. For parallel port operation where we allow multiple cameras on the same parallel port, substitutions should be used to as a replacement to the read and write commands. The following describes the operation of the parallel port interface. The parallel port operation requires a simple 8 bit bidirectional bus. THERE ARE NO CHANGES TO CAMERA OPERATION BEYOND THE READ/WRITE REPLACEMENT ROUTINES DESCRIBED HERE and base address/register locations. The camera uses the port signals as follows; Data Register (Port Base Address) Bits 0-7 ­ 8 bit data to and from camera. All INP and OUTP instructions send 16 bit data to the registers via this port. First Low byte and then High byte. Control Register (Port Base Address + 2) Bit 0 ­ Latch: Used to latch data to camera or bring data from camera. Bit 1 ­ Select/Transfer: When high, data written to port selects a camera register. When low, data written to the port makes data available to the selected register. Bit 2 ­ Read/Write: When high, data is written to registers. When Low, data is read from registers. Bit 3 ­ Low/High: Selects byte to be written or read. When low, high byte is selected. When high, low byte is selected. Bits 5 and 7 ­ Port Output Disable: When high, disables parallel port outputs and allows read functions. The preceding port assignments are used in three routines. These include REGISTER_SELECT, INP AND OUTP. It is assumed that unless explicitly stated, all bits not specifically changing are left at their previous value.

4.3.1.3 REGISTER_SELECT Description
Common to both the INP and OUTP functions, REGISTER_SELECT tells the camera which 16 bit register will be operated on by the INP and OUTP instructions. It also identifies the camera on the bus as defined by the reg_offset parameter in the .INI file (see INI file description). The firmware is preset for a particular offset on the parallel port bus. The Register_select function always precedes a inp or outp function. The byte passed during a register select is defined as follows: 34


DEVELOPMENT SPECIFICATION
Bit 7 Offset bit128 Bit 6 Offset bit64 Bit 5 Offset bit32 Bit 4 Offset bit16 Bit 3 Register bit3 Bit 2 Register bit2

APOGEE INSTRUMENTS INC
Bit 1 Register bit1 Bit 0 Register bit0

Register values selected by the register_select function and described in the bitmap later in this document are as follows: DATA(hex) x0 x2 x4 x6 x8 xa xc xe x0 x2 x6 x8 REGISTER 1 2 3 4 5 6 7 8 9 10 11 12 FUNCTION Misc Commands ­ write only Lower Timer ­ write only Upper Timer/Vbin ­ write only AIC Counter ­ write only Temp/Relay ­ write only Pixel Counter ­ write only Line Counter ­ write only BIC Counter ­ write only FIFO Data ­ read only Desired Temperature ­ read only Status Register ­ read only Register 1 Mirror ­ read only

Offset values selected by the register_select function and defined by the reg_offset command in the .INI file are as follows: DATA(hex) 1x 2x 4x 8x FUNCTION Reg_offset=16 Reg_offset=32 Reg_offset=64 Reg_offset=128

4.3.1.4 Detailed Parallel I/O sequences
4.3.1.4.1 a. b. Register_Select

Write the following bits to the control register (Base +2). C0=low, C1=high, C2=high, C3=high, C5=low, C7=low. Write 8 bit camera register selection to Data port (Base Address). Valid values are:

Repeat "c" as many times as "pp_repeat=" specifies c. Write the desired register_select bits to the control register (Base +2). C0=high d. e. Write the following bits to the control register (Base +2). C0=low Write the following bits to the control register (Base +2). C1=low. O UT P

4.3.1.4.2 a. b.

Write the following bits to the control register (Base +2). C0=low, C1=low, C2=high, C3=high, C5=low, C7=low. Write low byte to Data port (Base Address).

Repeat "c" as many times as "pp_repeat=" specifies c. Write the following bits to the control register (Base +2). C0=high d. e. f. Write the following bits to the control register (Base +2). C0=low Write the following bits to the control register (Base +2). C3=low Write high byte to Data port (Base Address).

Repeat "g" as many times as "pp_repeat=" specifies g. Write the following bits to the control register (Base +2). C0=high

35


DEVELOPMENT SPECIFICATION h. Write the following bits to the control register (Base +2). C0=low INP

APOGEE INSTRUMENTS INC

4.3.1.4.3 a. b.

Write the following bits to the control register (Base +2). C0=low, C1=low, C2=high, C3=high, C5=high, C7=high. Write the following bits to the control register (Base +2). C2=low

Repeat "c" as many times as "pp_repeat=" specifies c. Write the following bits to the control register (Base +2). C0=high d. e. f. Read low byte from Data port (Base Address). Write the following bits to the control register (Base +2). C0=low Write the following bits to the control register (Base +2). C3=low

Repeat "g" as many times as "pp_repeat=" specifies g. Write the following bits to the control register (Base +2). C0=high h. i. j. k. Read Write Write Write high byte from Data the following bits to the following bits to the following bits to port the the the (Base Address) control register control register control register . (Base +2). C0=low, (Base +2). C2=high (Base +2). C3=high.

36