pykitcommander package¶

Kit manager¶

Kit state management functions

class pykitcommander.kitmanager.CellularKitLeds¶

Bases: KitLeds

Definition of LED names on Cellular IoT kits

CONNECTION_LED = 'CONN'¶

DATA_LED = 'DATA'¶

ERROR_LED = 'ERR'¶

USER_LED = 'USER'¶

WIRELESS_LED = 'CELL'¶

class pykitcommander.kitmanager.CellularMiniKitLeds¶

Bases: KitLeds

Definition of LED names on Cellular Mini IoT kits

CONNECTION_LED = 'CONN'¶

DATA_LED = 'DATA'¶

ERROR_LED = 'ERROR'¶

USER_LED = 'USER'¶

WIRELESS_LED = 'CELL'¶

class pykitcommander.kitmanager.KitApplicationFirmwareProvider(kitname, hexfile_path=INSTALLDIR)¶

Bases: object

Finds applications based on required functionality, device/board and ‘cloud provider’.

Looks in:

bundled folders
internal server / artifact repo (todo)
external server / github (todo)

Parameters:

kitname (str) – Name of kit being used
hexfile_path (str, optional) – Path to hexfile to use

locate_firmware(firmware_identifier)¶

Looks up and returns firmware for a given identifier

Parameters:: firmware_identifier (str) – Unique ID of firmware
Returns:: Dictionary containing information about the firmware image
Return type:: dict

class pykitcommander.kitmanager.KitLeds¶

Bases: object

Base class for LED name definitions on IoT kits

CONNECTION_LED = None¶

DATA_LED = None¶

ERROR_LED = None¶

USER_LED = None¶

WIRELESS_LED = None¶

class pykitcommander.kitmanager.KitProgrammer(serialnumber=None)¶

Bases: object

Programming applications onto kits

Parameters:: serialnumber (str, optional) – Serial number of kit/programmer to connect to

erase()¶: Erases the target

get_kit_info()¶: Retrieves kit info dict

program_application(hexfile, strategy='cached')¶

Programs an application into the kit

Parameters:

hexfile (str) – Path to hex file to program
strategy (str) – Use caching, or other special mode

reboot()¶: Reboots the debugger

reset_target()¶: Resets the target

class pykitcommander.kitmanager.TrustplatformKitLeds¶

Bases: KitLeds

Definition of LED names on CryptoAuth Trust Platform kits

ERROR_LED = 'STATUS'¶

class pykitcommander.kitmanager.WifiKitLeds¶

Bases: KitLeds

Definition of LED names on WIFI IoT kits

CONNECTION_LED = 'CONN'¶

DATA_LED = 'DATA'¶

ERROR_LED = 'ERROR'¶

WIRELESS_LED = 'WIFI'¶

pykitcommander.kitmanager.get_supported_kits()¶: Simple accessor of supported kits (and variants thereof)

Kit protocols¶

Helper functions for setting up simple applications

pykitcommander.kitprotocols.get_iot_provision_protocol(skip_programming=False, serialnumber=None)¶: Back compatibility API - render “not supported” message.

pykitcommander.kitprotocols.get_protocol(protocol_name, skip_programming=False, serialnumber=None)¶: Back compatibility API - render “not supported” message.

pykitcommander.kitprotocols.setup_kit(function, skip_programming=False, serialnumber=None, programmer=None)¶

Sets up a kit for communication

Parameters:

function (str) – Requested function of the kit
skip_programming (boolean) – Set to true to not program the kit
serialnumber (str) – Serial number of kit to connect to
programmer (object (KitProgrammer)) – Optional programmer object to use

Firmware interface¶

A collection of firmware Serial-port-based communication drivers

Python-side clients that need to request services from firmware running on an embedded device use these drivers to send commands and receive responses over a standard serial port.

Good practise is to follow this kind of pattern, which ensures port closure after use:

# Open a serial connection with given attributes
with Serial(port, baud, timeout, stopbits) as serial_connection:
    # Instantiate a driver to handle communications
    firmware_driver = ProvisioningFirmwareDriver (serial_connection)
    # Send firmware command to turn on LED
    firmware_driver.firmware_command("MC+SETLED", ["conn","on"])

class pykitcommander.firmwareinterface.IoTWxDemoFirmwareDriver(serial_connection)¶

Bases: object

Interface to demo firmware on WiFi boards (AVR-IoT-Wx/PIC-IoT-Wx)

Parameters:: serial_connection (object (Serial)) – Serial-port object to use, must be opened by the caller

demo_firmware_command(cmd, args=[])¶

Send a request to demo FW CLI, return response.

Parameters:

cmd (str) – Command to send
args (list of str) – Argument list

Returns:

response from firmware

Return type:

str

class pykitcommander.firmwareinterface.ProvisioningFirmwareDriver(serial_connection, encoding='UTF-8')¶

Bases: object

Firmware driver for communicating with “version 2” provisioning firmware Commands and responses are strings as described here: - Commands are terminated with r (rn and n are also accepted) - Command syntax: <cmd>=[<arg>[,<arg>…]rn [blob rn]] - Response: [<blob> rn] “OKrn” | “ERROR:”<xxxx>rn - <hex> is hex-encoded blob, <xxxx> 16-bit hex error code

Parameters:

serial_port – Serial-port object to use, must be opened by the caller
encoding (str) – Encoding format to use

MC_STATUS_BAD_ARGUMENT_COUNT = 3¶

MC_STATUS_BAD_ARGUMENT_VALUE = 5¶

MC_STATUS_BAD_BLOB = 4¶

MC_STATUS_BAD_COMMAND = 1¶

MC_STATUS_BUFFER_OVERRUN = 2¶

MC_STATUS_OK = 0¶

STATUS_SOURCE_COMMAND_HANDLER = 0¶

STATUS_SOURCE_CRYPTOAUTHLIB = 1¶

STATUS_SOURCE_WINC = 2¶

firmware_command(command, args=None, payload_blob=None)¶

Send a command to the firmware and receive a response

Parameters:

command (str) – Command string to send to firmware
args (list of str) – Argument list
payload_blob (str) – Binary data to send (normally hex-encoded)

Returns:

Response

Return type:

str

parse_error_code(errorline)¶

Parse a line containing error code The error code will be parsed and a more informative error message will be logged

Parameters:: errorline (str) – String from target containing error code
Returns:: User friendly error message
Return type:: str

read_response()¶

Read response from kit. Response can be multiple lines either terminated with “OKrn”, “ERRORrn”, or ‘>’ so a simple read_until won’t do.

Returns:: Response lines (blank lines and CR-LF stripped)
Return type:: list of str

synchronize()¶: Synchronize with firmware CLI using the ping command and unique sequence number

wait_for_reset()¶: Wait for ‘READY’ prompt to be received after restart of application, indicating firmware is ready to accept commands. This method will time out without raising if READY is not received, meaning target was not reset prior to this command, :return: Welcome banner + “READY” if it was reset, else empty string or garbage.

Programmer¶

Programming related functions, using pymcuprog backend API.

class pykitcommander.programmer.Programmer(serialnumber=None)¶

Bases: object

Class to program applications

Parameters:: serialnumber (str) – Serial number of programmer

erase_target_device()¶: Erases target device Useful to clean up after provisioning etc when no application is available.

program_data(data, memory=MemoryNames.FLASH, offset=0, erase=True, verify=False)¶

Program target with memory data, assumed to be a byte array. Returns: True if OK

Parameters:

data (bytearray) – Raw data bytes to program
memory (str) – Memory type to program
offset (int) – First address to program
erase (boolean) – True to erase before programming
verify (boolean) – True to verify after programming

Returns:

True if programming succeeded

Return type:

boolean

program_hexfile(filename, memory=MemoryNames.FLASH, erase=True, verify=False)¶

Program target with hex file. Returns: True if OK

Parameters:

filename – Full path to file to program
memory (str) – Memory type to program
erase (boolean) – True to erase before programming
verify (boolean) – True to verify after programming

Returns:

True if programming succeeded

Return type:

boolean

read_data(memory=MemoryNames.FLASH, offset=0, size=0)¶

Read data from device memory. This function only supports reading a single memory, and returns a single bytearray. size=0 means read the whole memory.

Parameters:

memory (str) – Memory type to read
offset (int) – First address to read
size (int) – Number of bytes to read

reboot()¶: Reboot debugger. Note that for IOT kits, this only reboots the debugger, not the target. Purpose is to invalidate the cache after the click-me file has been updated.

reset_target(delay=0.0)¶

Resets the target device

Parameters:: delay (float, optional, defaults to 0.5s) – Number of seconds to delay after reset

class pykitcommander.programmer.PymcuprogProgrammer(serialnumber=None, dfp_path='.')¶

Bases: Programmer

Class to interface pymcuprog backend.

Parameters:

serialnumber (str) – Serial number of programmer
dfp_path (str) – Path to device family pack (for PIC programming only)

erase_target_device()¶: Erases target device Useful to clean up after provisioning etc when no application is available.

get_usable_kits()¶

Get a list of usable kits. Programming methods below will only work if there is exactly one usable kit in the list.

Returns:: Usable kits connected
Return type:: list of dict

program_data(data, memory=MemoryNames.FLASH, offset=0, erase=True, verify=False)¶

Program target with memory data, assumed to be a byte array.

Parameters:

data (bytearray) – Raw data bytes to program
memory (str) – Memory type to program
offset (int) – First address to program
erase (boolean) – True to erase before programming
verify (boolean) – True to verify after programming

Returns:

True if programming succeeded

Return type:

boolean

program_hexfile(filename, memory=MemoryNames.FLASH, erase=True, verify=False)¶

Program target with hex file.

Parameters:

filename – Full path to file to program
memory (str) – Memory type to program
erase (boolean) – True to erase before programming
verify (boolean) – True to verify after programming

Returns:

True if programming succeeded

Return type:

boolean

read_data(memory=MemoryNames.FLASH, offset=0, size=0)¶

Read data from device memory. This function only supports reading a single memory, and returns a single bytearray. size=0 means read the whole memory.

Parameters:

memory (str) – Memory type to read
offset (int) – First address to read
size (int) – Number of bytes to read

read_kit_info(register)¶

Reads a single kit info register (that is not in the CMSIS-DAP info struct from config)

Parameters:: register (str) – Name of register to read

reboot()¶: Reboot debugger. Note that for IOT kits, this only reboots the debugger, not the target. Purpose is to invalidate the cache after the click-me file has been updated.

reset_target(delay=0.0)¶

Resets the target device

Parameters:: delay (float, optional, defaults to 0.5s) – Number of seconds to delay after reset

Errors¶

Exceptions/Errors that pykitcommander can raise

exception pykitcommander.kitcommandererrors.KitCommunicationError(msg=None)¶

Bases: PykitcommanderError

Error when sending command or receiving response

Parameters:: msg (str) – Error message

exception pykitcommander.kitcommandererrors.KitConnectionError(value, msg=None)¶

Bases: PykitcommanderError

Kit connection failure

Parameters:

value (error dependent) – Additional information (payload)
msg (str) – Error message

exception pykitcommander.kitcommandererrors.KitError(msg=None)¶

Bases: PykitcommanderError

Kit failure

Parameters:: msg (str) – Error message

exception pykitcommander.kitcommandererrors.PortError(msg=None)¶

Bases: PykitcommanderError

Port connection failure

Parameters:: msg (str) – Error message

exception pykitcommander.kitcommandererrors.ProgrammingError(msg=None)¶

Bases: PykitcommanderError

Unable to program the requested application

Parameters:: msg (str) – Error message

exception pykitcommander.kitcommandererrors.PykitcommanderError(msg=None, code=0)¶

Bases: Exception

Base class for all Pykitcommander specific exceptions

Parameters:

msg (str) – Error message
code (int) – Error code

Module contents¶

pykitcommander - Python Kit Commander¶

pykitcommander manages interaction with Microchip development kits based on PKOB nano on-board debugger

In many situations interaction with peripheral hardware components on a development kit is done via a “bridge” application running on the MCU on that kit. To achieve this, the bridge firmware must be programmed onto that MCU, and then communications over a given channel and protocol can logically link the host computer to the peripheral components.

pykitcommander manages some aspects of this interaction by:

Containing a registry of application hex files for various applications on various kits
Programming the application onto the kit
Providing a most-probable serial-port connection string for that kit
Providing an indication of what protocol format is in use on the application
Supporting common protocol framing formats being used

Supported kits are:

AVR-IoT WG and WA
PIC-IoT WG and WA
AVR-IoT Cellular Mini
SAM-IoT WG
CryptoAuth Trust Platform Development Kit

Overview¶

pykitcommander is available:

install using pip from pypi: https://pypi.org/project/pykitcommander
browse source code on github: https://github.com/microchip-pic-avr-tools/pykitcommander
read API documentation on github: https://microchip-pic-avr-tools.github.io/pykitcommander
read the changelog on github: https://github.com/microchip-pic-avr-tools/pykitcommander/blob/main/CHANGELOG.md

Usage example¶

Usage in AVR-IoT and PIC-IoT kits:

from pykitcommander.kitprotocols import setup_kit

# Request iotprovision protocol to be set up on a connected kit
info = setup_kit("iotprovision")

# Create a serial connection to communicate with the firmware
# Note: SerialCDC class wraps pyserial Serial class
from pyedbglib.serialport.serialcdc import SerialCDC
with SerialCDC(info['port'], info['protocol_baud'], timeout=10, stopbits=2) as serial_connection:
    # The firmware driver wraps this serial connection which enables a simple command-response transaction
    # This is defined in pykitcommander
    from pykitcommander.firmwareinterface import ProvisioningFirmwareDriver
    firmware_driver = ProvisioningFirmwareDriver(serial_connection)

    # Send firmware command to turn LED on
    firmware_driver.firmware_command("MC+SETLED", ["conn","on"])

    # Send firmware command to read the ECC serial number
    ecc_serial_number = firmware_driver.firmware_command("MC+ECC+SERIAL")
    print("ECC serial number read out: '{}'".format(ecc_serial_number))

    # Send firmware command to turn LED off
    firmware_driver.firmware_command("MC+SETLED", ["conn","off"])

Notes for Linux® systems¶

This package uses pyedbglib and other libraries for USB transport and some udev rules are required. For details see the pyedbglib package: https://pypi.org/project/pyedbglib

Table of Contents

Previous topic

This Page

pykitcommander package¶

Kit manager¶

Kit protocols¶

Firmware interface¶

Programmer¶

Errors¶

Module contents¶

pykitcommander - Python Kit Commander¶

Overview¶

Usage example¶

Notes for Linux® systems¶