This guide documents how to configure pyOCD.
pyOCD allows you to control many aspects of its behaviour by setting session options. There are multiple ways to set these options.
- Many of the most commonly used session options have dedicated command line arguments.
- Options can be placed in a YAML config file.
- Arbitrary options can be set individually with the -Ooption=value command line argument.
- If you are using the Python API, see the session options developer documentation for information about using session options.
The priorities of the different session option sources, from highest to lowest:
- Dedicated command-line arguments.
- Probe-specific options from a config file.
- Global options from a config file.
- Changes to an option’s default value. Used only in rare cases for certain subcommands.
- The option’s default value.
The full set of session options is documented in the Session options list reference.
To help pyOCD automatically find configuration files and other resources, it has the concept of the project directory.
When pyOCD looks for files such as the config file or a user script, it first expands ‘~’ references to the home directory. Then it checks whether the filename is absolute, and if so, it uses the filename as-is. Otherwise, it looks for the file in the project directory.
By default, the project directory is simply the working directory where you ran the
You can change the project directory to another location with the
--dir command line
arguments. This can be helpful if you are running pyOCD from another tool or application. The project
directory can also be set using the
PYOCD_PROJECT_DIR environment variable. Command line arguments
have precedence over the environment variable.
pyOCD supports a YAML configuration file that lets you set session options that either apply to all probes or to a single probe, based on the probe’s unique ID.
The easiest way to use a config file is to place a
pyocd.yaml file in the project directory.
.yml extension and
optional dot prefix on the config file name are allowed. Alternatively, you can use the
--config command line option, for instance
--config=myconfig.yaml. Finally, you can set the
config_file option. If there is a need to prevent reading a config file, use the
The top level of the YAML file is a dictionary. The keys in the top-level dictionary must be names
of session options, or the key
probes. Session options are set to the value corresponding to the
dictionary entry. Unrecognized option names are ignored.
If there is a top-level
probes key, its value must be a dictionary with keys that match a
substring of debug probe unique IDs. Usually you would just use the complete unique ID shown by
listing connected boards (i.e.,
pyocd list). The values for the unique ID entries are
dictionaries containing session options, just like the top level of the YAML file. Of course, these
options are only applied when connecting with the given probe. If the probe unique ID
substring listed in the config file matches more than one probe, the corresponding options
will be applied to all matching probes.
Options set in the config file will override any options set via the command line.
Example config file:
probes: 066EFF555051897267233656: # Probe's unique ID. target_override: stm32l475xg test_binary: stm32l475vg_iot01a.bin # Global options auto_unlock: false frequency: 8000000 # Set 8 MHz SWD default for all probes