Lua/Lua Reference

Lua Scripting commands

This page will become a reference page to all new or changed script commands for the Lua scripting language.

Most of the uBASIC commands are also available in Lua and can be used the same way, so UBASIC/TutorialScratchpad can be used as reference also for Lua.

New Lua commands

Commands in this section are only available in the Lua scripting language!

I/O functions

In Lua there are also I/O library functions for file manipulation available, see *Lua Standard libraries

OS system functions

In Lua there are also OS library functions for operating system calls available, see *Lua Standard libraries

String manipulation functions

The standard Lua string library is available. *Lua Standard libraries

peek

(since changeset #468)

value = peek(address[,size])

Return the value in memory at the given address, or nil if the address alignment or size is invalid.

size is one of 1, 2 or 4, and specifies to whether to read a byte, half word, or word. Default is 4. (since changeset #864)

WARNING: Reading invalid addresses will crash your camera!

poke

(since changeset #520)

status = poke(address,value[,size])

Set the memory at address to value. Returns true, or nil if the address allignment or size is invalid.

size is one of 1, 2 or 4, and specifies to whether to write a byte, half word, or word. Default is 4. (since changeset #864)

WARNING: Setting random memory locations is risky. If you don't know what you are doing, don't use it. If you do know what you are doing, you know you could crash your camera, or if you try hard enough something even worse.

bitwise operations

(since changeset #468)

bitand       bitor       bitxor      bitshl
bitshri      bishru      bitnot

→ perform the like named bitwise operations.

These work as functions, not as operators, e.g.:

c = bitand(a, b)

shri

→ performs an arithmetic (sign extending) right shift.

shru

→ performs a logical (non-sign extending) right shift.

get_buildinfo

(since changeset #520)

get information about the running platform and chdk version. Returns a table with the members platform, platsub, version, build_number, build_date and build_time. As of changeset #606 os ("dryos" or "vxworks") and platformid (a number) are also returned.

bi=get_buildinfo()
print("platform: ",bi.platform," ",bi.platsub)
print("version: ",bi.version," ",bi.build_number," built on ",bi.build_date," ",bi.build_time)

This can be used to make scripts work around camera differences without requiring users to set anything.

Note: version in is currently just the string "CHDK". build_number contains the entire build number as a string. This isn't very convenient, and may change in the future.

get_prop

(available since build 0.6.5 / changeset #541)

With this command a Lua script can use PropertyCases without knowing the cameras propset and the propcase number.

get_prop can be used with propcase.lua library which is included in the 'complete' download packages. This module loads a table which maps camera property case names to their respective numbers. It also takes care to load the correct property case set for the camera.

There are 2 different property sets known for CHDK cameras: propset 1 (used on most Digic II cameras) and propset 2 (used on most Digic III cameras). During the CHDK build process or each propset a Lua library with a table of the property case names and numbers is generated. These generic libraries are saved in the \CHDK\LUALIB\GEN\ folder. The propcase.lua library automatically selects the needed file with the correct property set for the camera (propset1.lua and propset2.lua at the moment).

Usage:

props=require("propcase")
tv=get_prop(props.TV)

(somebody should place a short sample here...)

RAW development

(available since CHDK version 0.8.4 / changeset #594)

There are the following four new functions for merging RAW images directly in the camera:

• set_raw_develop("filename")

Develop RAW on next shot. If filename is nil (or omitted), any pending raw develop is canceled.

• raw_merge_start(operation)

Start merging process, operation is a number: 0=sum 1=average. Other=error.

• raw_merge_add("filename")

merge a file

• raw_merge_end()

complete the merge operation.

Notes:

• Error checking is minimal. If you pass an invalid filename, things may silently fail. If you call raw_merge_add or raw_merge_end without calling start first, or call raw_merge_start multiple times without an intervening end, the results are undefined.

• The RAW merge stuff runs in the same task as the script (the keyhook task), while raw operations from the menu run from the spytask. This appears to work, but it's a bit suspect.

Sample script

This script demonstrates the usage of the RAW development commands, it performs the requested RAW operation on n files.

• You can specify what exposure number to start at, or use 0 to specify the most recent.
• The script works by counting down through the files until it find enough RAW files, so they don't need to be sequential.
• It can optionally develop the resulting file.
• The merged file will be named with the number of the last merged file, which will be the lowest number found.

--[[
@title raw merge and develop
@param a op: 0=sum 1=avg
@default a 1
@param b start file: 0=latest
@default b 0
@param c files to merge
@default c 4
@param d develop ? 0=n 1=y
@default d 0

based on work by fudgey and dsvilko
http://chdk.setepontos.com/index.php/topic,2646.0.html
--]]

rawpath="A/DCIM/100CANON/"
rawprefix="CRW_"
rawext=".CRW"

-- no range check, so we can check error cond
operation=a
-- limit 1-9999
start=b
-- sanity check ?
numfiles=c
develop=d~=0
--RAW_OPERATION_SUM=0
--RAW_OPERATION_AVERAGE=1

function fastshoot()
  press("shoot_half")
  repeat 
    sleep(1)
  until get_shooting() == true
  log("shooting...")
  press("shoot_full")
  release("shoot_full")
  release("shoot_half")
  repeat
    sleep(1)
  until get_shooting() ~= true
end

function leadingzeros(num)
	local zs=""
	if num < 10 then
		zs="000"
	elseif num < 100 then
		zs="00"
	elseif num < 1000 then
	    zs="0"
	end
	return zs .. num
end

logfile=io.open("A/rawops.log","wb")
io.output(logfile)

function log(...)
	io.write(...)
	io.write("\n")
end

if start == 0 then
	start = get_exp_count()%10000
end

raw_merge_start(operation)

log("raw_merge_start(",tostring(operation),")")

count=0
i = start
log("merging ",numfiles," files start at ",start)
while count < numfiles and i > 0 do
	-- so we can get the name to develop
	rawbasename=rawpath..rawprefix..leadingzeros(i)
	rawname=rawbasename..rawext
	log("trying ",rawname)
	if os.stat(rawname) then
		log("raw_merge_add_file(",rawname,")")
		raw_merge_add_file(rawname)
		count = count + 1
	end
	i = i - 1
end
log("merged ",count," files")

log("raw_merge_end()")
raw_merge_end()

if develop then
	log("developing...")
	-- only develop in rec mode
	if get_mode() then
		-- assumes input files were .cr*
		developname=rawbasename..".WAV"
		log("set_raw_develop(",developname,")")
		set_raw_develop(developname)
		fastshoot()
	else
		log("not in record mode")
	end
end
log("done!")
logfile:close()

---

Flash parameters

(available since CHDK version 0.8.7 / changeset #607)

Note: please update List of Params as you see fit.

Canon cameras store some parameters in onboard flash memory. These functions allow you to query them.

• num=get_flash_params_count()

num is the number of parameters. Parameters are numbered starting form zero.

• str,num=get_parameter_data(id)

str is the parameter value as a lua string, which may contain embedded NULLs or other non-printable characters. If the size of the flash parameter is 4 bytes or less, a second value is returned, containing the parameter value as a number. If the parameter id is invalid, or the parameter size is 0, then nil is returned for both values.

Notes

• parameter IDs and meanings vary between cameras. Using them will make your script non-portable, unless your script has code to check what camera it is running on (using get_buildinfo) and select the correct parameter IDs for each camera.
• You can find useful parameter IDs in the CHDK source.
• Setting parameter values is not supported yet.

Sample script

This script dumps the parameters from the internal flash memory and write them to a logfile paramdmp.log on the root folder of the memory card.

Notes:

• The parameter IDs may vary between cameras, so scripts using them will not be portable !
• This script is included in the 'complete' download packages from the Autobuild server

--[[
dump parameters from internal flash memory
NOTE:
parameter ids may vary between cameras, so scripts
using them will not be portable
--]]
logfile=io.open("A/paramdmp.log","wb")
for i=0,get_flash_params_count()-1 do
        s,n = get_parameter_data(i)
        logfile:write(i,": ")
        if s then
                -- string as hex
                for j=1,s:len() do
                        logfile:write(string.format("0x%02x ",s:byte(j)))
                end
                -- string quoted
                logfile:write(string.format("[%q]",s))
                -- as number, if available
                if n then
                        logfile:write(string.format(" 0x%x %d",n,n))
                end
        else
                logfile:write("nil")
        end
        logfile:write("\n")
end
logfile:close()

---

set_curve_state

(available since CHDK version 0.9.6 / changeset #709)

Set the status of curve function for postprocessing in scripts:

set_curve_state(n) n: 0, 1, 2, 3, 4 = None, Custom, +1EV, +2EV, AutoDR

---

Changed Lua commands

This section lists commands which are available both in Lua and in uBasic. It describes differences or improvements in the syntax / behaviour of these commands

print_screen

Logging can be disabled by 'print_screen(false)'

get_time

(available in Juciphox build since changeset #487)

get_time delivers a selectable part of the current date or time

→ Additional, optional parameters: Y[ear], M[onth], D[ay], h[our], m[inute] or s[econd]

Usage: get_time("unit") , where unit can be Y[ear], M[onth], D[ay], h[our], m[inute] or s[econd] ([ ]=optional/example)

Note: you might want to use os.date instead.

get_mode

(available since CHDK version 0.6.7 / changeset #545)

Returns the active mode of the camera (3 values): bool is_record, bool is_video, number mode. The mode number is a bit field with several different values, exactly as would be returned by mode_get() in the CHDK C code. See the CHDK source for more information.

See also capmode.

Usage:

rec,vid,mode=get_mode()

Sample script

modestrings={
	'AUTO',
	'P',
	'TV',
	'AV',
	'M',
	'PORTRAIT',
	'NIGHT',
	'LANDSCAPE',
	'VIDEO_STD',
	'VIDEO_SPEED',
	'VIDEO_COMPACT',
	'VIDEO_MY_COLORS',
	'VIDEO_COLOR_ACCENT',
	'VIDEO_COLOR_SWAP',
	'STITCH',
	'MY_COLORS',
	'SCN_WATER',
	'SCN_NIGHT',
	'SCN_CHILD',
	'SCN_PARTY',
	'SCN_GRASS',
	'SCN_SNOW',
	'SCN_BEACH',
	'SCN_FIREWORK',
	'SCN_COLOR_ACCENT',
	'SCN_COLOR_SWAP',
	'VIDEO_HIRES',
	'SCN_AQUARIUM',
	'COLOR_ACCENT',
	'SCN_NIGHT1',
	'SCN_ISO_3200',
	'SCN_SPORT',
	'SCN_KIDS_PETS',
	'INDOOR',
	'KIDS_PETS',
	'NIGHT_SNAPSHOT',
	'DIGITAL_MACRO',
	'SCN_FOLIAGE',
	'VIDEO_TIME_LAPSE',
	'SCN_INDOOR',
	'SCN_PORTRAIT',
	'SUPER_MACRO',
	'VIDEO_PORTRAIT',
	'VIDEO_NIGHT',
	'VIDEO_INDOOR',
	'VIDEO_FOLIAGE',
	'VIDEO_SNOW',
	'VIDEO_BEACH',
	'VIDEO_AQUARIUM',
	'VIDEO_SUPER_MACRO',
	'VIDEO_STITCH',
	'VIDEO_MANUAL',
	'SPORTS',
}
rec,vid,mode=get_mode()
print("rec:",rec,"vid:",vid)
print("mode:",mode,tostring(modestrings[bitand(mode,0xFF)])) -- 0xFF is MODE_SHOOTING_MASK
sleep(2000)

---

LogicalEvent API

See Lua/Lua_Reference/Levent

---

Event procedure and native function API

See Lua/Lua Reference/Native Function Calls

---