darktable/libgphoto2
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
2f627cb99869db52f252d5d014b0f87e94de6709
libgphoto2/doc/camlib_devel.lyx
Hans Ulrich Niedermann 2c801c35bb moved doc files from docs/ to doc/ 
git-svn-id: https://svn.code.sf.net/p/gphoto/code/trunk/libgphoto2@2481 67ed7778-7388-44ab-90cf-0a291f65f57c
2001-10-11 15:00:05 +00:00

1097 lines
22 KiB
Plaintext
Raw Blame History

#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 occured.
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 succesful 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
Reference in New Issue View Git Blame Copy Permalink