1S10sh readme
2
3OVERVIEW
4
5 S10sh is a Canon PowerShot digital camera driver that
6 implements a DOS filesystem like interface. Using S10sh you can
7 download/explore the images captured with your digital camera.
8 This software is developed by Salvatore Sanfilippo that can
9 be contacted at the email address <antirez@invece.org>, and
10 is distributed under the terms of the GNU public license version 2.
11
12 This driver works at least with the following PowerShot models:
13
14 PS10
15 PS20
16 PS100 (Digital Ixus)
17 A50
18 Pro70
19
20 It has been reported by various people that the following models work, but I
21 don't have direct access to these cameras. Your mileage may vary:
22
23 Digital Ixus V3
24 Powershot S30
25 Powershot A60
26 EOS-10D
27
28 This driver was tested with the following Unix-like systems:
29
30 (Serial) Linux 2.2.x -- glibc
31 (Serial) Linux 2.2.x -- libc5
32 (USB) Linux 2.4.0-test1-ac19 for USB support -- libc5
33 (USB) Linux 2.2.16 (+usb-2.3.99-pre7-1-for-2.2.14) -- glibc 2.1.3
34
35 The driver was developed using the serial and USB protocol description
36 that is shipped with the gphoto's driver. The news about the protocol
37 discovered coding s10sh was merged to the gphoto's description.
38
39DOWNLOAD
40
41 You can find the latest release of this software at:
42
43 http://www.reynoldsnet.org/s10sh/s10sh-0.2.1.tar.gz
44
45 After John Reynolds took pseudo-ownership of the code after he could not get
46 any reply from Salvatore.
47
48AUTHORS
49
50Philippe Marzouk <bullmali@afribone.net.ml>
51 A50 support improvements
52
53Edouard Lafargue <lafargue@oslo.geco-prakla.slb.com>
54 Endianess issue
55 New serial commands implementation.
56 Valuable bugfixing.
57
58Martin Janzen <janzen@magix.com.sg>
59 Support for the S100
60 Camera USB detection cleanup
61
62John Reynolds <johnjen@reynoldsnet.org>
63 <jreynold@sedona.ch.intel.com>
64 Enanched the configure script to find an already installed libusb
65 Case conversion of filenames
66 Local TZ date
67 Set atime/mtime in retrivied files
68 FreeBSD serial default device name fix
69 Some other minor fix
70 Added '-n' option to automatically retreive all 'new' images in batch
71 Maintainer of FreeBSD port
72 Maintainer of code after 0.2.0 and long silence from Salvatore :(
73
74Salvatore Sanfilippo <antirez@invece.org>
75 all the rest
76
77KNOWN BUGS
78
79* Serial protocol error recovering is primitive:
80
81 S10sh don't implement retrasmission and error recovery reliably.
82 Anyway error recovery implementation is quite simple, you can for
83 example just add a little buffer for old frames in the function that
84 sends the frames and when ACK isn't received resend the old frames,
85 also the resending should be applied in presence of an explicit request
86 from the camera (with a special ACK). Finally when old eot are received
87 they should be ACKnowledged.
88
89 Note that with USB there are not retrasmission problems.
90
91* Sometimes thumbnails download is broken, s10sh does not parse the Exif
92 header, but just search the JPG tags in order to understand where the
93 image starts.
94
95* The code is quite ugly, maybe I'll rewrite it in a clear way as library
96 some time.
97
98TODO
99
100 - Better error recovering for serial protocol.
101 - Support new PowerShot models.
102 - Encryption layer, Who would use a PowerShot as key-repository? :)
103
104WHY NOT GPHOTO?
105
106 This is just a text-only alternative for the Canon PowerShot users.
107 Without the efforts of the gphoto's developers, the developing of this
108 software might be more hard. Anyway I suggest to look at the latest
109 gphoto beta, the 0.5.x. Thanks gphoto developers!
110
111 JUST A NOTE -- the freesoftware strange world.
112
113 You can think I'm a stupid since instead to work at gphoto's canon
114 driver and use it in order to code s10sh I recoded it. Unfortunately
115 in the free software world this happens often, s10sh started as 40
116 lines of C code in order to understand why gphoto's canon driver did not
117 work with my camera, but with some additional coding it became an hack that
118 I used to download my photos, and finally a quite-usable software.
119 I'm planning to merge this two GPLed driver in order to obtain a
120 canon powershot lib, that join all the features and that will implement
121 an easy-to-use API.
122
123THANKS
124
125 gphoto developers For the cool program with many many
126 digital camera supported and for
127 protocol reverse engineering.
128
129 Christof Meerwald <cmeerw@web.de> For an important support and
130 bugs reported.
131
132 Canon For its closed-mind policy about
133 protocol specifications.
134
135 Linux USB team For the Linux USB support.
136
137 Johannes Erdfelt, Thomas Sailer For the libusb
138
139 Bull Afrique Mali <bullmali@afribone.net.ml> &&
140 Edouard Lafargue <lafargue@oslo.geco-prakla.slb.com> &&
141 Mikael Nystr�m <mikaeln@tripnet.se> For gphoto coding, protocol
142 and feedbacks.
143
144 Martin Janzen <janzen@magix.com.sg> S100 support.
145
146 Kevin Fenzi <kevin@scrye.com> S100 new USB Product ID.
147
148 David Grant <dave@reach.net> G1 product ID + patch.
149
150 GNU No comments.
151
152 See also the AUTHORS section for additional credits.
153
154PERFORMANCE
155
156 Serial: about 5500 bytes/s
157 USB: about 350000 bytes/s
158
159 the timer used has a 1 second resolution, if you download little files
160 with USB s10sh will display a not reliable information about transfer speed.
161
162HOW TO COMPILE
163
164 - Configure
165
166 Exec the ./configure script, that enables/disables readline and usb support.
167 This script try to guess the right default for readline, if the compilation
168 will fail try to disable the readline support answering "n".
169 The USB support is turned off by default, if you have the USB support in your
170 kernel (2.4-test1-ac19 should work) try to ask yes, USB performances are
171 drastically higher than serial performances.
172
173 - How to Build the binary
174
175 If you compile with the USB support first compile the libusb, shipped
176 with the s10sh tarball:
177
178 cd libusb
179 ./configure
180 make
181 cd ..
182
183 make install is NOT needed
184 if you experience compilation truble with libusb please, don't mail me,
185 mail instead the libusb authors.
186
187 The next step (the first if you don't compile with USB support) is
188 to type 'make', if it doesn't work send me an email <antirez@invece.org>,
189 please, report all the needed informations like OS type/ver, libc version,
190 kernel version, camera type, what is the problem, et cetera.
191
192NOTE FOR USB USERS
193
194 *********** WARNING ************
195 * A lot of users mailed me for *
196 * problems with the USB driver:*
197 * 99% of the cases the problem *
198 * was that they tryed to run *
199 * S10sh as normal user. YOU *
200 * MUST USE IT AS ROOT, you may *
201 * setuid it, but it's insecure *
202 * ------ YOU ARE WARNED ------ *
203 ********************************
204
205 In order to work, s10sh (libusb, that uses the userspace way to access
206 to the USB hardware) needs that you performs the following steps:
207
208 insmod usbcore
209 insmod usb-ohci *OR* isnmod usb-uhci
210 mount none /proc/bus/usb -t usbdevfs
211
212 How to know if you need to insert the OHCI or the UHCI driver?
213 UHCI is for the following motherboards: Intel PIIX4, VIA, ...
214 OHCI is for the following motherboards: Compaq, iMacs, OPTi, SiS, ALi, ...
215
216 If you are in trouble just try both the drivers :)
217
218 Obviously if you compiled a kernel without USB support you needs
219 to compile another kernel.
220 Anyway check http://www.linux-usb.org for more information.
221
222HOW TO USE
223
224 s10sh accepts the following command line options:
225
226 -D enable debug mode
227 -d <serialdevice> set the serial device, default /dev/ttyS0
228 -a enable A50/Pro70 compatibility mode
229 -s <serialspeed> set the serial speed (9600 19200 38400 57600 115200)
230 -u USB mode, default is serial mode
231 -g non-interactive mode, get all images
232 -l non-interactive mode, list all images
233 -E non-interactive mode, delete all images
234 -h show this help scree
235 reports)
236 Example:
237
238 ./s10sh -d /dev/ttyS1 -- start the program in serial mode, COM2.
239
240 ./s10sh -u -- start the program in USB mode.
241
242 ./s10sh -ug -- get all images in USB mode.
243
244 If you are able to use a command line ftp client you can use S10sh. When you
245 start the program S10sh contacts the camera and shows a prompt like
246 this:
247
248 [Canon PowerShot S10] D:>
249
250 the format is [CAMERA ID] [CURRENT PATH]>
251
252 Now you can use 'ls' or 'cd' that are aliases in order to walk
253 among directories. The commands are:
254
255help show this help screen
256open open the camera
257reopen close and open the camera
258close close the connection with the camera
259speed [speed] change the serial speed
260quit close the camera and quit the program
261ping ping four times the camera
262clear clear the screen under some terminal types
263id show the camera id
264date show the internal date of the camera
265disk show the CF disk letter
266diskinfo <disk> show disk information
267ls | cd | dir <dir> change to and list the specified directory
268lastls show the last cached directory listing
269get <pathname> get the specified image
270getall get all the files in the current directory
271getallold get all the old files in the current directory
272getallnew get all the new files in the current directory
273tget <pathname> get the specified image as thumbnail
274view <pathname> view the thumbnail using xv
275viewall view all thumbnails in the current directory
276power show informations about power status
277overwrite switch on/off the overwrite mode, when overwrite
278 mode is ON the old files will be overwritten with
279 the new files. For default ovewrite mode is
280 turned OFF.
281mkdir <dirname> create a directory
282rmdir <dirname> remove a directory
283debug (DEBUG) turn the debug on/off
284getpkt (DEBUG) wait for a packet from the camera
285test <num> (DEBUG) send the specified request and wait for data
286rm | delete <filename> remove a file in the current path
287deleteall remove all files in the current directory
288deleteold remove downloaded files in the current directory
289deletenew remove new files in the current directory
290protect <filename> set the protected flag (in the current path)
291unprotect <filename> clear the protected flag (in the current path)
292new <filename> clear the downloaded flag (in the current path)
293newall exec new against all files in the current directory
294old <filename> set the downloaded flag (in the current path)
295oldall exec old against all files in the current directory
296protectall protect all files in the current directory
297unprotectall unprotect all files in the current directory
298upload <source> [dest] upload a file (USB only)
299
300 some command is not available in both serial and USB mode.
301
302 A directory entry has the following format:
303
304 --n- IMG_0852 JPG 53k Fri Jun 23 19:11:40 2000
305
306 the first 4 characters are the file attributes, the flags are:
307
308 p--- -i-- --n- ---e or combinations.
309 p = protected
310 i = directory
311 n = the file was not downloaded, alias "new" file. if the file does not
312 have the 'n' flags it is "old". So you can guess how the commands
313 with "new" or "old" postfix works.
314 e = directory entered with recursion.
315
316 An example of session:
317
318--- EXAMPLE BEGIN ---
319
320PowerShot SH -- version 0.0.1
321Copyright (C) 2000 by Salvatore Sanfilippo <antirez@invece.org>
322S10sh is FREE SOFTWARE under the terms of the GNU public license
323
324Open /dev/ttyS0: OK
325Sync: .....
326::Canon PowerShot A5::
327Switching to 115200 bound ..OK
328[Canon PowerShot S10] D:> ls
329
330DCIM <DIR> Thu Jun 8 20:41:56 2000
331 1 files 0 bytes
332
333[Canon PowerShot S10] D:> cd dcim
334
335102CANON <DIR> Thu Jun 8 20:41:56 2000
336CANONMSC <DIR> Fri Jun 9 00:16:10 2000
337 2 files 0 bytes
338
339[Canon PowerShot S10] D:\dcim> cd 102canon
340
341IMG_0252 JPG 1809k Thu Jun 8 20:42:52 2000
342IMG_0253 JPG 210k Thu Jun 8 20:54:44 2000
343 2 files 2068073 bytes
344
345[Canon PowerShot S10] D:\dcim\102canon> get img_0253.jpg
346Getting D:\dcim\102canon\img_0253.jpg, 215388 Kbytes
3470------------------25------------------50------------------75----------------100
348................................................................................
349Downloaded in 36 seconds, 5983 bytes/s
350get successful
351[Canon PowerShot S10] D:\dcim\102canon> exit
352bye!
353
354--- EXAMPLE END ---
355
356In order to get all your photos just login, cd to CANONxxx directory
357and use the 'getall' command.
358
359SOLUTION TO SERIAL PROBLEMS
360
361If you see 'X' instead of '.' during file download there are some
362transmission error, S10sh handles this conditions but if you get
363too 'X' maybe it's better to switch to a lower speed. A tip in order
364to get less serial errors is to take the system load low during file dowloading.
365There are'nt trasmission problems using USB. THe right order to check
366if s10sh works for your camera in serial mode is to try it using this
367command line, the first is the more simple to get working, the last
368is the more hard.
369
370s10sh -a -s 9600
371s10sh -a -s 19200
372s10sh -a -s 38400
373s10sh -a -s 57600
374s10sh -a -s 115200
375s10sh -s 9600
376s10sh -s 19200
377s10sh -s 38400
378s10sh -s 57600
379s10sh -s 115200
380
381Yes, if you experienced serial problems use the A50/Pro70 compatibility mode
382even if your camera isn't a PowerShot A50 or a PowerShot Pro70.
383
384SECURITY:
385
386This software open new files in an unsafe mode, this means that if you
387download your photos in a word-writable directory malcious users can
388overwrite/create files with your privileges. DONT use it in a world
389writable directory, also DONT setuid this software. If you need
390to access your devices as unprivileged user joke with groups.
391Security issues will be fixed later.
392
393REFERENCES:
394
395 gphoto http://www.gphoto.org
396 ComLite32 http://www.endymion.com/portfolio/software/comlite32.htm
397 Canon PowerShot site http://www.powershot.com
398 libusb http://libusb.sourceforge.net/
399 Linux USB http://www.linux-usb.org
400
401 * ALL THIRD PARTY BRAND, PRODUCT AND SERVICE NAMES MENTIONED ARE
402 * THE TRADEMARK OR REGISTERED TRADEMARK OF THEIR RESPECTIVE OWNERS
403
