git-svn-id: https://svn.code.sf.net/p/gphoto/code/trunk/libgphoto2@9210 67ed7778-7388-44ab-90cf-0a291f65f57c
270 lines
12 KiB
Plaintext
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)! |