source: trunk/USAGE.TXT @ 540

Revision 537, 21.5 KB checked in by reyalp, 4 days ago (diff)

gui - add pref to control connection status / device list check interval

  • 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][-l]    : - print API and program versions
210 -p print program version
211 -l print library versions
212
213connect (c)  [-b=<bus>] [-d=<dev>] [-p=<pid>] [-s=<serial>] [model] | -h=host [-p=port]: - connect to device
214 If no options are given, connects to the first available device.
215 <pid> is the USB product ID, as a decimal or hexadecimal number.
216 All other options are treated as a Lua pattern. For alphanumerics, this is a case sensitive substring match.
217 If the serial or model are specified, a temporary connection will be made to each device
218 If <model> includes spaces, it must be quoted.
219 If multiple devices match, the first matching device will be connected.
220
221reconnect (r)             : - reconnect to current device
222disconnect (dis)             : - disconnect from device
223ls           [-l] [path] : - list files/directories on camera
224reboot       [options] [file]: - reboot the camera
225 file: Optional file to boot.
226  Must be an unencoded binary or for DryOS only, an encoded .FI2
227  Format is assumed based on extension
228  If not set, firmware boots normally, loading diskboot.bin if configured
229 options:
230   -norecon  don't try to reconnect
231   -wait=<N> wait N ms before attempting to reconnect, default 3500
232
233lvdump (dumpframes) [options] [file]: - dump camera display frames to file
234 file:
235        optional output file name, defaults to chdk_<pid>_<date>_<time>.lvdump
236 options:
237   -count=<N> number of frames to dump
238   -wait=<N>  wait N ms between frames
239   -novp      don't get viewfinder data
240   -nobm      don't get ui overlay data
241   -nopal     don't get palette for ui overlay
242   -quiet     don't print progress
243
244lvdumpimg    [options]   : - dump camera display frames to images
245 options:
246   -count=<N> number of frames to dump, default 1
247   -wait=<N>  wait N ms between frames
248   -vp[=file] get viewfinder data to file
249   -bm[=file] get ui overlay data to file
250   -nopal     don't get palette for ui overlay
251   -quiet     don't print progress
252  file may include substitution pattern
253   ${date,datefmt}  current time formatted with os.date()
254   ${frame,strfmt}  current frame number formatted with string.format
255   ${time,strfmt}   current time in seconds, as float, formatted with string.format
256   default vp_${time,%014.3f}.pbm bm_${time,%014.3f}.pam for viewfinder and ui respectively
257
258shoot        [options]   : - shoot a picture with specified exposure
259 options:
260   -u=<s|a|96>
261      s   standard units (default)
262      a   APEX
263      96  APEX*96
264   -tv=<v>    shutter speed. In standard units both decimal and X/Y accepted
265   -sv=<v>    ISO value. In standard units, Canon "real" ISO
266   -av=<v>    Aperture value. In standard units, f number
267   -isomode=<v> ISO mode, must be ISO value in Canon UI, shooting mode must have manual ISO
268   -nd=<in|out> set ND filter state
269   -raw[=1|0] Force raw on or off, defaults to current camera setting
270   -dng[=1|0] Force DNG on or off, implies raw if on, default current camera setting
271   -pretend   print actions instead of running them
272   -nowait    don't wait for shot to complete
273   -dl        download shot file(s)
274   -rm        remove file after shooting
275  Any exposure parameters not set use camera defaults
276
277remoteshoot (rs) [local] [options]: - shoot and download without saving to SD (requires CHDK 1.2)
278 [local]       local destination directory or filename (w/o extension!)
279 options:
280   -u=<s|a|96>
281      s   standard units (default)
282      a   APEX
283      96  APEX*96
284   -tv=<v>    shutter speed. In standard units both decimal and X/Y accepted
285   -sv=<v>    ISO value. In standard units, Canon "real" ISO
286   -av=<v>    Aperture value. In standard units, f number
287   -isomode=<v> ISO mode, must be ISO value in Canon UI, shooting mode must have manual ISO
288   -nd=<in|out> set ND filter state
289   -jpg         jpeg, default if no other options (not supported on all cams)
290   -raw         framebuffer dump raw
291   -dng         DNG format raw
292   -dnghdr      save DNG header to a separate file, ignored with -dng
293   -s=<start>   first line of for subimage raw
294   -c=<count>   number of lines for subimage
295   -cont=<num>  shoot num shots in continuous mode
296   -badpix[=n]  interpolate over pixels with value <= n, default 0, (dng only)
297
298rsint        [local] [options]: - shoot and download in continuous mode with interactive control
299 [local]       local destination directory or filename (w/o extension!)
300 options:
301   -u=<s|a|96>
302      s   standard units (default)
303      a   APEX
304      96  APEX*96
305   -tv=<v>    shutter speed. In standard units both decimal and X/Y accepted
306   -sv=<v>    ISO value. In standard units, Canon "real" ISO
307   -av=<v>    Aperture value. In standard units, f number
308   -isomode=<v> ISO mode, must be ISO value in Canon UI, shooting mode must have manual ISO
309   -nd=<in|out> set ND filter state
310   -jpg         jpeg, default if no other options (not supported on all cams)
311   -raw         framebuffer dump raw
312   -dng         DNG format raw
313   -dnghdr      save DNG header to a seperate file, ignored with -dng
314   -s=<start>   first line of for subimage raw
315   -c=<count>   number of lines for subimage
316   -badpix[=n]  interpolate over pixels with value <= n, default 0, (dng only)
317   -cmdwait=n   wait n seconds for command, default 60
318
319rec                      : - switch camera to shooting mode
320play                     : - switch camera to playback mode
321dngload      [options] <file>: - load a dng file
322 file: file to load
323   only DNGs generated by CHDK or chdkptp are supported
324 options
325   -nosel  do not automatically select loaded file
326
327dngsave      [options] [image num] [file]: - save a dng file
328 file:       file or directory to write to
329   defaults to loaded name. if directory, appends original filename
330 options:
331   -over     overwrite existing files
332   -keepmtime preserve existing modification time
333
334dngunload    [image num] : - unload dng file
335dnginfo      [options] [image num]: - display information about a dng
336 options:
337   -s   summary info, default if no other options given
338   -h   tiff header
339   -ifd[=<ifd>]
340         raw, exif, main, or 0, 0.0 etc. default 0
341   -r   recurse into sub-ifds
342   -vals[=N]
343     display up to N values for each IFD entry, default 20
344
345dnghist      [options] [image num]: - generate a histogram
346 options:
347  -min=N   list pixels with value >= N
348  -max=N   list pixels with value <= N
349  -reg=<active|all>
350        region of image to search, either active area (default) or all
351  -bin=<n>
352    number of values in histogram bin
353  -fmt=<count|%>
354    format for output
355
356dnglistpixels [options] [image num]: - generate a list of pixel coordinates
357 options:
358  -min=N   list pixels with value >= N
359  -max=N   list pixels with value <= N
360  -out=<file>
361        <file> is name of output file
362  -fmt=<chdk|rt|dcraw|count>
363        format badpixel list for chdk badpixel.txt, raw therapee, dcraw, or just count them
364  -reg=<active|all>
365        region of image to search, either active area (default) or all
366  -coords=<abs|rel>
367    output coordinates relative to region, or absolute
368        use rel for raw therapee and dcraw
369
370dnglist                  : - list loaded dng files
371dngsel       <number>    : - select dng
372 number:
373   dng number from dnglist to select
374
375dngmod       [options] [files]: - modify dng
376 options:
377   -patch[=n]   interpolate over pixels with value less than n (default 0)
378
379dngdump      [options] [image num]: - extract data from dng
380 options:
381   -thm[=name]   extract thumbnail to name, default dngname_thm.(rgb|ppm)
382   -raw[=name]   extract raw data to name, default dngname.(raw|pgm)
383   -over         overwrite existing file
384   -rfmt=fmt raw format (default: unmodified from DNG)
385     format is <bpp>[endian][pgm], e.g. 8pgm or 12l
386         pgm is only valid for 8 and 16 bpp
387         endian is l or b and defaults to little, except for 16 bit pgm
388   -tfmt=fmt thumb format (default, unmodified rgb)
389     ppm   8 bit rgb ppm
390
391dngbatch     [options] [files] { command ; command ... }: - manipulate multiple files
392 options:
393   -odir             output directory, if no name specified in file commands
394   -pretend          print actions instead of doing them
395   -verbose[=n]      print detail about actions
396 file selection
397   -fmatch=<pattern> only file with path/name matching <pattern>
398   -rmatch=<pattern> only recurse into directories with path/name matching <pattern>
399   -maxdepth=n       only recurse into N levels of directory (default 1, only those specified in command)
400   -ext=string       only files with specified extension, default dng, * for all. Not a pattern
401 commands:
402   mod dump save info listpixels
403  take the same options as the corresponding standalone commands
404  load and unload are implicitly called for each file
405
406==Runtime options==
407The set command allows you to set the following runtime options
408cli_time=false       - boolean: show cli execution times
409cli_xferstats=false  - boolean: show cli data transfer stats
410cli_verbose=1        - number: control verbosity of cli
411cli_source_max=10    - number: max nested source calls
412core_verbose=0       - number: ptp core verbosity
413
414In the GUI, the following additional options are available:
415gui_live_sched=false - boolean: use scheduler for live updates
416gui_live_dropframes=false - boolean: drop frames if target fps too high
417gui_dump_palette=false - boolean: dump live palette data on state change
418gui_context_plus=false - boolean: use IUP context plus if available
419gui_force_replay_palette=-1 - number: override palette type dump replay, -1 disable
420gui_verbose=1        - number: control verbosity of gui
421gui_dev_check_interval=500 - number: connection/device list check time in ms, 0=never
422
423Notes:
4241) Outside of startup files, setting a gui option when the gui is not running
425   is currently an error
4262) gui_context_plus must be set in a startup file to take effect.
4273) gui_live_dropframes defaults to true under Linux
428
429=Examples=
430start chdkptp in interactive mode and connect to the first available camera
431 chdkptp -i -c
432
433execute lua on host PC and print the result
434con> !return 1+1
435=2
436
437execute lua on the camera, and print the result
438con> =return get_buildinfo()
4391: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",}
440
441upload diskboot.bin to A/diskboot.bin, reboot camera, enter interactive mode
442 chdkptp -c -e"u bin/diskboot.bin" -ereboot -i
443
444upload interval.lua to A/CHDK/SCRIPTS/interval.lua, from the command line
445 chdkptp -c -e"u interval.lua CHDK/SCRIPTS/"
446
447download A/CHDK/CCHDK.CFG to BACKUP.CFG in the current directory
448 chdkptp -c -e"d CHDK/CCHDK.CFG BACKUP.CFG"
449
450connect to the device with name containing D10 on bus "bus-0",
451 chdkptp -c"D10 -b=bus%-0" -i
452note connect -b takes a lua pattern, so % is needed to escapes the -
453
454download some jpeg images (in 100CANON etc folders)
455con> mdl -fmatch=%.JPG$ DCIM C:\temp
456
457delete some raw images
458con> rm -nodirs -fmatch=%.CRW$ DCIM
459
460upload some scripts
461con> mup c:\CHDK\SCRIPTS CHDK/SCRIPTS
462
463ad hoc scripting on PC side - download some files
464con> !t=con:listdir('A/DCIM/100CANON',{match="%.JPG$"})
465con> !for i,n in ipairs(t) do con:download("A/DCIM/100CANON/"..n,"C:/TEMP/"..n) end
466NOTE the mdownload cli command above is probably more convenient
467
468list devices and connect to a specific camera
469___> list
470 1:Canon PowerShot D10 b=bus-0 d=\\.\libusb0-0001--0x04a9-0x31bc v=0x4a9 p=0x31bc s=12345678123456781234567812345678
471 2:Canon PowerShot A540 b=bus-0 d=\\.\libusb0-0002--0x04a9-0x311b v=0x4a9 p=0x311b s=nil
472___> c 540
473con> list
474 1:Canon PowerShot D10 b=bus-0 d=\\.\libusb0-0001--0x04a9-0x31bc v=0x4a9 p=0x31bc s=12345678123456781234567812345678
475*2:Canon PowerShot A540 b=bus-0 d=\\.\libusb0-0002--0x04a9-0x311b v=0x4a9 p=0x311b s=nil
476
477
478==Run a script file on the camera==
479The suggested way to run a lua script file on the cameras is
480
481con> .loadfile('A/CHDK/SCRIPTS/MY.LUA')()
482
483loadfile returns a function, the following () executes it immediately.
484
485The reason to loadfile instead of the more obvious dofile() or require() is
486that code executed in these functions cannot yield, which means you wouldn't
487be able to use sleep or keyboard functions.
488
489If the script was written to be loaded from the CHDK script menu and expects
490menu settings, you will need to manually set the corresponding variables, e.g.
491
492con> .a=1; b=2; loadfile("A/CHDK/SCRIPTS/MY.LUA")()
493
494While the script is running you will not be able to control the camera from
495chdkptp using the GUI key buttons or any other script commands. You also will
496note be able to gracefully terminate the script without physically pressing the
497shutter button.
498
499If you want to have a script that runs for a long time on the camera, but still
500be able to control it over ptp, you will probably need to write your own script
501using the ptp message interface. Some examples of this in the chdkptp lua code
502lua/rlibs.lua msg_shell and lua/multicam.lua
Note: See TracBrowser for help on using the repository browser.