3 gPhoto2 Camera Library Developer's Guide
11 1 Reverse Engineering the Camera Protocol
13 The most difficult part for most developers is obtaining the transfer
14 protocol. If the OEM's are lucky enough, they will simply provide
15 us with the protocol specifications for their cameras and the drivers
16 will be written at no cost to them. Most OEM's refuse to do so though,
17 citing trade secrets or company policy; this is truly unfortunate
18 in that they have effectively told their own customers who use operating
19 systems other than Windows and the Mac that they don't want their
20 future business and that they aren't valued customer to begin with.
22 When OEM's do not cooperate, the developer is left to determine the
23 protocol him/herself through reverse engineering.
25 1.1 Sniffing the Protocol
27 What follows are the most common setups for sniffing camera protocol
28 traffic. In all setups, a host computer runs the native camera drivers.;
29 typically, the Windows serial port drivers are used for reverse engineering.
30 The drivers are run through a series of functions that include getting
31 a picture index, downloading thumbnails, download full images, deleting
32 images, camera configuration options, in addition to any other features
33 a camera might have. During these operations, one or more of the following
34 methods are used to capture the communication between the host computer
39 A serial repeater consists of the host computer, a computer used as
40 a repeater, and the camera. The setup is shown in figure .
42 The repeater runs special software which reads data from one serial
43 port, logs the communication, and then outputs the data to the other
44 serial port. Data that is from the host computer to the camera and
45 from the camera to the host computer is logged sequentially in a single
46 log file. Information logged includes hexadecimal data values, direction
47 of the communication, as well as time stamps for synchronization.
48 An example sniffer to use for this configuration is ``sersniff''.
50 1.1.2 ``Y'' Serial Cable
52 To avoid using two computers, a Y serial cable can be used. The ``trunk''
53 end of the serial cable attaches to the camera's serial transfer cable,
54 while the two ``branches'' plug in to two serial ports on the host
55 computer. Figure shows this setup.
57 The camera drivers use one of the serial ports on the host computer,
58 while the other port is opened with a hexadecimal monitor application
59 that dumps all communications on the port to a file. The downside
60 to this approach is the developer would have to determine which sets
61 of data was generated by the camera or the host computer. Also, a
62 Y cable would have to be either built or purchased from an electronics
65 1.1.3 Virtual Device Driver Hooks
67 The Windows platform allows virtual device drivers to ``hook'' into
68 other drivers to provide additional functionality or feature enhancements.
69 A combination GUI and device driver named PortMon by Systems Internals
70 is a communications debugging utility that hooks into the existing
71 Windows serial device driver (vcomm.vxd) and logs communications.
72 Figure shows this equipment arrangement.
74 This setup allows the developer to not use any extra hardware by simply
75 relying on software. This is perhaps the easiest method for capturing
78 1.2 Making Sense Out of the Protocol
80 What follows are some pointers on decoding camera protocols. It uses
81 a protocol that isn't really any camera protocol in particular, but
82 should demonstrate some commonalities between most camera protocols.
84 1. Cameras like to ping. This is the in the form of an "ACK"" command
85 that is different for different cameras. Basically, it is usually
86 a short packet (probably 1 byte) that is sent both ways in order
87 for the camera to know the computer is there or vice versa. It is
88 also sometimes used to wake up a camera that has gone into power-save
89 mode. It usually starts out the communications, as well as confirms
90 each packet in any sort of "mass" transfer. The opposite, a "NAK",
91 is sent to basically say the last packet was not received, or an
92 error has occured. Again, this is usually just a single byte as
99 The Camera sent an ACK ("01") and the Computer responded with an
102 2. Transfers are usually in "reverse network order", meaning least significant
103 bytes come before most significant bytes. For example, ``00 08''
104 should actually be reassembled as ``08 00''.
106 3. Most protocols use starting and stopping bytes.
109 Computer: 03 50 00 0f e0 04
110 Camera : 03 03 00 3f 03 04
113 For this example, notice the packets begin with "03" and end with
114 "04" (don't pay attention to what is between them). Also notice
115 the Computer sent an "ACK" to confirm it got the packet.
117 4. Packets usually have a "command" byte, which tells either the computer
118 or the camera what to do. Let's say you told the software to retrieve
119 the number of pictures, which at the time happened to be "8", and
120 you got the following:
122 Computer: 03 01 00 00 00 04
123 Camera : 03 01 00 00 08 04
126 In this example, you notice the "03" and "04" specifying the start
127 and stop of the packet. Also, you notice the second byte in the
128 Computer packet is "01". The camera responds with the above packet,
129 and low and behold, you see the number 8 in the same packet. It
130 would appear, initially, that the second byte is used as a command
131 byte, and that "01" specifies the camera to return the number of
132 pictures. This may very well be right, but don't jump into it yet.
133 Make sure you look at a bunch of similar situations to confirm this.
134 (Again, notice the "ACK" sent by the computer).
136 5. Most protocols have a "data size" byte(s) in data packets. Let's
137 say that you told the camera to retrieve thumbnail 8 and you get
140 Computer: 03 02 00 00 08 04
141 Camera : 03 02 00 0F (15 bytes) 04
144 OK, here's a brief breakdown of this transaction:
146 -Looks like the command to retrieve a thumbnail is "02" (2nd byte
147 in the computer packet), and that the byte that is "08" specifies
148 which thumbnail to return.
149 -The camera responds with a "02" in the command field, specifying
150 it is returning a thumbnail, and then sends "0F", and 15 bytes of
152 -It looks like the byte "0F" specifies how many bytes are after it
153 in the same packet. This is a data size byte.
154 (Note: this is a simplistic example. No thumbnail will only be 15
155 bytes :) this leads up to the next thing to consider)
157 6. Most protocols have an "order" or "counter" byte. This is used so
158 that, in large data transfers where the picture may be split up
159 into several different packets, the computer knows how to reassemble
160 all the data. The entire thumbnail more than likely will not be
161 contained in a single packet for logistical reasons, so they break
162 up the data into many different packets and give each packet a unique
163 number (or ``order'' byte). Let's say you told your camera to return
164 thumbnail 8 (which is, as mentioned, pretty big), and you get the
167 Computer: 02 03 00 00 08 03
168 Camera : 02 03 00 0F (15 bytes) 03
170 Camera : 02 03 01 0F (15 bytes) 03
172 Camera : 02 03 02 0F (15 bytes) 03
174 ... 5 more packets and ACKs ...
175 Camera : 02 03 08 09 (9 bytes) 03
178 You notice that the 3rd byte of each of the camera packets increments
179 with each packet sent from the camera. This looks like it is an
180 order (counter) byte. the computer can then reassemble the data
181 from all the packets in order to reproduce the image.
183 7. Most protocols have some sort of error detection byte(s) at the end
184 of the packet. This is usually a simple checksum (summation of bytes),
185 or a CRC (a somewhat complex algorithm that reduces the probability
186 of mis-diagnosing a packet with errors by magnitudes). These bytes
187 can take into account only the data, or maybe the entire packet
188 excluding those error detection bytes. If this isn't a known scheme,
189 this winds up being the hardest part of reimplementing the protocol.
190 Lets take the above example again, this time we'll add a couple
191 bytes on the end for error detection:
193 Computer: 02 03 00 00 08 03
194 Camera : 02 03 00 0F (15 bytes) 0f 02 03
196 Camera : 02 03 01 0F (15 bytes) 0e 00 03
198 Camera : 02 03 01 0F (15 bytes) fa d0 03
200 Camera : 02 03 02 0F (15 bytes) fa d0 03
202 ... 5 more packets and ACKs
203 Camera : 02 03 08 09 (9 bytes) d7 38 03
206 Notice how the error detection bytes are usually different for each
207 packet. These may be checksums, or CRC's, or something else. Only
208 way to find out really is to try each one, on different combinations
209 of packet parts (data, order byte, command byte, etc...) and see
210 if you get the same thing. Try this on the shorter packets to make
213 Look at one more thing that sticks out in this transaction: for packet
214 with order byte ``01'', the Computer responded with a "02''. and
215 the Camera then resent the same packet it just did. This shows that
216 the NAK byte is "02", and this could happen because maybe the error
217 detection bytes didn't match with the data, or maybe something else
218 happened. either way, the camera resent the last packet, and now
219 you know how the camera can recover from transfer errors. If you
220 didn't get the packet you were expecting, send the camera a NAK
221 and it will resend the same packet again.
223 2 Understanding the gPhoto2 Design
225 The gPhoto2 design is the same three-tiered structure that has worked
226 extremely well in the past with other software packages. Here is a
227 listing of the 3 tiers:
237 2.1 Role of the Camera Library
239 The camera library is in charge of talking directly with the camera.
240 The library uses the gPhoto2 Camera API in order to provide a common
241 access-method for the library itself. Being dynamically linked, the
242 libraries are loaded at run-time depending on the camera model the
243 end-user would like to access.
245 In order to provide flexilibity with variations in camera design, there
246 are camera ``abilities'' which list, well, the abilities of each camera
247 model. Some camera may support serial port connections only, while
248 others may be able to use USB and a serial port. We've run into cameras
249 that don't support thumbnailing on the camera so there is an ``abilities''
250 field to specify whether or not the camera supports thumbnailing.
251 The ``abilities'' also list other things such as supported serial
252 transfer speeds, file deletion, and other functionality.
254 The camera libraries only make functions calls to the I/O library and
257 There is more information on the specifics of the camera library in
258 section 3 of this document.
260 2.2 Role of the I/O Library
262 The gPhoto2 I/O library is a platform-independent communications library
263 that support serial, parallel, USB, firewire, and network connections.
264 It is a work-in-progress with a constantly expanding list of supported
265 platforms. This library uses the gPhoto2 I/O library API for accessing
266 communications devices. It enumerates the devices available on a system,
267 and provides read/write access.
269 The camera libraries all use the I/O library for communications with
270 the cameras. By doing having all communications go through a single
271 library, the camera libraries become as portable as the I/O library.
272 Porting gPhoto2 to other platforms become extremely easy.
274 There is more information on the specifics of the I/O library in section
277 2.3 Role of the Front-end
279 The front-end is the application that the user interacts with. It is
280 usually a command-line program, or a graphical point-and-click interface.
281 The front-end talks only with the gPhoto2 core in order to retrieve
282 pictures and perform other functions with the camera.
284 2.4 Role of the gPhoto2 Core
286 The gPhoto2 ``core'' is the heart of gPhoto2. It provides services
287 to both the camera libraries and the front-ends. Most of the services
288 deal with error-checking and enumeration of devices (cameras, I/O
289 devices, etc...). The core performs validity checking on data passed
290 to/from the front-end or the camera library.
292 You could consider the core a translator/interpreter/spell-checker/army-general
293 in the ``big picture'' of gPhoto2. It does the grunt-work and performs
294 the coordination of the other parts.
296 3 Implementing the Library
298 gPhoto2 camera libraries use the gPhoto2 Camera API (CAPI) for implementation.
299 Here is a listing of the CAPI functions:
315 camera_file_get_preview
334 Section 3.1 details the purpose of each of these functions, while Section
335 3.2 discusses how to use the I/O library.
339 The CAPI provides the full set of functions for doing various tasks
340 with the camera. All CAPI functions return either GP_OK for succesful
341 execution , or GP_ERROR for a failure of execution
343 What follows is a listing of the functions, including prototypes and
348 Purpose: Retrieve the unique id for the camera library.
350 Prototype: int camera_id (CameraText *id);
354 CameraText *id : unique string to represent the camera library
357 In order to guarantee that only once instance of the camera library
358 is loaded for each instance of the core, the camera library must copy
359 a unique string into the ``id''. Please consult the gPhoto developers
360 to determine which string you should use.
365 int camera_id(CameraText *id) {
367 strcpy(id->text, ``my-unique-string'');
373 3.1.2 camera_abilities
375 Purpose: Retrieve the list of supported cameras and the abilities for
378 Prototype: int camera_abilities (CameraAbilitiesList *list);
382 CameraAbilities *abilities : the list of abilities for the supported
385 int *count : the number of
389 Purpose: Initialize the camera
391 Prototype: int camera_init (Camera *camera, CameraInit *init);
397 Purpose: Close the camera
399 Prototype: int camera_exit (Camera *camera);
403 3.1.5 camera_file_list
405 Purpose: List the files in a particular folder on the camera
407 Prototype: int camera_file_list(Camera *camera, CameraList *list, char
412 3.1.6 camera_folder_list
414 Purpose: List the subfolders in a particular folder on the camera
416 Prototype: int camera_folder_list(Camera *camera, CameraList *list,
421 3.1.7 camera_file_get
423 Purpose: Retrieve a file from the camera
425 Prototype: int camera_file_get (Camera *camera, CameraFile *file, char
426 *folder, char *filename);
430 3.1.8 camera_file_get_preview
432 Purpose: Retrieve a file's preview from the camera
434 Prototype: int camera_file_get_preview (Camera *camera, CameraFile
435 *file, char *folder, char *filename);
439 3.1.9 camera_file_put
441 Purpose: Place (upload) a file to the camera
443 Prototype: int camera_file_put (Camera *camera, CameraFile *file, char
448 3.1.10 camera_file_delete
450 Purpose: Delete a file from the camera
452 Prototype: int camera_file_delete (Camera *camera, char *folder, char
457 3.1.11 camera_config_get
459 Purpose: Retrieve the configuration window.
461 Prototype: int camera_config_get (Camera *camera, CameraWidget *window);
465 3.1.12 camera_config_set
467 Purpose: Set camera configuration
469 Prototype: int camera_config_set (Camera *camera, CameraSetting *setting,
474 3.1.13 camera_capture
476 Purpose: Retrieve live data from the camera
478 Prototype: int camera_capture (Camera *camera, CameraFile *file, CameraCaptureInfo
483 3.1.14 camera_summary
485 Purpose: Retrieve the camera summary information
487 Prototype: int camera_summary (Camera *camera, CameraText *summary);
493 Purpose: Retrieve the camera user's guide (manual)
495 Prototype: int camera_manual (Camera *camera, CameraText *manual);
501 Purpose: Retrieve information about the camera library
503 Prototype: int camera_about (Camera *camera, CameraText *about);
507 3.2 The gPhoto2 I/O Library