1 <!doctype linuxdoc system>
3 <!-- LyX 1.1 created this file. For more info see http://www.lyx.org/ -->
6 gPhoto2 Camera Library Developer's Guide
15 Reverse Engineering the Camera Protocol
17 The most difficult part for most developers is obtaining the transfer protocol.
18 If the OEM's are lucky enough, they will simply provide us with the protocol
19 specifications for their cameras and the drivers will be written at no cost
20 to them. Most OEM's refuse to do so though, citing trade secrets or company
21 policy; this is truly unfortunate in that they have effectively told their
22 own customers who use operating systems other than Windows and the Mac that
23 they don't want their future business and that they aren't valued customer
27 When OEM's do not cooperate, the developer is left to determine the protocol
28 him/herself through reverse engineering.
33 What follows are the most common setups for sniffing camera protocol traffic.
34 In all setups, a host computer runs the native camera drivers.; typically,
35 the Windows serial port drivers are used for reverse engineering. The drivers
36 are run through a series of functions that include getting a picture index,
37 downloading thumbnails, download full images, deleting images, camera configuration
38 options, in addition to any other features a camera might have. During these
39 operations, one or more of the following methods are used to capture the communication
40 between the host computer and the camera.
45 A serial repeater consists of the host computer, a computer used as a repeater,
46 and the camera. The setup is shown in figure .
49 The repeater runs special software which reads data from one serial port,
50 logs the communication, and then outputs the data to the other serial port.
51 Data that is from the host computer to the camera and from the camera to the
52 host computer is logged sequentially in a single log file. Information logged
53 includes hexadecimal data values, direction of the communication, as well as
54 time stamps for synchronization. An example sniffer to use for this configuration
60 To avoid using two computers, a Y serial cable can be used. The "trunk" end
61 of the serial cable attaches to the camera's serial transfer cable, while the
62 two "branches" plug in to two serial ports on the host computer. Figure shows
66 The camera drivers use one of the serial ports on the host computer, while
67 the other port is opened with a hexadecimal monitor application that dumps
68 all communications on the port to a file. The downside to this approach is
69 the developer would have to determine which sets of data was generated by the
70 camera or the host computer. Also, a Y cable would have to be either built
71 or purchased from an electronics supply store.
74 Virtual Device Driver Hooks
76 The Windows platform allows virtual device drivers to "hook" into other drivers
77 to provide additional functionality or feature enhancements. A combination
78 GUI and device driver named PortMon by Systems Internals is a communications
79 debugging utility that hooks into the existing Windows serial device driver
80 (vcomm.vxd) and logs communications. Figure shows this equipment arrangement.
83 This setup allows the developer to not use any extra hardware by simply
84 relying on software. This is perhaps the easiest method for capturing camera
88 Making Sense Out of the Protocol
90 What follows are some pointers on decoding camera protocols. It uses a
91 protocol that isn't really any camera protocol in particular, but should demonstrate
92 some commonalities between most camera protocols.
97 Cameras like to ping. This is the in the form of an "ACK""
98 command that is different for different cameras. Basically, it is usually a
99 short packet (probably 1 byte) that is sent both ways in order for the camera
100 to know the computer is there or vice versa. It is also sometimes used to wake
101 up a camera that has gone into power-save mode. It usually starts out the communications,
102 as well as confirms each packet in any sort of "mass" transfer. The
103 opposite, a "NAK", is sent to basically say the last packet was not
104 received, or an error has occured. Again, this is usually just a single byte
111 The Camera sent an ACK ("01")
112 and the Computer responded with an ACK as well.
114 Transfers are usually in "reverse network order", meaning least
115 significant bytes come before most significant bytes. For example, "00 08" should
116 actually be reassembled as "08 00".
118 Most protocols use starting and stopping bytes.
123 Camera : 03 03 00 3f 03 04
127 notice the packets begin with "03" and end with "04" (don't
128 pay attention to what is between them). Also notice the Computer sent an "ACK"
129 to confirm it got the packet.
131 Packets usually have a "command" byte, which tells either the
132 computer or the camera what to do. Let's say you told the software to retrieve
133 the number of pictures, which at the time happened to be "8", and
134 you got the following:
136 Computer: 03 01 00 00 00 04
137 Camera : 03 01 00 00 08
141 In this example, you notice the "03" and "04"
142 specifying the start and stop of the packet. Also, you notice the second byte
143 in the Computer packet is "01". The camera responds with the above
144 packet, and low and behold, you see the number 8 in the same packet. It would
145 appear, initially, that the second byte is used as a command byte, and that
146 "01" specifies the camera to return the number of pictures. This
147 may very well be right, but don't jump into it yet. Make sure you look at a
148 bunch of similar situations to confirm this. (Again, notice the "ACK"
149 sent by the computer).
151 Most protocols have a "data size" byte(s) in data packets. Let's
152 say that you told the camera to retrieve thumbnail 8 and you get the following:
156 Camera : 03 02 00 0F (15 bytes) 04
160 a brief breakdown of this transaction:
162 -Looks like the command to retrieve
163 a thumbnail is "02" (2nd byte in the computer packet), and that the
164 byte that is "08" specifies which thumbnail to return.
166 responds with a "02" in the command field, specifying it is returning
167 a thumbnail, and then sends "0F", and 15 bytes of data.
169 like the byte "0F" specifies how many bytes are after it in the same
170 packet. This is a data size byte.
171 (Note: this is a simplistic example. No
172 thumbnail will only be 15 bytes :) this leads up to the next thing to consider)
174 Most protocols have an "order" or "counter" byte. This
175 is used so that, in large data transfers where the picture may be split up
176 into several different packets, the computer knows how to reassemble all the
177 data. The entire thumbnail more than likely will not be contained in a single
178 packet for logistical reasons, so they break up the data into many different
179 packets and give each packet a unique number (or "order" byte). Let's say you
180 told your camera to return thumbnail 8 (which is, as mentioned, pretty big),
181 and you get the following:
183 Computer: 02 03 00 00 08 03
187 Camera : 02 03 01 0F (15 bytes) 03
190 Camera : 02 03 02 0F (15 bytes) 03
192 ... 5 more packets and ACKs
194 Camera : 02 03 08 09 (9 bytes) 03
197 You notice that the 3rd
198 byte of each of the camera packets increments with each packet sent from the
199 camera. This looks like it is an order (counter) byte. the computer can then
200 reassemble the data from all the packets in order to reproduce the image.
202 Most protocols have some sort of error detection byte(s) at the end of
203 the packet. This is usually a simple checksum (summation of bytes), or a CRC
204 (a somewhat complex algorithm that reduces the probability of mis-diagnosing
205 a packet with errors by magnitudes). These bytes can take into account only
206 the data, or maybe the entire packet excluding those error detection bytes.
207 If this isn't a known scheme, this winds up being the hardest part of reimplementing
208 the protocol. Lets take the above example again, this time we'll add a couple
209 bytes on the end for error detection:
211 Computer: 02 03 00 00 08 03
213 02 03 00 0F (15 bytes) 0f 02 03
215 Camera : 02 03 01 0F (15 bytes)
218 Camera : 02 03 01 0F (15 bytes) fa d0 03
221 : 02 03 02 0F (15 bytes) fa d0 03
223 ... 5 more packets and ACKs
225 : 02 03 08 09 (9 bytes) d7 38 03
228 Notice how the error detection
229 bytes are usually different for each packet. These may be checksums, or CRC's,
230 or something else. Only way to find out really is to try each one, on different
231 combinations of packet parts (data, order byte, command byte, etc...) and see
232 if you get the same thing. Try this on the shorter packets to make life easier.
235 at one more thing that sticks out in this transaction: for packet with order
236 byte "01", the Computer responded with a "02". and the Camera then resent
237 the same packet it just did. This shows that the NAK byte is "02",
238 and this could happen because maybe the error detection bytes didn't match
239 with the data, or maybe something else happened. either way, the camera resent
240 the last packet, and now you know how the camera can recover from transfer
241 errors. If you didn't get the packet you were expecting, send the camera a
242 NAK and it will resend the same packet again.
245 Understanding the gPhoto2 Design
247 The gPhoto2 design is the same three-tiered structure that has worked extremely
248 well in the past with other software packages. Here is a listing of the 3 tiers:
262 Role of the Camera Library
264 The camera library is in charge of talking directly with the camera. The
265 library uses the gPhoto2 Camera API in order to provide a common access-method
266 for the library itself. Being dynamically linked, the libraries are loaded
267 at run-time depending on the camera model the end-user would like to access.
271 In order to provide flexilibity with variations in camera design, there
272 are camera "abilities" which list, well, the abilities of each camera model.
273 Some camera may support serial port connections only, while others may be able
274 to use USB and a serial port. We've run into cameras that don't support thumbnailing
275 on the camera so there is an "abilities" field to specify whether or not the
276 camera supports thumbnailing. The "abilities" also list other things such as
277 supported serial transfer speeds, file deletion, and other functionality.
280 The camera libraries only make functions calls to the I/O library and to
284 There is more information on the specifics of the camera library in section
288 Role of the I/O Library
290 The gPhoto2 I/O library is a platform-independent communications library
291 that support serial, parallel, USB, firewire, and network connections. It is
292 a work-in-progress with a constantly expanding list of supported platforms.
293 This library uses the gPhoto2 I/O library API for accessing communications
294 devices. It enumerates the devices available on a system, and provides read/write
298 The camera libraries all use the I/O library for communications with the
299 cameras. By doing having all communications go through a single library, the
300 camera libraries become as portable as the I/O library. Porting gPhoto2 to
301 other platforms become extremely easy.
304 There is more information on the specifics of the I/O library in section
308 Role of the Front-end
310 The front-end is the application that the user interacts with. It is usually
311 a command-line program, or a graphical point-and-click interface. The front-end
312 talks only with the gPhoto2 core in order to retrieve pictures and perform
313 other functions with the camera.
316 Role of the gPhoto2 Core
318 The gPhoto2 "core" is the heart of gPhoto2. It provides services to both
319 the camera libraries and the front-ends. Most of the services deal with error-checking
320 and enumeration of devices (cameras, I/O devices, etc...). The core performs
321 validity checking on data passed to/from the front-end or the camera library.
324 You could consider the core a translator/interpreter/spell-checker/army-general
325 in the "big picture" of gPhoto2. It does the grunt-work and performs the coordination
329 Implementing the Library
331 gPhoto2 camera libraries use the gPhoto2 Camera API (CAPI) for implementation.
332 Here is a listing of the CAPI functions:
356 camera_file_get_preview
384 Section 3.1 details the purpose of each of these functions, while Section
385 3.2 discusses how to use the I/O library.
390 The CAPI provides the full set of functions for doing various tasks with
391 the camera. All CAPI functions return either GP_OK for succesful execution
392 , or GP_ERROR for a failure of execution
395 What follows is a listing of the functions, including prototypes and data
401 <bf>Purpose: </bf>Retrieve the unique id for the camera library.
404 <bf>Prototype: </bf>int camera_id (CameraText *id);
410 CameraText *id : unique string to represent the camera library
414 In order to guarantee that only once instance of the camera library is
415 loaded for each instance of the core, the camera library must copy a unique
416 string into the "id". Please consult the gPhoto developers to determine which
417 string you should use.
424 int camera_id(CameraText *id) {
427 strcpy(id->text, "my-unique-string");
438 <bf>Purpose: </bf>Retrieve the list of supported cameras and the abilities for each
442 <bf>Prototype: </bf>int camera_abilities (CameraAbilitiesList *list);
445 <bf>Arguments: </bf>d
448 CameraAbilities *abilities : the list of abilities for the supported cameras
451 int *count : the number of
456 <bf>Purpose: </bf>Initialize the camera
459 <bf>Prototype: </bf>int camera_init (Camera *camera, CameraInit *init);
462 <bf>Arguments: </bf>d
467 <bf>Purpose: </bf>Close the camera
470 <bf>Prototype: </bf>int camera_exit (Camera *camera);
473 <bf>Arguments: </bf>d
478 <bf>Purpose: </bf>List the files in a particular folder on the camera
481 <bf>Prototype: </bf>int camera_file_list(Camera *camera, CameraList *list, char
485 <bf>Arguments: </bf>d
490 <bf>Purpose: </bf>List the subfolders in a particular folder on the camera
493 <bf>Prototype: </bf>int camera_folder_list(Camera *camera, CameraList *list, char
497 <bf>Arguments: </bf>d
502 <bf>Purpose: </bf>Retrieve a file from the camera
505 <bf>Prototype: </bf>int camera_file_get (Camera *camera, CameraFile *file, char
506 *folder, char *filename);
509 <bf>Arguments: </bf>d
512 camera_file_get_preview
514 <bf>Purpose: </bf>Retrieve a file's preview from the camera
517 <bf>Prototype: </bf>int camera_file_get_preview (Camera *camera, CameraFile *file,
518 char *folder, char *filename);
521 <bf>Arguments: </bf>d
526 <bf>Purpose: </bf>Place (upload) a file to the camera
529 <bf>Prototype: </bf>int camera_file_put (Camera *camera, CameraFile *file, char
533 <bf>Arguments: </bf>d
538 <bf>Purpose: </bf>Delete a file from the camera
541 <bf>Prototype: </bf>int camera_file_delete (Camera *camera, char *folder, char *filename);
545 <bf>Arguments: </bf>d
550 <bf>Purpose: </bf>Retrieve the configuration window.
553 <bf>Prototype: </bf>int camera_config_get (Camera *camera, CameraWidget *window);
557 <bf>Arguments: </bf>d
562 <bf>Purpose: </bf>Set camera configuration
565 <bf>Prototype: </bf>int camera_config_set (Camera *camera, CameraSetting *setting,
569 <bf>Arguments: </bf>d
574 <bf>Purpose: </bf>Retrieve live data from the camera
577 <bf>Prototype: </bf>int camera_capture (Camera *camera, CameraFile *file, CameraCaptureInfo
581 <bf>Arguments: </bf>d
586 <bf>Purpose: </bf>Retrieve the camera summary information
589 <bf>Prototype: </bf>int camera_summary (Camera *camera, CameraText *summary);
592 <bf>Arguments: </bf>d
597 <bf>Purpose: </bf>Retrieve the camera user's guide (manual)
600 <bf>Prototype: </bf>int camera_manual (Camera *camera, CameraText *manual);
603 <bf>Arguments: </bf>d
608 <bf>Purpose: </bf>Retrieve information about the camera library
611 <bf>Prototype: </bf>int camera_about (Camera *camera, CameraText *about);
614 <bf>Arguments: </bf>d
617 The gPhoto2 I/O Library