METROLOGIC INSTRUMENTS, INC.
Copyright © 2008 by Metrologic Instruments, Inc. All rights reserved. No part of this work may be reproduced, transmitted, or stored in any form or by any means without prior written consent, except by reviewer, who may quote brief passages in a review, or provided for in the Copyright Act of 1976. Trademarks Metrologic is a registered trademark of Metrologic Instruments, Inc. Products identified in this document are hereby acknowledged as trademarks, registered or otherwise, of Metrologic Instruments, Inc.
TABLE OF CONTENTS IS4910 SYSTEM HARDWARE ARCHITECTURE ................................................................................................... 1 OVERVIEW OF THE IS4910 SOFTWARE COMPONENTS IS4910 Device Driver and Its Configuration Parameters .......................................................................... 3 Minimum and Maximum Illumination Times ......................................................................................... 4 Image Sensor Gain..................................
TABLE OF CONTENTS Window of Interest.............................................................................................................................. 11 camSetCenteredWOI.....................................................................................................................................12 camSetWOI ...................................................................................................................................................12 camGetWOI .......................
TABLE OF CONTENTS Aiming APIs ............................................................................................................................................. 22 camTurnAimingOn.............................................................................................................................. 22 camTurnAimingOff.............................................................................................................................. 22 camGetAimingStatus............................
IS4910 SYSTEM HARDWARE ARCHITECTURE Figure 1: IS4910 System Hardware Architecture Communication with the image sensor is done over two buses – the control bus (I2C) and the data bus. The control bus is used to send commands to the image sensor, and the data bus is used to transfer images from the image sensor to the host system. The image sensor can operate in two modes – snapshot mode and video mode. • In snapshot mode, the image sensor acquires and transfers a single image.
OVERVIEW OF THE IS4910 SOFTWARE COMPONENTS The IS4910 camera engine cannot operate on its own and must be supported by the underlying hardware and software systems. The IS4910 user system software architecture is shown on Figure 2. Figure 2: IS4910 User System Architecture Metrologic is currently targeting user systems that run Microsoft Windows CE® operating system. Metrologic is fully supporting an Intel PXA270 processing platform.
OVERVIEW OF THE IS4910 SOFTWARE COMPONENTS IS4910 Device Driver and Its Configuration Parameters IS4910 Device Driver is a software component that does all the physical communications with IS4910 camera device. It is pre-compiled as a DLL (vuqdrv.dll) for Windows CE OS and a particular processing platform and must be properly installed on the target device – please refer to the software installation instructions below in this document.
OVERVIEW OF THE IS4910 SOFTWARE COMPONENTS Minimum and Maximum Illumination Times These values, specified in microseconds, control the IS4910 illumination system in the snapshot mode. The minimum illumination time specifies the minimum time the illumination flash should last when the camera is operating in the snapshot mode. The maximum illumination time specifies the maximum time the illumination flash should last when the camera is operating in the snapshot mode.
OVERVIEW OF THE IS4910 SOFTWARE COMPONENTS Data Readout Order ReverseRows and ReverseCols entries in the VuQuest2D.ini file provide information on whether the pixel read-out order for the image sensor rows and columns respectively should be reversed. The specified value can be either 0 (FALSE) or 1 (TRUE). By default, both values are set to 0 (FALSE), meaning that the read-out orders are not reversed.
INSTALLING IS4910 SOFTWARE Installation of the IS4910 software is a two-stage process. In the first stage, the IS4910 software development kit (SDK) must be installed on a Windows PC. To perform the first-stage installation, insert the IS4910 CD into the CD drive of the Windows PC and follow the on-screen instructions. (If the autorun feature is disabled on your Windows PC, run setup.exe from the root directory on the CD.
INSTALLING IS4910 SOFTWARE Easy Downloading Using Device Setup Tool and MS ActiveSync Connection The easiest way to download software to the target device is to use the installation program "Device Setup Tool", which is installed on the host Windows PC during the first-stage installation of the IS4910 SDK. To download IS4910 software to the target device using Device Setup Tool, follow this procedure. 1. Make sure that Microsoft ActiveSync software is installed on your Windows PC.
INSTALLING IS4910 SOFTWARE Manual Downloading Using MS ActiveSync Connection Alternatively to using the Device Setup Tool, the IS4910 target device-specific software components can be manually transferred to the target device by following the procedure described below. 1. Make sure that Microsoft ActiveSync software is installed on your Windows PC.
CAMERA SUPPORT LIBRARY CAMLIB The IS4910 Camera Support Library CamLib provides convenient interface between an application and the IS4910 Device Driver. The library is available in two versions: static library (camlib.dll) and dynamiclink library (camdll.dll). Both versions provide exactly the same set of high-level APIs to acquire images, program, re-program or inquire the status of the camera device. The library APIs are defined in the camlib.h header file.
CAMERA SUPPORT LIBRARY CAMLIB camOpen This function establishes communication with the specified camera device. Note: The target OS must support the MultiByteToWideChar function in order for the camera support library to open the device driver properly. Prototype: int camOpen (char *device_name, char *ctl_bus_name, int *p_dev_type); Parameters: device_name - [in] must be a valid IS4910 camera device name registered in the operating system.
CAMERA SUPPORT LIBRARY CAMLIB Clocks The IS4910 camera has the master and pixel clocks. The master clock provides the image sensor with the input clock. The pixel clock used by the host system to sample the sensor data. The master clock is provided by the onboard oscillator and its frequency is 48 MHz. Allowed pixel clock frequencies on PXA270 platform are: 12 and 24 MHz. By default, if not specified otherwise in the IS4910 device driver initialization file VuQuest2D.
CAMERA SUPPORT LIBRARY CAMLIB camSetCenteredWOI This function sets the window of interest (WOI) of the given size centered horizontally and vertically in the field of view of the camera. Prototype: int camSetCenteredWOI (int cam_handle, int img_width, int img_height); Parameters: cam_handle img_width img_height - [in] handle to the camera device returned by the camOpen function. - [in] image width, in pixels (should be a multiple of 16, the maximum value is 1280).
CAMERA SUPPORT LIBRARY CAMLIB camGetImageSize This function returns the size of the window of interest (WOI). Prototype: int camGetImageSize (int cam_handle, int *img_width, int *img_height, int *num_bytes_per_row); Parameters: cam_handle - [in] handle to the camera device returned by the camOpen function. img_width - [out] image width, in pixels. img_height - [out] image height, in rows. num_bytes_per_row - [out] If not NULL, number of bytes in one row of pixels.
CAMERA SUPPORT LIBRARY CAMLIB Parameters: cam_handle gain - [in] handle to the camera device returned by the camOpen function. - [out] the gain value, in dB. Can be in the range from 0 to 24 dB. Return Value: 0: Success; -1: Failure camSetAutoGainRange_db This function sets the minimum and maximum boundaries for the gain value during an execution of the automatic brightness adjustment, see the function camAdjustBrightness() for more details.
CAMERA SUPPORT LIBRARY CAMLIB For the purposes of automatic brightness adjustments, an application can specify the minimum and maximum boundaries for the image integration time. By default, the minimum image integration time is set to 10 µs and the maximum is set to 8000 µs. If the camera is running in the video mode, it must be stopped or paused before changing the image integration time. To change the boundaries for the image integration time, the camera must be stopped.
CAMERA SUPPORT LIBRARY CAMLIB camGetAutoExpoRange This function returns the minimum and maximum boundaries for the image integration time during an execution of the automatic brightness adjustment, see the function camAdjustBrightness() for more details. Prototype: int camGetAutoExpoRange (int cam_handle, long *min_time_µs, long *max_time_µs); Parameters: cam_handle - [in] handle to the camera device returned by the camOpen function.
CAMERA SUPPORT LIBRARY CAMLIB Parameters: cam_handle - [in] handle to the camera device returned by the camOpen function. reverse_left_right - [out] 0 if normal readout from left to right, or 1 if inverted. reverse_top_bottom - [out] 0 if normal readout from top to bottom, or 1 if inverted. Return Value: 0: Success; -1: Failure Illumination The IS4910 camera has an integrated illumination system. In the snapshot mode of operation, the minimum and maximum illumination flash time can be specified.
CAMERA SUPPORT LIBRARY CAMLIB Prototype: int camSetMinFlashTime(int cam_handle, long min_time_µs); Parameters: cam_handle min_time_µs - [in] handle to the camera device returned by the camOpen function. - [in] minimum illumination time, in microseconds. Return Value: 0: Success; -1: Failure camGetMinFlashTime This function returns the minimum illumination flash time for the snapshot mode of camera operation.
CAMERA SUPPORT LIBRARY CAMLIB camAcquireImage This function performs an image acquisition and delivers the image data to the application. If called when the camera is running in the video mode, the function delivers the image of the most recent video frame.
CAMERA SUPPORT LIBRARY CAMLIB Parameters: cam_handle - [in] handle to the camera device returned by the camOpen function. image_buf - [out] image data buffer (optional in the video mode). image_buf_size - [in] image data buffer’s size, in bytes (optional in the video mode). frame_offset - [out] if not NULL, the frame offset, in bytes, starting with 0. Return Value: 0: Success; -1: Failure camStartVideo This function turns the camera into video mode.
CAMERA SUPPORT LIBRARY CAMLIB camStopVideo This function stops video mode and turns the camera back into snapshot mode. Prototype: int camStopVideo (int cam_handle); Parameters: cam_handle - [in] handle to the camera device returned by the camOpen function. Return Value: 0: Success; -1: Failure camPauseVideo This function pauses the video mode. The video mode can be resumed by calling camResumeVideo().
CAMERA SUPPORT LIBRARY CAMLIB Aiming APIs The camera’s aiming system can be turned on or off by calling camTurnAimingOn() or camTurnAimingOff() respectively. Note, however, that even if the aiming is turned on, the function camStartVideo() turns the aiming off until the video is stopped. camTurnAimingOn This function turns the IS4910 camera’s aiming system on. Prototype: int camTurnAimingOn (int cam_handle); Parameters: cam_handle - [in] handle to the camera device returned by the camOpen function.
CAMERA SUPPORT LIBRARY CAMLIB Automatic Brightness Adjustment APIs The set of automatic brightness adjustment APIs allows an application to automatically adjust the camera’s gain and image integration time based on the quality of the previous images. camAdjustBrightness This function adjusts the IS4910 camera’s gain and/or image integration time (exposure) based on the known quality of the last image and the desired correction, in dB, to this quality.
CAMERA SUPPORT LIBRARY CAMLIB The flags parameter indicates whether the gain and/or image integration time (exposure) are allowed to be adjusted, and whether the new values should be applied to the camera immediately after taking the current image or postponed until and applied upon the next image acquisition. Note that in the snapshot mode adjustment of the image integration time is not allowed regardless of the flags parameter. By default, the automatic brightness adjustment is disabled.
IS4910 DEVICE DRIVER The device driver is a software component that provides the low-level interface between operating system and the IS4910 camera module. It is strongly recommended that the applications use CamLib APIs to communicate with the IS4910 camera instead of calling the IS4910 Device Driver directly. The CamLib APIs provide an easier and more convenient way of communicating with the camera.
IS4910 DEVICE DRIVER Registry Settings The registry settings allow to load and to configure the driver. The driver must be properly configured on the target device in order to work properly. For that purpose the driver reads the configuration parameters from the registry during loading.
IS4910 DEVICE DRIVER Value Type Description GPIO_CIF_FV DWORD Specifies the GPIO pin connected to the “VSYNC” signal. If it’s not specified the driver fails to load. GPIO_CIF_LV DWORD Specifies the GPIO pin connected to the “HSYNC” signal. If it’s not specified the driver fails to load. GPIO_CIF_PCLK DWORD Specifies the GPIO pin connected to the “PCLK” signal. If it’s not specified the driver fails to load. GPIO_CIF_DD0 DWORD Specifies the GPIO pin connected to the “D0” signal.
IS4910 DEVICE DRIVER Value Type Description (Optional) Defines the polarity (active “high” or “low”) of the “Trigger” signal. Allowed values are 1 (normal polarity, active “high”) and 0 (inverted polarity, active “low”). Default is 1 (normal polarity, active “high”). (Optional) Defines the polarity (active “high” or “low”) of the “Illum_ON” signal. Allowed values are 1 (normal polarity, active “high”) and 0 (inverted polarity, active “low”). Default is 1 (normal polarity, active “high”).
IS4910 DEVICE DRIVER Power Management The driver supports the standard power management interface PMCLASS_GENERIC_DEVICE used by the Power Manager under Windows CE to query the power capabilities of the device and to control its state.
APPENDIX A: DRIVER REGISTRATION APPLICATION The driver registration application allows to install or to uninstall the IS4900 device driver into the operating system running on the target device. It is a simple console application. The installed device name is constructed from the VUQ prefix appended the index number. On success the application exits with zero value, otherwise the exit code is the system error value.
APPENDIX B: IS4910 DRIVER INITIALIZATION FILE The IS4910 Driver initialization file VuQuest2D.ini contains the driver configuration settings.
APPENDIX B: IS4910 DRIVER INITIALIZATION FILE Index (optional) defines the instance number of the device and can be a single decimal digit starting from 1 (first instance) to 9 (ninth instance) and 0 (tenth instance). The Index number is appended to the VUQ prefix to construct the device name. Default is 1. DLL specifies the name of the DLL that implements the driver (vuqdrv.dll). Path specifies the full path to the DLL that implements the driver.
APPENDIX B: IS4910 DRIVER INITIALIZATION FILE Gain1000 (optional) defines the image sensor absolute gain multiplied by 1000. It ranges from 1000 (Gain = 1 or 0 dB) to 1600 (Gain = 16 or 24.08 dB). Default is 1000 (Gain = 1 or 0 dB). PixelClock (optional) defines the image sensor pixel clock frequency, in Hz. Allowed values are 12000000 Hz and 24000000 Hz. Default is 24000000 Hz. I2CBusClock (optional) defines the I2C bus transfer rate, in Hz.
APPENDIX C: DEMO APPLICATION The demo application CamTest is simple and easy to use. Just follow the on-screen instructions. The Push me button starts/stops or continues image acquisition and real-time displaying. The currently displayed image can be stored in BMP file (\My Documents\My Pictures\vuq.bmp) by pressing the Save button. The application main window is implemented as a modal dialog window. Therefore, there is no window message loop in the WinMain() function.
35
January 2008 Revision 2.