The latest development version of this page may be more current than this released 1.14.0 version.

West and Extension APIs

This page documents the Python APIs provided by west, as well as some additional APIs used by the west extensions in the zephyr repository.

Contents:

West

This section contains documentation for west’s APIs.

Warning

These APIs should be considered unstable until west version 1.0. Further, until west #38 is closed, these modules can only be imported from extension command files (and within west itself, of course).

west.commands

This package provides WestCommand, which is the common abstraction all west commands subclass.

All built-in west commands are implemented as modules in this package. This package also provides support for extension commands.

class west.commands.WestCommand(name, help, description, accepts_unknown_args=False)

Abstract superclass for a west command.

All top-level commands supported by west implement this interface.

add_parser(parser_adder)

Registers a parser for this command, and returns it.

The parser object is stored in the parser attribute of this WestCommand.

Parameters:parser_adder – The return value of a call to argparse.ArgumentParser.add_subparsers()

do_add_parser(parser_adder)

Subclass method for registering command line arguments.

This is called by WestCommand.add_parser() to do the work of adding the parser itself.

The subclass should call parser_adder.add_parser() to add an ArgumentParser for that subcommand, then add any arguments. The final parser must be returned.

Parameters:parser_adder – The return value of a call to argparse.ArgumentParser.add_subparsers()

do_run(args, unknown)

Subclasses must implement; called when the command is run.

Parameters:

• args – is the namespace of parsed known arguments.
• unknown – If accepts_unknown_args was False when constructing this object, this parameter is an empty sequence. Otherwise, it is an iterable containing all unknown arguments present on the command line.

run(args, unknown)

Run the command.

This raises CommandContextError if the command cannot be run due to a context mismatch. Other exceptions may be raised as well.

Parameters:

• args – known arguments parsed via add_parser().
• unknown – unknown arguments present on the command line; this must be empty if the constructor was passed accepts_unknown_args=False.

exception west.commands.CommandError(returncode=1)

Indicates that a command failed. The return code attribute specifies the error code to return to the system.

exception west.commands.CommandContextError(returncode=1)

Indicates that a context-dependent command could not be run.

Subclass of CommandError.

exception west.commands.ExtensionCommandError(**kwargs)

Exception class indicating an extension command was badly defined and could not be created.

Subclass of CommandError.

west.configuration

West configuration file handling.

class west.configuration.ConfigFile

Enum representing the possible types of configuration file.

• SYSTEM: the system-wide file shared by all users
• GLOBAL: the “global” or user-wide file
• LOCAL: the per-installation file
• ALL: all three of the above, where applicable

west.configuration.read_config(config_file=<ConfigFile.ALL: 0>, config=<configparser.ConfigParser object>)

Reads all configuration files, making the configuration values available as a configparser.ConfigParser object in config.config. This object works similarly to a dictionary: config.config[‘foo’][‘bar’] gets the value for key ‘bar’ in section ‘foo’.

If config_file is given, then read only that particular file, file can be either ‘ConfigFile.LOCAL’, ‘ConfigFile.GLOBAL’, or ‘ConfigFile.SYSTEM’.

If config object is provided, then configuration values will be copied to there instead of the module global ‘config’ variable.

Git conventions for configuration file locations are used. See the FILES section in the git-config(1) man page.

The following configuration files are read.

System-wide:

• Linux: /etc/westconfig
• macOS: /usr/local/etc/westconfig
• Windows: %PROGRAMDATA%\west\config

“Global” or user-wide:

• Linux: ~/.westconfig or $XDG_CONFIG_HOME/west/config
• macOS: ~/.westconfig
• Windows: .westconfig in the user’s home directory, as determined by os.path.expanduser.

Local (per-installation)

• Linux, macOS, Windows: path/to/installation/.west/config

Configuration values from later configuration files override configuration from earlier ones. Local values have highest precedence, and system values lowest.

west.configuration.update_config(section, key, value, configfile=<ConfigFile.LOCAL: 'config'>)

Sets ‘key’ to ‘value’ in the given config ‘section’, creating the section if it does not exist.

The destination file to write is given by ‘configfile’.

west.log

Provides common methods for logging messages to display to the user.

west.log.set_verbosity(value)

Set the logging verbosity level.

Parameters:value – verbosity level to set, e.g. VERBOSE_VERY.

west.log.VERBOSE_NONE = 0

Default verbosity level, no dbg() messages printed.

west.log.VERBOSE_NORMAL = 1

Some verbose messages printed.

west.log.VERBOSE_VERY = 2

Very verbose output messages will be printed.

west.log.VERBOSE_EXTREME = 3

Extremely verbose output messages will be printed.

west.log.dbg(*args, level=1)

Print a verbose debug logging message.

Parameters:

• args – sequence of arguments to print.
• value – verbosity level to set, e.g. VERBOSE_VERY.

The message is only printed if level is at least the current verbosity level.

west.log.inf(*args, colorize=False)

Print an informational message.

Parameters:

• args – sequence of arguments to print.
• colorize – If this is True, the configuration option color.ui is undefined or true, and stdout is a terminal, then the message is printed in green.

west.log.wrn(*args)

Print a warning.

Parameters:args – sequence of arguments to print.

The message is prefixed with “WARNING: “.

If this is True, the configuration option color.ui is undefined or true, and stdout is a terminal, then the message is printed in yellow.

west.log.err(*args, fatal=False)

Print an error.

This function does not abort the program. For that, use die().

Parameters:

• args – sequence of arguments to print.
• fatal – if True, the the message is prefixed with “FATAL ERROR: “; otherwise, “ERROR: ” is used.

If this is True, the configuration option color.ui is undefined or true, and stdout is a terminal, then the message is printed in red.

west.log.die(*args, exit_code=1)

Print a fatal error, and abort the program.

Parameters:

• args – sequence of arguments to print.
• exit_code – return code the program should use when aborting.

Equivalent to die(*args, fatal=True), followed by an attempt to abort.

west.manifest

Parser and abstract data types for west manifests.

The main class is Manifest. The recommended method for creating a Manifest instance is via its from_file() or from_data() helper methods.

There are additionally Defaults, Remote, and Project types defined, which represent the values by the same names in a west manifest. (I.e. “Remote” represents one of the elements in the “remote” sequence in the manifest, and so on.) Some Default values, such as the default project revision, may be supplied by this module if they are not present in the manifest data.

west.manifest.manifest_path()

Return the path to the manifest file.

Raises WestNotFound if called from outside of a west working directory.

class west.manifest.Manifest(source_file=None, source_data=None, sections=['manifest', 'west'])

Represents the contents of a West manifest file.

The most convenient way to construct an instance is using the from_file and from_data helper methods.

as_frozen_dict()

Returns an OrderedDict representing this manifest, frozen.

The manifest is ‘frozen’ in that all Git revisions in the original data are replaced with the corresponding SHAs.

Note that this requires that all projects are checked out.

defaults = None

west.manifest.Defaults object representing default values in the manifest, either as specified by the user or west itself.

static from_data(source_data, sections=['manifest', 'west'])

Create and return a new Manifest object given parsed YAML data.

Parameters:

• source_data – Parsed YAML data as a Python object.
• sections – Only parse specified sections from YAML data, default: all sections are parsed.

Raises MalformedManifest in case of validation errors. Raises MalformedConfig in case of missing configuration settings.

static from_file(source_file=None, sections=['manifest', 'west'])

Create and return a new Manifest object given a source YAML file.

Parameters:

• source_file – Path to a YAML file containing the manifest.
• sections – Only parse specified sections from YAML file, default: all sections are parsed.

If source_file is None, the value returned by manifest_path() is used.

Raises MalformedManifest in case of validation errors. Raises MalformedConfig in case of missing configuration settings.

get_remote(name)

Get a manifest Remote, given its name.

path = None

Path to the file containing the manifest, or None if created from data rather than the file system.

projects = None

Sequence of west.manifest.Project objects representing manifest projects.

Each element’s values are fully initialized; there is no need to consult the defaults field to supply missing values.

Note: The index MANIFEST_PROJECT_INDEX in sequence will hold the project which contains the project manifest file.

remotes = None

Sequence of west.manifest.Remote objects representing manifest remotes.

west_project = None

west.manifest.SpecialProject object representing the west meta project.

class west.manifest.Defaults(remote=None, revision=None)

Represents default values in a manifest, either specified by the user or by west itself.

Defaults are neither comparable nor hashable.

as_dict()

Return a representation of this object as a dict, as it would be parsed from an equivalent YAML manifest.

remote

Remote corresponding to the default remote, or None.

revision

Revision to applied to projects without an explicit value.

class west.manifest.Remote(name, url_base)

Represents a remote defined in a west manifest.

Remotes may be compared for equality, but are not hashable.

as_dict()

Return a representation of this object as a dict, as it would be parsed from an equivalent YAML manifest.

name

Remote name as it appears in the manifest.

url_base

Remote url-base value as it appears in the manifest.

class west.manifest.Project(name, remote, defaults, path=None, clone_depth=None, revision=None, west_commands=None)

Represents a project defined in a west manifest.

Projects are neither comparable nor hashable.

abspath

Absolute path to the project.

as_dict()

Return a representation of this object as a dict, as it would be parsed from an equivalent YAML manifest.

clone_depth

Project’s clone depth, or None

format(s, *args, **kwargs)

Calls s.format() with instance-related format keys.

The formatted value is returned.

Parameters:s – string (or other object) whose format() method to call

The format method is called with *args and the following kwargs:

• this object’s __slots__ / values (name, url, etc.)
• name_and_path: “self.name + (self.path)”
• remote_name: “None” if no remote, otherwise self.remote.name
• any additional kwargs passed as parameters

The kwargs passed as parameters override the other values.

git(cmd, extra_args=(), capture_stdout=False, check=True, cwd=None)

Helper for running a git command using metadata from a Project instance.

Parameters:

• cmd – git command as a string (or list of strings); all strings are formatted using self.format() before use.
• extra_args – sequence of additional arguments to pass to the git command (useful mostly if cmd is a string).
• capture_stdout – True if stdout should be captured into the returned object instead of being printed. The stderr output is never captured, to prevent error messages from being eaten.
• check – True if a subprocess.CalledProcessError should be raised if the git command finishes with a non-zero return code.
• cwd – directory to run command in (default: self.abspath)

Returns a CompletedProcess (which is back-ported for Python 3.4).

is_ancestor_of(rev1, rev2)

Check if ‘rev1’ is an ancestor of ‘rev2’ in this project.

Parameters:

• rev1 – commit that could be the ancestor
• rev2 – commit that could be a descendant

Returns True if rev1 is an ancestor commit of rev2 in the given project; rev1 and rev2 can be anything that resolves to a commit. (If rev1 and rev2 refer to the same commit, the return value is True, i.e. a commit is considered an ancestor of itself.) Returns False otherwise.

is_up_to_date()

Returns is_up_to_date_with(self.revision).

is_up_to_date_with(rev)

Check if a project is up to date with revision ‘rev’.

Parameters:rev – base revision to check if project is up to date with.

Returns True if all commits in ‘rev’ are also in HEAD. This can be used to check if this project needs updates, rebasing, etc.; ‘rev’ can be anything that resolves to a commit.

This is a special case of is_ancestor_of() provided for convenience.

name

Project name as it appears in the manifest.

path

Relative path to the project in the installation.

posixpath

Absolute path to the project, POSIX style (with forward slashes).

remote

Remote instance corresponding to the project’s remote.

revision

Revision to check out for this project, as given in the manifest, from manifest defaults, or from the default supplied by west.

sha(rev)

Returns the SHA of the given revision in the current project.

Parameters:rev – git revision (HEAD, v2.0.0, etc.) as a string

url

Complete fetch URL for the project.

west_commands

Path to project’s “west-commands”, or None.

class west.manifest.SpecialProject(name, path=None, revision='(not set)', url='(not set)', west_commands=None)

Represents a special project, e.g. the west or manifest project.

Projects are neither comparable nor hashable.

as_dict()

Return a representation of this object as a dict, as it would be parsed from an equivalent YAML manifest.

exception west.manifest.MalformedManifest

Exception indicating that west manifest parsing failed due to a malformed value.

exception west.manifest.MalformedConfig

Exception indicating that west config is malformed and thus causing west manifest parsing to fail.

west.manifest.MANIFEST_SECTIONS = ['manifest', 'west']

Sections in the manifest file

west.manifest.MANIFEST_PROJECT_INDEX = 0

Index in projects where the project with contains project manifest file is located

west.manifest.MANIFEST_REV_BRANCH = 'manifest-rev'

The name of the branch that points to the revision specified in the manifest

west.manifest.QUAL_MANIFEST_REV_BRANCH = 'refs/heads/manifest-rev'

A qualified reference to MANIFEST_REV_BRANCH, i.e. refs/heads/manifest-rev.

west.util

Miscellaneous utilities used by west

west.util.west_dir(start=None)

Returns the absolute path of the west/ top level directory.

Starts the search from the start directory, and goes to its parents. If the start directory is not specified, the current directory is used.

Raises WestNotFound if no west top-level directory is found.

west.util.west_topdir(start=None, fall_back=True)

Like west_dir(), but returns the path to the parent directory of the .west/ directory instead, where project repositories are stored

exception west.util.WestNotFound

Neither the current directory nor any parent has a West installation.

Zephyr Extensions

This section contains documentation for APIs used by the extension commands which are part of the Zephyr repository. In particular, it documents the runners.core module used by the Building, Flashing and Debugging commands. This is the core abstraction used to implement support for these features.

Warning

These APIs are provided for reference, but they are more “shared code” used to implement multiple extension commands than a stable API.

Zephyr binary runner core interfaces

This provides the core ZephyrBinaryRunner class meant for public use, as well as some other helpers for concrete runner classes.

class runners.core.BuildConfiguration(build_dir)

This helper class provides access to build-time configuration.

Configuration options can be read as if the object were a dict, either object[‘CONFIG_FOO’] or object.get(‘CONFIG_FOO’).

Configuration values in .config and generated_dts_board.conf are available.

class runners.core.NetworkPortHelper

Helper class for dealing with local IP network ports.

get_unused_ports(starting_from)

Find unused network ports, starting at given values.

starting_from is an iterable of ports the caller would like to use.

The return value is an iterable of ports, in the same order, using the given values if they were unused, or the next sequentially available unused port otherwise.

Ports may be bound between this call’s check and actual usage, so callers still need to handle errors involving returned ports.

class runners.core.RunnerCaps(commands={'debugserver', 'debug', 'flash', 'attach'}, flash_addr=False)

This class represents a runner class’s capabilities.

Each capability is represented as an attribute with the same name. Flag attributes are True or False.

Available capabilities:

• commands: set of supported commands; default is {‘flash’, ‘debug’, ‘debugserver’, ‘attach’}.
• flash_addr: whether the runner supports flashing to an arbitrary address. Default is False. If true, the runner must honor the –dt-flash option.

class runners.core.RunnerConfig(build_dir, board_dir, elf_file, hex_file, bin_file, gdb=None, openocd=None, openocd_search=None)

Runner execution-time configuration.

This is a common object shared by all runners. Individual runners can register specific configuration options using their do_add_parser() hooks.

This class’s __slots__ contains exactly the configuration variables.

bin_file

Path to the bin file that the runner should operate on

board_dir

Zephyr board directory

build_dir

Zephyr application build directory

elf_file

Path to the elf file that the runner should operate on

gdb

‘Path to GDB compatible with the target, may be None.

hex_file

Path to the hex file that the runner should operate on

openocd

Path to OpenOCD to use for this target, may be None.

openocd_search

directory to add to OpenOCD search path, may be None.

class runners.core.ZephyrBinaryRunner(cfg)

Abstract superclass for binary runners (flashers, debuggers).

Note: these APIs are still evolving, and will change!

With some exceptions, boards supported by Zephyr must provide generic means to be flashed (have a Zephyr firmware binary permanently installed on the device for running) and debugged (have a breakpoint debugger and program loader on a host workstation attached to a running target).

This is supported by three top-level commands managed by the Zephyr build system:

• ‘flash’: flash a previously configured binary to the board, start execution on the target, then return.
• ‘debug’: connect to the board via a debugging protocol, program the flash, then drop the user into a debugger interface with symbol tables loaded from the current binary, and block until it exits.
• ‘debugserver’: connect via a board-specific debugging protocol, then reset and halt the target. Ensure the user is now able to connect to a debug server with symbol tables loaded from the binary.
• ‘attach’: connect to the board via a debugging protocol, then drop the user into a debugger interface with symbol tables loaded from the current binary, and block until it exits. Unlike ‘debug’, this command does not program the flash.

This class provides an API for these commands. Every runner has a name (like ‘pyocd’), and declares commands it can handle (like ‘flash’). Zephyr boards (like ‘nrf52_pca10040’) declare compatible runner(s) by name to the build system, which makes concrete runner instances to execute commands via this class.

If your board can use an existing runner, all you have to do is give its name to the build system. How to do that is out of the scope of this documentation, but use the existing boards as a starting point.

If you want to define and use your own runner:

1. Define a ZephyrBinaryRunner subclass, and implement its abstract methods. You may need to override capabilities().
2. Make sure the Python module defining your runner class is imported, e.g. by editing this package’s __init__.py (otherwise, get_runners() won’t work).
3. Give your runner’s name to the Zephyr build system in your board’s build files.

For command-line invocation from the Zephyr build system, runners define their own argparse-based interface through the common add_parser() (and runner-specific do_add_parser() it delegates to), and provide a way to create instances of themselves from a RunnerConfig and parsed runner-specific arguments via create().

Runners use a variety of target-specific tools and configuration values, the user interface to which is abstracted by this class. Each runner subclass should take any values it needs to execute one of these commands in its constructor. The actual command execution is handled in the run() method.

classmethod add_parser(parser)

Adds a sub-command parser for this runner.

The given object, parser, is a sub-command parser from the argparse module. For more details, refer to the documentation for argparse.ArgumentParser.add_subparsers().

The lone common optional argument is:

• –dt-flash (if the runner capabilities includes flash_addr)

Runner-specific options are added through the do_add_parser() hook.

call(cmd)

Subclass subprocess.call() wrapper.

Subclasses should use this method to run command in a subprocess and get its return code, rather than using subprocess directly, to keep accurate debug logs.

classmethod capabilities()

Returns a RunnerCaps representing this runner’s capabilities.

This implementation returns the default capabilities.

Subclasses should override appropriately if needed.

check_call(cmd)

Subclass subprocess.check_call() wrapper.

Subclasses should use this method to run command in a subprocess and check that it executed correctly, rather than using subprocess directly, to keep accurate debug logs.

check_output(cmd)

Subclass subprocess.check_output() wrapper.

Subclasses should use this method to run command in a subprocess and check that it executed correctly, rather than using subprocess directly, to keep accurate debug logs.

classmethod create(cfg, args)

Create an instance from command-line arguments.

• cfg: RunnerConfig instance (pass to superclass __init__)
• args: runner-specific argument namespace parsed from execution environment, as specified by add_parser().

classmethod do_add_parser(parser)

Hook for adding runner-specific options.

do_run(command, **kwargs)

Concrete runner; run() delegates to this. Implement in subclasses.

In case of an unsupported command, raise a ValueError.

classmethod get_flash_address(args, build_conf, default=0)

Helper method for extracting a flash address.

If args.dt_flash is true, get the address from the BoardConfiguration, build_conf. (If CONFIG_HAS_FLASH_LOAD_OFFSET is n in that configuration, it returns CONFIG_FLASH_BASE_ADDRESS. Otherwise, it returns CONFIG_FLASH_BASE_ADDRESS + CONFIG_FLASH_LOAD_OFFSET.)

Otherwise (when args.dt_flash is False), the default value is returned.

static get_runners()

Get a list of all currently defined runner classes.

classmethod name()

Return this runner’s user-visible name.

When choosing a name, pick something short and lowercase, based on the name of the tool (like openocd, jlink, etc.) or the target architecture/board (like xtensa, em-starterkit, etc.).

popen_ignore_int(cmd)

Spawn a child command, ensuring it ignores SIGINT.

The returned subprocess.Popen object must be manually terminated.

run(command, **kwargs)

Runs command (‘flash’, ‘debug’, ‘debugserver’, ‘attach’).

This is the main entry point to this runner.

run_server_and_client(server, client)

Run a server that ignores SIGINT, and a client that handles it.

This routine portably:

• creates a Popen object for the server command which ignores SIGINT
• runs client in a subprocess while temporarily ignoring SIGINT
• cleans up the server after the client exits.

It’s useful to e.g. open a GDB server and client.