/* This is the README file for libgphoto2/camlibs/digigr8. This README is an 
 * integral part of the libgphoto2/camlibs/digigr8 library source code and is 
 * distributed with that source code under the LGPL license. a copy of which 
 * license may be seen in any of the source files in libgphoto2/camlibs/digigr8, 
 * or in the head directory of libgphoto2.
 */ 
 
 
INTRODUCTION:

The cameras supported here have a controller chip from S&Q Technologies. 
They have USB Vendor:Product number 0x2770:0x905c. These cameras are cheap 
and basic. Their functioning resembles that of the cameras supported by the 
sq905 camera library, but is a bit different. More recently (07/11/2007) I 
have discovered a camera with Product ID 0x9050 which will also function with 
the same driver library. I will describe it further at the end of this document.

The first camera which I knew of with this USB ID was the Digigr8 from 
RadioShack. Hence comes the name of this camera library. Several more cameras 
have since been reported, including one which has the same make/model painted
on the plastic case as that of a camera which previously used an sq905 chip 
and used the sq905 Vendor:Product number instead of this one. SQ Technologies 
seems to have discontinued the SQ905 and this chip is apparently its successor. 

For information about additional cameras with the same USB ID, I am totally 
dependent on reports from users and testers. If you have another 0x2770:0x905c 
camera and want it to work and it currently does not, then I will be very glad 
to hear from you. Saying this a different way: further progress with your 
camera will depend upon your input. If on the other hand your camera does work
and is not explicitly listed, I would still like to know about it for the sake
of completeness. I will give it an explicit line listing in library.c and I 
will credit you as the finder of the camera, in the ChangeLog file. 


WHAT CHIP IS ACTUALLY IN THESE CAMERAS? 

I do not know. I did not take mine apart to look inside. (update) Someone has 
reported to me that he did take his camera apart, and it really is an SQ905C 
chip inside. 

WHAT FEATURES DO THESE CAMERAS HAVE, AND WHAT DOES THIS DRIVER SUPPORT?

	FEATURE LIST					SUPPORTED (Y/N/Part)
-- USB connection to computer
-- High resolution 640x480, uncompressed 				Y
-- Low resolution 320x240, uncompressed					Y
-- High resolution 640x480, compressed 					Y
-- Low resolution 320x240, compressed					Y
-- Ability to "switch" resolution between pictures 			Y
-- Ability to download all pictures on camera				Y
-- Ability to download the first k pictures, where 
	k is less than the number on the camera 			Y
-- Ability to download individual photos				Y (faked, but works)
-- Shoot a frame and save image to computer				Y
-- Internal battery, which recharges through the USB port	(some models)

-------------------------------------------------------------------------
The following things can be done with button-pushes on the camera:
-------------------------------------------------------------------------
-- Frequency filter for use in artificial light. Can be set 
	to cancel 60hz or 50hz interference. 
-- Delete all, delete last, resolution setting, compression mode setting. 
-- "Clip" mode will shoot three frames. The camera "sees" these frames as 
	ordinary photos. Also the photo counter on the LED counts them.
-- "AVI" mode shoots until the shutter button is released, or until the 
	camera is full. The photo counter does NOT count the AVI frames, 
	but thinks all of the frames are part of one photo. Otherwise, the
	camera sees the frames as ordinary photos, so gphoto2 will give the 
	actual count of all frames, whether photos or part of an AVI clip,
	Also gphoto2 will download the AVI frames as if they were ordinary 
	photos. Apparently, AVI frames are always 320x240 regardless of the 
	resolution setting. AVI mode does honor the compression setting, 
	though, if it happens to be turned on. However, compressed AVI 
	processing is _not_ implemented at this time. 

Notes:  

One camera has been discovered, in July 2007, to which the above list does 
not correspond. See the section "More concerning the newly discovered 
0x2770:0x9050 camera".

The only known cameras supported by the camlibs/digigr8 have a 640x480 
high-resolution setting and a 320x240 low-resolution setting. If your
0x2770:0x905c camera uses another resolution setting, then it might still 
work. There is some similarity with the sq905 cameras, and I kept that part 
of the code here. Specifically, if the camera has 352x288 and 176x144 
resolution settings, these might work but are not tested (Note added July 2007:
the code for 352x288 _does_ continue to work; see below). If your camera does 
not work due to unknown resolution settings, then the new resolution settings 
need to be listed in digigr8.c in digi_get_picture_width (). Please report any
such problem. I will ask you to run a gphoto2 command in debug mode and we can
easily find the information we need -- which information, understand, I do not 
possess unless you share it with me. 

The pictures obtained on the uncompressed settings can often be superior to
those obtained using the software which came with the camera, but not
always. Generally, considering that they are cheap, low resolution cameras,
these cameras give relatively good pictures.

The digigr8 cameras can also function as webcams, but that is outside the 
scope of gphoto2. 


HARDWARE LIMITATIONS AND CONSTRAINTS

The SQ905C chip, like the SQ905 before it, is a minimalist controller chip; if 
any of its functionality at all were removed, it would probably be impossible to 
use it to run a digital camera. To program around the limitations of the chip, 
therefore, is a special challenge. Here are some examples. 

1. 	The manufacturer's driver will do nothing but to download all photos 
on the camera, and display them, keeping temporary copies in C:\TEMP, to be
deleted when the camera access program is closed. After downloading everything, 
then, the OEM program allows the user to "select" and to "save" any or all of
the photos which have, in fact, already been downloaded (indeed the displayed
"thumbnails" came from the files in C:\TEMP, too). Now, gphoto2 does not 
operate thus, has preconceived notions about how any respectable camera should 
act, and regards such a primitive camera controller chip as an untamed beast. 
Thus, many of the gphoto2 functions will not work unless, through a bit of 
fakery which involves downloading data and throwing it away and on some 
occasions resetting the camera, this primitive behavior is somewhat improved.
That all has to be done in the driver, with fakery invisible to the user. These
remarks apply not only to getting thumbnails, but also to many other gphoto2 
options as well. See item 2. 

2.	The camera's data storage provides only sequential access, not
random access. In other words, it acts as though it were a tape drive
instead of a disk. Worse, it's like a tape drive with no fast forward and 
no rewind controls. The constraints which this places are obvious. It means 
for example that to download all the photos on the camera to display thumbnails 
requires the camera to be reset afterwards, because that is the only way to do
the "rewind" required before any of the photos can be accessed again. It also 
menas that "gphoto2 -p 2" would NOT download the second photo on the camera, 
unless the support for it is so written as to download the first photo, then 
the second photo, and to process only the second one, having consigned the 
data from the first photo to /dev/null. The camera simply cannot do better. 
The gphoto2 -p 2 command option does work, of course, but only because the 
necessary jury-rigging has been built into the download function. 

3.	Considering the way the communication protocols of these cameras
seem to work, it would seem nearly impossible to copy any data to the camera
for storage and transport. The camera clearly does not have files on it,
only data addresses. And the camera does not keep time. For similar 
reasons, it would also seem impossible to delete a photo from the camera by
action of software on the computer. The camera itself supports two choices for
deletion: delete the last photo taken, or delete all. Each action is
performed by an appropriate sequence of button pushes on the camera.


WHAT GUI FRONTENDS DOES THIS CAMERA LIBRARY SUPPORT?

Gtkam seems to work well for me with this library. Some of the other various
frontends do not seem to work quite so well for me. But one of them may work 
nicely for you, and you are hereby encouraged to try it. If you want to use 
either gtkam or digikam, you are encouraged to read the camera's manual (in 
gtkam, right-click on the name of the camera in the left panel, after starting 
the program and having chosen the right camera). 


NOTES  

1.	The program is set up to put out pictures in PPM or raw format. The OEM
program offers JPEGs, which the user can easily create on Linux, using other   
software which exists independently from libgphoto2. 

2.	 The gamma setting (actually seems to be one over gamma) used for
the construction of PPM image files has been obtained by trial and error. It
seems to work very well for outdoor pictures, but the setting is a
compromise between what happens with outdoor photos and what happens with
indoor photos. Conceivably, the program could support a choice between two
or more gamma settings, optimizing for different conditions. 

3. 	A still-experimental postprocessing routine is added, to provide
some sharpening and color correction for different lighting conditions. The
routine can easily be turned off if one wishes, and because it is
experimental you may so wish. To disable it, just comment out the line in
get_file_func ( ) in library.c where the function digi_postprocess ( ) is
called. Then do "make install" to install your change.

4. 	The "High Compression" setting uses an unpublished compression 
algorithm; decompression seems now to work pretty well.  

5. 	Please get back to me with reports about other SQ cameras (any cameras 
with Vendor number 0x2770), with their specifications (what it says in the OEM 
manual about resolution and number of pictures, as well as make and model, and 
whether it works or not with any libgphoto2 driver or not, would be enough), 
and with a log file if it seems it is supposed to work but there are problems. 


More concerning the newly discovered 0x2770:0x9050 camera:

This camera is the "Disney pix micro," found at KB Toys. Its functionality 
is very basic. On the package it says the camera is able to take 20 photos, but 
in fact the number of photos is variable. For, they are all compressed. Since 
the compression algorithm is the same as that in the 0x905C cameras, this new 
camera is quite usable, for what it is. Resolution for this camera is fixed at 
352x288 and can not be adjusted. In fact, the only thing on the camera which 
can be controlled at all, aside from snapping photos one at a time, is to 
delete photos one at a time or to delete all.  To delete one photo with the 
delete button on the camera, press the button. To delete all, hold it down 
longer. The camera has no clip option, no delayed-shooting option, and no 
multi-frame clips intended for AVI images. However, the camera will do 
software deletion of all photos using the option gphoto2 -D, while for the 
other cameras supported in camlibs/digigr8 the gphoto2 -D option does nothing 
at all. However:

The USB command to delete is the same as the command to shoot a frame 
(gphoto2 option is --capture-preview). If you shoot a frame with the Disney 
pix micro, it will deledte whatever photos are on the camera !!!


A note on capture:

These cameras will perform "gphoto2 --capture-preview" which means, to shoot a 
frame and download it to the computer immediately. On the 0x9050 camera, the 
same USB command is what is used to delete all frames on the camera. On the 
0x905C cameras, the capture function works, too, but will not affect whatever
is on the camera. The default resolution setting for capture with all these 
cameras is 320x240. For those cameras which will do 640x480 resolution in 
still photo mode, there is a tweak which can cause the camera to do the 
capture at 640x480 as well. It is as follows:

Look through the code in camlibs/library.c for the capture function. You will 
see a USB command in which the digit 0x1440 appears. Change that to 0x2840 and 
re-compile and re-install. It is also possible to get 160x120 resolution, but 
that is not so interesting. Evidently, the "40" means to do capture, and the 
previous two digits are the resolution setting in hexadecimal, with the final 
"0" removed. For example, 640=0x280 -> 0x2840 and 320=0x140 -> 0x1440 (which, 
again, is the default setting). I am not sure what would happen if the 
resolution setting here is too high for the camera (the known 0x9050 camera
will only do 352x288 at max resolution in still mode, for instance). Therefore,
this tweak is not implemented. However, it does work for me with those cameras 
for which it works. It should be repeated, too, that this tweak is not 
documented by any manufacturer and is not available in the OEM driver for any 
of these cameras. 


WARRANTY? 

	Absolutely not. No warranty. Never. Not responsible for any actual
	or potential damage or consequences to anyone or to the equipment of
	anyone for using this program, whether the alleged damage or alleged
	consequences are claimed to be real, imaginary, direct, collateral,
	for pain and suffering, or are claimed to be inflicted upon any
	"third party" who is not the user or installer of the program. The
	program has been written for my pleasure and to broaden and deepen
	my knowledge of computer hardware and software. The program has not
	been written with the immediate expectation of financial gain or
	profit on my part, nor has it been commissioned for pay. It is
	presumed that any end-user of this program will have access to the
	source code of the program and can judge for himself or herself
	whether he/she wishes to use it or not, or can consult someone with
	appropriate expertise to make such a judgment. 


Theodore Kilgore
12/05/05
(revised 12/29/05, 03/28/07, 06/25/07, 07/16/07, 07/23/07)