Kodak Alaris Inc. KDS TWAIN Driver
Simulator for Virtual Integration
11-November-2013
Contents
1. Overview...................................................................................................................... 3
2. Glossary of Terms......................................................................................................... 4
3. Simulate Setting............................................................................................................. 5
3.1. Version 2/3/4 TWAIN Drivers.................................................................................. 6
3.2. Version 5+ TWAIN Drivers...................................................................................... 7
3.2. Version 9.x+ TWAIN Drivers................................................................................... 8
4. RAMSCAN.TXT File................................................................................................... 9
4.1. Command Format..................................................................................................... 10
4.2. @check.................................................................................................................... 11
4.3. @delay................................................................................................................... 13
4.4. @image.................................................................................................................. 14
4.5. @init....................................................................................................................... 16
4.6. @jam...................................................................................................................... 17
4.7. @multifeed.............................................................................................................. 18
4.8. @nodata................................................................................................................. 19
4.9. @patch................................................................................................................... 20
4.9.1. @patch #............................................................................................................ 21
4.9.2. @patch toggle..................................................................................................... 22
4.10. @repeat label count............................................................................................ 23
4.11. @restart.............................................................................................................. 24
4.12. @stop................................................................................................................. 25
The session simulator mimics events that occur in a real session with a Kodak Alaris Inc. Document Scanner. It allows the logging system to record the exact commands that would be sent to a physical scanner, and as a result of this allows an application to get a good feeling for how a physical scanner behaves; especially during the negotiation phase prior to scanning.
The simulator is appropriate as a tool to exercise developing applications without a physical scanner, especially if the application writer is interested in testing against several models. Using the simulator frees the programmer from the bulk of a physical scanner in the early phases of development. We always recommend full testing with a physical scanner, but believe that the integration time will be shorter and the process more smooth when the simulator is used.
The simulator also serves as a diagnostic tool. It can be used to precisely recreate specific conditions (like errors) that may be hard to duplicate with a physical scanner. When combined with the debugging features of the driver it becomes possible to easily analyze most situations.
Here are some terms used in the document.
A2O2 - Family name for the i1400 scanners
Gemini - Family name for the 500/900/923/990/55xx/75xx/95xx scanners
Viper - Family name for the 35xx/4500 scanners
Phoenix - Family name for the i6xx scanners
Inferno - Family name for the i7xx scanners
Prism - Family name for the i8xx scanners
Alien - Family name for the i2xx scanners
Mustang - Family name for the i30/i40/i50/i60 scanners
Fosters - Family name for the i1100 scanners
Piranha - Family name for the i1200/i1300 scanners
Wildfire - Family name for the i1800 scanners
Panther - Family name for the i4000 scanners
Piranha2 - Family name for the i2000 scanners
Blaze - Family name for the i5000 scanners
Rufous - Family name for the i900 scanners
Falcon - Family name for the i2900 (FalconA4) and i3000 (FalconA3) scanners
Saturn - Family name for the i1150 and i1180 scanners
In the ramscan.txt file, set simulate to the desired value (ex: simulate i280).
The simulator is activated by going into the ramscan.txt file, and changing the simulate value to the full model name of the desired scanner. The default value is 0. Valid values are found in the ramscan.txt file. Each driver is only intended to support certain kinds of scanners. The name of the TWAIN directory is a good clue about what is supported. For instance, if the directory path to the TWAIN driver is %windir%\twain_32\kodak\kds_i800, then the supported scanners are: i810, i820, i830 and i840.
In the const.ini file, under [dsIdentity], set simulate to the desired value (ex: simulate i660).
The simulator is activated by going into the const.ini file, and changing the simulate value to the model name of the desired scanner. The default value is 0. Valid values are found in the ramscan.txt file. Each driver is only capable of supporting certain kinds of scanners. The name of the TWAIN directory is a good clue about what is supported. For instance, if the directory path to the TWAIN driver is %windir%\twain_32\kodak\kds_i800, then the support scanners are: i810, i820, i830 and i840. The ramscan.txt file is the final authority on what is supported in simulation mode.
In the const.ini file, under
[Simulation], set simulation to true to enable simulation. Set simmodel to the
desired ADF scanner model (ex: i2900).Set simflatbed to the desired
flatbed accessory (ex: i2000legal).
For example to simulate a FalconA3 scanner with attached KODAK Legal Size Flatbed Accessory:
[Simulation]
simulation=true
simmodel=i3000
simflatbed=i2000legal
This file owns the configurations that describe the supported scanners. For instance, if a user wants to simulate an i260 without a printer, they can go into this file, find the setting for the printer accessory and turn it off. The simulator will then run like an i260 that has no printer. By default the virtual scanners are simulated with all available accessories.
The ramscan.txt is also able to simulate a wide range of scanning behavior, which is accomplished via the @-commands at the end of the file. For example:
@init
@image
@image
@stop
This sequence initializes the simulator and allows two ‘images’ to be captured before ending the session. The word ‘image’ isn’t ideal, it actually corresponds to a side of a sheet of paper, so if this particular sequence was used with dualstream settings (simultaneous output of bitonal/color on the front and rear) then we’d get four images in total from the two @image commands.
The format of any given command is as follows:
@command.platform arguments
Where
@command is the command to be issued.
.platform is an optional specifier for one of the following:
Gemini, Viper, Prism, Alien
arguments are any data for the command
For example:
@image
@jam.Prism
@stop
The full list of available commands follow:
This command generates an error during a session. Typically the value is dotted with the targeted command. If a dot isn’t specified, then the check is applied to any command. @check is platform dependent, meaning that the error codes have meaning for particular platforms. For instance, this is the list of jam conditions for all the scanner platforms.
@check.ReadHeader.Gemini F0 00 04 00 00 00 00 0A 00 00 00 09 82 00
@check.ReadHeader.Viper F0 00 04 00 00 00 00 0A 00 00 00 09 3B 05
@check.ReadHeader.Prism F0 00 04 00 00 00 00 0A 00 00 00 09 3B 05
@check.ReadHeader.Alien F0 00 04 00 00 00 00 0A 00 00 00 09 3B 05
The underlined values are the only ones that have any meaning for the simulator. All numbers are hexadecimal. If necessary, an SRB status can be added as an extra number at the end of the list to simulate errors from the SCSI/SBP2 Class Drivers. A list of these codes are wire/protocol specific, and can be found in ASPI’s wnaspi.h file or SCSISCAN’s scsiscan.h file. The check codes come from the SCSI Interface Spec for each of the supported scanner models, usually they will be obtained from a KDS.LOG.
@check has become increasingly sophisticated as time has gone on. Most users will not need this additional behavior, but here it is anyway.
@check without a specifier is applied to any attempt to get an image (the @image command) and is position sensitive in the simulation. @check with a specifier is used to target a specific scanner command and is NOT position specific within the simulation. We’ll use examples to illustrate this.
; Jam with one image in the scanner buffer
@init
@image
@jam
@image
@stop
; Jam with one image in the scanner buffer
@init
@image
@check F0 00 04 00 00 00 00 0A 00 00 00 09 3B 05
@image
@stop
; Jam with two images in the scanner buffer
@init
@image
@check.ReadHeader F0 00 04 00 00 00 00 0A 00 00 00 09 3B 05
@image
@stop
Note that the third example will throw its jam message before reading any images from the scanner. If we want to target a specific occurrence of a command, then we have to get somewhat fancy. The following example will give us the result we want. We’ve moved the check conditions to the top, since it doesn’t matter where they are located.
; Jam with two images in the scanner buffer
@init
@check.ReadHeader 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@check.ReadHeader F0 00 04 00 00 00 00 0A 00 00 00 09 3B 05
@image
@image
@stop
The simulator ignores any check condition that is all zeros. Here is a list of the current supported commands that can be checked.
@check - @image command
@check.Enable - Enable scanner
@check.GetWindow - SCSI Get Window
@check.SetWindow - SCSI Define Window
@check.ReadHeader - Gemini Read Header
@check.ReadImage - Read Image
@check.ReadLength - Viper Read Length
@check.ReadBitdepth - Viper Read Bitdepth
@check.ReadSide - Viper Read Side (not currently used)
@check.XX - XX == scanner unique command, like SC for Scan Configuration
Not all commands are supported, but many of them are. Note that the text is case sensitive, and the simulator isn’t very tolerate of whitespace, so only use single spaces to separate items.
Pauses the driver for the specified number of milliseconds; for example:
@delay 1000
Generates or specifies an image to the simulator. This command comes in several forms:
@image
@image 1280 1692 1 0 250 c:\twain\bitonal.tif
@image 640 848 24 6 0 c:\twain\color.jpg
@image 1280 1692 1 0 250 c:\twain\bitonal.tif 640 848 24 6 0 c:\twain\color.jpg
The first form is the easiest to use. The simulator will generate an image meeting the following characteristics of the negotiated session: cropping, compression, polarity (if appropriate) and pixel type. The image is largely blank with a horizontal line at the top and the bottom, and with a counting image number in each of the four corners. The line is always black. The first three digits of the number (reading left to right) should always be red/green/blue if the image is in color.
The second and third forms show how to use an image file from disk. The arguments are, in order:
width - in pixels
height - in pixels
bitdepth - 1=bitonal, 8=grayscale, 24=color
compression - 0=none, 2=Group 31D, 4=Group 32D, 5=Group 4, 6=JPEG
offset - byte offset to the raw image data
filename - the full path to the image
The offset is always 0 for JPEG/JFIF images. It corresponds to the StripByteOffset for TIFF images, and skips over the file header, bitmap header, and color table (if any) for bitmap images. Any image format is permissible, provided that the data can be handled by the simulator as a single block for data. Stripped TIFF images are not supported. If for any reason the @image requested doesn’t match the image values negotiated with the driver (for example, if the file is uncompressed, but ICAP_COMPRESSION is TWCP_JPEG), then the simulator falls back to the first form, discarding the file info. The version 4+ drivers report the reason for the failure in the KDS.LOG file (though it may be necessary to set Debug=1 to get the information).
The third form is a combination of bitonal and color, and can be used to provide two images for dualstream scanning for i600/i800/i1800. The order of the images in the @image does not matter; the simulator will grab the appropriate one needed to match the requirements of the CAP_CAMERAORDER capability.
Note that dualstream for the 3590/4500/i30/i40/i200 scanners always comes from a single (or grayscale) color image generated by the scanner.
One final note, for most of the scanners it is possible to generate the input images used by the simulator in a variety of ways: using image editing packages or scanning them in from other scanner models. For instance, it is possible to scan JPEG images on a KODAK 4500 Scanner and use them in simulations for a KODAK i840 Scanner. This is not true for the KODAK i200 Scanners, these devices output image data in YCC411 format, the simulator must receive the data in this same format to perform properly. Likewise the KODAK i600/i1800 Scanners output uncompressed color in YCC444 format. In both cases the best way to generate the needed images is to capture data from an existing scanner. The Scanner Validation Tool (SVT) has a raw dump feature on the Dump tab (which only appears if you have a Level-1 or higher License); it is also possible to get this tab through the CONST.INI file, please contact Kodak Alaris Inc. for information about how to do this. This dump is capable of generating the needed images along with a fragment of a ramscan.txt file to help set up the simulation.
This has to be the first command in any sequence of @-commands in the ramscan.txt file. The simulator uses it as the reset point so that it is possible to run multiple scanning sessions without exiting from the application.
Indicates that a paper jam check condition is to be thrown before the next command is read, this command is position sensitive, so the following two lists will throw the check condition at different points in the simulation.
; Jam with two images still in the scanner buffer.
@init
@jam
@image
@image
@stop
; Jam with no images in the scanner buffer.
@init
@image
@image
@jam
@stop
Indicates that a multifeed check condition is to be thrown before the next command is read, this command is position sensitive, so the following two lists will throw the check condition at different points in the simulation. Note that the inclusion of @multifeed will result in the generation of the check condition no matter what the current settings are on the TWAIN Multifeed tab.
; Multifeed with two images still in the scanner buffer.
@init
@multifeed
@image
@image
@stop
; Multifeed with no images in the scanner buffer.
@init
@jam
@image
@image
@multifeed
@stop
The 5000/7000/9000 scanners do not support a clear buffer command, so the only way to guarantee that the buffers are empty prior to scanning is to read out any images from the buffers and discard them. The i200 requires a test to make sure the camera is homed. And the i600/i1800 needs a way to wait until the elevator is homed. We use @nodata.Gemini or @nodata.Prism to consume these read image instruction so that the @image commands are not accidentally included.
The patch page command causes the simulator to behave as if a patch has been seen by the scanner.
For the 5000/7000/900/i800 this command causes the scanner to report the presence of a patch page (1 – 6). Since the image address simulation isn’t very sophisticated, this part of the simulation is most useful when trying to generate feature patches that the application has to handle.
For the 3590/4500/i200/i600/i800/i1800 this command tells the simulator to toggle back and forth between bitonal and grayscale/color output.
@init
@image
@patch toggle
@image
@stop
This command is only available for Version 4+ of the TWAIN driver. There are times when it is desirable to repeat a sequence of commands many times. The typical case is scanning several hundred or several thousand images. This command allows the construction of a repeat loop.
@init
@:label
@image
@repeat label 5
@stop
This loop will generate five @image commands to the simulator. Note the use of the colon ( : ) before “label” to mark the topmost point in the loop. Repeat loops can be nested.
This is the command that preceded @repeat. All it does is move the simulation reader back to the top of the file. Version 2/3 drivers can use it, newer ones should not.
This command indicates the End-Of-Job condition (for 5000/7000/9000/i30/i40/i200/i600/i800/i1800) and the transport timeout / disabled state for 3000/4000. It must be at the end of any sequence of @image commands.