hppsmtools 0.99
---------------

hppsmtools is a program for communicating with the HP PhotoSmart
and Konica Q-EZ digital cameras.  I've written it because I don't
(and don't want to) have Windows and wanted to access the camera
anyway.  Quite possibly it will work for you as well.

In the meantime, of the order of 40 people have provided feedback
about using this program, and most of them were happy with it.  I,
on the other hand, was not when I got myself a notebook with a
somewhat flaky serial port and so I gave the program an overhaul.
Since I also had an chance to glimpse at the protocol docs, this
program should be much better behaved than its predecessors.  In
particular, doing a ^C should be safe in most cases.

In January 2000, Jeff Schaller <schaller+psmget@southwind.net> did some
good things to this program.  Among other things, he made it work with
the PhotoSmart C30 and made the source look so pretty that I'm no longer
exactly ashamed of it.  Later, he convinced me to split the binaries
and do a big cleanup, and in the end did most of the work.  What you see
now is the result of that effort.

In December 2002, Brian Goines provided man pages for the four programs.
Thanks, Brian.


Installation
------------

You may want to change PREFIX (and ADDIT_DEFS if you are on a libc5
system) in the Makefile, and/or config.h (see below) before compiling.

Doing make will hopefully produce the binaries psmget, psmdir, psmdel,
and psmsho, and make install will put them into $(PREFIX)/bin, the
man pages will go to $(PREFIX)/man/man1.  That's it, nothing else gets
dumped into your file system.

Psmget does not have any configuration files.  However, if the environment
variables PSM_BPS and/or PSM_PORT exist, it will use the values in there
as the bitrate and the port used to talk to the camera.  Built-in defaults
(defined in config.h in DEFAULT_PORT and DEFAULT_BITRATE, in case you want
to change that) are 115200 and /dev/ttyS0, respectively.  Legal values
for PSM_BPS are 19200, 38400, 57600, and 115200, PSM_PORT has to contain
the full path to the device.



Usage
-----
The following options are available in all four programs

-p <port>       \ These two override the settings
-r <bitrate>    / in PSM_PORT and PSM_BPS
-t              sync the camera's clock with the host computer's
-h              print a short help

In addition, psmget and psmdir understand
-n <string>     sets a prefix for the names of the files written
                (For psmdir, the idea is that you can do
                psmdir -n blabla > index.txt and then comment the
                images with the proper names filled in)

psmget and psmdel understand
-i              the number in the parameter(s) are image ids as opposed to
                image numbers.  Basically, you can ignore this option
                unless you use psmsho, when you have to use -i with the
                number psmsho returns.

psmget understands
-b              get thumBnails instead of full size images.  The file names
                are then *.tbn.jpg.  If you have a better idea, tell me...

psmsho understands
-f              don't switch off the flash (once you switched off the flash,
                it will remain off until you switch off the camera)

psmdir understands
-w              don't show directories, give some not so terribly interesting
                numbers about the camera

psmget {<number>}|all  reads the numbered picture and puts it to stdout
  or to files <prefix><image id>.jpg if -n was given.  Thus,
  psmget 1 >test.jpg
  reads the first picture to the file test.jpg, whereas
  psmget -n test 1 2
  writes pictures 1 and 2 into the files test01.jpg and test02.jpg.
  psmget -n today all
  reads all pictures in the camera.

psmdel {<number>}|all  deletes the given pictures

psmdir prints a directory of the camera with dates (in the
  rather odd form the camera gives them) and the image quality.

psmsho instructs the camera to take a picture. By default, the flash
  is turned off by this command.  You may try to do some kind of a
  webcam with this command, I won't bet how long your flash card will
  take this, though.  psmsho returns the image id of the picture just
  taken (or -1 on failure, whatever your shell makes of that)

You probably don't want to read the following two paragraphs.

There is a catch -- when you communicate with psmget, you'll use image
numbers, counting the images from 1 to the number of images consecutively.
The camera, on the other hand, deals with image ids, numbers that are
usually identical with the image numbers but may differ when you have
deleted images.

Now, the hppsmtools try to hide these image ids from you, but psmsho
returns an image id (because I couldn't find an easy way to find an image
number from an image id), and therefore the dreaded -i option exists.
Also, just to confuse you, the image ids are displayed in the download
messages generated by psmget, and of course they are in the exif headers.

Your probably want to forget the last two paragraphs.


Examples
--------

Get all images in the cameras, naming them mypic1.jpg through mypicnn.jpg:
psmget -n mypic all

Get image 15 and write it to file gronk.jpg:
psmget 15 > gronk.jpg     or      psmget -n gronk 15
(actually, the second form will write to gronk15.jpg)

Take a picture and write it to test.jpg (in (t)csh):
psmsho; psmget -i $status > test.jpg
the same, only delete the image after the fact
psmsho; set tmpvar=$status; psmget -i $tmpvar; psmdel -i $tmpvar
(notice the i)

Look at the directory of the flash card and set the time while being at it:
psmdir -t

Look at the directory with the names that the a psmget -n would store
the pics in filled in:
psmdir -n mypic


If it doesn't work
------------------
Check the permissions on the device the camera is attached to and all the
usual things.  If you may read and write to it, it's serious and you
should really contact me.  Which you should do anyway, or else this
program will always only do what *I* need and will always be the mess
it is now.

If it works
-----------
Please contact me anyway.

Non-Legalese
------------
Since it looks like this program is almost serious, I decided to go
for a serious license: the GPL.  If you want to lift the exif stuff,
do so, I won't sue you even if it ends up in a closed-source thing.
Otherwise, read COPYING.

I did not re-engineer or disassemble programs from either HP or Konica
to write this program (quite obviously).  All the information that went
into the program come entirely from watching the camera and the software
HP bundles with the camera talk to each other (and from a glimpse I was
allowed to take at the HP's docs).

To-Do
-----
Probably still a lot. I'll have to look into portability issues.  Wishes
may be directed to me and will probably be encouraging.  Bug reports, too.
If you send in bug reports, core dumps or debug logs (set MASTERDEBUG in
psmget.c to 1, recompile, catch stderr into a file, and send it to me),
even strace logs will be helpful.

The compression ratios for the C-30 are *very* weird indeed.  I doubt
that this is correct, and if so, than HP's (or whomever's) engineers have
messed up royally.  Any tips on where the errors are is greatly appreciated.

Updates
-------
Check out http://unimut.fsk.uni-heidelberg.de/demi/photosmart

Contacting me
-------------
Write an E-mail to
msdemlei@users.sf.net

Dec 2002