CHDK Wiki
Register
(add set_exit_key())
(Update for restore fixes, clarify that restore is only called on key interrupt)
Tag: Source edit
 
(142 intermediate revisions by 12 users not shown)
Line 1: Line 1:
  +
 
''Note: This is work in progress... Please add.'' <small><sub>''[[User:Fe50|Fe50]] 01:21, December 28, 2010 (UTC)''</sub></small>
 
''Note: This is work in progress... Please add.'' <small><sub>''[[User:Fe50|Fe50]] 01:21, December 28, 2010 (UTC)''</sub></small>
 
----
 
----
Line 4: Line 5:
   
 
=Additional uBASIC and Lua Scripting Commands=
 
=Additional uBASIC and Lua Scripting Commands=
{{notice|CHDK scripting basics and the most commonly used scripting commands are explained on the [[UBASIC/TutorialScratchpad]] page. Lua specific commands are documented at [[Lua/Lua_Reference]]. A complete cross reference of all scripting commands can be found here : [[CHDK_Scripting_Cross_Reference_Page|CHDK Scripting Cross Reference Page]]}}
+
{{notice|CHDK scripting basics and the most commonly used scripting commands are explained on the [[UBASIC/TutorialScratchpad]] page. Lua specific commands are documented at [[Lua/Lua_Reference]]. A complete cross reference of all scripting commands can be found here : [[CHDK_Scripting_Cross_Reference_Page|CHDK Scripting Cross Reference Page]]}}__TOC__
__TOC__
 
   
 
==get_config_value==
 
==get_config_value==
   
 
Returns the value of the specified CHDK configuration item. These are the items set in the CHDK menus. Use the index number found in CHDK source file [http://subversion.assembla.com/svn/chdk/trunk/core/conf.c conf.c] in the structure conf_info[].
 
Returns the value of the specified CHDK configuration item. These are the items set in the CHDK menus. Use the index number found in CHDK source file [http://subversion.assembla.com/svn/chdk/trunk/core/conf.c conf.c] in the structure conf_info[].
  +
  +
'''uBASIC usage:'''
  +
  +
v=get_config_value <configID>
   
 
'''Lua usage:'''
 
'''Lua usage:'''
Line 23: Line 27:
 
*table1 = config value fields
 
*table1 = config value fields
 
*<span style="line-height:21px;">configid = </span><span style="line-height:21px;">index number from </span>[http://subversion.assembla.com/svn/chdk/trunk/core/conf.c conf.c]<span style="line-height:21px;"> </span><span style="line-height:21px;">structure conf_info[]</span>
 
*<span style="line-height:21px;">configid = </span><span style="line-height:21px;">index number from </span>[http://subversion.assembla.com/svn/chdk/trunk/core/conf.c conf.c]<span style="line-height:21px;"> </span><span style="line-height:21px;">structure conf_info[]</span>
*default = message value, when ID was not found
+
*default = message value, when ID not found
   
 
*nil = error (ID not found and no default given)
 
*nil = error (ID not found and no default given)
Line 29: Line 33:
 
*id_max = get_config_value(0); id_max is the highest ID value in conf_info[]
 
*id_max = get_config_value(0); id_max is the highest ID value in conf_info[]
 
Example:
 
Example:
*print("Restart lua on error?", get_config_value(238)) --0=no; 1=yes
+
print("Restart lua on error?", get_config_value(238)) --0=no; 1=yes
  +
*output: Restart lua on error? 0
 
  +
outputs: Restart lua on error? 0
  +
  +
'''Note:''' Effective with CHDK 1.3, some config values can be accessed by name -> [http://chdk.setepontos.com/index.php?topic=9602.10 CHDK Forum : Suggestion for CHDK configuration file saving]
   
 
==set_config_value==
 
==set_config_value==
   
 
Sets the value of the specified CHKD configuration value. Configuration values are selected by an index number found in CHDK source file [http://subversion.assembla.com/svn/chdk/trunk/core/conf.c conf.c] in the structure conf_info[].
 
Sets the value of the specified CHKD configuration value. Configuration values are selected by an index number found in CHDK source file [http://subversion.assembla.com/svn/chdk/trunk/core/conf.c conf.c] in the structure conf_info[].
  +
  +
'''uBASIC usage:'''
  +
  +
set_config_value <configID> <value>
   
 
'''Lua usage:'''
 
'''Lua usage:'''
Line 40: Line 51:
 
set_config_value(<ConfigID>[,int1][,int2][,str1][,table1])
 
set_config_value(<ConfigID>[,int1][,int2][,str1][,table1])
   
*returns true for success or false for error
+
*returns true on success or false on error
 
Example:
 
Example:
   
*set_config_value(238, 1) --conf.debug_lua_restart_on_error = 1 yes; 0 no
+
set_config_value(238, 1) --conf.debug_lua_restart_on_error = 1 yes; 0 no
  +
*Look in CHDK menu > Miscellaneous Stuff > Debug Parameters > Restart Lua on error (now has a dot beside it)
 
  +
In the CHDK menu > Miscellaneous Stuff > Debug Parameters > Restart Lua on error now has a dot beside it.
  +
  +
'''Note''': Effective with CHDK 1.3, some config values can be accessed by name -> [http://chdk.setepontos.com/index.php?topic=9602.10 CHDK Forum : Suggestion for CHDK configuration file saving]
   
 
==get_movie_status==
 
==get_movie_status==
   
Returns status of movie recording.
+
Returns the video recording status.
  +
  +
Can be used to check whether the camera has stopped recording and has finished writing to the SD card.
  +
  +
If 0 or 1 is returned, movie recording is stopped or paused.
  +
  +
If 4 is returned, recording is in progress.
  +
  +
If 5 is returned, recording has stopped but camera is still writing movie to SD card.
  +
  +
'''Note :''' a return status of "6" has been reported from the sx150. It '''may '''mean that recording has stopped and writing to the SD card is complete.
  +
  +
== get_video_recording ==
  +
Returns the video recording state.
  +
  +
Can be used to check whether the camera is currently recording.
  +
  +
In uBASIC, 0 is returned if video is not recording, 1 is returned if recording.
   
  +
In Lua, false is returned if video is not recording, true is returned if recording.
can be used for stuff like checks instead of sleep commands. if get_movie_status is 0 or 1, movie recording is stopped or paused. if get_movie_status is 4, recording is in progress. if it is 5, recording is stopped but camera is still writing movie to sdcard.
 
   
 
==set_movie_status==
 
==set_movie_status==
   
is experimental and so far only works on a720 & s3is properly. using this command you can pause, unpause and stop video recordings.
+
Is experimental and so far only works on A720 and S3IS cameras properly. Using this command video recording can be paused, unpaused and stopped.
   
set_movie_status 1 will pause movie (will not work on all cameras, typically they freeze or shutdown after 2 seconds !)
+
set_movie_status 1 will pause recording (will not work on all cameras, typically they freeze or shutdown after 2 seconds!).
   
set_movie_status 2 will unpause
+
set_movie_status 2 will unpause (restart) recording.
   
 
set_movie_status 3 will stop video recording (this should work on all types of cameras).
 
set_movie_status 3 will stop video recording (this should work on all types of cameras).
 
   
 
==get_video_button==
 
==get_video_button==
   
  +
uBASIC:
Return 1 when camera has a video button.
 
   
  +
Lua (CHDK version 1.3 or less):
Return 0 when camera has no video button.
 
  +
  +
Returns 1 if the camera has a video button.
  +
  +
Returns 0 if the camera has no video button.
  +
  +
Lua (CHDK version 1.4 or higher):
  +
  +
Returns true if the camera has a video button.
  +
  +
Returns false if the camera has no video button.
   
 
The returned value is based on the whether the platform_camera.h file for the camea indicates that it has a video button.
 
The returned value is based on the whether the platform_camera.h file for the camea indicates that it has a video button.
   
 
==get_display_mode==
 
==get_display_mode==
returns LCD display mode (in record mode only) regardless of propset used by the camera (one of the features to help get chdk scripts universal)
+
Returns LCD display mode (in record mode only), regardless of propset used by the camera (i.e. the function is universally available).
  +
  +
0 = show info icons, 1 = do not show info icons, 2 = LCD off, 3 = EVF
   
  +
Note : this function is available in uBASIC only.  For Lua use:
(0 = show info icons, 1 = Do not show info icons, 2 = LCD off, 3 = EVF)
 
  +
props=require("propcase")
  +
display_mode=get_prop(props.DISPLAY_MODE)
   
 
==get_propset==
 
==get_propset==
Returns the propset number used by the camera. Returns 1 for propset1, 2 for propset2, 3 for propset3 etc. Useful for writing scripts that are not dependent on a particular camera model or DIGIC processor. Information about values used for propsets can be found here: http://chdk.wikia.com/wiki/PropertyCase
+
Returns the propset number used by the camera. Returns 1 for propset1, 2 for propset2, 3 for propset3 etc. Useful for writing scripts that are not dependent on a particular camera model or DIGIC processor. Information about values used for propsets can be found here: [https://chdk.fandom.com/wiki/PropertyCase http://chdk.wikia.com/wiki/PropertyCase]
   
 
==get_zoom_steps==
 
==get_zoom_steps==
Line 93: Line 137:
   
 
==get_exp_count==
 
==get_exp_count==
  +
Returns the file number of the last exposure, ie the last 4 digits of the filename of the most recently taken photo. The camera only updates this counter after a shot is taken, so if you erase the last photo, it will still return the same number even though it doesn't exist. Similarly turning the camera off and on or even swapping flash cards will not update this value. The sole exception is after you format an SD card in the camera, this function will return 0.
 
will return number of shots in a session (afaik). useful for counting when you are for example in burst mode and want to stop after 3 shots.
 
 
On SD1000 returns file number of last exposure.
 
   
 
==get_drive_mode==
 
==get_drive_mode==
   
returns drivemode (as described on the property page)
+
Returns drive mode (as described on the property case page).
   
0 = single
+
0 = single shot,
1 = continuous
+
1 = continuous shooting,
2 = timer (on Digic II)
+
2 = timer (on Digic II) or
 
3 = timer (on Digic III)
 
3 = timer (on Digic III)
   
The timer issue will somewhat make it difficult to use it in universal scripts, however together with a get_propset this should be do-able.
+
The timer issue will somewhat make it difficult to use it in universal scripts, however, together with a get_propset this should be do-able.
   
 
==get_flash_mode==
 
==get_flash_mode==
  +
Returns flash mode.
returns flash mode (0,1,2 = flash auto, flash on, flash off)
 
  +
  +
0 = auto,
  +
1 = on,
  +
2 = off
   
 
==get_flash_ready==
 
==get_flash_ready==
returns 1 if flash is ready and charged,  0 otherwise
+
Returns 1 if flash is ready and charged, 0 otherwise.
   
 
==get_IS_mode==
 
==get_IS_mode==
returns IS mode
+
Returns IS mode.
   
  +
older cameras:
0,1,2,3 = continous, shoot only, panning, off
 
  +
0 = continuous,
  +
1 = shoot only,
  +
2 = panning,
  +
3 = off
  +
  +
newer cameras:
  +
0 = continuous,
  +
2 = shoot only,
  +
3 = panning,
  +
4 = off
   
 
==get_orientation_sensor==
 
==get_orientation_sensor==
regardless of Digic II / Digic III it will return the orientation sensor's degrees.
+
Regardless of Digic II / Digic III it will return the orientation sensor's degrees.
  +
  +
==get_min_av96==
  +
Get minimum valid av96 value (widest aperture), or nil (-1 in ubasic) if in playback or no iris.
  +
  +
This value is the minimum supported value at the time of the call, including the the effect of zoom position.
  +
  +
(''CHDK 1.5 and later'')
  +
  +
==get_max_av96==
  +
Get maximum valid av96 value (smallest aperture), or nil (-1 in ubasic) if in playback or no iris.
  +
  +
This value is the maximum supported value at the time of the call, including the the effect of zoom position.
  +
  +
(''CHDK 1.5 and later'')
   
 
==get_nd_present==
 
==get_nd_present==
returns 0 if no [[ND_Filter|ND Filter]] present, 1 if ND present and real diaphragm NOT present, 2 if both ND & diaphragm present.
+
Returns whether the camera has a switchable [[ND_Filter|ND Filter]], and, by inference, whether it has an adjustable aperture (as all Canon P&S cameras have at least one or the other).
  +
  +
0 = adjustable aperture only (camera does not have a switchable ND filter)
  +
  +
1 = ND filter only (camera does not have an adjustable aperture)
  +
  +
2 = camera has both ND filter and adjustable aperture 
  +
  +
==get_nd_value_ev96==
  +
Returns the value of the ND filter, in APEX*96 units. 0 if cameras does not have a built in ND.
  +
  +
(''CHDK 1.5 and later'')
  +
  +
==get_nd_current_ev96==
  +
Returns the exposure value of the current ND filter state, 0 if ND is out or camara does not have an ND filter, value returned by get_nd_value_ev96 if in.
  +
  +
'''Note''' This reflects the current state of the filter at the time of the call, not the override value set for the next shot. In live view, cameras may put the ND in or out based on lighting conditions.
  +
  +
(''CHDK 1.5 and later'')
   
 
==get_histo_range==
 
==get_histo_range==
Usage: &nbsp; <tt>get_histo_range</tt> <<tt>'''from'''</tt>> <<tt>'''to'''</tt>> &nbsp; returns percent of values between <from> and <to> in histogram data.
 
   
  +
Usage:<br /><tt>get_histo_range</tt> <<tt>'''from'''</tt>> <<tt>'''to'''</tt>><br />returns percentages of pixels with values between <from> and <to> in the histogram data.
This command gets the information about the histogram of the last image that was shot (i.e. after you have focused, metered, shot etc.), it operates reading the RAW buffer (but doesn't require raw saving to be enabled: the shot histogram data is obtained from the RAW data before discarding or further processing it).
 
   
  +
This command retrieves information about the histogram of the last image shot (i.e. after focussing and metering). It reads the RAW buffer (but does not require raw saving to be enabled): The histogram data is obtained from the RAW data before discarding or further processing.
It can be very useful to get informations about very dark scenes: the live preview screen is completely black, while the RAW buffer (with a long enough exposure) would contain an image.
 
  +
  +
It can be very useful in accessing information about very dark scenes: The live preview screen may be completely black, while the RAW buffer (with a long enough exposure) would contain an image.
   
 
* It depends on the <tt>shot_histo_enable</tt> command: if <tt>shot_histo_enable</tt> is not set, <tt>get_histo_range</tt> returns a value of <tt>-1</tt>, so <tt>shot_histo_enable</tt> has to be enabled first.
 
* It depends on the <tt>shot_histo_enable</tt> command: if <tt>shot_histo_enable</tt> is not set, <tt>get_histo_range</tt> returns a value of <tt>-1</tt>, so <tt>shot_histo_enable</tt> has to be enabled first.
   
This is necessary because the shot-histogram is calculated just after each shot and takes some time. So, by default the shot-histogram is disabled and you need to enable it with shot_histo_enable.
+
Because the shot histogram is calculated just after each shot and takes some time, it is disabled by default.
   
 
* Find more about this in this forum thread: [http://chdk.setepontos.com/index.php/topic,1145.0.html Timelapse with variable shutter speed]
 
* Find more about this in this forum thread: [http://chdk.setepontos.com/index.php/topic,1145.0.html Timelapse with variable shutter speed]
   
 
<u>Sample:</u>
 
<u>Sample:</u>
  +
 
<source lang="sdlbasic">
 
<source lang="sdlbasic">
 
rem enable shooting histogram
 
rem enable shooting histogram
Line 156: Line 245:
 
==autostarted==
 
==autostarted==
 
returns 1 (true) if script was autostarted
 
returns 1 (true) if script was autostarted
 
==is_pressed "key"==
 
checks if the specified key is being pressed when the command is called,  returns 1 for true,  0 for false
 
   
 
==get_shooting==
 
==get_shooting==
Line 168: Line 254:
   
 
==get_ev==
 
==get_ev==
  +
returns current (ev) exposure adjustment setting <span style="font-size:14px;"> </span><span style="font-size:14px;">in APEX96 units</span><span style="font-size:14px;"> (from propcase)</span>
returns propcase 25 (Digic II) / 107 (Digic III)
 
   
 
==set_ev==
 
==set_ev==
  +
sets the camera's (ev) exposure adjustment setting in APEX96 units (via propcase)
sets propcases 25 & 26 (Digic II) / 107 & 207 (Digic III)
 
   
 
==get_autostart & set_autostart==
 
==get_autostart & set_autostart==
Line 192: Line 278:
   
 
:http://chdk.setepontos.com/index.php/topic,1995.0.html
 
:http://chdk.setepontos.com/index.php/topic,1995.0.html
  +
Syntax:
   
Syntax:<pre>
+
<pre>
 
select EXPRESSION
 
select EXPRESSION
 
case EXPR. [to EXPR.] | [,EXPR.2[, ...]]; STATEMENT
 
case EXPR. [to EXPR.] | [,EXPR.2[, ...]]; STATEMENT
Line 201: Line 288:
 
end_select
 
end_select
 
</pre>
 
</pre>
  +
Sample:
   
Sample:<pre>
+
<pre>
 
for x=1 to 7
 
for x=1 to 7
 
select x
 
select x
Line 253: Line 341:
   
 
==print_screen==
 
==print_screen==
Usage: '''print_screen(123)''' (in Lua) or '''print_screen 123''' (in uBasic) creates LOG_0123.TXT in the \CHDK\LOGS folder
+
Usage: '''print_screen(123)''' (in Lua) or '''print_screen 123''' (in uBasic) creates LOG_0123.TXT in the \CHDK\LOGS folder.
   
  +
In uBasic:
*logging is disabled by 'print_screen(false)' in Lua or 'print_screen 0' in uBasic
 
*'print_screen(0)' in Lua or 'print_screen 10000' in uBasic writes to LOG_0000.TXT
 
*'print_screen(1)'  of ''print_screen(true' 'in Lua opens log file LOG_0001.TXT in overwrite mode''
 
*in uBASIC, calling print_screen with a positive number opens the log file in overwrite mode, ? and calling with a negative number opens an existing log file in append mode?
 
*in Lua, calling print_screen() with a number greater than zero opens an existing log file in overwrite mode, and calling with a number less than zero opens an existing file in append mode.  The file name number is abs(n).
 
   
  +
*logging is disabled 'print_screen 0';
  +
*'print_screen nnnn' writes to LOG_nnnn.TXT in overwrite mode (where nnnn is a number between 1 and 9999)
  +
*'print_screen -nnnn' writes to LOG_nnnn.TXT in append mode (where -nnnn is a number between -1 and -9999)
  +
In Lua:
   
  +
*logging is disabled by 'print_screen(false)'
<span style="line-height:21px;">Log files are stored in the folder \CHDK\LOGS with a naming scheme? </span>'''LOG_XXXX.TXT'''
 
  +
*print_screen(nnnn) writes to LOG_nnnn.TXT in overwrite mode (where nnnn is a number between 1 and 9999)
  +
*print_screen( -nnnn) writes to LOG_nnnn.TXT in append mode (where -nnnn is a number between -1 and -9999)
  +
*'print_screen(0)' writes to LOG_0000.TXT;
  +
*'print_screen(1)'  or 'print_screen(true)' opens log file LOG_0001.TXT in overwrite mode;
   
 
==get_time==
 
==get_time==
Line 287: Line 379:
   
 
==get_quality==
 
==get_quality==
''(since changeset #497)''
 
   
Returns the current capturing quality setting in Canon grades, regardless of the cameras OS
+
Returns the current image capture quality setting in Canon grades, regardless of the cameras OS
*For possible values see [[PropertyCase]] (basically quality can be 0-2 where 2 being the worst)
+
*For possible values see [[PropertyCase]] (basically quality can be <span style="font-size:14.4444446563721px;">0=Superfine, 1=Fine, 2=Normal</span>)
   
  +
''Note'' : uBASIC only : for Lua use :
''(not available in Lua yet)''
 
  +
  +
<source lang="lua">
  +
props=require("propcase")
  +
quality=get_prop(props.QUALITY)
  +
</source>
   
 
==get_resolution==
 
==get_resolution==
''(since changeset #497)''
 
   
Returns the current capturing resolution setting in Canon grades, regardless of the cameras OS
+
Returns the current image capture resolution setting in Canon grades, regardless of the cameras OS
*For possible values see [[PropertyCase]] (basically resolution can be 0-8, corresponding to the Canon settings)
+
*For possible values see [[PropertyCase]] (basically resolution might be <span style="font-size:14.4444446563721px;">0=L, 1=M1, 2=M2, 3=M3, 4=S, 5=RAW, 6=Postcard, 8=LW, 9=SW</span>, corresponding to the Canon settings)
   
  +
''Note'' : uBASIC only : for Lua use :
''(not available in Lua yet)''
 
  +
  +
<source lang="lua">
  +
props=require("propcase")
  +
resolution=get_prop(props.RESOLUTION)
  +
</source>
   
 
==set_quality==
 
==set_quality==
  +
Set the image quality (in Canon grades), usually 0-2, see [[PropertyCase]] for possible values.
''(since changeset #497)''
 
   
  +
''Note'' : uBASIC only : for Lua use :
Set the quality (in Canon grades), usually 0-2, see [[PropertyCase]] for possible values
 
   
  +
<source lang="lua">
''(not available in Lua yet)''
 
  +
props=require("propcase")
  +
value = 1 -- 0=best, 2=worst
  +
status=set_prop(props.QUALITY, value)
  +
</source>
   
 
==set_resolution==
 
==set_resolution==
  +
Set the image resolution (in Canon steps), usually 0-8, see [[PropertyCase]] for possible values.
''(since changeset #497)''
 
   
  +
Note: uBASIC only.
Set the resolution (in Canon grades), usually 0-8, see [[PropertyCase]] for possible values
 
   
  +
In Lua use :
''(not available in Lua yet)''
 
  +
  +
<source lang="lua">
  +
props=require("propcase")
  +
value = 1
  +
status=set_prop(props.RESOLUTION, value)
  +
</source>
  +
  +
==get_canon_raw_support==
  +
''(Since CHDK 1.5.1, Lua only until build 5851)''
  +
  +
Returns true if the original Canon firmware supports raw.
  +
  +
==get_canon_image_format==
  +
''(Since CHDK 1.5.1, Lua only until build 5851)''
  +
  +
Returns current Canon RAW/JPEG settings as a bitmask, 1 = JPEG, 2 = CR2, 3 = BOTH. On cameras without native raw support, always returns 1.
  +
  +
==set_canon_image_format==
  +
''(Since CHDK 1.5.1, Lua only until build 5851)''
  +
  +
For cameras with native raw support, set Canon firmware image format: 1 = JPEG, 2 = CR2, 3 = BOTH. Returns true if format is supported by Canon firmware, false if not.
  +
  +
''Notes'':
  +
* The setting is lost when shooting mode is changed or the camera is switched to playback
  +
* On models where "RAW" is an image resolution in the Canon UI, setting format to JPEG sets resolution to "Large" if the previous setting is unknown.
   
 
==get_platform_id==
 
==get_platform_id==
 
''(since version 0.8.3 / changeset #593)''
 
''(since version 0.8.3 / changeset #593)''
   
Returns <tt>'''platformid'''</tt> (integer), with the help of this you can code platform depending scripts (in Lua we dont need this, as we can get strings there). '''?'''[[Platform-ID|Platform-ID list]]
+
Returns <tt>'''platformid'''</tt> (integer) which helps to code platform-dependent scripts. '''?'''[[Platform-ID|Platform-ID list]]
   
''(only available in uBasic; for Lua scripts use <tt>get_buildinfo</tt> instead)''
+
''(Only available in uBasic; in Lua scripts use <tt>get_buildinfo</tt> instead.)''
   
 
==set_backlight()==
 
==set_backlight()==
With this function the LCD Backlight (or EVF backlight) can be turned on and off - useful for energy saving or camouflage missions. (Backlight is a bright light inside the LCD, making the image visible.)
+
With this function the LCD backlight (or EVF backlight) can be turned on and off - useful for energy saving or camouflage missions. (Backlight is a bright light inside the LCD making the image visible.)
   
  +
Usage:
Usage: <tt>set_backlight(x)</tt> (Lua) or <tt>set_backlight x</tt> (uBASIC), where '''0''' disables backlight and '''1''' enables it.
 
   
  +
*<tt>set_backlight(x)</tt>       ''(Lua) '' 
* Note: Camera enables backlight after each shot. To keep backlight mostly disabled, this command must be called after each shot. But do not call it immediately after a shot or its effect will be very shortlived. You must wait for LCD live view image exposure to settle before calling. The regular shoot state loop may help, possibly with some added delay. Test in varying lighting conditions to see if you got it right.
 
  +
* Note: If you accidentally exit a script while backlight is disabled, you can get it back by leaving ALT mode and shooting, or by powering off. The LCD can probably be somewhat read even when backlight is disabled if bright light is pointed at it from a suitable angle. Alternatively, you may turn on the LCD Backlight in a section labeled :restore (uBasic) or a function called restore (Lua), which will be executed when the script is interrupted.
 
  +
*<tt>set_backlight x    </tt>  ''(uBASIC)''
  +
  +
where '''0''' disables backlight and '''1''' enables the backlight.
  +
  +
Notes:
  +
  +
* The camera re-enables the backlight after each shot. To keep backlight mostly disabled, this command must be called after each shot. But if called immediately after a shot its effect is very shortlived. The LCD live view image exposure has to settle before calling to take effect. The regular shoot state loop may help, possibly with some added delay. Test in varying lighting conditions to see if it works.
  +
* If a script is accidentally exited while the backlight is disabled, it can be restored by leaving ALT mode and shooting, or by powering off. The LCD can probably be somewhat read even when backlight is disabled if bright light is pointed at it from a suitable angle. Alternatively, the LCD backlight can be turned back on again in a script section labeled :restore (uBASIC) or a function called restore (Lua), which is executed when the script is interrupted.
 
* An example script can be found here: [http://chdk.setepontos.com/index.php/topic,2744.msg27703.html#msg27703]
 
* An example script can be found here: [http://chdk.setepontos.com/index.php/topic,2744.msg27703.html#msg27703]
   
  +
==set_lcd_display()==
==set_aflock==
 
  +
With this function the LCD display and backlight (or EVF backlight) can be turned on and off - useful for energy saving or camouflage missions. (Backlight is a bright light inside the LCD, making the image visible.)
''(since version 0.9.2 / changeset #681)''
 
   
  +
Usage:  
Lock/unlock autofocus
 
  +
  +
*<tt>set_lcd_display(x)   </tt>'' (Lua) ''  
  +
  +
*<tt>set_lcd_display x</tt>         ''(uBASIC)''
  +
  +
where '''0''' disables the display and '''1''' enables the display. Lua also accepts boolean values.
  +
  +
Notes:
  +
  +
* This command works much like set_backlight() except that it actually turns off the whole display and not just the backlight.   The display also stays off after each shot - unlike the backlight when set_backlight() is used. 
  +
* It may be necessary to set Review mode to Off in the Canon menu for this to work reliably 
  +
* Restoring the display via set_lcd_display(1) may be somewhat slower than when restoring the backlight with set_backlight(1)
  +
* When set_lcd_display(1) is issued, the various Canon OSD icons and text may not be redrawn until the next press of a camera button while the camera is not in <ALT> mode.
  +
* If you accidentally exit a script while the display is disabled, you can get it back by leaving ALT mode (by pressing the <ALT> key once) and then repeatedly pressing the DISP key.  You can also get it back by powering off.  Alternatively, you may turn on the display in a section labeled :restore (uBasic) or a function called restore (Lua), which will be executed when the script is interrupted.
  +
* On some cameras, attempting to switch from rec to play mode with the display turned off may cause the camera to hang. Temporarily turning the display on for the duration of the switch should avoid this. See https://chdk.setepontos.com/index.php?topic=10551.msg136577#msg136577
  +
* An example script can be found here: [http://chdk.setepontos.com/index.php?topic=10551.msg106578#msg106578]
  +
* Available in CHDK version 1.2.0 or newer
  +
  +
==set_draw_title_line==
  +
'''(CHDK Version 1.3.0 or greater required)'''
  +
  +
This function enables / disables the drawing of the CHDK OSD title line at the bottom of the LCD screen ( <ALT> and current script name )
  +
*''set_draw_title_line(0)'' - disables the display of the <ALT> symbol and the currently loaded script name
  +
*''set_draw_title_line(1)'' - enables the display of the <ALT> symbol and the currently loaded script name 
  +
'''From CHDK version 1.7.0 revision 6203 or later:'''
  +
  +
* ''set_draw_title_line(2)'' - displays the <ALT> text; but hides the currently loaded script name 
  +
  +
Note : Lua syntax shown -  uBASIC  syntax is  ''set_draw_title_line 0''    and    ''set_draw_title_line 1''
  +
  +
==get_draw_title_line==
  +
'''(CHDK 1.3.0 or later)'''
  +
  +
This function returns the current on/off status of the CHDK OSD title line at the bottom of the LCD screen ( <ALT> and current script name ).
  +
  +
==get_sd_over_modes==
  +
Returns a bit field value indicating when subject distance override (i.e. ''set_focus() '') will work with this camera.
  +
  +
{| border="1" cellpadding="1" cellspacing="1" class="article-table" style="margin: 0px auto; width: 500px;"
  +
|-
  +
! scope="col"|Bit
  +
! scope="col"|Meaning
  +
|-
  +
|0x01
  +
|set_focus() works in AutoFocus mode (i.e. MF or AFL not active)
  +
|-
  +
|0x02
  +
|set_focus() works when AFL active (see ''set_aflock()'' command)
  +
|-
  +
|0x04
  +
|set_focus() works when MF active (see ''set_mf()'' command)
  +
|}
  +
  +
'''Note:''' CHDK 1.3.0 or later.
  +
  +
==set_aflock==
  +
Lock/unlock autofocus.
   
 
Usage:
 
Usage:
   
<tt>Lua: set_aflock(x)</tt>
+
: <tt>Lua: set_aflock(x)</tt>
   
<tt>uBASIC:</tt> <tt>set_aflock x</tt>
+
: <tt>uBASIC:</tt> <tt>set_aflock x</tt>
   
 
where '''1''' locks the autofocus and '''0''' unlocks it.
 
where '''1''' locks the autofocus and '''0''' unlocks it.
   
It is like MF, but better in several ways, such as a) it is available on ALL cameras; b) focus is locked even after camera returns from deep display sleep (via display key cycle or print button shortcut), which is very good for timelapse, with regard to power consumption, camera shake, an actual fixed focus throughout the whole timelapse and also less stress on the mechanical parts of the camera.
+
It is like Canon's built-in manual focus mode (MF), but better because focus stays locked even after camera returns from deep display sleep (via display key cycle or print button shortcut), which is very good for timelapse.
   
 
Example:
 
Example:
   
<tt>press "shoot_half"<br />
+
<tt>press "shoot_half"<br /> 
sleep 800<br />
+
sleep 800<br /> 
release "shoot_half"<br />
+
release "shoot_half"<br /> 
 
set_aflock 1</tt>
 
set_aflock 1</tt>
  +
  +
'''Note''': In older versions of CHDK (prior to 1.3.0), this function does not work on all cameras and may actually crash the camera. More information here: [http://chdk.setepontos.com/index.php?topic=11078.0 CHDK Forum Thread]. See also the following function, set_mf().
  +
  +
==set_mf==
  +
'''(CHDK 1.3.0 or later)'''
  +
  +
Lock/unlock Canon manual focus (MF) mode.
  +
  +
Usage:
  +
  +
: <tt>Lua: set_mf(x)</tt>
  +
  +
: <tt>uBASIC: set_mf x</tt>
  +
  +
where '''1''' locks the camera in MF mode and '''0''' unlocks it.
  +
  +
When used with Lua, returns "0" if MF is not supported and "1" if it is supported on the camera using the function.
  +
  +
Similar to set_aflock(), this function places the camera in a mode where SD override commands (e.g. set_focus) can be used and the value requested will be maintained across multiple shots.
  +
  +
'''Note: '''works on almost all cameras, even those that do not have a Canon MF mode. More information here:  [http://chdk.setepontos.com/index.php?topic=11078.0 CHDK Forum Thread].
  +
  +
==set_aelock==
  +
'''(CHDK 1.3.0 or later)'''
  +
  +
<span style="line-height:21px;">Lock/unlock auto exposure adjust in still or video shooting modes.</span>
  +
  +
Usage:
  +
  +
: <tt>Lua: set_aelock(x)</tt>
  +
  +
: <tt>uBASIC:</tt> <tt>set_aelock x</tt>
  +
  +
where '''1''' locks autoexposure adjustments and '''0''' unlocks them.
  +
  +
'''Note:''' using set_aelock(1) will always cause [[Script_commands#get_shooting|get_shooting()]] to return true. This will lock the script [[CHDK_scripting#shoot|shoot()]] function. A script using set_aelock() must use press(shoot_half) and press(shoot_full) commands to shoot.  Use [[Script_commands#get_focus_ok|get_focus_ok()]] to check for focus rather than  [[Script_commands#get_shooting|get_shooting()]]  (which checks both focus and exposure).
   
 
==set_record(state)==
 
==set_record(state)==
 
'''state''' 0 (or false) changes to play mode. 1 or true changes to record mode.
 
'''state''' 0 (or false) changes to play mode. 1 or true changes to record mode.
   
NOTE 1: this only begins the mode change. Script should wait until get_mode() reflects the change before doing anything that requires the new mode. e.g.
+
Note 1: This only initiates the mode change. Script should wait until get_mode() reflects the change before doing anything that requires the new mode. e.g.
   
 
set_record(true)
 
set_record(true)
Line 364: Line 594:
 
end
 
end
   
NOTE 2: In ubasic, get_mode returns 0 for record, 1 for play and 2 for movie, so if you want save the state and restore it with set_record, you cannot just use the get_mode value directly. You can adjust the value from get_mode, or use get_capture_mode instead.
+
Note 2: In uBASIC, get_mode returns 0 for record, 1 for play and 2 for movie, so if you want save the state and restore it with set_record, you cannot just use the get_mode value directly. You can adjust the value from get_mode, or use get_capture_mode instead.
   
 
''(since version 0.9.8 / changeset #826)''
 
''(since version 0.9.8 / changeset #826)''
Line 406: Line 636:
   
 
==get_capture_mode==
 
==get_capture_mode==
Ubasic only, not needed in lua, use [[Lua/Lua_Reference#get_mode|get_mode()]] instead.
+
uBASIC only, not needed in Lua, use [[Lua/Lua_Reference#get_mode|get_mode()]] instead.
   
 
returns the current camera automatic image mode, or 0 if camera is in play mode or 0 if there is no modemap entry
 
returns the current camera automatic image mode, or 0 if camera is in play mode or 0 if there is no modemap entry
Line 418: Line 648:
   
 
==set_console_autoredraw==
 
==set_console_autoredraw==
''New commands for the customizable script console, introduced with changeset #899, updated in changeset #1394.''
 
   
'''set_console_autoredraw('''-1|0|1''')''' --> enable or disable automatic rewrite/refresh of the console.
+
'''set_console_autoredraw('''-1|0|1''')''' --> determines how text from a script's ''print()'' statement is handled when it is sent to the screen console buffer.
   
 
Parameters:
 
Parameters:
'''-1''' = log only (update to log file but not to display)
 
''' 0''' = disable
 
''' 1''' = enable (update to log file and display)
 
   
  +
* -1 = text from print statement is not added to console buffer
==console_redraw==
 
''New commands for the customizable script console, introduced with changeset '''#899''' ''
 
   
  +
* 0 = text from print statement is added to console buffer but the console display is not refreshed.
  +
  +
* 1 = text from print statement is added to console buffer and the console display is refreshed.
  +
Default setting = 1
  +
  +
'''Note :'''  the ''print_screen()'' statement determines how text from a print statement is logged to the camera's SD card. It functions independently from the ''set_console_autoredraw()'' statement.
  +
  +
==console_redraw==
 
'''console_redraw()''' --> manually refresh/rewrite the script console
 
'''console_redraw()''' --> manually refresh/rewrite the script console
   
Line 435: Line 668:
 
Reboot the the camera, optionally using a specified file.
 
Reboot the the camera, optionally using a specified file.
   
If file is not given, a normal the normal camera boot sequence is used, CHDK will be started or not based on the normal autostart rules.
+
If file is not given, the normal camera boot sequence is used - CHDK will be started or not based on the normal autostart rules (i.e. SD card lock switch position).
   
 
If the first two characters of the file extension are "FI" the file will be treated loaded as a firmware update file, encoded with the normal firmware update encoding. Currently, this only works on DryOS, vxworks cameras will just return without rebooting.
 
If the first two characters of the file extension are "FI" the file will be treated loaded as a firmware update file, encoded with the normal firmware update encoding. Currently, this only works on DryOS, vxworks cameras will just return without rebooting.
Line 451: Line 684:
   
 
==restore==
 
==restore==
Both Lua and uBasic provide a mechanism for allowing the programmer to specify a piece of code to be executed immediately prior to the termination or interruption of a running program. This allows for such things as enabling the backlight if it was turned off or releasing overrides. To use this capability in uBasic, insert a label called '':restore'' in your code (usually right before the end statement) and add the lines of code you would like executed as the program terminates or is interrupted.
+
Both Lua and uBasic provide a mechanism for allowing the programmer to specify a piece of code to be executed when the script is terminated with the interrupt key (by default, shutter full press). This allows for such things as enabling the backlight if it was turned off or releasing overrides. To use this capability in uBasic, insert a label called '':restore'' in your code (usually right before the end statement) and add the lines of code you would like executed as the program terminates or is interrupted.
   
To use this capability in Lua, add a function called ''restore()'' to your Lua script with the commands you would like to see executed when Lua terminates or interrupts the currently running script. In Lua, this function should be near to the top of your script, before any loops so it is defined when the script is interrupted.
+
To use this capability in Lua, add a function called ''restore()'' to your Lua script with the commands you would like to see executed when the script is interrupted. In Lua, this function should be near to the top of your script, before any loops so it is defined when the script is interrupted.
   
 
'''Notes:'''
 
'''Notes:'''
*This code will be called when the script is terminated by pressing the camera's shutter button. However, in ubasic, the code will wait for any ''sleep'' commands to finish before executing so it might be better to use short ''sleep'' commands inside a counting loop rather than one long ''sleep'' command. In Lua, the function is executed immediately
+
* The restore code will be called when the script is terminated by pressing the camera's shutter button. However, in ubasic, the code will wait for any ''sleep'' commands to finish before executing so it might be better to use short ''sleep'' commands inside a counting loop rather than one long ''sleep'' command. In Lua, the function is executed immediately
* Restore in lua should not using any functions that yield, such as sleep, key press / release etc.
+
* Restore is '''not''' called when a script exits due to a runtime error such as error() in Lua, or a syntax error
  +
* When a script exits normally, restore can be executed using normal control flow, by reaching the :restore label in ubasic or calling restore() in Lua
  +
* In Lua, restore must not use functions functions that wait (yield), such as sleep, wait_click, key press / release etc. Prior to build 6253 these functions immediately end the script without any message. Later versions end with the error message "ERROR: cannot yield in restore"
  +
* In Lua prior to CHDK 1.7 r6253 and 1.6 r6256, restore silently ends the script after a small, unpredictable number of Lua statements, typically, not more than 10-20. Later versions allow restore to run for up to one second, and exit with the error "restore timeout" if the time is exceeded ([https://chdk.setepontos.com/index.php?topic=14793.msg149934#msg149934 forum discussion])
   
 
==set_exit_key==
 
==set_exit_key==
  +
'''(CHDK Version 1.3.0 or greater required)'''
Allows a script to set the key used to terminate its execution. The default key for this action is the shutter full press key. However, for scripts that need to capture a shutter full press, an alternate key can be selected. Takes a string argument using the same values as press / click / release.
 
   
  +
Allows a script to set the key used to terminate its execution. The default key for this action is the shutter full press key. However, for scripts that need to capture a shutter full press, an alternate key can be selected. Takes a string argument using the same values used by is_pressed / press / click / release.
==set_yield==
 
This command controls how CPU time is allocated to running scripts.
 
   
  +
'''Note : ''' you can use  '' set_exit_key("no_key")''   so that there is no key sequence that forces the termination of a running script
You can adjust these values to allow complex scripts to run more quickly. This will cause less CPU to be available for other tasks, which may have side effects. Note that increasing these values will '''not''' make operations that happen outside of script code (e.g. shooting, motion detection) any faster.
 
   
  +
==set_yield==
The script task yields (sleep for 10ms) when either condition is met. Values are treated as unsigned, so -1 can be used to effectively disable either condition.
 
  +
This command controls how much of the camera's CPU time is allocated to running scripts.
   
  +
The CHDK script engine yields (sleep for 10ms, or possibly more on some cameras) when either a specified number of script lines have been executed or a specified time period has passed. These limits can be adjusted to allow complex scripts to run more quickly. However, this will cause less CPU to be available for other camera tasks, which may have side effects. Note that increasing these values will '''not''' make operations that happen outside of script code (e.g. shooting, motion detection) any faster. Specified values are treated as unsigned, so -1 can be used to effectively disable either condition by making the number of lines or time period very large.
Commands that wait (such as sleep, wait_click, md_detect_motion etc) or send key presses yield immediately.
 
   
  +
Commands that wait (such as sleep, wait_click, md_detect_motion etc) or send key presses yield immediately.  
ubasic usage:
 
  +
  +
'''ubasic usage:'''
   
 
<tt>set_yield &lt;MAX_LINES&gt; &lt;MAX_MS&gt;</tt>
 
<tt>set_yield &lt;MAX_LINES&gt; &lt;MAX_MS&gt;</tt>
Line 479: Line 717:
 
MAX_MS is the maximum number of milliseconds a single iteration of the script task is allowed to run for before yielding. Default is 10.
 
MAX_MS is the maximum number of milliseconds a single iteration of the script task is allowed to run for before yielding. Default is 10.
   
The value has a resolution of 10ms, and is checked after each line. Since the resolution is 10ms, and the start of a script iteration does not necessarily begin in sync with the system clock, the actual time may be less than ten ms.
+
The value has a resolution of 10ms, and is checked after each line. Since the start of a script iteration does not necessarily begin in sync with the system clock, the actual time may be less than 10ms.
   
 
Passing zero for either value resets it to default.
 
Passing zero for either value resets it to default.
   
lua usage:
+
'''lua usage''':
   
 
<tt>old_max_count,old_max_ms=set_yield(&lt;MAX_COUNT&gt;,&lt;MAX_MS&gt;)</tt>
 
<tt>old_max_count,old_max_ms=set_yield(&lt;MAX_COUNT&gt;,&lt;MAX_MS&gt;)</tt>
Line 494: Line 732:
   
 
In Lua, calls to lua code from within C (for example, using pcall()) cannot yield. However the VM calls and time will still be counted, so a yield will occur within 100 instructions after the C call if the limits are exceeded.
 
In Lua, calls to lua code from within C (for example, using pcall()) cannot yield. However the VM calls and time will still be counted, so a yield will occur within 100 instructions after the C call if the limits are exceeded.
 
''(since changeset #1434, an incompatible variant for ubasic was introduced in changeset #1427)''
 
   
 
==get_curve_file==
 
==get_curve_file==
Line 556: Line 792:
 
(only for Lua)
 
(only for Lua)
   
==swap_partition==
+
==swap_partitions==
   
Change the partition. swap_partition(n) -> n = num of partition
+
Change the partition. swap_partitions(n) -> n = num of partition
   
 
(only for Lua)
 
(only for Lua)
Line 568: Line 804:
 
bi=get_buildinfo()
 
bi=get_buildinfo()
   
  +
* bi.platform - CHDK platform name, as string like "ixus80_sd1100"
* bi.platform
 
  +
* bi.platsub - Canon firmware version CHDK was compiled for, as string like "100c"
* bi.platsub
 
* bi.version
+
* bi.version - string "CHDK"
* bi.build_number
+
* bi.build_number - as string like "1.5.1"
* bi.build_revision
+
* bi.build_revision - SVN revision number, as string like "1234"
* bi.build_date
+
* bi.build_date - Date CHDK was compiled, as string
* bi.build_time
+
* bi.build_time - Time CHDK was compiled, as string
  +
* bi.os - String "vxworks" or "dryos"
* bi.os
 
* bi.platformid
+
* bi.platformid - USB product ID of camera, as number
  +
* bi.digic - Digic version as number times 10, like digic 2 = 20, digic 4 = 40, digic 4+ = 41. (CHDK 1.5 and later)
   
 
(only for Lua)
 
(only for Lua)
Line 582: Line 819:
 
==get_dofinfo==
 
==get_dofinfo==
   
Returns a table with dof and focus related informations.
+
Returns a table with dof and focus related information. Note that depending on camera settings, some values are only updated on half press.
   
 
dof=get_dofinfo()
 
dof=get_dofinfo()
   
 
* dof.hyp_valid [boolean] - Is hyperfocal distance valid?
 
* dof.hyp_valid [boolean] - Is hyperfocal distance valid?
* dof.focus_valid [boolean] - Is focus valid?
 
* dof.aperture [x 1000] - aperture
 
* dof.coc [x 1000 mm] - circle of confusion
 
* dof.focal_length [x 1000 mm] - focal length
 
 
* dof.eff_focal_length [x 1000 mm] - 35mm equivalent focal length
 
* dof.eff_focal_length [x 1000 mm] - 35mm equivalent focal length
* dof.focus [mm] - focus distance
+
* dof.coc [x 1000 mm] - circle of confusion
  +
* dof.aperture [x 1000] - aperture
 
* dof.near [mm] - near limit
 
* dof.near [mm] - near limit
* dof.far [mm] - far limit
+
* dof.min_stack_dist [mm] - smallest meaningful stack distance
 
* dof.dof [mm] - DOF
 
* dof.dof [mm] - DOF
  +
* dof.focal_length [x 1000 mm] - focal length
 
* dof.hyp_dist [mm] - hyperfocal distance
 
* dof.hyp_dist [mm] - hyperfocal distance
* dof.min_stack_dist [mm] - smallest meaningful stack distance
+
* dof.far [mm] - far limit
  +
* dof.focus [mm] - focus distance
  +
* dof.focus_valid [boolean] - Is focus valid?
   
 
(only for Lua)
 
(only for Lua)
   
==get_video_details==
 
 
<<deprecated>>
 
   
 
==textbox==
 
==textbox==
Line 620: Line 854:
   
 
*SHOOT_HALF switches between lower case/upper case/digits/special
 
*SHOOT_HALF switches between lower case/upper case/digits/special
*ZOOM_IN od DISPLAY- spacebar
+
*ZOOM_IN or DISPLAY- spacebar
 
*ZOOM_OUT or ERASE - delete
 
*ZOOM_OUT or ERASE - delete
 
*JOGDIAL moves the cursor
 
*JOGDIAL moves the cursor
Line 626: Line 860:
 
*MENU once again switches to OK/CANCEL - user can submit or cancel the editing.
 
*MENU once again switches to OK/CANCEL - user can submit or cancel the editing.
 
(Lua only)
 
(Lua only)
  +
  +
==get_raw_support==
  +
'''(CHDK 1.4 and later)'''
  +
  +
Return true (1 in uBASIC) if in rec mode and raw data is available in the current capture mode. If raw data is not available, CHDK raw will not be saved, and [[Lua/Raw Hook Operations]] cannot be used.
  +
  +
'''Note:''' Currently returns true in dedicated video modes, even if still shooting is not possible.
  +
  +
==get_digic==
  +
returns DIGIC processor type multipied by ten (to capture first decimal place) 
  +
digic 2 = 20, digic IV = 40, digic IV+ = 41 etc
  +
uBASIC only
  +
  +
== set_clock ==
  +
:'''set_clock('''''year, month, day, hour, minute, second''''')'''
  +
:Set the camera date / time (Lua only). Values are integers and all are required. Values are all exactly as they would appear in the camera clock: 4 digit year, month and day numbers start at 1. It is not aware of DST, the displayed time after setting is the values set, regardless of the DST setting.
  +
:See https://chdk.setepontos.com/index.php?topic=14091.0
  +
==set_focus_interlock_bypass==
  +
disables CHDK internal safety checks related to whether scripted manual focussing is allowed
  +
  +
Lua only
   
 
==APEX96 Conversion Functions==
 
==APEX96 Conversion Functions==
Line 642: Line 897:
   
 
===sv96_real_to_market===
 
===sv96_real_to_market===
converts an sv96 value to a "market" ISO sensitivity value
+
converts a "real" sv96 value to a "market" sv96 value
   
 
===sv96_market_to_real===
 
===sv96_market_to_real===
converts an sv96 value to a "real" ISO sensitivity value
+
converts an "market" sv96 value to a "real" sv96 value
   
 
===aperture_to_av96===
 
===aperture_to_av96===
Line 710: Line 965:
   
 
</syntaxhighlight>
 
</syntaxhighlight>
  +
  +
== Live View Exposure Functions==
  +
( see https://chdk.setepontos.com/index.php?topic=13508.0 )
  +
  +
''(CHDK 1.5 and later)''
  +
  +
===get_imager_active===
  +
returns boolean of camera's image sensor active status (true=running, false=not running).
  +
  +
The sensor usually goes inactive when the Canon firmware turns off the display for power saving. In this state, features like motion detection and live histogram will not function correctly. Additional, some firmware functions may fail or crash. This can include focus related functions like set_aflock, and switching to playback mode over PTP.
  +
  +
===get_current_tv96===
  +
returns current TV96 value being used by camera in live view
  +
  +
===get_current_av96===
  +
returns current AV96 value being used by camera in live view
 
[[Category:Scripting]]
 
[[Category:Scripting]]
 
[[Category:uBASIC]]
 
[[Category:uBASIC]]

Latest revision as of 05:00, 28 August 2023

Note: This is work in progress... Please add. Fe50 01:21, December 28, 2010 (UTC)



Additional uBASIC and Lua Scripting Commands

Notice

CHDK scripting basics and the most commonly used scripting commands are explained on the UBASIC/TutorialScratchpad page. Lua specific commands are documented at Lua/Lua_Reference. A complete cross reference of all scripting commands can be found here : CHDK Scripting Cross Reference Page

get_config_value

Returns the value of the specified CHDK configuration item. These are the items set in the CHDK menus. Use the index number found in CHDK source file conf.c in the structure conf_info[].

uBASIC usage:

v=get_config_value <configID>

Lua usage:

int1[,int2][,str1][,table1]=get_config_value(configid[,default])

  • int1 = config value integer
  • int1, int2 = positions of OSD elements (x,y)
  • str1 = config value string (eg. a file path)
  • table1 = config value fields
  • configid = index number from conf.c structure conf_info[]
  • default = message value, when ID not found
  • nil = error (ID not found and no default given)
  • id_max = get_config_value(0); id_max is the highest ID value in conf_info[]

Example:

print("Restart lua on error?", get_config_value(238)) --0=no; 1=yes

outputs: Restart lua on error? 0

Note: Effective with CHDK 1.3, some config values can be accessed by name -> CHDK Forum : Suggestion for CHDK configuration file saving

set_config_value

Sets the value of the specified CHKD configuration value. Configuration values are selected by an index number found in CHDK source file conf.c in the structure conf_info[].

uBASIC usage:

set_config_value <configID> <value>

Lua usage:

set_config_value(<ConfigID>[,int1][,int2][,str1][,table1])

  • returns true on success or false on error

Example:

set_config_value(238, 1) --conf.debug_lua_restart_on_error = 1 yes; 0 no

In the CHDK menu > Miscellaneous Stuff > Debug Parameters > Restart Lua on error now has a dot beside it.

Note: Effective with CHDK 1.3, some config values can be accessed by name -> CHDK Forum : Suggestion for CHDK configuration file saving

get_movie_status

Returns the video recording status.

Can be used to check whether the camera has stopped recording and has finished writing to the SD card.

If 0 or 1 is returned, movie recording is stopped or paused.

If 4 is returned, recording is in progress.

If 5 is returned, recording has stopped but camera is still writing movie to SD card.

Note : a return status of "6" has been reported from the sx150. It may mean that recording has stopped and writing to the SD card is complete.

get_video_recording

Returns the video recording state.

Can be used to check whether the camera is currently recording.

In uBASIC, 0 is returned if video is not recording, 1 is returned if recording.

In Lua, false is returned if video is not recording, true is returned if recording.

set_movie_status

Is experimental and so far only works on A720 and S3IS cameras properly. Using this command video recording can be paused, unpaused and stopped.

set_movie_status 1 will pause recording (will not work on all cameras, typically they freeze or shutdown after 2 seconds!).

set_movie_status 2 will unpause (restart) recording.

set_movie_status 3 will stop video recording (this should work on all types of cameras).

get_video_button

uBASIC:

Lua (CHDK version 1.3 or less):

Returns 1 if the camera has a video button.

Returns 0 if the camera has no video button.

Lua (CHDK version 1.4 or higher):

Returns true if the camera has a video button.

Returns false if the camera has no video button.

The returned value is based on the whether the platform_camera.h file for the camea indicates that it has a video button.

get_display_mode

Returns LCD display mode (in record mode only), regardless of propset used by the camera (i.e. the function is universally available).

0 = show info icons, 1 = do not show info icons, 2 = LCD off, 3 = EVF

Note : this function is available in uBASIC only.  For Lua use:

props=require("propcase")
display_mode=get_prop(props.DISPLAY_MODE)

get_propset

Returns the propset number used by the camera. Returns 1 for propset1, 2 for propset2, 3 for propset3 etc. Useful for writing scripts that are not dependent on a particular camera model or DIGIC processor. Information about values used for propsets can be found here: http://chdk.wikia.com/wiki/PropertyCase

get_zoom_steps

Returns number of maximum zoom steps, irrespective of the processor. For example on the A620 it will return 8, on the S3IS it will return 128.

This allows for universal zoom scripts.

Example:

for i=0 to get_zoom_steps

... do some things in this loop

next i

get_exp_count

Returns the file number of the last exposure, ie the last 4 digits of the filename of the most recently taken photo. The camera only updates this counter after a shot is taken, so if you erase the last photo, it will still return the same number even though it doesn't exist. Similarly turning the camera off and on or even swapping flash cards will not update this value. The sole exception is after you format an SD card in the camera, this function will return 0.

get_drive_mode

Returns drive mode (as described on the property case page).

0 = single shot, 1 = continuous shooting, 2 = timer (on Digic II) or 3 = timer (on Digic III)

The timer issue will somewhat make it difficult to use it in universal scripts, however, together with a get_propset this should be do-able.

get_flash_mode

Returns flash mode.

0 = auto, 1 = on, 2 = off

get_flash_ready

Returns 1 if flash is ready and charged, 0 otherwise.

get_IS_mode

Returns IS mode.

older cameras: 0 = continuous, 1 = shoot only, 2 = panning, 3 = off

newer cameras: 0 = continuous, 2 = shoot only, 3 = panning, 4 = off

get_orientation_sensor

Regardless of Digic II / Digic III it will return the orientation sensor's degrees.

get_min_av96

Get minimum valid av96 value (widest aperture), or nil (-1 in ubasic) if in playback or no iris.

This value is the minimum supported value at the time of the call, including the the effect of zoom position.

(CHDK 1.5 and later)

get_max_av96

Get maximum valid av96 value (smallest aperture), or nil (-1 in ubasic) if in playback or no iris.

This value is the maximum supported value at the time of the call, including the the effect of zoom position.

(CHDK 1.5 and later)

get_nd_present

Returns whether the camera has a switchable ND Filter, and, by inference, whether it has an adjustable aperture (as all Canon P&S cameras have at least one or the other).

0 = adjustable aperture only (camera does not have a switchable ND filter)

1 = ND filter only (camera does not have an adjustable aperture)

2 = camera has both ND filter and adjustable aperture 

get_nd_value_ev96

Returns the value of the ND filter, in APEX*96 units. 0 if cameras does not have a built in ND.

(CHDK 1.5 and later)

get_nd_current_ev96

Returns the exposure value of the current ND filter state, 0 if ND is out or camara does not have an ND filter, value returned by get_nd_value_ev96 if in.

Note This reflects the current state of the filter at the time of the call, not the override value set for the next shot. In live view, cameras may put the ND in or out based on lighting conditions.

(CHDK 1.5 and later)

get_histo_range

Usage:
get_histo_range <from> <to>
returns percentages of pixels with values between <from> and <to> in the histogram data.

This command retrieves information about the histogram of the last image shot (i.e. after focussing and metering). It reads the RAW buffer (but does not require raw saving to be enabled): The histogram data is obtained from the RAW data before discarding or further processing.

It can be very useful in accessing information about very dark scenes: The live preview screen may be completely black, while the RAW buffer (with a long enough exposure) would contain an image.

  • It depends on the shot_histo_enable command: if shot_histo_enable is not set, get_histo_range returns a value of -1, so shot_histo_enable has to be enabled first.

Because the shot histogram is calculated just after each shot and takes some time, it is disabled by default.

Sample:

rem enable shooting histogram
shot_histo_enable 1
rem shoot
shoot
sleep 100
rem let's read histogram of the shot that was just taken
h=get_histo_range 100 800
rem h contains the percentage of pixels that are between 100/1024 and 800/1024

shot_histo_enable

setting to 1 enables building of shot histogram data, 0 disables (see get_histo_range)

autostarted

returns 1 (true) if script was autostarted

get_shooting

UBASIC : returns 1 if half_press active and focus+exposure is set,  0 otherwise.  

Lua : return boolean true if half_press active and focus+exposure is set , false otherwise

Note : based on propcase variable 205 (Digic II) / 206 (Digic III) / 210 (Digic IV & V)

get_ev

returns current (ev) exposure adjustment setting  in APEX96 units (from propcase)

set_ev

sets the camera's (ev) exposure adjustment setting in APEX96 units (via propcase)

get_autostart & set_autostart

read and write conf.script_autostart (0=off, 1=on, 2=once)

get_temperature

"get_temperature 0", 0 returns optical, 1 returns CCD, and 2 returns battery temp

This can be used to both assign a variable or to print directly
Example:
a = get_temperature 0
print "Optical Temp:",a

print "Battery Temp:",get_temperature 2

select/case function

Here's a thread describing the use of the new uBASIC "select/case" feature:
http://chdk.setepontos.com/index.php/topic,1995.0.html

Syntax:

select EXPRESSION
  case EXPR. [to EXPR.] | [,EXPR.2[, ...]]; STATEMENT
  .
  .
  [case_else STATEMENT]
end_select

Sample:

for x=1 to 7
  select x
    case 1; gosub "new"
    case 7; goto "EXIT"
    case 2,4; print "x=2 | x=4"
    case 2 to 5; print "x=3 | x=5"
    case_else print"x=6"
  end_select
next x
:EXIT
  print "ready"
  end
:new
  print "sub"
  for y=1 to 2
    select y
      case 1; print "y=1"
      case_else print"y=2"
    end_select
  next y
return

changed RANDOM command

Now you can supply two values min & max
Example: "playsound random 3 6" will play the sounds 3,4,5,6 in random order (if repeated in a while loop)

playsound

Plays any of the built-in sound events, when sounds are turned on.
Example: "playsound 0"
Where 0 is the startup sound. There are sounds ranging from 0 to 7, 7 being a nasty long beep. The first few sounds can only be played if they are NOT muted by the camera, the other beeps will be played though (cam must be unmuted). This feature will lead to many more features, for example anti theft protection together with DataGhost's Disco lights.
0 = startup sound
1 = shutter sound
2 = button press sound
3 = selftimer
4 = short beep
5 = af (auto focus) confirmation
6 = error beep
7 = long beeeeeeeeeeeeeeeeeeep (nasty ! - can be stopped by half-pressing the shutter)
  • for Lua the command is play_sound (Example: "play_sound(3)")
  • sound 7 plays even on a muted camera (tested on A610)

print_screen

Usage: print_screen(123) (in Lua) or print_screen 123 (in uBasic) creates LOG_0123.TXT in the \CHDK\LOGS folder.

In uBasic:

  • logging is disabled 'print_screen 0';
  • 'print_screen nnnn' writes to LOG_nnnn.TXT in overwrite mode (where nnnn is a number between 1 and 9999)
  • 'print_screen -nnnn' writes to LOG_nnnn.TXT in append mode (where -nnnn is a number between -1 and -9999)

In Lua:

  • logging is disabled by 'print_screen(false)'
  • print_screen(nnnn) writes to LOG_nnnn.TXT in overwrite mode (where nnnn is a number between 1 and 9999)
  • print_screen( -nnnn) writes to LOG_nnnn.TXT in append mode (where -nnnn is a number between -1 and -9999)
  • 'print_screen(0)' writes to LOG_0000.TXT;
  • 'print_screen(1)'  or 'print_screen(true)' opens log file LOG_0001.TXT in overwrite mode;

get_time

(since changeset #497)

Returns elements of the camera's current time.

Usage: get_time 0 (returns seconds), 1 (minute), 2 (hour), 3 (day), 4 (month), 5 (year).

Example:

a=get_time 0

will set the value of "a" to the current number of seconds.

(command also exists in Lua, though must be fed with CHARS, see Lua Reference)

get_mode

(since changeset #497)

Returns whether record mode or playback mode is active, useful for closing scripts that are meant to be run in a certain mode (like the majority of all available scripts).

Returns 0 in record mode, 1 in playback mode, 2 when mode dial is set to videomode AND camera is in record mode (2 since changeset #499)

get_quality

Returns the current image capture quality setting in Canon grades, regardless of the cameras OS

  • For possible values see PropertyCase (basically quality can be 0=Superfine, 1=Fine, 2=Normal)

Note : uBASIC only : for Lua use :

props=require("propcase")
quality=get_prop(props.QUALITY)

get_resolution

Returns the current image capture resolution setting in Canon grades, regardless of the cameras OS

  • For possible values see PropertyCase (basically resolution might be 0=L, 1=M1, 2=M2, 3=M3, 4=S, 5=RAW, 6=Postcard, 8=LW, 9=SW, corresponding to the Canon settings)

Note : uBASIC only : for Lua use :

props=require("propcase")
resolution=get_prop(props.RESOLUTION)

set_quality

Set the image quality (in Canon grades), usually 0-2, see PropertyCase for possible values.

Note : uBASIC only : for Lua use :

props=require("propcase")
value = 1    -- 0=best, 2=worst
status=set_prop(props.QUALITY, value)

set_resolution

Set the image resolution (in Canon steps), usually 0-8, see PropertyCase for possible values.

Note: uBASIC only.

In Lua use :

props=require("propcase")
value = 1
status=set_prop(props.RESOLUTION, value)

get_canon_raw_support

(Since CHDK 1.5.1, Lua only until build 5851)

Returns true if the original Canon firmware supports raw.

get_canon_image_format

(Since CHDK 1.5.1, Lua only until build 5851)

Returns current Canon RAW/JPEG settings as a bitmask, 1 = JPEG, 2 = CR2, 3 = BOTH. On cameras without native raw support, always returns 1.

set_canon_image_format

(Since CHDK 1.5.1, Lua only until build 5851)

For cameras with native raw support, set Canon firmware image format: 1 = JPEG, 2 = CR2, 3 = BOTH. Returns true if format is supported by Canon firmware, false if not.

Notes:

  • The setting is lost when shooting mode is changed or the camera is switched to playback
  • On models where "RAW" is an image resolution in the Canon UI, setting format to JPEG sets resolution to "Large" if the previous setting is unknown.

get_platform_id

(since version 0.8.3 / changeset #593)

Returns platformid (integer) which helps to code platform-dependent scripts. ?Platform-ID list

(Only available in uBasic; in Lua scripts use get_buildinfo instead.)

set_backlight()

With this function the LCD backlight (or EVF backlight) can be turned on and off - useful for energy saving or camouflage missions. (Backlight is a bright light inside the LCD making the image visible.)

Usage:

  • set_backlight(x)       (Lua)  
  • set_backlight x      (uBASIC)

where 0 disables backlight and 1 enables the backlight.

Notes:

  • The camera re-enables the backlight after each shot. To keep backlight mostly disabled, this command must be called after each shot. But if called immediately after a shot its effect is very shortlived. The LCD live view image exposure has to settle before calling to take effect. The regular shoot state loop may help, possibly with some added delay. Test in varying lighting conditions to see if it works.
  • If a script is accidentally exited while the backlight is disabled, it can be restored by leaving ALT mode and shooting, or by powering off. The LCD can probably be somewhat read even when backlight is disabled if bright light is pointed at it from a suitable angle. Alternatively, the LCD backlight can be turned back on again in a script section labeled :restore (uBASIC) or a function called restore (Lua), which is executed when the script is interrupted.
  • An example script can be found here: [1]

set_lcd_display()

With this function the LCD display and backlight (or EVF backlight) can be turned on and off - useful for energy saving or camouflage missions. (Backlight is a bright light inside the LCD, making the image visible.)

Usage:  

  • set_lcd_display(x)    (Lua)   
  • set_lcd_display x         (uBASIC)

where 0 disables the display and 1 enables the display. Lua also accepts boolean values.

Notes:

  • This command works much like set_backlight() except that it actually turns off the whole display and not just the backlight.   The display also stays off after each shot - unlike the backlight when set_backlight() is used. 
  • It may be necessary to set Review mode to Off in the Canon menu for this to work reliably 
  • Restoring the display via set_lcd_display(1) may be somewhat slower than when restoring the backlight with set_backlight(1)
  • When set_lcd_display(1) is issued, the various Canon OSD icons and text may not be redrawn until the next press of a camera button while the camera is not in <ALT> mode.
  • If you accidentally exit a script while the display is disabled, you can get it back by leaving ALT mode (by pressing the <ALT> key once) and then repeatedly pressing the DISP key.  You can also get it back by powering off.  Alternatively, you may turn on the display in a section labeled :restore (uBasic) or a function called restore (Lua), which will be executed when the script is interrupted.
  • On some cameras, attempting to switch from rec to play mode with the display turned off may cause the camera to hang. Temporarily turning the display on for the duration of the switch should avoid this. See https://chdk.setepontos.com/index.php?topic=10551.msg136577#msg136577
  • An example script can be found here: [2]
  • Available in CHDK version 1.2.0 or newer

set_draw_title_line

(CHDK Version 1.3.0 or greater required)

This function enables / disables the drawing of the CHDK OSD title line at the bottom of the LCD screen ( <ALT> and current script name )

  • set_draw_title_line(0) - disables the display of the <ALT> symbol and the currently loaded script name
  • set_draw_title_line(1) - enables the display of the <ALT> symbol and the currently loaded script name 

From CHDK version 1.7.0 revision 6203 or later:

  • set_draw_title_line(2) - displays the <ALT> text; but hides the currently loaded script name 

Note : Lua syntax shown -  uBASIC  syntax is  set_draw_title_line 0    and    set_draw_title_line 1

get_draw_title_line

(CHDK 1.3.0 or later)

This function returns the current on/off status of the CHDK OSD title line at the bottom of the LCD screen ( <ALT> and current script name ).

get_sd_over_modes

Returns a bit field value indicating when subject distance override (i.e. set_focus() ) will work with this camera.

Bit Meaning
0x01 set_focus() works in AutoFocus mode (i.e. MF or AFL not active)
0x02 set_focus() works when AFL active (see set_aflock() command)
0x04 set_focus() works when MF active (see set_mf() command)

Note: CHDK 1.3.0 or later.

set_aflock

Lock/unlock autofocus.

Usage:

Lua: set_aflock(x)
uBASIC: set_aflock x

where 1 locks the autofocus and 0 unlocks it.

It is like Canon's built-in manual focus mode (MF), but better because focus stays locked even after camera returns from deep display sleep (via display key cycle or print button shortcut), which is very good for timelapse.

Example:

press "shoot_half"
  sleep 800
  release "shoot_half"
  set_aflock 1

Note: In older versions of CHDK (prior to 1.3.0), this function does not work on all cameras and may actually crash the camera. More information here: CHDK Forum Thread. See also the following function, set_mf().

set_mf

(CHDK 1.3.0 or later)

Lock/unlock Canon manual focus (MF) mode.

Usage:

Lua: set_mf(x)
uBASIC: set_mf x

where 1 locks the camera in MF mode and 0 unlocks it.

When used with Lua, returns "0" if MF is not supported and "1" if it is supported on the camera using the function.

Similar to set_aflock(), this function places the camera in a mode where SD override commands (e.g. set_focus) can be used and the value requested will be maintained across multiple shots.

Note: works on almost all cameras, even those that do not have a Canon MF mode. More information here:  CHDK Forum Thread.

set_aelock

(CHDK 1.3.0 or later)

Lock/unlock auto exposure adjust in still or video shooting modes.

Usage:

Lua: set_aelock(x)
uBASIC: set_aelock x

where 1 locks autoexposure adjustments and 0 unlocks them.

Note: using set_aelock(1) will always cause get_shooting() to return true. This will lock the script shoot() function. A script using set_aelock() must use press(shoot_half) and press(shoot_full) commands to shoot.  Use get_focus_ok() to check for focus rather than  get_shooting()  (which checks both focus and exposure).

set_record(state)

state 0 (or false) changes to play mode. 1 or true changes to record mode.

Note 1: This only initiates the mode change. Script should wait until get_mode() reflects the change before doing anything that requires the new mode. e.g.

set_record(true)
while not get_mode() do
  sleep(10)
end

Note 2: In uBASIC, get_mode returns 0 for record, 1 for play and 2 for movie, so if you want save the state and restore it with set_record, you cannot just use the get_mode value directly. You can adjust the value from get_mode, or use get_capture_mode instead.

(since version 0.9.8 / changeset #826)

set_capture_mode_canon(value)

value is a valid PROPCASE_SHOOTING_MODE value for the current camera. If the value is negative, it is assumed to be a sign-extended short representation of the propcase value and is converted accordingly.

returns true (Lua only) if the camera is in rec mode.

NOTE: On some cameras, a short sleep (10ms) may be required before the mode change is complete.

(since version 0.9.9 / changeset #847)

set_capture_mode(modenum)

  • modenum is a valid mode in the CHDK modemap.  The enumerated list of valid modes can be found in the source file modelist.h.  The first five entries in that list are :
1 MODE_AUTO
2 MODE_P
3 MODE_TV
4 MODE_AV
5 MODE_M
  • e.g. : set_capture_mode 1 will set the camera into AUTO mode, set_capture_mode 3 will set the camera into Tv mode
  • returns true (lua only) if modenum is a valid modemap value and the camera is in rec mode, otherwise false

NOTE: On some cameras, a short sleep (10ms) may be required before the mode change is complete.

is_capture_mode_valid(modenum)

modenum is a CHDK mode value

returns is true if modenum is a a valid mode in the cameras modemap, otherwise false

(since version 0.9.9 / changeset #847)

get_capture_mode

uBASIC only, not needed in Lua, use get_mode() instead.

returns the current camera automatic image mode, or 0 if camera is in play mode or 0 if there is no modemap entry

(since version 0.9.9 / changeset #847)

set_console_layout

set_console_layout x1 y1 x2 y2 --> set console position and size, range is x=0 to 45 and y=0 to 14

Note : coordinates are in units of characters and are  numbered from the lower left hand corner of the screen. So x1,y1 is the lower left corner and x2,y2 is the upper right corner.

set_console_autoredraw

set_console_autoredraw(-1|0|1) --> determines how text from a script's print() statement is handled when it is sent to the screen console buffer.

Parameters:

  • -1 = text from print statement is not added to console buffer
  • 0 = text from print statement is added to console buffer but the console display is not refreshed.
  • 1 = text from print statement is added to console buffer and the console display is refreshed.

Default setting = 1

Note :  the print_screen() statement determines how text from a print statement is logged to the camera's SD card. It functions independently from the set_console_autoredraw() statement.

console_redraw

console_redraw() --> manually refresh/rewrite the script console

reboot([file])

Reboot the the camera, optionally using a specified file.

If file is not given, the normal camera boot sequence is used - CHDK will be started or not based on the normal autostart rules (i.e. SD card lock switch position).

If the first two characters of the file extension are "FI" the file will be treated loaded as a firmware update file, encoded with the normal firmware update encoding. Currently, this only works on DryOS, vxworks cameras will just return without rebooting.

In all other cases, the file must be an un-encoded binary, which is compiled to load at 0x1900.

On success, reboot does not return.

note reboot does not do a "nice" shutdown.

  • If the lens is extended, it will not be retracted before reboot.
  • Canon camera settings that are normally saved on shutdown are not saved. This includes the exposure counter.
  • If called from Lua, the Lua script script will not be terminated normally, so any open files etc will not be closed.

(since changeset #944 / FI* support in changeset 957)

restore

Both Lua and uBasic provide a mechanism for allowing the programmer to specify a piece of code to be executed when the script is terminated with the interrupt key (by default, shutter full press). This allows for such things as enabling the backlight if it was turned off or releasing overrides. To use this capability in uBasic, insert a label called :restore in your code (usually right before the end statement) and add the lines of code you would like executed as the program terminates or is interrupted.

To use this capability in Lua, add a function called restore() to your Lua script with the commands you would like to see executed when the script is interrupted. In Lua, this function should be near to the top of your script, before any loops so it is defined when the script is interrupted.

Notes:

  • The restore code will be called when the script is terminated by pressing the camera's shutter button. However, in ubasic, the code will wait for any sleep commands to finish before executing so it might be better to use short sleep commands inside a counting loop rather than one long sleep command. In Lua, the function is executed immediately
  • Restore is not called when a script exits due to a runtime error such as error() in Lua, or a syntax error
  • When a script exits normally, restore can be executed using normal control flow, by reaching the :restore label in ubasic or calling restore() in Lua
  • In Lua, restore must not use functions functions that wait (yield), such as sleep, wait_click, key press / release etc. Prior to build 6253 these functions immediately end the script without any message. Later versions end with the error message "ERROR: cannot yield in restore"
  • In Lua prior to CHDK 1.7 r6253 and 1.6 r6256, restore silently ends the script after a small, unpredictable number of Lua statements, typically, not more than 10-20. Later versions allow restore to run for up to one second, and exit with the error "restore timeout" if the time is exceeded (forum discussion)

set_exit_key

(CHDK Version 1.3.0 or greater required)

Allows a script to set the key used to terminate its execution. The default key for this action is the shutter full press key. However, for scripts that need to capture a shutter full press, an alternate key can be selected. Takes a string argument using the same values used by is_pressed / press / click / release.

Note :  you can use   set_exit_key("no_key")   so that there is no key sequence that forces the termination of a running script

set_yield

This command controls how much of the camera's CPU time is allocated to running scripts.

The CHDK script engine yields (sleep for 10ms, or possibly more on some cameras) when either a specified number of script lines have been executed or a specified time period has passed. These limits can be adjusted to allow complex scripts to run more quickly. However, this will cause less CPU to be available for other camera tasks, which may have side effects. Note that increasing these values will not make operations that happen outside of script code (e.g. shooting, motion detection) any faster. Specified values are treated as unsigned, so -1 can be used to effectively disable either condition by making the number of lines or time period very large.

Commands that wait (such as sleep, wait_click, md_detect_motion etc) or send key presses yield immediately.  

ubasic usage:

set_yield <MAX_LINES> <MAX_MS>

MAX_LINES is the maximum number of lines to execute in a single iteration of the script task. Default is 1, meaning that ubasic scripts take at least 10ms to execute each line.

MAX_MS is the maximum number of milliseconds a single iteration of the script task is allowed to run for before yielding. Default is 10.

The value has a resolution of 10ms, and is checked after each line. Since the start of a script iteration does not necessarily begin in sync with the system clock, the actual time may be less than 10ms.

Passing zero for either value resets it to default.

lua usage:

old_max_count,old_max_ms=set_yield(<MAX_COUNT>,<MAX_MS>)

MAX_COUNT is the maximum number of lua VM instructions to execute in a single iteration of the script task, divided by 100. Default is 25, meaning a maximum of 2500 VM instructions will be executed.

MAX_MS is as described for ubasic, except it is checked every 100 VM instructions rather than every line.

The return values are the previous values of MAX_COUNT and MAX_MS. Libraries that need to adjust these values should save and restore the values. Passing nil for either value resets it to the default.

In Lua, calls to lua code from within C (for example, using pcall()) cannot yield. However the VM calls and time will still be counted, so a yield will occur within 100 instructions after the C call if the limits are exceeded.

get_curve_file

Lua commands to report on tone curve file currently loaded. Returns path as a string.

(only for 10bit-RAW cameras)

set_curve_file

Lua commands to load a tone curve file, set_curve_file(<path>).

(only for 10bit-RAW cameras)

get_curve_state

Lua commands to determine if tone curve file is active or disabled. 0, 1, 2, 3, 4 = None, Custom, +1EV, +2EV, AutoDR

(only for 10bit-RAW cameras)

set_curve_state

Lua commands to enable/disable tone curve file usage. 0, 1, 2, 3, 4 = None, Custom, +1EV, +2EV, AutoDR

(only for 10bit-RAW cameras)

get_focus_mode

returns focus mode, 0=auto, 1=MF, 3=inf., 4=macro, 5=supermacro

get_focus_state

returns focus status, > 0 focus successful, =0 not successful, < 0 MF

get_focus_ok

returns 0=focus not ok, 1=ok if get_focus_state<>0 and get_shooting=1

get_focal_length

get current lens focal length * 1000, e.g. 5800 = focal length 5.8

get_min_stack_dist

Calculates the minimum object distance in mm. This is required for focus stacking.

(Only uBasic, in Lua use get_dofinfo() as table for all dof related values)

set_file_attributes

Set the file attributes, 0x1 = read-only, 0x2 = hidden, 0x20 = archiv

set_file_attributes(<file>, <attributes>), e.g. set_file_attributes(file_name, bitor(bitor(0x1,0x2),0x20)) sets all attributes.

(only for Lua)

get_partitionInfo

Returns a table with informations about the partition.

part=get_partitionInfo()

  • part.count - number of partitions
  • part.active - active partition starting with 1
  • part.type - type of the active partition
  • part.size - size of the active partition

(only for Lua)

swap_partitions

Change the partition. swap_partitions(n) -> n = num of partition

(only for Lua)

get_buildinfo

Returns a table of informations about camera & CHDK.

bi=get_buildinfo()

  • bi.platform - CHDK platform name, as string like "ixus80_sd1100"
  • bi.platsub - Canon firmware version CHDK was compiled for, as string like "100c"
  • bi.version - string "CHDK"
  • bi.build_number - as string like "1.5.1"
  • bi.build_revision - SVN revision number, as string like "1234"
  • bi.build_date - Date CHDK was compiled, as string
  • bi.build_time - Time CHDK was compiled, as string
  • bi.os - String "vxworks" or "dryos"
  • bi.platformid - USB product ID of camera, as number
  • bi.digic - Digic version as number times 10, like digic 2 = 20, digic 4 = 40, digic 4+ = 41. (CHDK 1.5 and later)

(only for Lua)

get_dofinfo

Returns a table with dof and focus related information. Note that depending on camera settings, some values are only updated on half press.

dof=get_dofinfo()

  • dof.hyp_valid [boolean] - Is hyperfocal distance valid?
  • dof.eff_focal_length [x 1000 mm] - 35mm equivalent focal length
  • dof.coc [x 1000 mm] - circle of confusion
  • dof.aperture [x 1000] - aperture
  • dof.near [mm] - near limit
  • dof.min_stack_dist [mm] - smallest meaningful stack distance
  • dof.dof [mm] - DOF
  • dof.focal_length [x 1000 mm] - focal length
  • dof.hyp_dist [mm] - hyperfocal distance
  • dof.far [mm] - far limit
  • dof.focus [mm] - focus distance
  • dof.focus_valid [boolean] - Is focus valid?

(only for Lua)


textbox

Provides a text input box. Usage:

textbox( "title" , "message" , "default_string" , max_len)

where:

  • "title" - string displayed as the title of the box; default is "Text box"
  • "message" - short message for the user; default is "Enter text"
  • "default_string" - appears as the string before user starts editing; default is an emtpy string
  • max_len - the maximum length of the input; default is 30.

Function returns a string typed or edited by user, when the user submits.

User can type by pressing left/up/right/down buttons in a similar way to mobile phone writing.

  • SHOOT_HALF switches between lower case/upper case/digits/special
  • ZOOM_IN or DISPLAY- spacebar
  • ZOOM_OUT or ERASE - delete
  • JOGDIAL moves the cursor
  • MENU switches to "navigate cursor" mode, where you can only move the cursor or add a space by DISPLAY
  • MENU once again switches to OK/CANCEL - user can submit or cancel the editing.

(Lua only)

get_raw_support

(CHDK 1.4 and later)

Return true (1 in uBASIC) if in rec mode and raw data is available in the current capture mode. If raw data is not available, CHDK raw will not be saved, and Lua/Raw Hook Operations cannot be used.

Note: Currently returns true in dedicated video modes, even if still shooting is not possible.

get_digic

returns DIGIC processor type multipied by ten (to capture first decimal place)  digic 2 = 20, digic IV = 40, digic IV+ = 41 etc uBASIC only

set_clock

set_clock(year, month, day, hour, minute, second)
Set the camera date / time (Lua only). Values are integers and all are required. Values are all exactly as they would appear in the camera clock: 4 digit year, month and day numbers start at 1. It is not aware of DST, the displayed time after setting is the values set, regardless of the DST setting.
See https://chdk.setepontos.com/index.php?topic=14091.0

set_focus_interlock_bypass

disables CHDK internal safety checks related to whether scripted manual focussing is allowed

Lua only

APEX96 Conversion Functions

(CHDK Version 1.3.0 or greater required)

iso_to_sv96

converts an ISO sensitivity value into sv96 units

sv96_to_iso

converts an sv96 value to an ISO sensitivity value

iso_real_to_market

converts a "real" ISO sensitivity value to a "market" ISO sensitivity value

iso_market_to_real

converts a "market" ISO sensitivity value to a "real" ISO sensitivity value

sv96_real_to_market

converts a "real" sv96 value to a "market" sv96 value

sv96_market_to_real

converts an "market" sv96 value to a "real" sv96 value

aperture_to_av96

converts an aperature setting (f-stop) to av96 units - f-stop is scaled by 1000

av96_to_aperture

converts an av96 value to aperature setting (f-stop) *1000 units

usec_to_tv96

converts shutter speed in uSec to a tv96 value

tv96_to_usec

converts a tv96 value to shutter speed in units of uSec

seconds_to_tv96

converts a fractional value to tv96 units - takes a numerator and denominator as parameters

APEX96 Example Lua Script

--[[
@title APEX96
@param i ISO value
@default i 200 
@param l Log
@default l 0
@range l 0 1
--]]
set_console_layout(0, 0, 44, 16)
print_screen(l)

sv96 = iso_to_sv96(i)
print("ISO "..i.." = SV96 "..sv96)
iso=sv96_to_iso(sv96)
print("SV96 "..sv96.." = ISO" , iso )

isom=iso_real_to_market(i)
isor=iso_market_to_real(i)
print("ISO "..i.." real  = ISO"..isom.." market")
print("ISO "..i.." market = ISO"..isor.." real")

sv96m=sv96_real_to_market(sv96)
sv96r=sv96_market_to_real(sv96)
print("SV96 "..sv96.." real = "..sv96m.." market")
print("SV96 "..sv96.." market = "..sv96r.." real")

fstop=5600
av96 = aperture_to_av96(fstop)
print("f"..(fstop/1000).."." ..((fstop%1000)/100).." = AV96 "..av96)
fstop = av96_to_aperture(av96)
print("AV96 "..av96.." = f"..(fstop/1000).."."..(fstop%1000)/100)

shutter=10000
tv96=usec_to_tv96(shutter)
print((shutter/1000000).."sec ".. (shutter/1000).." msec = TV96 "..tv96)
shutter=tv96_to_usec(tv96)
print("TV96 "..tv96.." = "..(shutter/1000000).."sec ".. (shutter/1000).." msec")

n=1
d=60
tv96=seconds_to_tv96(n,d)
print(n.."/"..d.." = ", tv96, "in apex96 units" )
shutter=tv96_to_usec(tv96)
print("TV96 "..tv96.." = "..(shutter/1000000).."sec ".. (shutter/1000).." msec")

Live View Exposure Functions

( see https://chdk.setepontos.com/index.php?topic=13508.0 )

(CHDK 1.5 and later)

get_imager_active

returns boolean of camera's image sensor active status (true=running, false=not running).

The sensor usually goes inactive when the Canon firmware turns off the display for power saving. In this state, features like motion detection and live histogram will not function correctly. Additional, some firmware functions may fail or crash. This can include focus related functions like set_aflock, and switching to playback mode over PTP.

get_current_tv96

returns current TV96 value being used by camera in live view

get_current_av96

returns current AV96 value being used by camera in live view