source: trunk/USAGE.TXT @ 530

Revision 518, 21.2 KB checked in by reyalp, 2 weeks ago (diff)

update USAGE.TXT

  • Property svn:eol-style set to native
Line 
1chdkptp supports console CLI, a GUI, and batch operation.
2
3The GUI is still unfinished
4
5Some additional information is available from the assembla project wiki:
6
7CLI information:
8https://www.assembla.com/spaces/chdkptp/wiki/CLI_Quickstart
9
10Scripting:
11https://www.assembla.com/spaces/chdkptp/wiki/Scripting_Guide
12
13=Installing=
14See INSTALL.TXT
15
16=Invoking=
17The interface is selected by command line options, described below.
18
19==Running under linux==
20Under linux, the .lua files will not automatically found relative to the
21executable directory. You can set LUA_PATH on the command line to allow them
22to be located:
23$ LUA_PATH="/path/to/chdkptp/lua/?.lua" /path/to/chdkptp ...
24
25Similarly, if the IUP and CD shared libraries are not on the default system
26path, you must also set LD_LIBARARY_PATH
27$ LD_LIBRARY_PATH=/path/to/iup LUA_PATH="/path/to/chdkptp/lua/?.lua" /path/to/chdkptp -g
28
29It is suggested that you put all this in a shell script, see chdkptp-sample.sh
30for an example.
31
32You may need to make permission changes to allow users other than root to open
33the USB device. Some notes can be found in this forum post:
34http://chdk.setepontos.com/index.php?topic=6231.msg89252#msg89252
35
36==Command line==
37Usage: chdkptp [options]
38Options:
39 -g  start GUI - default if GUI available and no options given
40 -i  start interactive CLI
41 -c  connect at startup, with optional device spec e.g. -c"-d001 -bbus-0"
42 -e  execute CLI command, multiple allowed, e.g -e"u DISKBOOT.BIN" -ereboot
43 -r  specify startup command file, if no file given skip default startup files
44 -h  help
45
46If invoked with no options, the GUI will be started if available.  Otherwise,
47the CLI will be started.
48
49If started with options and neither -g nor -i is given, chdkptp will run in
50batch mode, exiting after performing the actions specified by the options.
51
52When using -e, -c or -r, the values must immediately follow the option, without
53any space, e.g. -rmyfile or -r=myfile, not -r myfile. If any arguments that
54include spaces, they must be quoted.
55
56==Startup files==
57Startup files can be used to automatically execute CLI commands at startup.
58Using the exec command, you may also execute arbitrary lua.
59
60If the -r command line option is used, it is treated as the full name of the
61file, and the default files are ignored. If -r is given without a filename,
62no startup file is used.
63
64If -r is not used, CHDKPTP checks for startup files using the CHDKPTP_HOME
65environment variable, or if that is not set, the HOME environment variable.
66
67.chdkptprc (linux) / _chdkptprc (windows) is the default startup file in CLI
68or batch mode.
69
70.chdkptpguirc (linux) / _chdkptpguirc (windows) is the default startup file
71in GUI mode. This is run after the gui module is loaded, but before the GUI
72is started.
73
74=CLI=
75CLI commands are available from the console, GUI and the command line
76
77Many CLI commands have full descriptive name and a short name. The short
78is listed in parenthesis in the command reference below.
79
80==CLI parsing==
81The cli commands lua, luar, exec and putm all accept a single line of free-form
82text and pass it unmodified to the underlying function.
83
84Most other commands parse the remaining input into switches and arguments
85Switches are in the for -switchname and may take values with -switch=value
86Arguments are any other sequence of non-space or quoted characters.
87
88Both switches and words may be quoted as follows:
89The characters " or ' can be used to quote arguments or switch values that
90contain spaces. Inside double quotes "",  backslash \ is treated as an escape
91character.
92
93==Command reference==
94output of help -v
95help (h)     [cmd]|[-v]  : - help on [cmd] or all commands
96 help -v gives full help on all commands, otherwise as summary is printed
97
98#                        : - comment
99exec (!)     <lua code>  : - execute local lua
100 Execute lua in chdkptp.
101 The global variable con accesses the current CLI connection.
102 Return values are printed in the console.
103
104set          [-v|-c] [option[=value]]: - show or set option
105 Use set with no options to see a list
106  -v show desciption when showing value
107  -c output as set command
108
109quit (q)                 : - quit program
110source       <file>      : - execute cli commands from file
111lua (.)      <lua code>  : - execute remote lua
112 Execute Lua code on the camera.
113 Returns immediately after the script is started.
114 Return values or error messages can be retrieved with getm after the script is completed.
115
116getm                     : - get messages
117putm         <msg string>: - send message
118luar (=)     <lua code>  : - execute remote lua, wait for result
119 Execute Lua code on the camera, waiting for the script to end.
120 Return values or error messages are printed after the script completes.
121
122killscript   [-noflush][-force][-nowait]: - kill running remote script
123 Terminate any running script on the camera
124   -noflush: don't discard script messages
125   -force: force kill even if camera does not support (crash / memory leaks likely!)
126
127rmem         <address> [count] [-i32[=fmt]]: - read memory
128 Dump <count> bytes or words starting at <address>
129  -i32 display as 32 bit words rather than byte oriented hex dump
130  -i32=<fmt> use printf format string fmt to display
131
132list                     : - list devices
133 Lists all recognized PTP devices in the following format on success
134  <status><num>:<modelname> b=<bus> d=<device> v=<usb vendor> p=<usb pid> s=<serial number>
135 or on error
136  <status><num> b=<bus> d=<device> ERROR: <error message>
137 status values
138  * connected, current target for CLI commands (con global variable)
139  + connected, not CLI target
140  - not connected
141  ! error querying status
142 serial numbers are not available from all models
143
144upload (u)   [-nolua] <local> [remote]: - upload a file to the camera
145 <local>  file to upload
146 [remote] destination
147   If not specified, file is uploaded to A/
148   If remote is a directory or ends in / uploaded to remote/<local file name>
149 -nolua   skip lua based checks on remote
150   Allows upload while running script
151   Prevents detecting if remote is a directory
152 Some cameras have problems with paths > 32 characters
153 Dryos cameras do not handle non 8.3 filenames well
154
155download (d) [-nolua] <remote> [local]: - download a file from the camera
156 <remote> file to download
157        A/ is prepended if not present
158 [local]  destination
159   If not specified, the file will be downloaded to the current directory
160   If a directory, the file will be downloaded into it
161 -nolua   skip lua based checks on remote
162   Allows download while running script
163
164mdownload (mdl) [options] <remote, remote, ...> <target dir>: - download file/directories from the camera
165 <remote...> files/directories to download
166 <target dir> directory to download into
167 options:
168   -fmatch=<pattern> download only file with path/name matching <pattern>
169   -dmatch=<pattern> only create directories with path/name matching <pattern>
170   -rmatch=<pattern> only recurse into directories with path/name matching <pattern>
171   -nodirs           only create directories needed to download file
172   -maxdepth=n       only recurse into N levels of directory
173   -pretend          print actions instead of doing them
174   -nomtime          don't preserve modification time of remote files
175   -batchsize=n      lower = slower, less memory used
176   -dbgmem           print memory usage info
177   -overwrite=<str>  overwrite existing files (y|n|old)
178 note <pattern> is a lua pattern, not a filesystem glob like *.JPG
179
180mupload (mup) [options] <local, local, ...> <target dir>: - upload file/directories to the camera
181 <local...> files/directories to upload
182 <target dir> directory to upload into
183 options:
184   -fmatch=<pattern> upload only file with path/name matching <pattern>
185   -dmatch=<pattern> only create directories with path/name matching <pattern>
186   -rmatch=<pattern> only recurse into directories with path/name matching <pattern>
187   -nodirs           only create directories needed to upload file
188   -maxdepth=n       only recurse into N levels of directory
189   -pretend          print actions instead of doing them
190   -nomtime          don't preserve local modification time
191 note <pattern> is a lua pattern, not a filesystem glob like *.JPG
192
193delete (rm)  [options] <target, target,...>: - delete file/directories from the camera
194 <target...> files/directories to remote
195 options:
196   -fmatch=<pattern> upload only file with names matching <pattern>
197   -dmatch=<pattern> only delete directories with names matching <pattern>
198   -rmatch=<pattern> only recurse into directories with names matching <pattern>
199   -nodirs           don't delete drictories recursed into, only files
200   -maxdepth=n       only recurse into N levels of directory
201   -pretend          print actions instead of doing them
202   -ignore_errors    don't abort if delete fails, continue to next item
203   -skip_topdirs     don't delete directories given in command line, only contents
204 note <pattern> is a lua pattern, not a filesystem glob like *.JPG
205
206mkdir        <directory> : - create directories on camera
207 <directory> directory to create. Intermediate directories will be created as needed
208
209version (ver) [-p]        : - print API and program versions
210 -p print program version
211
212connect (c)  [-b=<bus>] [-d=<dev>] [-p=<pid>] [-s=<serial>] [model] | -h=host [-p=port]: - connect to device
213 If no options are given, connects to the first available device.
214 <pid> is the USB product ID, as a decimal or hexadecimal number.
215 All other options are treated as a Lua pattern. For alphanumerics, this is a case sensitive substring match.
216 If the serial or model are specified, a temporary connection will be made to each device
217 If <model> includes spaces, it must be quoted.
218 If multiple devices match, the first matching device will be connected.
219
220reconnect (r)             : - reconnect to current device
221disconnect (dis)             : - disconnect from device
222ls           [-l] [path] : - list files/directories on camera
223reboot       [options] [file]: - reboot the camera
224 file: Optional file to boot.
225  Must be an unencoded binary or for DryOS only, an encoded .FI2
226  Format is assumed based on extension
227  If not set, firmware boots normally, loading diskboot.bin if configured
228 options:
229   -norecon  don't try to reconnect
230   -wait=<N> wait N ms before attempting to reconnect, default 3500
231
232lvdump (dumpframes) [options] [file]: - dump camera display frames to file
233 file:
234        optional output file name, defaults to chdk_<pid>_<date>_<time>.lvdump
235 options:
236   -count=<N> number of frames to dump
237   -wait=<N>  wait N ms between frames
238   -novp      don't get viewfinder data
239   -nobm      don't get ui overlay data
240   -nopal     don't get palette for ui overlay
241   -quiet     don't print progress
242
243lvdumpimg    [options]   : - dump camera display frames to images
244 options:
245   -count=<N> number of frames to dump, default 1
246   -wait=<N>  wait N ms between frames
247   -vp[=file] get viewfinder data to file
248   -bm[=file] get ui overlay data to file
249   -nopal     don't get palette for ui overlay
250   -quiet     don't print progress
251  file may include substitution pattern
252   ${date,datefmt}  current time formatted with os.date()
253   ${frame,strfmt}  current frame number formatted with string.format
254   ${time,strfmt}   current time in seconds, as float, formatted with string.format
255   default vp_${time,%014.3f}.pbm bm_${time,%014.3f}.pam for viewfinder and ui respectively
256
257shoot        [options]   : - shoot a picture with specified exposure
258 options:
259   -u=<s|a|96>
260      s   standard units (default)
261      a   APEX
262      96  APEX*96
263   -tv=<v>    shutter speed. In standard units both decimal and X/Y accepted
264   -sv=<v>    ISO value. In standard units, Canon "real" ISO
265   -av=<v>    Aperture value. In standard units, f number
266   -isomode=<v> ISO mode, must be ISO value in Canon UI, shooting mode must have manual ISO
267   -nd=<in|out> set ND filter state
268   -raw[=1|0] Force raw on or off, defaults to current camera setting
269   -dng[=1|0] Force DNG on or off, implies raw if on, default current camera setting
270   -pretend   print actions instead of running them
271   -nowait    don't wait for shot to complete
272   -dl        download shot file(s)
273   -rm        remove file after shooting
274  Any exposure parameters not set use camera defaults
275
276remoteshoot (rs) [local] [options]: - shoot and download without saving to SD (requires CHDK 1.2)
277 [local]       local destination directory or filename (w/o extension!)
278 options:
279   -u=<s|a|96>
280      s   standard units (default)
281      a   APEX
282      96  APEX*96
283   -tv=<v>    shutter speed. In standard units both decimal and X/Y accepted
284   -sv=<v>    ISO value. In standard units, Canon "real" ISO
285   -av=<v>    Aperture value. In standard units, f number
286   -isomode=<v> ISO mode, must be ISO value in Canon UI, shooting mode must have manual ISO
287   -nd=<in|out> set ND filter state
288   -jpg         jpeg, default if no other options (not supported on all cams)
289   -raw         framebuffer dump raw
290   -dng         DNG format raw
291   -dnghdr      save DNG header to a separate file, ignored with -dng
292   -s=<start>   first line of for subimage raw
293   -c=<count>   number of lines for subimage
294   -cont=<num>  shoot num shots in continuous mode
295   -badpix[=n]  interpolate over pixels with value <= n, default 0, (dng only)
296
297rsint        [local] [options]: - shoot and download in continuous mode with interactive control
298 [local]       local destination directory or filename (w/o extension!)
299 options:
300   -u=<s|a|96>
301      s   standard units (default)
302      a   APEX
303      96  APEX*96
304   -tv=<v>    shutter speed. In standard units both decimal and X/Y accepted
305   -sv=<v>    ISO value. In standard units, Canon "real" ISO
306   -av=<v>    Aperture value. In standard units, f number
307   -isomode=<v> ISO mode, must be ISO value in Canon UI, shooting mode must have manual ISO
308   -nd=<in|out> set ND filter state
309   -jpg         jpeg, default if no other options (not supported on all cams)
310   -raw         framebuffer dump raw
311   -dng         DNG format raw
312   -dnghdr      save DNG header to a seperate file, ignored with -dng
313   -s=<start>   first line of for subimage raw
314   -c=<count>   number of lines for subimage
315   -badpix[=n]  interpolate over pixels with value <= n, default 0, (dng only)
316   -cmdwait=n   wait n seconds for command, default 60
317
318rec                      : - switch camera to shooting mode
319play                     : - switch camera to playback mode
320dngload      [options] <file>: - load a dng file
321 file: file to load
322   only DNGs generated by CHDK or chdkptp are supported
323 options
324   -nosel  do not automatically select loaded file
325
326dngsave      [options] [image num] [file]: - save a dng file
327 file:       file or directory to write to
328   defaults to loaded name. if directory, appends original filename
329 options:
330   -over     overwrite existing files
331   -keepmtime preserve existing modification time
332
333dngunload    [image num] : - unload dng file
334dnginfo      [options] [image num]: - display information about a dng
335 options:
336   -s   summary info, default if no other options given
337   -h   tiff header
338   -ifd[=<ifd>]
339         raw, exif, main, or 0, 0.0 etc. default 0
340   -r   recurse into sub-ifds
341   -vals[=N]
342     display up to N values for each IFD entry, default 20
343
344dnghist      [options] [image num]: - generate a histogram
345 options:
346  -min=N   list pixels with value >= N
347  -max=N   list pixels with value <= N
348  -reg=<active|all>
349        region of image to search, either active area (default) or all
350  -bin=<n>
351    number of values in histogram bin
352  -fmt=<count|%>
353    format for output
354
355dnglistpixels [options] [image num]: - generate a list of pixel coordinates
356 options:
357  -min=N   list pixels with value >= N
358  -max=N   list pixels with value <= N
359  -out=<file>
360        <file> is name of output file
361  -fmt=<chdk|rt|dcraw|count>
362        format badpixel list for chdk badpixel.txt, raw therapee, dcraw, or just count them
363  -reg=<active|all>
364        region of image to search, either active area (default) or all
365  -coords=<abs|rel>
366    output coordinates relative to region, or absolute
367        use rel for raw therapee and dcraw
368
369dnglist                  : - list loaded dng files
370dngsel       <number>    : - select dng
371 number:
372   dng number from dnglist to select
373
374dngmod       [options] [files]: - modify dng
375 options:
376   -patch[=n]   interpolate over pixels with value less than n (default 0)
377
378dngdump      [options] [image num]: - extract data from dng
379 options:
380   -thm[=name]   extract thumbnail to name, default dngname_thm.(rgb|ppm)
381   -raw[=name]   extract raw data to name, default dngname.(raw|pgm)
382   -over         overwrite existing file
383   -rfmt=fmt raw format (default: unmodified from DNG)
384     format is <bpp>[endian][pgm], e.g. 8pgm or 12l
385         pgm is only valid for 8 and 16 bpp
386         endian is l or b and defaults to little, except for 16 bit pgm
387   -tfmt=fmt thumb format (default, unmodified rgb)
388     ppm   8 bit rgb ppm
389
390dngbatch     [options] [files] { command ; command ... }: - manipulate multiple files
391 options:
392   -odir             output directory, if no name specified in file commands
393   -pretend          print actions instead of doing them
394   -verbose[=n]      print detail about actions
395 file selection
396   -fmatch=<pattern> only file with path/name matching <pattern>
397   -rmatch=<pattern> only recurse into directories with path/name matching <pattern>
398   -maxdepth=n       only recurse into N levels of directory (default 1, only those specified in command)
399   -ext=string       only files with specified extension, default dng, * for all. Not a pattern
400 commands:
401   mod dump save info listpixels
402  take the same options as the corresponding standalone commands
403  load and unload are implicitly called for each file
404
405==Runtime options==
406The set command allows you to set the following runtime options
407cli_time=false       - boolean: show cli execution times
408cli_xferstats=false  - boolean: show cli data transfer stats
409cli_verbose=1        - number: control verbosity of cli
410cli_source_max=10    - number: max nested source calls
411core_verbose=0       - number: ptp core verbosity
412
413In the GUI, the following additional options are available:
414gui_dump_palette=false - boolean: dump live palette data on state change
415gui_context_plus=false - boolean: use IUP context plus if available
416gui_force_replay_palette=-1 - number: override palette type dump replay, -1 disable
417gui_verbose=1        - number: control verbosity of gui
418
419Notes:
4201) Setting a gui option when the gui is not running is currently an error
4212) gui_context_plus must be set in a startup file to take effect.
422
423=Examples=
424start chdkptp in interactive mode and connect to the first available camera
425 chdkptp -i -c
426
427execute lua on host PC and print the result
428con> !return 1+1
429=2
430
431execute lua on the camera, and print the result
432con> =return get_buildinfo()
4331:return:table:{platformid=12732,platform="d10",version="CHDK",platsub="100a",build_number="0.9.9",os="dryos",build_date="May  3 2011",build_time="20:54:20",}
434
435upload diskboot.bin to A/diskboot.bin, reboot camera, enter interactive mode
436 chdkptp -c -e"u bin/diskboot.bin" -ereboot -i
437
438upload interval.lua to A/CHDK/SCRIPTS/interval.lua, from the command line
439 chdkptp -c -e"u interval.lua CHDK/SCRIPTS/"
440
441download A/CHDK/CCHDK.CFG to BACKUP.CFG in the current directory
442 chdkptp -c -e"d CHDK/CCHDK.CFG BACKUP.CFG"
443
444connect to the device with name containing D10 on bus "bus-0",
445 chdkptp -c"D10 -b=bus%-0" -i
446note connect -b takes a lua pattern, so % is needed to escapes the -
447
448download some jpeg images (in 100CANON etc folders)
449con> mdl -fmatch=%.JPG$ DCIM C:\temp
450
451delete some raw images
452con> rm -nodirs -fmatch=%.CRW$ DCIM
453
454upload some scripts
455con> mup c:\CHDK\SCRIPTS CHDK/SCRIPTS
456
457ad hoc scripting on PC side - download some files
458con> !t=con:listdir('A/DCIM/100CANON',{match="%.JPG$"})
459con> !for i,n in ipairs(t) do con:download("A/DCIM/100CANON/"..n,"C:/TEMP/"..n) end
460note the mdownload cli command above is probably more convenient
461
462list devices and connect to a specific camera
463___> list
464 1:Canon PowerShot D10 b=bus-0 d=\\.\libusb0-0001--0x04a9-0x31bc v=0x4a9 p=0x31bc s=12345678123456781234567812345678
465 2:Canon PowerShot A540 b=bus-0 d=\\.\libusb0-0002--0x04a9-0x311b v=0x4a9 p=0x311b s=nil
466___> c 540
467con> list
468 1:Canon PowerShot D10 b=bus-0 d=\\.\libusb0-0001--0x04a9-0x31bc v=0x4a9 p=0x31bc s=12345678123456781234567812345678
469*2:Canon PowerShot A540 b=bus-0 d=\\.\libusb0-0002--0x04a9-0x311b v=0x4a9 p=0x311b s=nil
470
471
472==Run a script file on the camera==
473The suggested way to run a lua script file on the cameras is
474
475con> .loadfile('A/CHDK/SCRIPTS/MY.LUA')()
476
477loadfile returns a function, the following () executes it immediately.
478
479The reason to loadfile instead of the more obvious dofile() or require() is
480that code executed in these functions cannot yield, which means you wouldn't
481be able to use sleep or keyboard functions.
482
483If the script was written to be loaded from the CHDK script menu and expects
484menu settings, you will need to manually set the corresponding variables, e.g.
485
486con> .a=1; b=2; loadfile("A/CHDK/SCRIPTS/MY.LUA")()
487
488While the script is running you will not be able to control the camera from
489chdkptp using the GUI key buttons or any other script commands. You also will
490note be able to gracefully terminate the script without physically pressing the
491shutter button.
492
493If you want to have a script that runs for a long time on the camera, but still
494be able to control it over ptp, you will probably need to write your own script
495using the ptp message interface. Some examples of this in the chdkptp lua code
496lua/rlibs.lua msg_shell and lua/multicam.lua
Note: See TracBrowser for help on using the repository browser.