CHDK Wiki
Register
Advertisement

The Script Header

At the start of each uBASIC or Lua script is a script header section.  The script header section is used to define the script's name,  to identify which version(s) of CHDK are compatible, contains comments or user notes needed,  and defines "user parameter variables" that can be set at script run time from the CHDK Script menu.  

For uBASIC scripts, each line of the script header starts with a keyword that begins with the @ symbol. Valid uBASIC keywords are : @title @chdk_version @param @default @range @values

For Lua scripts, the header is enclosed in a standard Lua long comment - delineated by --[[ and ]]. Valid script header keywords used within the comment field for Lua are the same as those for uBASIC although Lua also includes a "shortcut" notation that offers a more compact format and additional functionality.

Example Script Headers

Lua

 --[[
 20080815 test script by xxx
 @title test script
 @chdk_version 1.3.0
 @param a Duration (min)/-1 disable
   @default a -1
   @range   a -1 3600
 @param     b Mode
   @default b 2
   @values  b None Night Day
 @param     h Endless?
   @default h 0
   @range   h 0 1
 --]]

uBASIC

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

Header Keywords

@title Your Script Title
Defines the title used for the currently loaded script.  The title appears on the CHDK <ALT> screen and in the "Scripting Parameters" menu selection of the "Script" menu. Keep your title short (24 characters or less) or the title will overlap the <ALT> symbol. If there is no @title command the file name of script is used.
@subtitle Section Comment
Defines a subtitle that will appear only in the list of script parameters. Used to delineate different sections or groups of script parameters. (CHDK 1.4.0 or later only)
@chdk_version
Used to specify the version of CHDK for which the script was written. In Lua, changes the behavior of several functions that return 0/1 in CHDK 1.3.0 or older and true/false in CHDK 1.4.0 or newer.
@param x (label)
Defines the user parameters that can be user entered (or set) from the "Scripting Parameters" menu selection of the "Script" menu. Typical uses include things like setting the number of exposures needed,  a time delay needed, or how many bracketing steps to use. "x" is the name of the variable to be set. 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.).
If there are no @param values specified, CHDK assumes that there are three adjustable variables: a, b and c.
@default x n
An optional statement that set a default value for variable "x", where "x" is a variable in an @param statement and "n" is the default value to use. This value is set when the script is first loaded.
@range x n m
An optional statement defines the minimum and maximum allowed values for script parameter "x". 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). 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.
@values x aaa bbb ccc ddd eee
An optional statement that specifies a list of strings that are can be scrolled by the user to select a parameter value. The "x" parameter value will be set to the position of the chosen string in the list (starting with 0). String values will only be assigned if there is no "@range" statement.

Notes :

CHDK 1.3.0 or older :

  • up to 26 @param statements (or user-controllable variables), may be used in any one script.
  • in uBASIC, there are a total of 52 variables available to use, a to z and A to Z, but the user-definable variables must be lower-case if used for that purpose. Lua allows longer variable names but user parameter variables must still be only a to z
  • be aware that lower and uppercase variables are unrelated.

CHDK 1.4.0 or newer :

  • uBASIC programs may use both a to z and A to Z as user parameters.  
  • Lua scripts may use any valid Lua variable name (up to 64 characters in length) that starts with an alpha character (a to z or A to Z) as a user parameter.

Lua Shorthand Parameter Syntax

Starting with CHDK 1.4.0, the Lua header file can also be configured using a "shorthand" syntax that allows a more compact format and a few additional input modes.

Shorthand Parameter syntax:

#varnam=defval "title"

  • for simple numeric parameters with no defined range
  • if deval is true or false then varnum will be treated as a Boolean variable

#varnam=defval "title" [min max]

  • specify range for varnum
  • replaces @range

#varnam=deval "title" {opt1 opt2 ... optN}

  • gives a list of options for user to select from
  • replaces @values

#varnam=defval "title" {opt1 opt2 ... optN} table

  • uses a Lua table for options.
  • varnam.value returns the user selected index
  • varnam[n] returns label string indexed by n

#varnam=defval "title" long

  • assigns a long number to varnam

Notes:

  • a "#" at the start of a line designates "shorthand" syntax
  • varnam is the variable name to be used
  • defval is the default value to be assigned to the variable. If value is "true" or "false" then varnam will be a Boolean variable
  • the '=' between varnam and defval is optional (if not present use a space),
  • spaces can be inserted before and after varname if desired
  • title is the sting that will be displayed in the Script menu parameter list
  • single or double quotes can be used for title but should match (quoting is mandatory).
  • true/false cause variable to be Boolean
  • long allows assigning a long number (i.e. greater that 65535)
  • table creates a Lua table named "varnam"

Sample Scripts

Simple uBasic test sample:

 @title Param Test
 @chdk_version 1.3.0
 @param   a Dial Position
 @default a 2
 @range   a 1 12
 @param   b Mode
 @default b 0
 @values  b Off Stop Start
 @param   c Debug?
 @default c 0
 @range   c 0 1 
 print a b c
 end

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

 --[[
 @title Param Test
 @chdk_version 1.3.0
 @param     a Dial Position
   @default a 2
   @range   a 1 12
 @param     b Mode
   @default b 0
   @values  b Off Stop Start
 @param     c Debug?
   @default c 0
   @range   c 0 1 
 --]]
 print(a,b,c)



Advertisement