path: root/doc/camlib_devel.lyx

#LyX 1.1 created this file. For more info see http://www.lyx.org/
\lyxformat 2.15
\textclass linuxdoc
\language default
\inputencoding latin1
\fontscheme default
\graphics default
\paperfontsize default
\spacing single 
\papersize Default
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Title
\added_space_top vfill \added_space_bottom vfill 
gPhoto2 Camera Library Developer's Guide
\layout Author

Scott Fritzinger
\newline 
2000-07-26
\newline 
Revision 1
\layout Standard


\begin_inset LatexCommand \tableofcontents{}

\end_inset 


\layout Section

Reverse Engineering the Camera Protocol
\layout Standard

The most difficult part for most developers is obtaining the transfer protocol.
 If the OEM's are lucky enough, they will simply provide us with the protocol
 specifications for their cameras and the drivers will be written at no
 cost to them.
 Most OEM's refuse to do so though, citing trade secrets or company policy;
 this is truly unfortunate in that they have effectively told their own
 customers who use operating systems other than Windows and the Mac that
 they don't want their future business and that they aren't valued customer
 to begin with.
\layout Standard

When OEM's do not cooperate, the developer is left to determine the protocol
 him/herself through reverse engineering.
 
\layout Subsection

Sniffing the Protocol
\layout Standard

What follows are the most common setups for sniffing camera protocol traffic.
 In all setups, a host computer runs the native camera drivers.; typically,
 the Windows serial port drivers are used for reverse engineering.
 The drivers are run through a series of functions that include getting
 a picture index, downloading thumbnails, download full images, deleting
 images, camera configuration options, in addition to any other features
 a camera might have.
 During these operations, one or more of the following methods are used
 to capture the communication between the host computer and the camera.
\layout Subsubsection

Serial Repeater
\layout Standard

A serial repeater consists of the host computer, a computer used as a repeater,
 and the camera.
 The setup is shown in figure .
\layout Standard

The repeater runs special software which reads data from one serial port,
 logs the communication, and then outputs the data to the other serial port.
 Data that is from the host computer to the camera and from the camera to
 the host computer is logged sequentially in a single log file.
 Information logged includes hexadecimal data values, direction of the communica
tion, as well as time stamps for synchronization.
 An example sniffer to use for this configuration is 
\begin_inset Quotes eld
\end_inset 

sersniff
\begin_inset Quotes erd
\end_inset 

.
\layout Subsubsection


\begin_inset Quotes eld
\end_inset 

Y
\begin_inset Quotes erd
\end_inset 

 Serial Cable
\layout Standard

To avoid using two computers, a Y serial cable can be used.
 The 
\begin_inset Quotes eld
\end_inset 

trunk
\begin_inset Quotes erd
\end_inset 

 end of the serial cable attaches to the camera's serial transfer cable,
 while the two 
\begin_inset Quotes eld
\end_inset 

branches
\begin_inset Quotes erd
\end_inset 

 plug in to two serial ports on the host computer.
 Figure shows this setup.
\layout Standard

The camera drivers use one of the serial ports on the host computer, while
 the other port is opened with a hexadecimal monitor application that dumps
 all communications on the port to a file.
 The downside to this approach is the developer would have to determine
 which sets of data was generated by the camera or the host computer.
 Also, a Y cable would have to be either built or purchased from an electronics
 supply store.
\layout Subsubsection

Virtual Device Driver Hooks
\layout Standard

The Windows platform allows virtual device drivers to 
\begin_inset Quotes eld
\end_inset 

hook
\begin_inset Quotes erd
\end_inset 

 into other drivers to provide additional functionality or feature enhancements.
 A combination GUI and device driver named PortMon by Systems Internals
 is a communications debugging utility that hooks into the existing Windows
 serial device driver (vcomm.vxd) and logs communications.
 Figure shows this equipment arrangement.
\layout Standard

This setup allows the developer to not use any extra hardware by simply
 relying on software.
 This is perhaps the easiest method for capturing camera data.
\layout Subsection

Making Sense Out of the Protocol
\layout Standard

What follows are some pointers on decoding camera protocols.
 It uses a protocol that isn't really any camera protocol in particular,
 but should demonstrate some commonalities between most camera protocols.
\layout Enumerate

Cameras like to ping.
 This is the in the form of an "ACK"" command that is different for different
 cameras.
 Basically, it is usually a short packet (probably 1 byte) that is sent
 both ways in order for the camera to know the computer is there or vice
 versa.
 It is also sometimes used to wake up a camera that has gone into power-save
 mode.
 It usually starts out the communications, as well as confirms each packet
 in any sort of "mass" transfer.
 The opposite, a "NAK", is sent to basically say the last packet was not
 received, or an error has occurred.
 Again, this is usually just a single byte as well.
\newline 

\newline 
Example:
\newline 
Computer: 01
\newline 
Camera : 01
\newline 

\newline 
The Camera sent an ACK ("01") and the Computer responded with an ACK as
 well.
\layout Enumerate

Transfers are usually in "reverse network order", meaning least significant
 bytes come before most significant bytes.
 For example, 
\begin_inset Quotes eld
\end_inset 

00 08
\begin_inset Quotes erd
\end_inset 

 should actually be reassembled as 
\begin_inset Quotes eld
\end_inset 

08 00
\begin_inset Quotes erd
\end_inset 

.
 
\layout Enumerate

Most protocols use starting and stopping bytes.
 
\newline 

\newline 
Example:
\newline 
Computer: 03 50 00 0f e0 04 
\newline 
Camera : 03 03 00 3f 03 04 
\newline 
Computer: 01 
\newline 

\newline 
For this example, notice the packets begin with "03" and end with "04" (don't
 pay attention to what is between them).
 Also notice the Computer sent an "ACK" to confirm it got the packet.
\layout Enumerate

Packets usually have a "command" byte, which tells either the computer or
 the camera what to do.
 Let's say you told the software to retrieve the number of pictures, which
 at the time happened to be "8", and you got the following:
\newline 

\newline 
Computer: 03 01 00 00 00 04 
\newline 
Camera : 03 01 00 00 08 04 
\newline 
Computer: 01
\newline 

\newline 
In this example, you notice the "03" and "04" specifying the start and stop
 of the packet.
 Also, you notice the second byte in the Computer packet is "01".
 The camera responds with the above packet, and low and behold, you see
 the number 8 in the same packet.
 It would appear, initially, that the second byte is used as a command byte,
 and that "01" specifies the camera to return the number of pictures.
 This may very well be right, but don't jump into it yet.
 Make sure you look at a bunch of similar situations to confirm this.
 (Again, notice the "ACK" sent by the computer).
\layout Enumerate

Most protocols have a "data size" byte(s) in data packets.
 Let's say that you told the camera to retrieve thumbnail 8 and you get
 the following:
\newline 

\newline 
Computer: 03 02 00 00 08 04
\newline 
Camera : 03 02 00 0F (15 bytes) 04
\newline 
Computer: 01 
\newline 

\newline 
OK, here's a brief breakdown of this transaction:
\newline 

\newline 
-Looks like the command to retrieve a thumbnail is "02" (2nd byte in the
 computer packet), and that the byte that is "08" specifies which thumbnail
 to return.
\newline 
-The camera responds with a "02" in the command field, specifying it is
 returning a thumbnail, and then sends "0F", and 15 bytes of data.
 
\newline 
-It looks like the byte "0F" specifies how many bytes are after it in the
 same packet.
 This is a data size byte.
 
\newline 
(Note: this is a simplistic example.
 No thumbnail will only be 15 bytes :) this leads up to the next thing to
 consider)
\layout Enumerate

Most protocols have an "order" or "counter" byte.
 This is used so that, in large data transfers where the picture may be
 split up into several different packets, the computer knows how to reassemble
 all the data.
 The entire thumbnail more than likely will not be contained in a single
 packet for logistical reasons, so they break up the data into many different
 packets and give each packet a unique number (or 
\begin_inset Quotes eld
\end_inset 

order
\begin_inset Quotes erd
\end_inset 

 byte).
 Let's say you told your camera to return thumbnail 8 (which is, as mentioned,
 pretty big), and you get the following:
\newline 

\newline 
Computer: 02 03 00 00 08 03 
\newline 
Camera : 02 03 00 0F (15 bytes) 03 
\newline 
Computer: 01
\newline 
Camera : 02 03 01 0F (15 bytes) 03 
\newline 
Computer: 01
\newline 
Camera : 02 03 02 0F (15 bytes) 03
\newline 
Computer: 01
\newline 
...
 5 more packets and ACKs ...
\newline 
Camera : 02 03 08 09 (9 bytes) 03
\newline 
Computer: 01
\newline 

\newline 
You notice that the 3rd byte of each of the camera packets increments with
 each packet sent from the camera.
 This looks like it is an order (counter) byte.
 the computer can then reassemble the data from all the packets in order
 to reproduce the image.
\layout Enumerate

Most protocols have some sort of error detection byte(s) at the end of the
 packet.
 This is usually a simple checksum (summation of bytes), or a CRC (a somewhat
 complex algorithm that reduces the probability of mis-diagnosing a packet
 with errors by magnitudes).
 These bytes can take into account only the data, or maybe the entire packet
 excluding those error detection bytes.
 If this isn't a known scheme, this winds up being the hardest part of reimpleme
nting the protocol.
 Lets take the above example again, this time we'll add a couple bytes on
 the end for error detection:
\newline 

\newline 
Computer: 02 03 00 00 08 03
\newline 
Camera : 02 03 00 0F (15 bytes) 0f 02 03
\newline 
Computer: 01
\newline 
Camera : 02 03 01 0F (15 bytes) 0e 00 03
\newline 
Computer: 02
\newline 
Camera : 02 03 01 0F (15 bytes) fa d0 03
\newline 
Computer: 01
\newline 
Camera : 02 03 02 0F (15 bytes) fa d0 03
\newline 
Computer: 01
\newline 
...
 5 more packets and ACKs
\newline 
Camera : 02 03 08 09 (9 bytes) d7 38 03
\newline 
Computer: 01
\newline 

\newline 
Notice how the error detection bytes are usually different for each packet.
 These may be checksums, or CRC's, or something else.
 Only way to find out really is to try each one, on different combinations
 of packet parts (data, order byte, command byte, etc...) and see if you get
 the same thing.
 Try this on the shorter packets to make life easier.
\newline 

\newline 
Look at one more thing that sticks out in this transaction: for packet with
 order byte 
\begin_inset Quotes eld
\end_inset 

01
\begin_inset Quotes erd
\end_inset 

, the Computer responded with a "02
\begin_inset Quotes erd
\end_inset 

.
 and the Camera then resent the same packet it just did.
 This shows that the NAK byte is "02", and this could happen because maybe
 the error detection bytes didn't match with the data, or maybe something
 else happened.
 either way, the camera resent the last packet, and now you know how the
 camera can recover from transfer errors.
 If you didn't get the packet you were expecting, send the camera a NAK
 and it will resend the same packet again.
\layout Section

Understanding the gPhoto2 Design
\layout Standard

The gPhoto2 design is the same three-tiered structure that has worked extremely
 well in the past with other software packages.
 Here is a listing of the 3 tiers:
\layout Itemize

the camera library
\layout Itemize

the I/O library
\layout Itemize

the front-end
\layout Itemize

the 
\begin_inset Quotes eld
\end_inset 

core
\begin_inset Quotes erd
\end_inset 


\layout Subsection

Role of the Camera Library
\layout Standard

The camera library is in charge of talking directly with the camera.
 The library uses the gPhoto2 Camera API in order to provide a common access-met
hod for the library itself.
 Being dynamically linked, the libraries are loaded at run-time depending
 on the camera model the end-user would like to access.
 
\layout Standard

In order to provide flexilibity with variations in camera design, there
 are camera 
\begin_inset Quotes eld
\end_inset 

abilities
\begin_inset Quotes erd
\end_inset 

 which list, well, the abilities of each camera model.
 Some camera may support serial port connections only, while others may
 be able to use USB and a serial port.
 We've run into cameras that don't support thumbnailing on the camera so
 there is an 
\begin_inset Quotes eld
\end_inset 

abilities
\begin_inset Quotes erd
\end_inset 

 field to specify whether or not the camera supports thumbnailing.
 The 
\begin_inset Quotes eld
\end_inset 

abilities
\begin_inset Quotes erd
\end_inset 

 also list other things such as supported serial transfer speeds, file deletion,
 and other functionality.
\layout Standard

The camera libraries only make functions calls to the I/O library and to
 the gPhoto2 core.
\layout Standard

There is more information on the specifics of the camera library in section
 3 of this document.
\layout Subsection

Role of the I/O Library
\layout Standard

The gPhoto2 I/O library is a platform-independent communications library
 that support serial, parallel, USB, firewire, and network connections.
 It is a work-in-progress with a constantly expanding list of supported
 platforms.
 This library uses the gPhoto2 I/O library API for accessing communications
 devices.
 It enumerates the devices available on a system, and provides read/write
 access.
\layout Standard

The camera libraries all use the I/O library for communications with the
 cameras.
 By doing having all communications go through a single library, the camera
 libraries become as portable as the I/O library.
 Porting gPhoto2 to other platforms become extremely easy.
\layout Standard

There is more information on the specifics of the I/O library in section
 3 of this document.
\layout Subsection

Role of the Front-end
\layout Standard

The front-end is the application that the user interacts with.
 It is usually a command-line program, or a graphical point-and-click interface.
 The front-end talks only with the gPhoto2 core in order to retrieve pictures
 and perform other functions with the camera.
\layout Subsection

Role of the gPhoto2 Core
\layout Standard

The gPhoto2 
\begin_inset Quotes eld
\end_inset 

core
\begin_inset Quotes erd
\end_inset 

 is the heart of gPhoto2.
 It provides services to both the camera libraries and the front-ends.
 Most of the services deal with error-checking and enumeration of devices
 (cameras, I/O devices, etc...).
 The core performs validity checking on data passed to/from the front-end
 or the camera library.
\layout Standard

You could consider the core a translator/interpreter/spell-checker/army-general
 in the 
\begin_inset Quotes eld
\end_inset 

big picture
\begin_inset Quotes erd
\end_inset 

 of gPhoto2.
 It does the grunt-work and performs the coordination of the other parts.
\layout Section

Implementing the Library
\layout Standard

gPhoto2 camera libraries use the gPhoto2 Camera API (CAPI) for implementation.
 Here is a listing of the CAPI functions: 
\layout Standard

camera_id 
\layout Standard

camera_abilities 
\layout Standard

camera_init 
\layout Standard

camera_exit
\layout Standard

camera_folder_list
\layout Standard

camera_file_list
\protected_separator 

\layout Standard

camera_file_get
\layout Standard

camera_file_get_preview
\layout Standard

camera_file_put 
\layout Standard

camera_file_delete 
\layout Standard

camera_config_get
\layout Standard

camera_config_set
\layout Standard

camera_capture
\layout Standard

camera_summary
\layout Standard

camera_manual
\layout Standard

camera_about
\newline 

\layout Standard

Section 3.1 details the purpose of each of these functions, while Section
 3.2 discusses how to use the I/O library.
\layout Subsection

Camera API
\layout Standard

The CAPI provides the full set of functions for doing various tasks with
 the camera.
 All CAPI functions return either GP_OK for successful execution , or GP_ERROR
 for a failure of execution
\layout Standard

What follows is a listing of the functions, including prototypes and data
 exchange:
\layout Subsubsection

camera_id
\layout Standard


\series bold 
Purpose: 
\series default 
Retrieve the unique id for the camera library.
\layout Standard


\series bold 
Prototype: 
\series default 
int camera_id (CameraText *id); 
\layout Standard


\series bold 
Arguments: 
\layout Standard

CameraText *id : unique string to represent the camera library
\newline 

\layout Standard

In order to guarantee that only once instance of the camera library is loaded
 for each instance of the core, the camera library must copy a unique string
 into the 
\begin_inset Quotes eld
\end_inset 

id
\begin_inset Quotes erd
\end_inset 

.
 Please consult the gPhoto developers to determine which string you should
 use.
\newline 

\layout Standard


\series bold 
Example:
\layout Standard

int camera_id(CameraText *id) {
\layout Standard

strcpy(id->text, 
\begin_inset Quotes eld
\end_inset 

my-unique-string
\begin_inset Quotes erd
\end_inset 

);
\layout Standard

return (GP_OK);
\layout Standard

}
\layout Subsubsection

camera_abilities
\layout Standard


\series bold 
Purpose: 
\series default 
Retrieve the list of supported cameras and the abilities for each camera
\layout Standard


\series bold 
Prototype: 
\series default 
int camera_abilities (CameraAbilitiesList *list); 
\layout Standard


\series bold 
Arguments: 
\series default 
d
\layout Standard

CameraAbilities *abilities : the list of abilities for the supported cameras
\layout Standard

int *count : the number of 
\layout Subsubsection

camera_init
\layout Standard


\series bold 
Purpose: 
\series default 
Initialize the camera
\layout Standard


\series bold 
Prototype: 
\series default 
int camera_init (Camera *camera, CameraInit *init); 
\layout Standard


\series bold 
Arguments: 
\series default 
d
\layout Subsubsection

camera_exit 
\layout Standard


\series bold 
Purpose: 
\series default 
Close the camera
\layout Standard


\series bold 
Prototype: 
\series default 
int camera_exit (Camera *camera); 
\layout Standard


\series bold 
Arguments: 
\series default 
d
\layout Subsubsection

camera_file_list
\layout Standard


\series bold 
Purpose: 
\series default 
List the files in a particular folder on the camera
\layout Standard


\series bold 
Prototype: 
\series default 
int camera_file_list(Camera *camera, CameraList *list, char *folder); 
\layout Standard


\series bold 
Arguments: 
\series default 
d
\layout Subsubsection

camera_folder_list
\layout Standard


\series bold 
Purpose: 
\series default 
List the subfolders in a particular folder on the camera
\layout Standard


\series bold 
Prototype: 
\series default 
int camera_folder_list(Camera *camera, CameraList *list, char *folder);
 
\layout Standard


\series bold 
Arguments: 
\series default 
d
\layout Subsubsection

camera_file_get
\layout Standard


\series bold 
Purpose: 
\series default 
Retrieve a file from the camera
\layout Standard


\series bold 
Prototype: 
\series default 
int camera_file_get (Camera *camera, CameraFile *file, char *folder, char
 *filename); 
\layout Standard


\series bold 
Arguments: 
\series default 
d
\layout Subsubsection

camera_file_get_preview
\layout Standard


\series bold 
Purpose: 
\series default 
Retrieve a file's preview from the camera
\layout Standard


\series bold 
Prototype: 
\series default 
int camera_file_get_preview (Camera *camera, CameraFile *file, char *folder,
 char *filename); 
\layout Standard


\series bold 
Arguments: 
\series default 
d
\layout Subsubsection

camera_file_put
\layout Standard


\series bold 
Purpose: 
\series default 
Place (upload) a file to the camera
\layout Standard


\series bold 
Prototype: 
\series default 
int camera_file_put (Camera *camera, CameraFile *file, char *folder); 
\layout Standard


\series bold 
Arguments: 
\series default 
d
\layout Subsubsection

camera_file_delete
\layout Standard


\series bold 
Purpose: 
\series default 
Delete a file from the camera
\layout Standard


\series bold 
Prototype: 
\series default 
int camera_file_delete (Camera *camera, char *folder, char *filename); 
\layout Standard


\series bold 
Arguments: 
\series default 
d
\layout Subsubsection

camera_config_get
\layout Standard


\series bold 
Purpose: 
\series default 
Retrieve the configuration window.
\layout Standard


\series bold 
Prototype: 
\series default 
int camera_config_get (Camera *camera, CameraWidget *window); 
\layout Standard


\series bold 
Arguments: 
\series default 
d
\layout Subsubsection

camera_config_set
\layout Standard


\series bold 
Purpose: 
\series default 
Set camera configuration
\layout Standard


\series bold 
Prototype: 
\series default 
int camera_config_set (Camera *camera, CameraSetting *setting, int count);
 
\layout Standard


\series bold 
Arguments: 
\series default 
d
\layout Subsubsection

camera_capture
\layout Standard


\series bold 
Purpose: 
\series default 
Retrieve live data from the camera
\layout Standard


\series bold 
Prototype: 
\series default 
int camera_capture (Camera *camera, CameraFile *file, CameraCaptureInfo
 *info); 
\layout Standard


\series bold 
Arguments: 
\series default 
d
\layout Subsubsection

camera_summary
\layout Standard


\series bold 
Purpose: 
\series default 
Retrieve the camera summary information
\layout Standard


\series bold 
Prototype: 
\series default 
int camera_summary (Camera *camera, CameraText *summary); 
\layout Standard


\series bold 
Arguments: 
\series default 
d
\layout Subsubsection

camera_manual
\layout Standard


\series bold 
Purpose: 
\series default 
Retrieve the camera user's guide (manual)
\layout Standard


\series bold 
Prototype: 
\series default 
int camera_manual (Camera *camera, CameraText *manual); 
\layout Standard


\series bold 
Arguments: 
\series default 
d
\layout Subsubsection

camera_about
\layout Standard


\series bold 
Purpose: 
\series default 
Retrieve information about the camera library
\layout Standard


\series bold 
Prototype: 
\series default 
int camera_about (Camera *camera, CameraText *about);
\layout Standard


\series bold 
Arguments: 
\series default 
d
\layout Subsection

The gPhoto2 I/O Library
\the_end