CONNECTION AND COMMAND PROTOCOLS OF THE MARS MR97310 Theodore Kilgore 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 . 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 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 for reporting his camera and for submitting the patch which makes it work. Nils Naumann 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 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 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 , 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)!