CueAct CueCat <-> Internet linker
v0.1.1
------
Pierre-Philippe Coupard <pcoupard@easyconnect.fr>
29/05/03
1 - What is CueAct ?
CueAct is a userspace utility that takes advantage of the Linux CueCat driver. Its purpose is to exploit barcodes read by a CueCat reader, and decoded by the CueCat driver, by performing an action of interest associated with the barcode swiped (the most obvious being to link a barcode with a suitable database to look up in no time the information relevant to that barcode).
The actions performed by CueAct are fully configurable.
2 - What is upce2upca ?
upce2upca is a companion utility for CueAct. Its function is to expand a UPC-E barcodes into UPC-A format. UPC-E barcodes really are UPC-A barcodes with a bunch of zeros taken out to make them smaller. They are usually found of commercial items where printing space is at a premium, such as soda cans. With upce2upca, CueAct can exploit UPC-E barcodes with programs or websites that only understand the standard UPC-A format.
3 - What is xautotype ?
xautotype is a very simple X application that takes a string as argument and sends it to the X application currently in focus "as if it was entered on the keyboard". As a companion utility to CueAct, it is useful to automatically "type" a barcode in an editor, or fill out a field in a web form with a barcode, for example.
4 - Compiling and installing CueAct, upce2upca and xautotype
In the source directory, simply type ./make : the "cueact", "upce2upca" and "xautotype" binaries should be created without problem, the software being very simple and portable. Then, type ./make install as root to install the them in /usr/local/bin.
5 - Using CueAct
You need to have the CueCat driver installed and enabled (please refer to the CueCat driver's documentation on how to install and enable it).
When run, CueAct expects to find a configuration file at ~/.cueactrc : to create one, simply copy the supplied configuration file (cueactrc.sample) into your home directory as .cueactrc.
NOTE : unless you wish to create a different application than Internet
information lookup with CueAct, you probably should simply reuse and
complete the supplied .cueactrc file.
Then, invoke :
$cueact
The software should start and wait for you to swipe a barcode with the CueCat. When you do this, if the barcode type is recognized, the corresponding command is executed. With the supplied configuration file, it is required that you have the Mozilla browser installed.
Options :
-d : run as a daemon
-f <filename> : specify alternative configuration file
(default is ~/.cueactrc
-h : gives a help screen
-o : read and process only one barcode
-s : run silently
-v : be verbose
By default, cueact runs continuously.
Tip : invoke "cueact -s &" from your ~/.Xclients file and you'll have cueact
automatically start each time you start X. If you use KDE, you might want
to make an executable script in ~.kde/Autostart/ containing the following
lines instead :
#!/bin/sh
cueact -s &
Note : if you modify the configuration file, cueact will see the change and
re-read it without having to be restarted.
6 - CueAct configuration file syntax
The configuration file lists what command is associated with what type of barcode. One barcode and its associated command are listed on a single line. The format of this line is :
<CUECAT ID, MAX 18 DIGITS>:<BARCODE TYPE, MAX 3 LETTER>:<CMD> <CMD ARGUMENTS>
The command arguments are separated by spaces, unless they are isolated by single or double quotes.
You can use jokers ('' and '?') within the CueCat ID or the barcode type. For example, a CueCat ID of 0000?12 will match any CueCat ID with 4 leading zeros, which 6th digit is 1 and last digit is 2.
Inside an argument, it is possible to specify a special substitution pattern that CueAct will substitute at runtime by any part of the barcode swipe information you wish. The substitution pattern has the following syntax :
[<v>,[a],[b]]
where <v> is 'i' for the CueCat device ID, 't' for the barcode type, or 'b' for the barcode itself, [a] is the letter of the piece of information to start substituting with, and [b] the number of letters to substitute with, from [a]. [a] and [b] are not required : if [a] is omitted, it is 0 by default (1st letter). if [b] is omitted, it is the length of the piece of information by default.
examples of configuration lines :
*:IBN:mozilla http://shop.barnesandnoble.com/booksearch/isbnInquiry.asp?ean= [b,,]
tells CueAct that when it sees a IBN (ISBN) type of barcode scanned by any CueCat, it should substitute "[b,,]" by the value of the entire barcode and run the command.
00000000*:IB5:mozilla http://shop.barnesandnoble.com/booksearch/isbnInquiry .asp?ean=[b,,13]
tells CueAct that when it sees a IB5 (ISBN-5) type of barcode scanned by a CueCat with an ID starting with 8 zeros, it should substitute "[b,,13]" by the 13 first letters of the barcode and run the command.
*:UPA:/bin/bash -c "echo [i,5,2]"
tells CueAct that when it sees a UPA (UPC-A) type of barcode scanned by any CueCat, it should substitute "[i,5,2]" by the 6th and the 7th digits of the CueCat device ID and run the command.
Tip : when creating a configuration line, put CueAct in verbose mode so it'll
tell you in detail what it scanned, and what it's doing with the
information.
7 - Using upce2upca
This very simple utility is meant to be called by CueAct from a line in .cueactrc. It takes a UPC-E barcode value as argument and prints out the corresponding UPC-A value. If no arguments or more than one argument are given, upce2upca prints out a help message. If the argument is not a UPC-E barcode (which should be an 8 digits long string), an error message is printed out and the program returns with a return code of -1, which is easy to catch in a script.
8 - Using xautotype
Under X, simply invoke "xautotype Testing123" and the X application currently in focus will receive keyboard events "typing" "Testing123" out of the blue. If you run the program from an X terminal, you will see the string appear on the command line after the program exits as if you entered them.
xautotype is an X application. Therefore, it needs to be able to connect to an X server and have the "DISPLAY" environment variable set, just like any other X application. In some cases, the target X application will reject the synthetic keyboard events sent by xautotype : depending on the application, you may be able to set it so it doesn't reject them (like setting the "allowSendEvents" with xterm for example).
9 - 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 ...