SDM uBasic Commands



Based on Adam Dunkel's uBasic, SDM supports a subset of the CHDK scripting commands and introduces some of its own.
Most users will use publically-available scripts or, if writing their own, will use relatively few of the available commands.

For reference, the SDM-supported commands are listed below.

Dave Mitchell has written a debugger for SDM uBasic scripts, you can download it here.

If writing your own scripts, use a simple text editor (such as Notepad or Wordpad) and save in plain ANSI format (not unicode).
Make sure that the first line of your script is not blank but there is a blank line at the end of the script.

Script header and remarks

@default
@param
@title
rem

Logic commands

<:>
<=
>=
<
><
and
not
or

Control and branching

call
do
else
end
endif
for
gosub
goto
if
let
next
return
step
then
to
until
wend
while

Mini-console messages

cls
print
print_screen

Camera Operation

click
wait_click
press
release
shoot
shut_down
sleep
is_key
wheel_left
wheel_right
get_autostart
get_day_seconds
get_flash_mode
get_focus
get_free_disk_space
get_mode
get_prop
get_quality
get_resolution
get_shooting
get_tick_count
get_usb_power
get_user_tv_id
get_video_button
get_zoom
get_zoom_steps

playsound

set_aflock
set_autostart
set_av
set_backlight
set_focus
set_iso
set_nd_filter
set_prop
set_quality
set_resolution
set_raw
set_tv
set_tv96_direct
set_zoom
set_zoom_speed
set_zoom_rel

md_detect_motion
md_get_cell_diff

exit_alt (exit <ALT> mode)
disable_main_flash
enable_main_flash

SDM Commands

SDM does not require the uBasic 'print' command.
Simply enclose the text between quotation marks.
If preceeded by a space, the background will be blue.
If preceeded by a '#' symbol, the background will be green.
If preceded by an exclamation (!) mark, the background will be red.
The colour-formatting symbols are not displayed.

Example 1:

" This is text"
"# Press shutter"
"! to exit"
while 1
do
wend

af_led_off/af_led_on

The autofocus LED is bright and visible from some distance.
This makes it useful for kite aerial photography (KAP) scripts to indicate completion of operations.

aperture

A user-friendly way of entering override aperture-values on cameras that have a physical aperture:-

aperture 3.5

@title Aperture
@param a numerator
@default a 2
@param b denominator
@default b 8
aperture a . b
shoot
end

blink_af_led_for

This blinks the autofocus LED for the set time.

e.g blink_af_led_for 5 blinks autofocus LED for five seconds.

auto_focus_bracketing

Used in continuous-shooting mode to capture images from focused distance to infinity.
The camera must be in a mode that allows focus-override and in continuous-shooting mode.
(if using custom timer mode, the sequence will end after the set number of exposures.
Focus may or may not reach infinity).
For the example below, set camera to continuous shooting.
At the wide-angle setting, infinity will be reached in only two or three steps from 1000mm.
The example zooms the lens to get more steps (on non 'S' series cameras).
The focused distance is displayed at the top of the screen for each step.
'DBA' is displayed to indicate 'distance-bracketing automatic' and 'CONT' for continuous-shooting mode.
Press your USB switch to start, the camera will beep when infinity-focus is reached.


Example 2:

set_zoom_to_step 7
set_focus_to 1000
auto_focus_bracketing
" Autofocus bracketing"
" Press switch"
wait_for_switch_press
start_continuous_sequence
wait_until_done
end_continuous_sequence

beep

Makes a brief 'beep' sound.

Example 3:

sleep_for 1000
beep
sleep_for 1000
beep
end

blue_led_off/blue_led_on

Turn the blue LED on/off.

Example 4:

sleep_for 1000
beep
blue_led_on
sleep_for 2000
beep
blue_led_off
end

bracketing_done

Returns '1' when all bracketing shots have been taken.
The following is equivalent to 'wait_until_done' command :

set_focus_to 500
do
until is_key "remote"
shoot
do
until bracketing_done = 1

break_usb_connection

Disables USB upload and returns to record mode.
This will only work with programmes on the PC that have already exited in a controlled manner.

Example:

make_usb_connection
sleep_for_seconds 35
break_usb_connection

data_received

When using the 'send_data' command to send three bytes of data to an external device (such as a Picaxe microcontroller), a returned value of '1' indicates that the data was received without error and the device replied within 100 msec.

e.g data_received a ('a' = 1 if data received).

digiscope_bracketing

Used to capture a number of images focused each side of the scope virtual image.
The camera must be in a mode that allows focus-override and continuous or custom-timer shooting.
For the example below, set camera to continuous shooting.
(To see the effect of focus-change with this example you really need a digiscope setup)
Focus value is displayed at the top of the screen and on completion the camera refocuses at the starting distance (reference focus).
The Canon firmware may not focus at a precise numerical distance, just as close as it can get.

Example 5:

set_zoom_to_step 3
set_focus_to 600
digiscope_bracketing
number_of_images_to_capture_is 5
" Digiscope bracketing"
" Press switch"
wait_for_switch_press
start_continuous_sequence
wait_until_done
end_continuous_sequence

enable_usb_download/disable_usb_download

When USB download is disabled, the camera will not try to connect to the PC when a voltage is present on the USB connector V+ pin.
This is the usual mode when using a remote switch.
By enabling USB download and switching to Playback mode, a selected programme on the PC will startup when the USB connector plugged-in.

each_photo_alternating/each_photo_darker/each_photo_lighter

Used before starting a Tv (shutter-speed) bracketing sequence with custom-timer shooting mode.
(continuous-shooting mode bracketing is alternating only).
For the example below, set number of exposures in custom-timer 'Shots' and delay to zero.

Example 6:

hdr_bracket_1/3_ev_steps 2
each_photo_lighter
" Press switch"
wait_for_switch_press
" Each image lighter"
start_custom_timer_sequence
wait_until_done

end_time

This is a synonym for 'finish_time' and is used in conjunction with 'sleep_until' or 'start_time'.
'end_time/finish_time' MUST come before 'sleep_until/start_time' in your script.
It indicates the time in hours and minutes that an operation should end.
At present, only 'time_lapse' command supports this feature.
The following script will blank the display until start time (default is 12:30) .
It will then take a photo every minute until end time.
End time is four minutes after start time

. The time-lapse setting for this feature must be 'endless'.

@title Real time
@param a hours
@default a 12
@param b minutes
@default b 30
" Going to sleep"
sleep_for_seconds 3
rem finish after four minutes
finish_time a, b + 4
start_time a, b
rem ten second delay then photo every one minute
time_lapse 0, 10 ,1 , 0, 3, 1, 0, 3, 3, 0, 2, 3, 0, 50, 500, 0, 0, 0, 0, 0
end

equal_step_focus_bracketing

Used to capture a number of images using a fixed focus-step from a start focus.
The camera must be in a mode that allows focus-override and continuous or custom-timer shooting.
Useful for extreme close-ups where depth-of-field increasing very slowly with focus distance.
For the example below, set camera to continuous shooting.

Example 7:

set_focus_to 500
equal_step_focus_bracketing
number_of_images_to_capture_is 3
" Equal-step bracketing"
" Press switch"
wait_for_switch_press
start_continuous_sequence
wait_until_done
end_continuous_sequence

finish_time

Synonym for 'end_time', you can use either.

get_focused_distance

This is a synonym for 'get_focus', you can use either.

get_focus_ref

Returns the focus position (on the virtual image) used by digiscoping function.

get_script_speed

Returns the current speed (1 to 5) of the script.
See the 'set_script_speed' statement below.

get_shooting_mode

Synonym for CHDK 'get_shooting'.

get_sync

Returns synch status and delay values. See 'set_synch' below.

hdr_bracket_1/3_ev_steps

Used in Tv bracketing to specify the exposure-step in units of 1/3EV.
3 EV is equivalent to one stop.

is_this_right_camera

is_this_right_camera a

Returns '1' in 'a' if true.

lcd_on_off

Toggles on/off state of the LCD by 'pressing' the DISPLAY button.
Not supported by all cameras.
(also see 'turn_backlight_off/turn_backlight_on' below)

Example 8:

" Press switch"
" LCD will blank"
" for 5 seconds."
wait_for_switch_press
lcd_on_off
sleep_for 5000
lcd_on_off
end

line_1,line_2,line_3

Print script output directly onto one of the script-console lines without scrolling.
See the readYUV script example below.

lock_autofocus/unlock_autofocus

After half-pressing shutter and giving camera sufficient time to focus, the auto-focus may be locked.
'AFL' will be displayed on the screen.
You may unlock autofocus using the script command or half-press shutter button and press right button until 'AFL'not displayed.

Example 9:

sleep_for 1000
press "shoot_half"
sleep_for 1000
lock_autofocus
"! locked"
"! 'AFL' top left"

make_usb_connection

Switches to playback mode and enables USB upload.
The following example connects to a remote-capture programme such as PSRemote and capture five images at ten seconds interval :-

make_usb_connection
time_lapse 0,15,0,10,5,0,0,3,3,0,2,3,0,50,500,0,0,0,0,0

movie_mode

The camera switches to movie mode.
Clicking "shoot_full" will start and stop the movie recording.
For cameras with a 'movie' button, 'movie_mode' does not do anything.
Normally, it is simpler to use the command 'shoot_movie_for' described below.

nd_filter_off/nd_filter_in/nd_filter_out

These perform same functions as 'set_nd_filter' but are easier to remember and make your script more readable.

number_of_images_to_capture_is

Used to specify the number of images in a bracketing mode.
For Tv bracketing and digiscope bracketing this is usually an odd number.

Example:

number_of_images_to_capture_is 5
start_continuous_sequence

playback_mode

Camera switches to playback mode.
Use 'record_mode' to return.

readYUV

Reads the luminance and UV chroma values from a 24 x 16 pixel area at the centre of the screen.
No parameters are required, the values are returned in 'a', 'b' and 'c' (so be careful how you use them in the rest of your script).
To use as a spotmeter, zoom to telephoto setting.
The values are read from the live-image buffer and the correlation with the real scene values is not known.
The following script displays the YUV and calculated RGB values in non-scrolling format on the console:-

@title Spot meter
:test_md_loop

readYUV

r = (a*4096 + c*5743 + 2048)/4096
if r < 0 then r = 0
if r > 255 then r = 255

g = (a*4096 - b*1411 - c*2925 + 2048)/4096
if g < 0 then g = 0
if g > 255 then g = 255

u = (a*4096 + b*7258 + 2048)/4096
if u < 0 then u = 0
if u > 255 then u = 255

line_1 "# YUV ", a," ",b," ", c
line_2 "! RGB ", r," ",g," ", u

goto "test_md_loop"

record_mode

Returns to record mode from playback mode.

save_stack

In bracketing modes, this command enables the saving of log files with the focus or Tv values recorded.
The command should come before any command that starts the bracketing sequence.
Try adding it to the top of Example 2.
The log files are in folder 'A/CHDK/STACKS'.

send_data

This command sends three bytes of data to an external device by flashing the Print LED.
The protocol is very simple and is described in the section Serial Communication with an external device
The following script sets parameter 'a' to 128 as a parameter identifier, you can choose any value you wish from -128 to +255.
It zooms the lens in and out and sends the zoom position to the external device (third byte not used) :

@title Tx data
@param a command
@param b low byte
@param c high byte
@default a 128
@default b 0
@default c 67
sleep_for_seconds 1

:loop
set_zoom_to_step b
" Sending data"
sleep_for_seconds 1
get_zoom d
send_data a, d, c
sleep_for_seconds 4
b = b + 1
if b <> 7 then goto "loop"

:loop2
set_zoom_to_step b
" Sending data"
sleep_for_seconds 1
get_zoom d
send_data a, d, c
sleep_for_seconds 4
b = b - 1
if b >= 0 then goto "loop2"
end

set_digi_focus_ref_to

Sets the reference-focus position (on the virtual image) used by digiscoping function.

set_focus_step_to

Sets size of focus-step to be used for equal-step bracketing.

set_focus_to

Synonym for CHDK 'set_focus'.

set_script_speed

Instead of executing one uBasic statement every 'tick' (1/100 sec), you can set script-speed up to five statements per tick.
At the start of the script, the speed is set to one statement per tick.
This will speed-up many operations, but not all.
The statement-execution loop will be exited for statements that return control to the camera (such as'press', 'shoot' and 'motion detect'

set_sync a b c d

'a' = 'Enable Synch' (1 = enable, 0 = disable) b = 'Enable Synch delay' (1 = enable, 0 = disable) c (delay in 0.1 msec units) d (delay in 0.1 sec units)

set_zoom_to_step/set_zoom_to

Synonyms for CHDK 'set_zoom'.
Sets zoom to defined position, starting from step '0'.

shoot_movie_for

Switches to movie mode,records a movie for the defined time and then returns to record mode.

shoot_when_camera_steady

This is an aid for detecting camera-shake when shooting in dim-light conditions or at the telephoto setting.
The photo is only taken when there has been less than a user-defined amount of movement.
The location of the monitored points is shown with an overlay of small rectangles and these aid sighting a reference object and keeping it steady.
shoot_when_camera_steady a, b
'a' is the sensitivity (1 to 255) and 'b' is the returned value.
The smaller the value of 'a', the more sensitive is the shake detection.
The command times-out after ten seconds if camera not steady enough.
A return value of '1' indicates success, no shake detected.

@title Camera shake
@param a sensitivity
@default a 128
sync_off
:md_loop
b=0
print "About to shoot"
shoot_when_camera_steady a, b
print N," ", b
N = N + 1
sleep_for_seconds 5
goto "md_loop"
end

shoot_when_no_movement_for

This is intended for longer time-scales than the 'shoot_when_camera_steady' command and takes a photo when there has been no subject movement for a defined amount of time.
Possible applications include kite aerial photography and microscopy.
shoot_when_no_movement_for a, b, c, d
a = required duration of no movement in seconds, a minimum of '1'.
b = return value, '1' is no movement detected.
c = movement sensitivity (optional), range 1 to 255. Set to 128 if not specified.
d = time-out (optional) in seconds, set to 10 if not specified.

@title No-motion
@param a time still
@default a 5
@param c sensitivity
@default c 128
@param d timeout
@default d 10
sync_off
:md_loop
b=0
print "About to shoot"
shoot_when_no_movement_for a, b, c, d
print N," ", b
N = N + 1
sleep_for_seconds 5
goto "md_loop"
end

shutter_speed

A user-friendly way to enter override shutter-speeds over the range 64 to 1/32,000 sec.
(it is not suggested that high shutter-speeds beyond the camera's native maximum are 'real').

shutter_speed 1/125

@title Shutter speed
@param a numerator
@default a 1
@param b denominator
@default b 125
shutter_speed a / b
shoot
end

sleep_for

Synonym for CHDK 'sleep'
Script pauses for defined number of milliseconds.

Example:

sleep_for 1000

sleep_for_minutes

Script pauses for defined number of minutes.

sleep_for_msecs

Pseudonym for 'sleep' statement.

sleep_for_seconds

Script pauses for defined number of seconds.

sleep_until

The camera blanks the screen and waits until the set hours and minutes before continuing.
With the following script, the camera sleeps until 12:30, shoots a fifteen second movie and then beeps to indicate completion.

@title Wake-up
@param a hours
@default a 12
@param b minutes
@default b 30
" Waiting"
sleep_for_seconds 3
sleep_until a, b
sleep_for_seconds 3
shoot_movie_for 15
beep
end

start_continuous_sequence/end_continuous_sequence

This command is used to start a Tv or focus-bracketing sequence when the camera is in continuous shooting mode.
Unlike custom-timer sequences, you are responsible for ending the sequence.
In effect, you are taking your finger off the button.

Example :

start_continuous_sequence
wait_until_done
end_continuous_sequence

start_custom_timer_sequence

This command is used to start a Tv or focus-bracketing sequence when the camera is in custom-timer shooting mode.
There is no need to explicitly end the sequence although you need to use 'wait_until_done' before executing next command.
Set number of exposures in custom-timer 'Shots' and set delay to zero.
'TvB' will be displayed to indicate Tv bracketing and 'TIME' for custom-timer mode.

Example 10:

hdr_bracket_1/3_ev_steps 3
each_photo_darker
" Press switch"
wait_for_switch_press
" Each image darker"
start_custom_timer_sequence
wait_until_done

start_time

Synonym for 'sleep_until', you can use either.

sync_on/sync_off

These perform same functions as 'set_sync' but are easier to remember and make your script more readable.

take_photo_now

Synonym for CHDK 'shoot'.

time_lapse

A very versatile command for time-lapse with bracketing,focus-lock, screen blanking, auto-shutdown and USB stop/start.
This is the default script provided with the download.
See separate section for full details.

turn_backlight_off/turn_backlight_on

This command works on all cameras to turn the backlight on/off.
After image capture, the backlight will briefly turn-on again.
For example below, press shutter button to start script.

Example 11:

" LCD will blank"
" for 5 seconds"
sleep_for 2000
turn_backlight_off
sleep_for 1000
shoot
sleep_for 3000
shoot
sleep_for 2000
turn_backlight_on
end

unit_pulse

The 'send_data' command blinks the Print LED for unit-pulse time or multiples thereof.
In order to set the time as accurately as possible, use this command to generate a single pulse that the connected, external device can then measure.
In the Serial Comms menu, you set the time in increments of ten msecs and can apply a tuning factor to vary the pulse-width.
The variation in pulse-width will be greater for short pulses and you should choose a value that gives reliable results.

upload_images_for

Switches to playback mode, enables USB upload for defined time and then returns to record mode.
This command may be used with WIA-Loader to upload images at regular intervals.


wait_for_switch_press

Script pauses until voltage signal present on USB V+ pin.
See the various examples above.
Signal can be from a switch, IR or wireless receiver, microcontroller, etc.

wait_until_done

Indicates that required number of images in a custom-timer or continuous-shooting mode sequence have been taken.
See the various examples above.