Files
libgphoto2/camlibs/mars/protocol.txt
Theodore Kilgore 944952cd2f updated
git-svn-id: https://svn.code.sf.net/p/gphoto/code/trunk/libgphoto2@9210 67ed7778-7388-44ab-90cf-0a291f65f57c
2006-09-23 23:37:57 +00:00

270 lines
12 KiB
Plaintext

CONNECTION AND COMMAND PROTOCOLS OF THE MARS MR97310
Theodore Kilgore <kilgota@auburn.edu> April, 2004.
(This camera library and all files in it carry the LGPL license;
see any of the source files for a more complete statement.)
Peculiarly, the MR97310 camera uses bulk endpoint 0x04 (out) to receive
commands, sending back its responses over bulk endpoint 0x83 (in). Then, it
uses bulk endpoint 0x82 (in) to send data to the computer. The driver has to
switch the pipe appropriately. A command is a bulk write operation of one or
two bytes, with the first byte being 0x19. All requests to read a block or
blocks of data are performed by sending only the single byte 0x19. Otherwise,
the second byte can apparently be either a command, or part of a sequence
giving information.
A command is usually followed by a read request for confirmation. The read
request is of a bulk write of the one byte 0x21. The camera responds by
sending 16 bytes, in which only the first byte seems significant.
When the single byte 0x19 is sent with no second byte, immediate intention to
download data is signalled. The 0x19 which is sent must be followed by an 0x21
read request for confirmation. If the response is correct (must begin with
0xa8), then the pipe must be switched to 0x82 and the download may be carried
out by repetition of
gp_port_read(port,data,size); (where maximum size is 0x2000),
until the intended amount of data has been read. After the data has been
successfully read, the pipe must be switched back to 0x83 for the next
command sequence.
To summarize: bulk inep 0x83 is for receiving responses to commands; bulk
inep 0x82 is for receiving data, and bulk outep 0x04 is for sending commands.
The camera also has bulk pipe 0x07, which one would reasonably expect could be
used to write data to the camera. However, it is not obvious how to do that.
It may not be possible.
The observed command sequences sent to the camera are:
19 51 (starts the initialization sequence, any data download
initialization sequence, and the exit sequence)
19 b5 (appears during initialization; could also be part of a memory
address)
19 0f (flag instructing to move to a memory location which will be
sent to the camera in immediately subsequent communications)
19 54 (computer's acknowledgement to camera that a data download has just
been successfully completed; causes much beeping; mostly not used here)
19 ba (flag indicating that memory location should be reset, on exit;
followed by instructions to reset memory pointer to 00 00).
Other things are instructions to go to a memory location. For example, to
download the first photo in the camera, which begins at memory block 0x400,
the sequence is
send 19 0f
send 21, read response
send 19 00
send 21, read response
send 19 04
send 21, read response; do this repeatedly until first byte of response is
0x0a, then proceed with next command. My conjecture is that this sequence of
read requests is causing the memory pointer to move to the right place,
which is registered as done when the 0x0a comes up.
After the memory pointer has been successfully moved, the camera must be
told several other things, by sending one byte at a time, ending with an
indication of how big is the photo to be downloaded. For example, if a photo
is 640x480 pixels, equal to 4b000 bytes, then the sequence
19 b0
21, read response
19 04
21, read response
must be sent. Where this comes from is presented in the next section.
THE CONFIGURATION DATA
The MR973120 camera uses a block of configuration data of size 0x2000, which
is downloaded during the initialization of the camera. Here is a sample of the
first few, relevant lines from the configuration data. We have 9 photos in the
camera.
0000 ff 00 ff 00 ff 00 ff 01-00 00 00 00 00 00 00 00
0010 08 00 04 00 0c b0 04 cc-86 13 9a 00 0c 2c 01 6c
0020 06 a6 bf 00 0c 2c 01 a4-88 39 e5 00 0c b0 04 66
0030 06 4c 7b 01 0c 2c 01 07-86 df a0 01 0c 2c 01 3f
0040 08 72 c6 01 0c b0 04 01-88 85 5c 02 0c b0 04 2b
0050 08 98 f2 02 0c b0 04 54-ff ff ff ff ff ff ff ff
0060 ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff
Line 0000 is always the same (or should be -- see next section).
The first block of 8 bytes seems to be a marker signifying the configuration
block. The second eight-byte block may, it will become later apparent, refer
to some data about the block itself -- its type and its memory
location, perhaps. This would seem paradoxical since one can not know the
configuration data before downloading it, but not all in life is logical.
Lines 0010 through 0050 give data about the photos. There are nine photos in
the camera in this sample. When we reach byte 0x58 and begin repeating 0xff,
we finished reading about these nine photos. Thus, each block of 8 bytes says
something about a photo, until the repetition of 0xff begins. After this
the rest of the configuration data is simply junk.
Let's rearrange the sample, throwing away the unhelpful line 0000 and also
terminating after byte 0x57:
photo 1 08 00 04 00 0c b0 04 cc
2 86 13 9a 00 0c 2c 01 6c
3 06 a6 bf 00 0c 2c 01 a4
4 88 39 e5 00 0c b0 04 66
5 06 4c 7b 01 0c 2c 01 07
6 86 df a0 01 0c 2c 01 3f
7 08 72 c6 01 0c b0 04 01
8 88 85 5c 02 0c b0 04 2b
9 08 98 f2 02 0c b0 04 54
(the columns in this table are numbered from 0 to 7 in what follows)
In this pattern, the entry in the zeroeth column is a code which gives the
size of the photo and indicates if there is compression, or not. In
this particular example, none of the photos are compressed. The second digit of
this byte indicates the size:
0 -> 176x144
2 -> 352x288
6 -> 320x240
8 -> 640x480
The first digit of this byte indicates presence or absence of compression. If
it is 2, 3, 6, 7, a, b, d, or f there is compression; otherwise the photo
is not compressed. For a photo of given size and compression status, the first
digit is also dependent upon the location in the line of config data. If in
the first position on the line, then that digit is less than 8, and if in the
second position then 8 is added. This is seen in our example, where 08 and 88
both signify 640x480 uncompressed, and 06 and 86 both signify 320x240
uncompressed.
The entries in columns 1, 2, and 3 of our rearranged data seem to indicate the
storage location, in (hexadecimal) little endian format. Comparison of these
numbers to the sizes of photos and to the size of the configuration data and
to the advertised 8 Meg size of the RAM in the camera would seem to imply
that the memory is addressed as storage blocks, or words, of size 8 bytes. For
example, the configuration data, of size 0x2000, would require
0x2000/8 = 0x400 storage blocks, and the beginning point for the first photo is
listed as location 0x400.
The entries in columns 4 through 6 indicate, again in little endian form, the
data size for the given photo, in bytes. The actual data size to be requested
and downloaded from the camera needs to be tne next integer multiple of 0x2000.
Finally, for the seventh column there is at this time no obvious
interpretation.
A DATA-SHIFTING PROBLEM
An example of what the same config data can look like if gphoto2 (or the OEM
camera software, too) is run twice without replugging the camera in between,
is as follows:
0000 5c 73 60 73 5c 71 5d 6e-5c 72 5d 6c 5c 70 5b 6e
0010 5d 71 5b 71 5e 71 5c 71-5c 72 5d 6e 5c 72 5e 71
0020 5c 6f 59 6f 58 67 49 4c-38 43 3a 4c 43 59 49 5b
0030 4b 5d 51 64 54 66 54 6b-58 6b 56 66 52 64 53 64
0040 56 6d 55 66 57 6a 56 6a-59 6d 57 6b 58 6a 59 6d
0050 59 6c 59 67 58 6b 56 6b-57 6a 56 6a 54 63 44 49
0060 31 3a 2c 38 2c 39 2c 39-2e 38 30 39 2a 36 2a 37
0070 2a 32 2a 34 26 30 29 31-1f 2d 21 29 1e 26 1c 25
0080 ff 00 ff 00 ff 00 ff 01-00 00 00 00 00 00 00 00
0090 08 00 04 00 0c b0 04 cc-86 13 9a 00 0c 2c 01 6c
00a0 06 a6 bf 00 0c 2c 01 a4-88 39 e5 00 0c b0 04 66
00b0 06 4c 7b 01 0c 2c 01 07-86 df a0 01 0c 2c 01 3f
00c0 08 72 c6 01 0c b0 04 01-88 85 5c 02 0c b0 04 2b
00d0 08 98 f2 02 0c b0 04 54-ff ff ff ff ff ff ff ff
00e0 ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff
For some unknown reason, this data shift occurs if the camera is not
replugged, but the data is always offset either not at all or by exactly 128
bytes. Thus the problem can apparently be overcome by checking whether
ff 00 ff 00 occurs on line 0000 or on line 0080.
For similarly unknown reasons, the same offset seems to occur at the
beginning of every download of a photo. One gets 128 bytes of pure junk,
followed by 12 bytes which include a signature, and only then comes the data.
UPDATES and REVISIONS:
This section is intended to give further explanations of some things which
are otherwise mentioned briefly, in the ChangeLog.
1. 2004-05-18 ID number of Emprex PDC3800 contributed by Hisham Muhammad
<hisham@apple2.com>.
2. 2004-06-09 Compatibility with gtkam ensured; method of adjusting the gamma
setting of a photo introduced, based upon photo's config data.
3. 2004-09-04 The Vivitar Vivicam 55 has the same USB ID as the Emprex PDC3800
and presumably is therefore the same camera. Turned out that the camera is
very finicky about initialization. Extensive efforts to make this camera
actually to work resulted in major revisions to the init sequence. Special
credit to Sebastien Soilen <sebastien@soilen.net> for sustained, patient, and
thorough testing.
4. 2004-10-26 Support for two new cameras with new ID of 0x093a:0x10e, which use
two new resolution settings, of 352x288 and 176x144. The new codes for these
resolution settings are:
352x288, uncompressed 0x02 or 0x82
352x288, compressed 0x22 or 0xa2
176x144, uncompressed 0x0 or 0x80
176x144, compressed 0x20 or 0xa0
Credits to
Scott MacKenzie <irrational@poboxes.com> for reporting his camera and for
submitting the patch which makes it work.
Nils Naumann <nau@gmx.net> for reporting his camera 24 hours after Scott,
and for testing Scott's patch.
5. 2005-06-12 Code streamlined considerably. There are several more cameras
out there which I call the "new generation." Some of these cameras are
compressed-mode only, and some of them have a flashlamp. the flashlamp seems
to need new codes for the photos sizes, starting with 1 or 9 (uncompressed), or
3 or b (compressed). The "routine" function needed to be rewritten, and it
is also discovered that the proper data size for the download of a photo is
always an integer multiple of 0x2000. Anything else, some of the new cameras
will freeze. The old Aiptek Pencam VGA+ seems to work better this way, too.
Some new cameras such as the Argus DC-1620 have the same Vendor:Product IDs
as older cameras.
6. 2005-09-12 Some minor changes to the init routine make it more reliable
across the various different cameras. The big change is the support for the
compression mode. I got lucky by noticing that the camlibs/sonix routine
almost works here. After this, credit to
Bertrik Sikkens <bertrik@zonnet.nl> for figuring out the rest of the codec,
which still needed a lot of tweaking and smoothing after that. The camera uses
a quite lossy differential Huffman encoding, and apparently due to the data
loss the decompression can get unstable.
Michel Xhaard <mxhaard@magic.fr> for testing.
7. 2006-02-08 "Tweaking and smoothing" of decompression carried out, for
the most part successfully. Several new cameras added. One of them is the
Argus QuickClix, which uses a *different* compression algorithm! I hope
nobody else buys one, unless the purchaser is a decompression expert.
8. 2006-09-23 A freeze-up using a Vivitar Vivicam 55 has been reported by
conon <troll@arach.net.au>, apparently due to a timing issue while switching
the USB inep from 0x83 to 0x82. Conon also proposed a fix, in the form of a
usleep() command. He reports that this works with his camera, and after
extensive testing it does not seem to impair the functioning of other MR97310
cameras. Patch adopted. Conon has also submitted some simplifications of the
decompression algorithm, which seem to work well. These changes also
incorporated in current version.
NOTE: Vivitar in fact has discontinued this camera. They now offer a
Vivicam 55 which uses the SQ905C chip instead (see camlibs/digigr8)!