Python bindings for chdkptp via an embedded, thread-safe Lua runtime (thanks to Stefan Behnel’s lupa).


  • C compiler
  • Lua 5.2, with headers
  • libusb, with headers
  • lupa, installed with the –no-luajit flag

API Reference

class chdkptp.ChdkDevice(device_info)

Create a new device instance and connect to the CHDK device.

Parameters:device_info (DeviceInfo) – Information about device to connect to
batch_download(remote_paths, local_path='./', overwrite=False)

Download multiple files/directories from the device.

  • remote_paths (collection of str/unicode) – Multiple paths on the device. The leading ‘A/’ is optional, it will be automatically prepended if not specified
  • local_path (str/unicode) – Target path on the local file system
  • overwrite (bool) – Overwrite existing files
batch_upload(local_paths, remote_path='A/')

Upload multiple files/directories to the device.

  • local_paths (collection of str/unicode) – Multiple locals paths
  • remote_path (str/unicode) – Target path on the device

Delete one or more files/directories from the device.

Parameters:remote_paths – One or more paths on the device. The leading ‘A/’ is optional, it will be automatically prepended if not specified
download_file(remote_path, local_path=None)

Download a single file from the device.

If no local path is specified, the file’s content is returned as a bytestring.

  • remote_path (str/unicode) – Path on the device. The leading ‘A/’ is optional, it will be automatically prepended if not specified
  • local_path (str/unicode) – (Optional) local path to store file under.

If local_path was not specified, the file content as a bytestring, otherwise None

Return type:


get_frames(format='ppm', scaled=None)

Get a generator that yields frames from the device’s viewport.

  • format (One of ‘ppm’, ‘jpg’, ‘png’) – Target format for frames, if None the raw image data is returned
  • scaled (bool) – The raw image has the wrong aspect ratio, with this flag this can be corrected on the device, which results in some quality degradation, but is very fast. Defaults to True when format is ‘ppm’, otherwise False.

Generator that yields bytestrings with frame data in the specified format


Get all messages from device buffer

Return type:generator, yields Message

Terminate any running script on the device.

Parameters:flush (bool) – Discard script messages
list_files(remote_path='A/DCIM', detailed=False)

Get directory listing for a path on the device.

  • remote_path (str/unicode) – Path on the device
  • detailed (bool) – Return detailed information about each file/dir

All files and directories in the path

lua_execute(lua_code, wait=True, do_return=True, remote_libs=[])

Execute Lua code on the device.

  • lua_code (str/unicode) – Lua code to execute
  • wait (bool) – Block until code has finished executing

Return value of lua code, only if wait=True

Return type:



Create a directory on the device. Intermediate directories will be created as needed.

Parameters:remote_path (str/unicode) – Path on the device
reboot(wait=3500, bootfile=None)

Reboot the device.

  • wait (int) – Time in miliseconds to wait before attempting to reconnect
  • bootfile (str/unicode) – Optional file to boot. Must be the path to an existing file on the device that is either an unencoded binary or (for DryOS) an encoded .FI2

Reset the connection to the device.

Parameters:wait (int) – Time in miliseconds to wait before attempting to reconnect
send_message(message, script_id=None)

Send a message to the device

  • message (str/unicode) – Message to be sent
  • script_id (int/None) – ID of script that the message should be sent to, defaults to the most recently started script

Shoot a picture

For all arguments where None is a legal type, it signifies that the current value from the camera should be used and not be overriden.

  • shutter_speed (int/float/None) – Shutter speed in APEX96 (default: None)
  • real_iso (int/float/None) – Canon ‘real’ ISO (default: None)
  • market_iso (int/float/None) – Canon ‘market’ ISO (default: None)
  • aperture (int/float/None) – Aperture value in APEX96 (default: None)
  • isomode (int/None) – Must conform to ISO value in Canon UI, shooting mode must have manual ISO (default: None)
  • nd_filter (boolean/None) – Toggle Neutral Density filter (default: None)
  • distance (str/unicode/int) – Subject distance. If specified as an integer, the value is interpreted as the distance in milimeters. You can also pass a string that contains a number followed by one of the following units: ‘mm’, ‘cm’, ‘m’, ‘ft’ or ‘in’ (default: None)
  • dng (boolean) – Dump raw framebuffer in DNG format (default: False)
  • wait (boolean) – Wait for capture to complete (default: True)
  • download_after (boolean) – Download and return image data after capture (default: False)
  • remove_after (boolean) – Remove image data after shooting (default: False)
  • stream (boolean) – Stream and return image data directly from device (will not be saved on camera storage) (default: True)
upload_file(local_path, remote_path='A/', skip_checks=False)

Upload a file to the device.

  • local_paths (str/unicode) – Path to a local file
  • remote_path (str/unicode) – Target path on the device
  • skip_checks – Skip sanity checks on the device, required if a script is running on the device while uploading.

Lists all recognized PTP devices on the USB bus.

Returns:All connected PTP devices
Return type:List of DeviceInfo named tuples
class chdkptp.DeviceInfo

DeviceInfo(model_name, bus_num, device_num, vendor_id, product_id, serial_num, chdk_api)


Alias for field number 1


Alias for field number 6


Alias for field number 2


Alias for field number 0


Alias for field number 4


Alias for field number 5


Alias for field number 3

class chdkptp.device.Message

Message(type, script_id, value)


Alias for field number 1


Alias for field number 0


Alias for field number 2

class chdkptp.lua.LuaContext[source]

Proxy object around lupa.LuaRuntime that wraps all Lua code inside of pcall and raises proper Exceptions.

Indices and tables