6914537184
git-svn-id: https://svn.code.sf.net/p/gphoto/code/trunk/libgphoto2@768 67ed7778-7388-44ab-90cf-0a291f65f57c
188 lines
6.9 KiB
Plaintext
188 lines
6.9 KiB
Plaintext
<!doctype linuxdoc system>
|
|
|
|
<!-- LyX 1.1 created this file. For more info see http://www.lyx.org/ -->
|
|
<article>
|
|
<title>
|
|
gPhoto Camera Library Developer's Guide
|
|
</title>
|
|
<toc>
|
|
<sect>
|
|
Reverse Engineering the Camera Protocol
|
|
<sect1>
|
|
Sniffing the Protocol
|
|
<sect1>
|
|
Making Sense Out of the Protocol
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
<enum>
|
|
<item>
|
|
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.
|
|
|
|
Example:
|
|
Computer: 01
|
|
Camera : 01
|
|
|
|
The Camera sent an ACK ("01")
|
|
and the Computer responded with an ACK as well.
|
|
<item>
|
|
Transfers are usually in "reverse network order", meaning least
|
|
significant bytes come before most significant bytes. Ex: 00 08 should actually
|
|
be "put together" as 08 00 This is usually only the case with the
|
|
data parts of packets. (more on that later).
|
|
<item>
|
|
Most protocols use starting and stopping bytes.
|
|
|
|
Example:
|
|
Computer: 03
|
|
50 00 0f e0 04
|
|
Camera : 03 03 00 3f 03 04
|
|
Computer: 01
|
|
|
|
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.
|
|
<item>
|
|
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:
|
|
|
|
Computer: 03 01 00 00 00 04
|
|
Camera : 03 01 00 00 08
|
|
04
|
|
Computer: 01
|
|
|
|
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).
|
|
<item>
|
|
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:
|
|
|
|
Computer:
|
|
03 02 00 00 08 04
|
|
Camera : 03 02 00 0F (15 bytes) 04
|
|
Computer: 01
|
|
|
|
OK, here's
|
|
a brief breakdown of this transaction:
|
|
|
|
-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.
|
|
-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.
|
|
-It looks
|
|
like the byte "0F" specifies how many bytes are after it in the same
|
|
packet. This is a data size byte.
|
|
(Note: this is a simplistic example. No
|
|
thumbnail will only be 15 bytes :) this leads up to the next thing to consider)
|
|
<item>
|
|
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 "order" byte). Let's say you
|
|
told your camera to return thumbnail 8 (which is, as mentioned, pretty big),
|
|
and you get the following:
|
|
|
|
Computer: 02 03 00 00 08 03
|
|
Camera : 02 03 00 0F
|
|
(15 bytes) 03
|
|
Computer: 01
|
|
Camera : 02 03 01 0F (15 bytes) 03
|
|
Computer: 01
|
|
Camera
|
|
: 02 03 02 0F (15 bytes) 03
|
|
Computer: 01
|
|
... 5 more packets and ACKs ...
|
|
Camera
|
|
: 02 03 08 09 (9 bytes) 03
|
|
Computer: 01
|
|
|
|
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.
|
|
<item>
|
|
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 reimplementing
|
|
the protocol. Lets take the above example again, this time we'll add a couple
|
|
bytes on the end for error detection:
|
|
|
|
Computer: 02 03 00 00 08 03
|
|
Camera :
|
|
02 03 00 0F (15 bytes) 0f 02 03
|
|
Computer: 01
|
|
Camera : 02 03 01 0F (15 bytes)
|
|
0e 00 03
|
|
Computer: 02
|
|
Camera : 02 03 01 0F (15 bytes) fa d0 03
|
|
Computer: 01
|
|
Camera
|
|
: 02 03 02 0F (15 bytes) fa d0 03
|
|
Computer: 01
|
|
... 5 more packets and ACKs
|
|
Camera
|
|
: 02 03 08 09 (9 bytes) d7 38 03
|
|
Computer: 01
|
|
|
|
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.
|
|
|
|
Look
|
|
at one more thing that sticks out in this transaction: for packet with order
|
|
byte "01", the Computer responded with a "02". 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.
|
|
</enum>
|
|
</p><sect>
|
|
Understanding the gPhoto2 Structure
|
|
<sect1>
|
|
Role of the gPhoto2 Core
|
|
<sect1>
|
|
Role of the Camera Library
|
|
<sect1>
|
|
Role of the Front-end
|
|
<sect>
|
|
Implementing the Library
|
|
<sect1>
|
|
Camera Library API
|
|
<sect1>
|
|
The gPhoto2 IO Library
|
|
|
|
|
|
</article>
|