                       :CUE:CAT BARCODE READER SOFTWARE
                       --------------------------------
                                    v0.0.8
                                    ------

                   Pierre-Philippe Coupard <pierre@lineo.com>
                                   31/08/00



The :Cue:Cat is a small barcode reader that connects to a standard PS/2
keyboard port. It is a very cheap little device that can, nonetheless, read
many types of bar codes. It is manufactured by DigitalConvergence
(http://www.digitalconvergence.com/). The main advantage of the :Cue:Cat is that
RadioShack has recently decided to give one away to anybody who requests it, for
the purpose of tying their paper catalog to their website. By the way, I reckon
you should rush to RadioShack to get a free barcode reader before they realize
nobody cares about them apart hackers and tech freaks :)

Anyway, what's free is good, and the device works great despite its cheapo
appearance.



1 - How to compile and use read_cuecat :

Simply type "make" and the program should build. It is a very simple program
so there shouldn't be any problem. The only real issues are console-related
ioctl calls and such.

NOTE : read_cuecat does NOT work under X. Bad things may happen if you run
       read_cuecat as root under X. Instead, you should run read_cuecat in
       a plain text console.



2 - What the :Cue:Cat send to the keyboard port when it has read a barcode :

The format is fairly simple, if bizarre :

<HEADER>.<CUECAT DEVICE ID>.<BARCODE TYPE CODE>.<BARCODE...>.<CR>

The header is simply the scancodes corresponding to ALT-F10 on a standard US
keyboard : 0x38, 0x44, 0xc4, 0xb8.

All characters transmitted by the CueCat are of the form :

[<SHIFT PRESS>] <ALNUM KEY PRESS> <ALNUM KEY RELEASE> [<SHIFT RELEASE>]

where ALNUM is a key scancode corresponding to 0->9 thru a->z, or '+' or '-' on
a standard US keyboard.

The CueCat device ID is a 18 character string, the barcode type is a 4 character
string, and the barcode can be any length.

Here is the explanation from Colin Cross about of how the CueCat encodes the
data representing the CueCat ID, the barcode type and the barcode itself :

--8<--8<--SNIP-SNIP--8<--8<--
The encoding is a base64 (not MIME tho) with a random XOR thrown in.  Each 
letter is a base 64 (6 bit) number, a is 0, z is 25, A is 26, Z is 51, 0 is 
52, 9 is 61, + is 62, - is 63 (and fill in the blanks between there).  A group 
of four of these 6 bit numbers are combined into a single 24 bit number, which 
is then split into three 8 bit ASCII codes (XORed with 67).

Taral corrected my first perl script to solve the short code problem.  If a 
group of 4 characters is not complete (ie there are only 2 characters), it 
should be padded with 0's ('a' in the base64 encoding), and then follow the 
same decoding process.  Then chop off the same number of characters from the 
decoded string that were padded onto the encoded string.

No tables/codes should be used anywhere - it is simply a coincidence that they 
work for numeric values, because the top 4 bits of all the number ASCII codes 
are the same, 0011 binary.
--8<--8<--SNIP-SNIP--8<--8<--

Example : The following coded CueCat device ID :

C3nZC3nZC3nYChj1C3D7CxnX

translates into :

000000001316048202

The barcode type indicates what kind of barcode the CueCat just read, like
"IBN" for ISBN, "UPA" for UPC-A, etc ...

NOTE : if you have a minute, could you tell me of any type of barcode that you
       have scanned with your CueCat, and what you know (or reckon) it means ?
       My email address is pierre@lineo.com. In return, I'll put you on my
       mailing list of people who will new versions of the driver immediately :)



3 - How to use the CueCat kernel driver

A patch against linux-2.2.16 is supplied. After many requests, here's the detail
of the kernel patching procedure (you need to be root) :

#cd ${HOME}
#tar -zx < cuecat-0.0.4.tar.gz
#cd /usr/src/linux
#patch -p1 < ${HOME}/cuecat-0.0.4/cuecat-linux-2.2.16.patch

Then, when you invoke

#make menuconfig

you should get 2 new options :

Support for :Cue:Cat barcode reader
  :Cue:Cat driver enabled by default

in the "character devices" section. Select the first one. If you don't select
the second one, also make sure "proc filesystem support" is enabled, then exit
and recompile by invoking :

#make dep && make bzImage

Then, create a "/dev/cuecat" device file by invoking :

mknod /dev/cuecat c 66 0

Then, reboot your new kernel.

If the CueCat driver is disabled by default (i.e. characters from the barcode
scanner will go throught as if the driver wasn't there), you need to enable it
by invoking :

#echo CC=1 > /proc/cuecat

You can now read /dev/cuecat : as soon as the driver decodes a barcode, it
sends a text line containing the CueCat device ID, the type of barcode and the barcode itself on /dev/cuecat.

If you want to be able to see the raw characters sent by the CueCat, or you
want to test the userland program, you can disable the driver again by
invoking :

#echo CC=0 > /proc/cuecat

NOTE : the CueCat driver cannot be compiled as a module
NOTE : if the driver is not enabled by default, it requires the /proc
       filesystem, otherwise it will never be enabled
NOTE : I chose major 66 for the CueCat driver, out of ignorance, because it
       looked free on my box. If this bother you in any way, please feel free
       to change it :)



4 - Known bugs

None



5 - Other people and projects for the CueCat device, and information about
    barcodes

UScan Bar Code Scanning system :      http://sourceforge.net/projects/uscan/
A Web Of Information About Bar Code : http://www.adams1.com/pub/russadam/
Colin Cross' decoding perl script :   http://www.mit.edu/~colin/cat.pl
Taral's homepage :                    http://ccwf.cc.utexas.edu/~taral/
Mirror for the CueCat driver :        http://www.flyingbuttmonkeys.com/cuecat/

Please feel free to send me any comment, suggestion, patch, ... that you may
have.



6 - LEGALESE

This software is released under the terms of the General Public License. See
the "COPYING" file for details.

Oh, and yes, I forgot :

DISCLAIMER :

I am not responsible for any damage caused by this software, whether it's on
your computer, your CueCat, or if it wipes out your hard-drive, or if it sets
off a nuclear bomb, etc ...
