API Reference#

A Python wrapper for tycmd.

Functions#

tycmd.list_boards()#

List the available boards.

Includes boards in bootloader mode. See Board for the details reported.

Returns:

Available boards.

Return type:

list[Board]

Raises:

TycmdError – If tycmd fails.

Examples

Get the serial numbers of all available boards:

>>> [board['serial'] for board in tycmd.list_boards()]
['3576040', '14014980']
tycmd.upload(filename, *, serial=None, port=None, check=True, reset=True, rtc='local', log_level=logging.INFO)#

Upload firmware to a board.

Unless check is False, tycmd first checks that the firmware is compatible with the board. It then reboots the board into its bootloader if needed, uploads the firmware and, unless reset is False, resets the board to start it. Without serial and port, the first board detected is used.

Parameters:

  • filename (PathLike | str) – Path to the firmware file.

  • serial (str | None, default: None) – Serial number of the board.

  • port (str | None, default: None) – Port of the board.

  • check (bool, default: True) – Check that the firmware is compatible with the board.

  • reset (bool, default: True) – Reset the board after the upload.

  • rtc (Literal['local', 'utc', 'none'], default: 'local') – Set the board’s real-time clock, if it has one: ‘local’, ‘utc’ or ‘none’.

  • log_level (int, default: logging.INFO) – Log level for tycmd’s status messages, logging.NOTSET to disable. Warnings are always logged as such.

Raises:
Return type:

None

Warning

If the board can’t be rebooted into its bootloader, tycmd waits until the board’s button is pressed. This is logged as a warning.

Examples

Upload to the board on a specific port:

>>> tycmd.upload('blink.hex', port='/dev/ttyACM0')

Upload to the board with a specific serial number, without resetting it:

>>> tycmd.upload('blink.hex', serial='14014980', reset=False)
tycmd.reset(*, serial=None, port=None, bootloader=False, log_level=logging.INFO)#

Reset a board.

A running board is first rebooted into its bootloader, then reset to start its firmware. With bootloader, it is only rebooted into its bootloader. Without serial and port, the first board detected is used.

Parameters:

  • serial (str | None, default: None) – Serial number of the board.

  • port (str | None, default: None) – Port of the board.

  • bootloader (bool, default: False) – Reboot into the bootloader instead.

  • log_level (int, default: logging.INFO) – Log level for tycmd’s status messages, logging.NOTSET to disable. Warnings are always logged as such.

Raises:

TycmdError – If tycmd fails.

Return type:

None

Examples

Restart the firmware of the board with a specific serial number:

>>> tycmd.reset(serial='14014980')

Reboot it into its bootloader instead:

>>> tycmd.reset(serial='14014980', bootloader=True)
tycmd.identify(filename)#

Identify the board models compatible with a firmware file.

Only the file is inspected - no board needs to be connected.

Parameters:

filename (PathLike | str) – Path to the firmware file.

Returns:

Names of the compatible models, empty if there are none.

Return type:

list[str]

Raises:

  • FileNotFoundError – If the firmware file does not exist.

  • IsADirectoryError – If the firmware path is a directory.

  • ValueError – If the firmware file has an unsupported extension or can’t be loaded, or if tycmd’s output can’t be parsed (e.g. if the filename contains ").

  • TycmdError – If tycmd fails.

Examples

List the models a firmware file is compatible with:

>>> tycmd.identify('blink.hex')
['Teensy 4.0', 'Teensy 4.0 (beta 1)']
tycmd.version()#

Return the version of the bundled tycmd binary.

Returns:

Version of tycmd, e.g. '0.9.9'.

Return type:

str

Raises:

Examples

Check the version of the bundled tycmd binary:

>>> tycmd.version()
'0.9.9'

Exceptions#

exception tycmd.TycmdError#

Bases: CalledProcessError

Raised when tycmd exits with an error.

classmethod __new__(*args, **kwargs)#
__init__(returncode, cmd, output=None, stderr=None)#

Types#

class tycmd.Board#

Bases: TypedDict

A board as reported by tycmd.

action: Literal['add', 'change', 'miss', 'remove']#

Event that produced this entry.

tag: str#

Tag of the board, e.g. '12345678-Teensy'.

serial: str | None#

Serial number, or None if not reported.

description: str | None#

USB description, or None if not reported.

model: str#

Model name, e.g. 'Teensy 4.1'.

location: str#

USB location, e.g. 'usb-3-2'.

capabilities: list[Literal['unique', 'run', 'upload', 'reset', 'rtc', 'reboot', 'serial']]#

Capabilities of the board.

interfaces: list[list[str]]#

Interfaces as [name, path] pairs, e.g. ['Serial', '/dev/ttyACM0'].

tycmd.Capability#

Something a board can do or be:

  • 'unique': the serial number tells this board apart from others

  • 'run': the board is running firmware

  • 'upload': the board is in bootloader mode and accepts firmware uploads

  • 'reset': the board is in bootloader mode and can be reset to start its firmware

  • 'rtc': the board’s real-time clock can be set when resetting after an upload

  • 'reboot': the running board can be rebooted into its bootloader

  • 'serial': the board has a serial interface

alias of Literal[‘unique’, ‘run’, ‘upload’, ‘reset’, ‘rtc’, ‘reboot’, ‘serial’]

tycmd.BoardAction#

Event that produced a board entry.

alias of Literal[‘add’, ‘change’, ‘miss’, ‘remove’]

tycmd.RtcMode#

How to set the board’s real-time clock on upload.

alias of Literal[‘local’, ‘utc’, ‘none’]