This page describes CHDK Lua functions available on the camera to support control using the PTP Extension.
PTP client applications use the PTP_CHDK_ExecuteScript API to execute Lua code. In chdkptp and ptpcam, this is available through the lua and luar commands.
General information about executing Lua code over PTP
- To execute a Lua script already loaded on your camera (e.g. testprgm.lua), send the following Lua code from your client
- This loads the file and executes it. This is generally preferable to using "require", because it avoids the problems with sleep etc mentioned below.
- Executing a script while another script is already running can cause crashes and memory leaks.
- To check whether your script has terminated, you can use the script status command (script-status in ptpcam.)
- by default, chdkptp checks script status and prevents executing a new script while a script is running.
- Lua return values and errors messages are sent using the message interface.
- Simple tables are returned in a limited human readable string format by default, see  for a description. This can be changed by providing your own usb_msg_table_to_string. A replacement that properly serializes Lua tables can be found in chdkptp.
- In CHDK 1.2 and later, CHDK alt mode is automatically entered when a PTP script starts to execute. Unless the alt state is explicitly set with enter_alt() or exit_alt(), the previous alt state is restored when the script ends. In CHDK version prior to 1.2 Lua script execution would CHDK alt mode in a confused state. On these builds you may need to press the alt button a couple times to get the alt menu and buttons to respond as expected.
- While scripts in files already on the camera may be used, functions that yield (e.g. sleep(), wait_click() etc.) cannot be used inside require (or other pcall).
- Any key presses generated by script are released when the script ends. If you want to control key press and releases over PTP, you can use the message interface, or use Logical event functions to send the key presses.
- In CHDK prior to version 1.2, the function switch_mode_usb() should be used instead of set_record to switch between record and play mode when PTP is connected. In 1.2 and later, set_record will call the USB code if a USB connection is detected. switch_mode_usb is still available, and always calls the USB specific code.
The following functions are intended specifically for use with PTP. While they are available to all scripts, using them without a PTP connection is not recommended.
Set the camera to play or record mode.
mode is 1 for record or 0 for play.
msg = read_usb_msg([timeout])
Read a message sent from the client program using the PTP_CHDK_WriteScriptMsg API from the CHDK PTP interface (putm command in ptpcam or chdkptp).
Returns the next available message as a string, or nil if no messages are available
If timeout is given and not zero, wait until a message is available or timeout expires.
status = write_usb_msg(msg,[timeout])
Writes a message to the CHDK PTP interface. Client applications can read the message using the PTP_CHDK_ReadScriptMsg API (getm command in ptpcam or chdkptp)
msg may be nil, boolean, number, string or table. Tables will be converted to a string by usb_msg_table_to_string
returns true if the message was queued successfully, otherwise false
If timeout is set and not zero, wait until message is written or timeout expires.
NOTE strings will not include a terminating NULL.
This function is called by the PTP message code when a table is returned from a Lua script, or sent using write_usb_msg. Lua code can override this function to provide different serialization formats. The return value should be a string on success. On failure, a Lua error should be thrown. PTP scripts may override this function to provide their own serialization format.
Note used only for values sent from the camera to the PC. Messages received with read_usb_msg are always strings, and user code is responsible for unserializing them if needed.