Lua Scripting functions
This is the reference page for Lua functions which do not have an equivalent command in ubasic, or are significantly modified compared to the ubasic equivalent.
Most of the uBASIC commands are also available in Lua and can be used the same way, so UBASIC/TutorialScratchpad and Script_commands can be used as reference also for Lua.
Lua standard libraries
Functions in this section are only available in Lua
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
New Lua functions
Functions in this section are only available in Lua
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)
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)
get_prop_str / set_prop_str / binstr
(available since changeset #1306)
The Lua commands get_prop_str, set_prop_str and binstr can be used to access arbitrary sized propcases from Lua.
Usage:
val=get_prop_str(prop_id,length)
- get the value of a PropertyCase as a string
- numeric values may be extracted using string.byte or or the binstr.lua module
- returns the value as a string, or false if the underlying propcase call returned non-zero
status=set_prop_str(prop_id,value)
- set propertycase value as a string. Length is taken from the string
- numeric propcase values may be assembled by setting byte values using string.char or the binstr module
- status: boolean - true if the underlying propcase call returns 0, otherwise false
→ Both of the above use Lua strings, which can contain any sequence of bytes.
binstr:
Because many of the values you'd want to get/set at are numbers or arrays of numbers, a lua helper module called binstr is available to convert to and from strings for use with the above.
The binstr module has 3 functions:
string=binstr.pack(value[,size])
- value is a number or array of numbers
- size is the number bytes to use from each number, default is 4, valid values are 1-4
- returns a lua string
num=binstr.getnum(str[,size[,pos]])
- extract size bytes from string into number, starting at pos
- size defaults to 4,
- pos defaults to 1
- returns a number (without sign extension) or nil if pos is outside the string
array=binstr.unpack(str[,size])
- split every size bytes of str into numbers and return as an array
- size defaults to 4
usage:
bs=require('binstr')
wbdata=bs.unpack(get_prop_str(0x10d,0x1c)) -- return propset 3 white balance as 7 ints
→ In all cases, the numbers are assumed to be little endian
file_browser(path)
(since changeset #1359; since #1360 works better)
This function allows you to run regular CHDK file browser from the script. When user will select a file, the command will return the string - a path to the selected file.
The 'path' given as an argument is the startup directory for the file browser.
Example code runs file browser in SCRIPTS directory and prints the path to the selected file:
--[[
@title select a file
--]]
startup_dir="A/CHDK/SCRIPTS"
file=file_browser(startup_dir)
print(file)
When user will not select any file (in example exit file browser by pressing 'menu' button) command wil return nil value.
Once browser is run by script it behaves exactly as CHDK file browser with all options - user can copy, cut and paste files, do RAW processings and other things that are allowed in browser run from menu. There's no way to control the things user can do.
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
get_meminfo
meminfo=get_meminfo([heapname]) get camera memory information heapname="system" or "exmem" if not given, meminfo is returned for heap used by CHDK for malloc meminfo is false if the requested heapname isn't valid ("exmem" when exmem is not enabled, or unknown) otherwise, a table of the form
meminfo = {
name -- string "system" or "exmem"
chdk_malloc -- bool, this is the heap used by CHDK for malloc
chdk_start -- number, load address of CHDK
chdk_size -- number, size of CHDK image
-- all the following are numbers, will not be set if not available
start_address
end_address
total_size
allocated_size
allocated_peak
allocated_count
free_size
free_block_max_size
free_block_count
}
notes
- under vxworks and cameras without GetMemInfo only the only valid fields for the system heap will be those defined by chdk and free_block_max_size
- the meaning of fields may not correspond exactly between exmem and system
LogicalEvent API
Event procedure and native function API
See Lua/Lua Reference/Native Function Calls
Changed Lua commands
This section lists commands which are available both in Lua and in uBasic. |
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)