CHDK Script Header

The Script Header

Lua

The header of a Lua script is the same as on a uBASIC script, packed into a long comment - the script parser interpretes this the same way in Lua as in uBASIC.

A Sample Lua header:

--[[
rem 20080815 test script by xxx
@title test script
@param a Duration (min)/-1 disable
@default a -1
@param b Duration (sec)/n of seqs
@default b 5
@param h Endless?
@default h 0
]]

• See also: Lua/Lua_syntax#The_script_header

uBasic

When viewing scripts you'll often see the opening section look something like this:

@title Interval shooting
@param a Shoot count
@default a 5
@param b Interval (Minutes)
@default b 1
@range b 0 10

Let's break down what each of those lines mean and how they are used by CHDK.

@title Your Script Title

This is the title that will appear when you have the script loaded in CHDK and go to "Scripting Parameters" menu selection. It will appear under the line "----Current Script----" as well as in the lower-left corner of your viewfinder when you are in <ALT> mode. Keep your title short (24 characters or less). Otherwise the title will cover up the <ALT> label.

@subtitle Section Comment

This is a subtitle that will appear in the list of script parameters. Used to delineate different sections or groups of script parameters. ( CHDK 1.4.0 or later only)

@param x (label)

@default x n

@range x n m

This is where you will define the beginning values of any variables used in your script. These are often used to set how many exposures you want, how long of a delay you want, how many bracketing steps you want, etc. These variables can be changed by the end-user from the "Scripting Parameters" menu items. In that sub-menu, they will appear under the line "----Script Parameters-----"

@param x (label)

The "x" in that line will be one of any lower-case latin letter from a to z. The (label) is the text string that will appear in your "----Script Parameters----" list, to let the end user know which of the variables they are changing (i.e. number of shots, how many steps, etc.).

Up to 26 @param statments, user-controllable variables, may be used in any one script.

Note: CHDK allows you to have up to 26 user-definable variables from a to z. There are a total number of 52 variables available for your use, a to z and A to Z, but the user-definable variables must be in lower-case if used for that purpose. Also be aware that lower and uppercase variables are unrelated. If you use a lower-case j for a variable, it is not the same as using J, and vice-versa.

@default x n

This optional statement sets up the default, or beginning value of your (lower-case letter) variable, where "x" is the variable from the @param statement above, and "n" is the default value to start with. This value is only used when a script is loaded for the first time.

@range x n m

This optional statement allows minimum and maximum allowed values for a script parameter (examples below).

If the range is set to 0..1 the parameter is displayed in the script menu as a boolean on/off toggle instead of an integer value (the actual parameter value is still an integer though).

Simple uBasic test sample:

@title Range Test
@param a A 1..12
@default a 2
@range a 1 12
@param b B 0..1
@default b 0
@range b 0 1
@param c C -12..12
@default c 0
@range c -12 12

print a
print b
print c

end

The script will also work for Lua with a few modifications:

--[[
@title Range Test
@param a A 1..12
@default a 2
@range a 1 12
@param b B 0..1
@default b 0
@range b 0 1
@param c C -12..12
@default c 0
@range c -12 12
--]]
print(a)
print(b)
print(c)

Note it is up to the script writer to ensure that the @default value lies within @range - this is not validated when the script is loaded.

Note also that defining a range will override setting string values (see next section).

@values x aaa bbb ccc ddd eee (CHDK release 1.2.0 and later only)

This optional statement specifies a list of strings that are can be scrolled by the user to select a parameter value. The parameter value will be the position of the chosen string in the list (starting with 0). String values will only be assigned if there is no "@range" statement. Usage example:

@param f Channel (U,Y,V,R,G,B)
@default f 1 
@values f U Y V R G B

In this case the string "Y" is the default, as f has the default value of 1.

If a variable had to be assigned the three values of -1, 0 and 1 via corresponding strings, then the three strings would be defined as "@values" with initial values of 0, 1, and 2, then 1 is subtracted in the body of the script:

@param f Brightness Threshold
@default f 1
@values f Darker Off Lighter
f=f-1
rem f now has the values of -1 for "Darker", 0 for "Off", and 1 for "Lighter"

Notes

If there is no @title command the filename of script is used.
If there are no @param commands CHDK assumes that there are three adjustable variables: a, b and c.
Remember -- when naming @param variables, use only a character from a through z.

After default variable values have been defined here, it is good to add some lines right after this section to ensure those numbers will be used in case the user has input 0 (zero) for some value that needs to be higher (or lower). This can be seen in scripts as:

if a<2 then let a=5

If the default value that you wanted the user to start out at for parameter variable a was 5, then if they left that setting at 0 (zero) or 1, then this will automatically increase that variable's value back up to 5.

After variable parameters have been initialised comes the brunt of your script, the part that does the actual work and tells the camera what to do, when to do it, and what buttons or commands need to be executed. Since we are working with a very small subset of the larger uBASIC programming language, it might be good to list and explain only those that are available to the CHDK script writer.

---