|
+ Canomate - Automation tool for Canon cameras |
+
This is the official homepage of Canomate, my open-source utility for automating operations on WiFi-equipped Canon cameras that support Canon's Camera Control API (CCAPI). Canomate runs on Windows, Mac, Linux, and any other platform that has support for Python 3.5+. Canomate is licensed under GPL v3.
+ +As of 8/26/20 the following Canon cameras support CCAPI. Canon USA's list can be downloaded via here:
+Canomate can be started in one of the following ways:
+Canomate is a command-line tool. There are many options, both from the command line and within the automation script you create. Here is a guide on the bare essential options to get started.
+--ipaddress=<addr> - The IP address of the camera on your local WiFi network. You can get this address by going to the "Wireless Communication settings" in the camera's menu and going to "Camera Control API", "Wi-Fi settings", "Camera Control API". The URL at the bottom of the screen includes the IP address of the camera
+--opfile=<filename> - The path/filename of the text file containing your automation script
+The automation script is a text file you create that lists all the automation operations to perform. Each line takes the form of <Operation Name> <param=value>. For example, here is a simple script that displays the model/serial # information from the camera, followed by the current P/A/S/M mode dial and exposure settings, and finally, the current still image quality settings:
++PrintCameraInfo +PrintShootingSettings +PrintStillImageQuality listavailable=yes ++
Here is the output from the above script:
++canomate v0.01 - Automation Utility for Canon cameras (uses Canon Control API via WiFi) +Copyright (c) Horshack, System Time: 08/26/20 12:38:00, Py: 3.8.0, OS: Windows + +PrintCameraInfo: Model: Canon EOS RP, S/N: XXXXXXXXXXXX, Firmware: 1.5.0 +PrintShootingSettings: Mode: m, Aperture: f8.0, SS: 1/250, ISO: 200, EC: +PrintStillImageQuality: Raw: none, JPEG: small2 Available: Raw: ['none', 'raw', 'craw'], JPEG: ['none', 'large_fine', 'large_normal', 'medium_fine', 'medium_normal', 'small1_fine', 'small1_normal', 'small2'] +>>>> canomate session over (exit=0), logs at "C:\develop\canomate\canomate-appdata" ++
After the program banner, each line of output corresponds to a single automation operation. Notice the "listavailable=yes" parameter for PrintStillImageQuality - this parameter is available for many of the PrintXXX operations and will display all the possible choices for the setting, along with the current setting on the camera. This is useful during the development of your script so you'll know how to specify a given setting. For example, let's say you want to change the JPEG shooting quality from it's current setting of 'small2' to a larger size. You would use the SetStillImageQuality operation, specifying the desired JPEG quality option from the available options displayed by PrintStillImageQuality.
+SetStillImageQuality rawquality=none jpegquality=large_normal+
Let's do something more useful - like taking a photo! Let's also set the specific exposure settings we want to use rather than relying on whatever the camera is currently set to. Here is the script:
++AssertCameraSettings moviemode=off modedial=m +SetAperture aperture=f5.6 +SetShutterSpeed shutterspeed=1/200 +SetIso iso=400 +TakePhoto ++
The first operation "AssertCameraSettings" tells Canomate to make sure the camera is in stills mode and the camera's mode dial is set to 'm' (Manual), which is necessary for the camera to accept all three of the exposure settings we want to set. If the camera were in another mode like 'av' (Aperture Priority) or 'tv' (Shutter Priority) then the camera wouldn't let us set the Shutter Speed and Aperture respectively since those are automatically calculated by the camera in those modes. Using "AssertCameraSettings" operations is good practice since it avoids having to decipher subsequent error messages if you attempt a setting or operation that is incompatible with the camera's current mode of operation. When Canomate encounters the "AssertCameraSettings" operation it retrieves the camera setting associated with each specified setting and verifies it matches the value specified, in this case making sure the camera's Mode Dial is set to 'm'. If the camera's mode dial is in any other position then Canomate will display a message and terminate the script. For example:
+AssertCameraSettings: Mode dial setting is "av" but must be "m"+
The remaining operations are self-explanatory. The photo will be stored on the camera's internal media card, the same as if you took the photo holding the camera yourself. There are additional automation operations you can use to retrieve information about the photo just taken and also an operation to download it. You can even configure an operation to launch an application of your choice to handle the downloaded photo, such as your favorite image viewer. All thisfunctionality isn't just limited to stills - you can also automate the taking of videos as well.
+The automation script is a text file you create that lists all the automation operations to perform. Each line is in the form of <Operation Name> <param=value>. Operations can take zero, one, or more parameters, depending on the specific operation. Some parameters are common to all operations.
+The value for each parameter can optionally be enclosed in double-quotes, unless the operation contains a space, in which case quotes are mandatory. Filenames are an example of parameters that should be quoted.
+If the same parameter is specified multiple times then the last parameter overrides the previous instances.
+You can include comments in your script by beginning the line with a # sign.
+Automation operations can optionally be placed inside a Group operation. This makes it easy to repeat a given set of operations using the 'grouprepeatcount' parameter. The alternative would require copying and pasting the same set of operations multiple times. Each Group operation in the script must have a corresponding EndGroup.
+There are up to four levels inheritance for parameters, listed as followed in lowest to highest priority: Defaults, Command Line, Group, and Operation. "Command Line" inheritance applies only to parameters that can be specified on both the command line and in the automation script, such as --timeout.
+Parameters specified for a Group operation are inherited by all operations within the group. For example, 'retrycount' specified for a Group becomes the default retry count for each operation contained within the Group. That paramter can be overridden on a per-operation basis by supplying the 'retrycount' parameter for the operation. Parameters specific to Groups are not inherited by the operations within the group, or to nested groups . For example, the following script will execute each operation within the group 2 times for each iteration of the group, and perform 3 iterations of the group.
++# Example of group vs operation repeat counts +Group grouprepeatcount=3 repeatcount=2 +PrintMessageToLog message="Hello, world" +PrintMessageToLog message="Cruel, Cruel, world" +EndGroup ++
Output:
++Performing group "Example 1", Iteration 1/3 +PrintMessageToLog: Hello, world +PrintMessageToLog: Hello, world +PrintMessageToLog: Cruel, Cruel, world +PrintMessageToLog: Cruel, Cruel, world +Performing group "Example 1", Iteration 2/3 +PrintMessageToLog: Hello, world +PrintMessageToLog: Hello, world +PrintMessageToLog: Cruel, Cruel, world +PrintMessageToLog: Cruel, Cruel, world +Performing group "Example 1", Iteration 3/3 +PrintMessageToLog: Hello, world +PrintMessageToLog: Hello, world +PrintMessageToLog: Cruel, Cruel, world +PrintMessageToLog: Cruel, Cruel, world ++
Groups can be nested. Parameters specified on the outer group are inherited by operations contained inside nested group. Group-specific parameters are never inherited by either operations or nested groups. In the following example, group "Inner" does not inherit the 'grouprepeatcount' of "Outer", but the operations within "Inner" do inherit the 'repeatcount' of "Outer"
+Group groupname="Outer" grouprepeatcount=2 repeatcount=3 +PrintMessageToLog message="I'm an outtie" +Group groupname="Inner" +PrintMessageToLog message="I'm an innie" +EndGroup +EndGroup ++
Output:
+Performing group "Outer", Iteration 1/2 +PrintMessageToLog: I'm an outtie +PrintMessageToLog: I'm an outtie +PrintMessageToLog: I'm an outtie +Performing group "Innner", Iteration 1/1 +PrintMessageToLog: I'm an innie +PrintMessageToLog: I'm an innie +PrintMessageToLog: I'm an innie +Performing group "Outer", Iteration 2/2 +PrintMessageToLog: I'm an outtie +PrintMessageToLog: I'm an outtie +PrintMessageToLog: I'm an outtie +Performing group "Innner", Iteration 1/1 +PrintMessageToLog: I'm an innie +PrintMessageToLog: I'm an innie +PrintMessageToLog: I'm an innie ++
The following table lists all operations available and the parameters they accept. Parameters in red are required. Parameters in black are optional
+| Operation | +Parameters | +
| Operation Containers | +|
| Group | +groupname, grouprepeatcount | +
| EndGroup | ++ |
| Information | +|
| PrintCameraInfo | ++ |
| PrintCameraDateTime | ++ |
| PrintShootingSettings | ++ |
| PrintShootingModeDial | ++ |
| PrintLensInfo | ++ |
| PrintBatteryInfo | ++ |
| PrintTemperatureStatus | ++ |
| Exposure | +|
| PrintAperture | +listavailable | +
| SetAperture | +aperture | +
| PrintShutterSpeed | +listavailable | +
| SetShutterSpeed | +shutterspeed | +
| PrintIso | +listavailable | +
| SetIso | +iso | +
| PrintExposureCompensation | +listavailable | +
| SetExposureCompensation | +exposurecompensation | +
| PrintMeteringMode | +listavailable | +
| SetMeteringMode | +meteringmode | +
| WB/Picture Controls | +|
| PrintWhiteBalance | +listavailable | +
| SetWhiteBalance | +whitebalance | +
| Stills Operation | +|
| TakePhoto | +autofocus | +
| PrintStillImageQuality | +listavailable | +
| SetStillImageQuality | +rawquality, jpegquality | +
| Movie Operation | +|
| PrintMovieMode | ++ |
| EnterMovieMode | ++ |
| ExitMovieMode | ++ |
| PrintMovieQuality | +listavailable | +
| SetMovieQuality | +moviequality | +
| StartMovieRecord | ++ |
| StopMovieRecord | ++ |
| AF/Drive Mode | +|
| PrintDriveMode | +listavailable | +
| SetDriveMode | +drivemode | +
| PrintAfOperation | ++ |
| PrintAfMethod | +listavailable | +
| SetAfMethod | +afmethod | +
| File Operations | +|
| WaitForNewFilesOnCamera | +maxwaittime | +
| GetInfoOnNewFilesPolled | ++ |
| DownloadNewFilesPolled | +outputdir, ifexists | +
| DownloadFileByUrl | +url, outputdir, ifexists | +
| Non-Camera Operations | +|
| RunExecutable | +executable, waitforcompletion, exitonlauncherr, appendlastdownloadstoargs, outputfile, writemode, assertexitcode. Arguments to executable specified on separate line via RunExecutableArgs |
+
| ExitApp | +exitcode | +
| Delay | +delaytime | +
| WaitForEnterKeyToContinue | +beep | +
| Beep | ++ |
| PrintMessageToLog | +message | +
| Misc. / Utility | +|
| SyncDateTime | +skewsecs | +
| AssertCameraSettings | +modedial, moviemode, afoperation | +
| GetPendingEvents | +printevents | +
| DisconnectWireless | ++ |
| PrintAPI | ++ |
| GetInfoByUrl | +url | +
The following table lists parameters available to all operations. When specified on a Group the parameters will be inherited by all operations the group contains - the children can still override their inherited parameters by specifying the parameter for the operation.
+| Parameter | +Description | +
| repeatcount | +Number of times operation is repeated before moving on to next operation. Default is 1 | +
| delayafter | +Amount of time to delay after completing operation before the next operation is performed. Can be specified as a value in seconds or in hh:mm:ss or mm:ss form. Default is 0 | +
| timeout | +Overrides --timeout command line parameter for this operation. | +
| downloadtimeout | +Overrides --downloadtimeout command line parameter for this operation. | +
| transportretries | +Overrides --transportretries command line parameter for this operation. | +
| cmdretries | +Overrides --cmdretries command line parameter for this operation. | +
| retrydelay | +Overrides --retrydelay command line parameter for this operation. | +
| maxbusyretrytime | +Overrides --maxbusyretrytime command line parameter for this operation. | +
| exitoncmderr | +Overrides --exitoncmderr command line parameter for this operation. | +
<To Do>
+All argument names are case sensitive but the optional values for each argument are case-insensitive. For example "--logginglevel" must be under-case but the actual value specified can be any case.
+You can abbreviate any argument name by using just enough characters to uniquely distinguish it from other argument names. For example, --ip in place of --ipaddress.
+--help
+ Prints a help display listing all the typical options supported. You can also obtain help by invoking Canomate with no arguments
!filename
+ Load additional arguments from a text file. In addition to any parameter files you specify, Canomate will always load a file named 'canomate-defaultopts' from the same directory Canomate is in. The parameters from the default file will be loaded first, allowing you to override them with parameters from your own files and those specified on the command line. All parameter files must be formatted so that each parameter word is on a separate line, which is a requirement of Python's argparse routine. For example:
--ipaddress + 192.168.1.155 + --opfile + takephotos.txt ++
--ipaddress address (no default - required parameter)
+Specifies the IP address of the camera. You can get this address by going to the "Wireless Communication settings" in the camera's menu and going to "Camera Control API", "Wi-Fi settings", "Camera Control API". The URL at the bottom of the screen includes the IP address of the camera
--port port (default = 8080)
+ The CCAPI port the camera is configured to. The default value is 8080, which is the default Canon uses.
--opfile <filename>
+ Path/filename of the automation script. Ops can alternatively be specified directly on the command line via --op.
--op <op | op | ...>
+ As an alternative to using an automation script via --optfile you can enter operations directly on the command line. This is useful for simple operations. You can specify multiple operations by separating each with a | character. It's recommended to enclose the entire list in double quotes, for example: --op "PrintCameraInfo | Delay time=5"
--outputdir <directory> (default = current directory)
+The directory to store downloaded images and movies. By default the current directory will be used. The directory specified with this option can be overridden on a per-automation op basis via outputdir=<path> parameter to the op.
--ifexists [uniquename | skip | overwrite | prompt | exit] (default = uniquename)
+ Specifies what operation to take if a local file exists in the output directory matching a file to be downloaded. The default 'uniquename' will cause a unique filename to be generated by adding -new-x suffix (for example, DSC_1575.cr3 becomes DSC_1575-new-1.cr3, DSC_1575-new-2.cr3, etc...). 'skip' will cause the file to be skipped and not downloaded. 'overwrite' will overwrite the local file with the downloaded file. 'prompt' will present a choice of operations to take on the console (uniquename/skip/overwrite/prompt/exit). 'exit' will cause the application to terminate whenever an existing file with the same name as a download candidate is found.
--exitoncmderr [yes | no] (default = yes)
+ Specifies whether the automation script is stopped whenever the Camera returns an error for an attempted operation. There are two broad types of errors in communication with the camera - transport and command. A transport error means the HTTP request failed to be delivered to the camera. The most common type of transport error is a Timeout, which can occur if the camera is turned off or has its CCAPI feature disabled. Transport errors are retried a user-configured number of times but if those retries are exhausted the script unconditionally terminates. In contrast, a command error occurs when the request was successfully delivered to the camera but the camera reported the request could not be completed. An example is attempting a StartMovieRecord when the camera is in stills mode or attempting to set the shutter speed while the camera is in Aperture-Priority mode. This option specifies whether the script is terminated if all the command error retries have been exhausted. This parameter can be override on a per-op basis in the automation script.
--timeout <time value> (default is 5)
+Specifies the timeout for all CCAPI requests to the camera except for downloads, which is specified via --downloadtimeout. <time value> can be either a value in seconds or a time code in hh:mm:ss or mm:ss format. For example, 5:30 to set a timeout of 5 minutes and 30 seconds. This parameter can be override on a per-op basis in the automation script.
--downloadtimeout <time value> (default is 0, for no timeout)
+Specifies the timeout for CCAPI requests to the camera corresponding to the download of images or movie files. <time value> can be either a value in seconds or a time code in hh:mm:ss or mm:ss format. This parameter can be override on a per-op basis in the automation script.
--transportretries <retry count> (default = 2)
+ Specifies the number of retries performed after a CCAPI transport error, such as a timeout. If all retries are exhausted the automation script will be terminated. This parameter can be override on a per-op basis in the automation script.
--cmdretries <retry count> (default = 2)
+ Specifies the number of retries performed after a CCAPI command error, which is an error that occurs when the camera successfully received a request but indicated it was invalid or could not be completed. If all retries are exhausted the automation script will be terminated based on the --exitoncmderr setting. This parameter can be override on a per-op basis in the automation script.
--retrydelay <time value> (default = 0, no delay)
+Specifies the amount of time to delay before retrying a transport or command error. <time value> can be either a value in seconds or a time code in hh:mm:ss or mm:ss format. This parameter can be override on a per-op basis in the automation script.
--maxbusyretrytime <time value> (default = 10 seconds)
+Specifies the amount of time a request is retried that fails with a "busy or "preparing" command error status from the camera, both of which indicate a temporary unavailability condition. This is a special case of command error handling that runs in parallel to the regular command error handling managed by --cmdretries. The purpose is to allow the recovery of temporary busy conditions without having to increase the normal command error retry counts. This parameter can be override on a per-op basis in the automation script.
--logginglevel [normal | verbose | debug] (default = normal)
+ The verbosity level of logging for an Canomate session. Canomate outputs its messages both to the console (stdout/stderr) and to a pair of logging files, named canomate-log-last.txt (log messages from most recent session) and canomate-log-lifetime.txt (log messages from all sessions). 'normal' indicates that only important/useful informational messages will be logged. 'verbose' includes some additional messages, useful for instance when you'd like more information about why a particular file was not downloaded. 'debug' will include all developer-level messages and debug information.
Canomate - Automation for Canon Cameras + Copyright (C) 2020, Horshack + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see <http://www.gnu.org/licenses/>. ++