Montana123 (talk | contribs) No edit summary |
(update for Canon raw support, formatting, more details) Tag: Source edit |
||
(23 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
+ | =Introduction= |
||
− | The following information applies to the client/PC side scripting to invoke actions on your camera from your PC using ptp client applications (see http://chdk.wikia.com/wiki/PTP_Extension) which also use LUA for PC side scripting (not to be confused with using LUA for scripts that run on your camera). (I believe that ->) This information doesn't apply to the (non-GUI) ptpcam client application but does apply to the (GUI) ptpcamgui and chdkptp client applications. |
||
+ | 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 <tt>lua</tt> and <tt>luar</tt> commands. |
||
⚫ | |||
+ | |||
⚫ | |||
⚫ | |||
⚫ | |||
+ | |||
⚫ | |||
+ | |||
+ | : This loads the file and executes it. This is generally preferable to using "require", because it avoids the problems with sleep etc mentioned below. |
||
+ | : If the script uses parameters from the CHDK script menu, set the variables defined in the script header fore loadfile, like a=1 b=2 loadfile... |
||
⚫ | |||
** To check whether your script has terminated, you can use the script status command (script-status in ptpcam.) |
** 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. |
||
− | * The function switch_mode_usb() should be used instead of set_record to switch between record and play mode when PTP is connected. |
||
+ | ** If using chdkptp with CHDK 1.3, you can use the killscript command to end a running script. |
||
* Lua return values and errors messages are sent using the message interface. |
* 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 [http://chdk.setepontos.com/index.php?topic=4338.msg62606#msg62606] for a description. This can be changed by providing your own usb_msg_table_to_string. A replacement that properly serializes |
+ | ** Simple tables are returned in a limited human readable string format by default, see [http://chdk.setepontos.com/index.php?topic=4338.msg62606#msg62606] 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. |
− | * Lua script execution |
+ | * 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 put 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). |
* 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 [[Lua/Lua_Reference/Levent|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. |
||
+ | * Many shooting override functions (like set_tv*, set_focus, etc) only take effect if the shot is taken in the same script as the override was set. When the script ends, the override is reset. Each lua or luar command is a new script, so |
||
+ | |||
+ | luar set_tv96_direct(1) |
||
+ | luar shoot() |
||
+ | : will not use the tv96 setting. Use |
||
+ | luar set_tv96_direct(1) shoot() |
||
+ | : instead, or use canon manual mode and set USER propcases, or set_config_value with CHDK overrides. |
||
=PTP Functions= |
=PTP Functions= |
||
+ | 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. |
||
+ | |||
==switch_mode_usb== |
==switch_mode_usb== |
||
Line 19: | Line 39: | ||
mode is 1 for record or 0 for play. |
mode is 1 for record or 0 for play. |
||
+ | |||
+ | ==usb_force_active== |
||
+ | |||
+ | usb_force_active(mode) |
||
+ | |||
+ | Forces the Canon firmware to see the USB 5V line as active regardless of its actual state. |
||
+ | |||
+ | * mode = 1 or ''true'' for USB 5V power detect forced active |
||
+ | |||
+ | * mode = 0 or ''false'' for USB 5V power detect normal |
||
+ | |||
+ | This function useful in multicam scripts that need to maintain PTP communications while the USB 5V line is switched on & off for USB remote shooting - particularly for precision sync. |
||
+ | |||
+ | Returns true if function is implemented, false otherwise. |
||
+ | |||
+ | '''Note : '''this function requires the ''CAM_ALLOWS_USB_PORT_FORCING'' option to be selected in the platform_camera.h build configuration file for the camera. As of CHDK release 1.4, the option is enabled by default for all cameras. |
||
+ | |||
+ | ==force_analog_av== |
||
+ | ( see https://chdk.setepontos.com/index.php?topic=13451.msg142423#msg142423 ) |
||
+ | |||
+ | force_analog_av(n) |
||
+ | |||
+ | where n=0 means leave the AV bit alone, n=1 force AV present, n=2 force AV not present |
||
+ | * similar to usb_force_active but for the A/V detect to allow A/V out while also using the detect signal as a remote trigger |
||
+ | * enabled for all cams with ANALOG_AV_FLAG, regardless of whether it's enabled as a remote input |
||
+ | <nowiki> </nowiki>Note : parameter meaning is different from force_usb_present, where 1 / true = force USB present, 0/ false = leave it alone. |
||
+ | |||
+ | == usb_sync_wait == |
||
+ | usb_sync_wait( mode ) |
||
+ | CHDK 1.4.0 or newer only. |
||
+ | |||
+ | Causes the camera to wait for a sync signal (USB power going from 5V to 0V) before completing the next exposure. |
||
+ | * mode = 1 or ''true ''for wait for sync at next shot |
||
+ | |||
+ | * mode = 0 or ''false ''for do not wait for sync at next shot |
||
+ | This function is useful in multicam scripts that need precise synchronization. |
||
+ | |||
+ | Returns nothing. |
||
==read_usb_msg== |
==read_usb_msg== |
||
Line 24: | Line 82: | ||
msg = read_usb_msg([timeout]) |
msg = read_usb_msg([timeout]) |
||
− | Read a message from the CHDK |
+ | Read a message sent from the client program using the PTP_CHDK_WriteScriptMsg API from the CHDK PTP interface (<tt>putm</tt> command in ptpcam or chdkptp). |
Returns the next available message as a string, or nil if no messages are available |
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 |
+ | If timeout is given and not zero, wait until a message is available or timeout expires. |
==write_usb_msg== |
==write_usb_msg== |
||
Line 34: | Line 92: | ||
status = write_usb_msg(msg,[timeout]) |
status = write_usb_msg(msg,[timeout]) |
||
− | Writes a message to the CHDK |
+ | Writes a message to the CHDK PTP interface. Client applications can read the message using the PTP_CHDK_ReadScriptMsg API (<tt>getm</tt> 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 |
msg may be nil, boolean, number, string or table. Tables will be converted to a string by usb_msg_table_to_string |
||
Line 45: | Line 103: | ||
==usb_msg_table_to_string== |
==usb_msg_table_to_string== |
||
− | s=usb_msg_table_to_string(table) |
+ | s=usb_msg_table_to_string(table) |
+ | |||
⚫ | 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. |
||
+ | |||
+ | ==USB Image Capture over PTP== |
||
+ | ( see https://chdk.setepontos.com/index.php?topic=4338.msg116518#msg116518 ) |
||
+ | |||
+ | ===get_usb_capture_support=== |
||
+ | Get supported remote capture data types |
||
+ | |||
+ | bitmask=get_usb_capture_support() |
||
+ | |||
+ | where full jpeg file = 0x1, CHDK raw = 0x2, CHDK DNG header 0x4, Canon raw file 0x8. |
||
+ | |||
+ | '''Note:''' The values only describe what is supported by the port, availability of specific formats depends on camera settings as described for init_usb_capture below. |
||
+ | |||
+ | ===init_usb_capture=== |
||
+ | Configure remote capture for following shots |
||
+ | |||
+ | status=init_usb_capture(bitmask[,startline, numlines]) |
||
+ | |||
+ | * bitmask = 0 clear usb capture mode, other values as described for get_usb_capture_support |
||
+ | * lines and startline only applies to CHDK raw |
||
+ | * startline defaults to 0 |
||
+ | * numlines defaults to full buffer |
||
+ | |||
+ | status is true if the the requested format are supported by the port in the current settings. Formats supported by the port (reported available by get_usb_capture_support) may be unavailable depending on settings. In particular: |
||
+ | * For jpeg and Canon raw, the appropriate format must be enabled in the Canon firmware. Canon raw is only available on cameras with raw support in the standard Canon firmware. See set_canon_image_format |
||
+ | * CHDK raw / DNG is not available in some shooting modes, frequently including Low Light, Auto and special scene modes like HDR |
||
+ | * On some cameras, remote capture is not available when Continuous Drive is enabled in the Canon firmware |
||
+ | |||
+ | |||
+ | ===get_usb_capture_target=== |
||
+ | Get currently configured remote capture formats |
||
+ | |||
+ | selected=get_usb_capture_target() |
||
+ | |||
+ | where selected = bitmask passed to init, or 0 if capture not configured or timed out/canceled |
||
+ | |||
+ | ===set_usb_capture_timeout=== |
||
+ | |||
+ | set_remotecap_timeout([timeout]) |
||
+ | |||
+ | where timeout: number of milliseconds remote capture waits for data of each type to be downloaded |
||
+ | <=0 or no value resets to the default value |
||
+ | |||
+ | If any data type is not downloaded before the timeout expires, remote capture is cancelled and none of the subsequent data types will be returned following a timeout, RemoteCaptureIsReady and RemoteCaptureGetData will behave as if remote capture were not initialized. |
||
+ | |||
+ | If the timeout expires while a transfer is in progress, an error will be generated and the data may be incomplete or corrupt. |
||
⚫ | |||
[[Category:Scripting]] |
[[Category:Scripting]] |
||
[[Category:PTP Extension]] |
[[Category:PTP Extension]] |
Latest revision as of 02:14, 26 November 2021
Introduction
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
loadfile('A/CHDK/SCRIPTS/testprgm.lua')()
- This loads the file and executes it. This is generally preferable to using "require", because it avoids the problems with sleep etc mentioned below.
- If the script uses parameters from the CHDK script menu, set the variables defined in the script header fore loadfile, like a=1 b=2 loadfile...
- In chdkptp 1.2 and earlier, 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.
- If using chdkptp with CHDK 1.3, you can use the killscript command to end a running script.
- 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 [1] 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 put 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.
- Many shooting override functions (like set_tv*, set_focus, etc) only take effect if the shot is taken in the same script as the override was set. When the script ends, the override is reset. Each lua or luar command is a new script, so
luar set_tv96_direct(1) luar shoot()
- will not use the tv96 setting. Use
luar set_tv96_direct(1) shoot()
- instead, or use canon manual mode and set USER propcases, or set_config_value with CHDK overrides.
PTP Functions
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.
switch_mode_usb
switch_mode_usb(mode)
Set the camera to play or record mode.
mode is 1 for record or 0 for play.
usb_force_active
usb_force_active(mode)
Forces the Canon firmware to see the USB 5V line as active regardless of its actual state.
- mode = 1 or true for USB 5V power detect forced active
- mode = 0 or false for USB 5V power detect normal
This function useful in multicam scripts that need to maintain PTP communications while the USB 5V line is switched on & off for USB remote shooting - particularly for precision sync.
Returns true if function is implemented, false otherwise.
Note : this function requires the CAM_ALLOWS_USB_PORT_FORCING option to be selected in the platform_camera.h build configuration file for the camera. As of CHDK release 1.4, the option is enabled by default for all cameras.
force_analog_av
( see https://chdk.setepontos.com/index.php?topic=13451.msg142423#msg142423 )
force_analog_av(n)
where n=0 means leave the AV bit alone, n=1 force AV present, n=2 force AV not present
- similar to usb_force_active but for the A/V detect to allow A/V out while also using the detect signal as a remote trigger
- enabled for all cams with ANALOG_AV_FLAG, regardless of whether it's enabled as a remote input
Note : parameter meaning is different from force_usb_present, where 1 / true = force USB present, 0/ false = leave it alone.
usb_sync_wait
usb_sync_wait( mode )
CHDK 1.4.0 or newer only.
Causes the camera to wait for a sync signal (USB power going from 5V to 0V) before completing the next exposure.
- mode = 1 or true for wait for sync at next shot
- mode = 0 or false for do not wait for sync at next shot
This function is useful in multicam scripts that need precise synchronization.
Returns nothing.
read_usb_msg
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.
write_usb_msg
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.
usb_msg_table_to_string
s=usb_msg_table_to_string(table)
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.
USB Image Capture over PTP
( see https://chdk.setepontos.com/index.php?topic=4338.msg116518#msg116518 )
get_usb_capture_support
Get supported remote capture data types
bitmask=get_usb_capture_support()
where full jpeg file = 0x1, CHDK raw = 0x2, CHDK DNG header 0x4, Canon raw file 0x8.
Note: The values only describe what is supported by the port, availability of specific formats depends on camera settings as described for init_usb_capture below.
init_usb_capture
Configure remote capture for following shots
status=init_usb_capture(bitmask[,startline, numlines])
- bitmask = 0 clear usb capture mode, other values as described for get_usb_capture_support
- lines and startline only applies to CHDK raw
- startline defaults to 0
- numlines defaults to full buffer
status is true if the the requested format are supported by the port in the current settings. Formats supported by the port (reported available by get_usb_capture_support) may be unavailable depending on settings. In particular:
- For jpeg and Canon raw, the appropriate format must be enabled in the Canon firmware. Canon raw is only available on cameras with raw support in the standard Canon firmware. See set_canon_image_format
- CHDK raw / DNG is not available in some shooting modes, frequently including Low Light, Auto and special scene modes like HDR
- On some cameras, remote capture is not available when Continuous Drive is enabled in the Canon firmware
get_usb_capture_target
Get currently configured remote capture formats
selected=get_usb_capture_target()
where selected = bitmask passed to init, or 0 if capture not configured or timed out/canceled
set_usb_capture_timeout
set_remotecap_timeout([timeout])
where timeout: number of milliseconds remote capture waits for data of each type to be downloaded <=0 or no value resets to the default value
If any data type is not downloaded before the timeout expires, remote capture is cancelled and none of the subsequent data types will be returned following a timeout, RemoteCaptureIsReady and RemoteCaptureGetData will behave as if remote capture were not initialized.
If the timeout expires while a transfer is in progress, an error will be generated and the data may be incomplete or corrupt.