pyedbglib.hidtransport

pyedbglib.hidtransport.cyhidapi

HID transport layer based on Cython and Hidapi

class pyedbglib.hidtransport.cyhidapi.CyHidApiTransport

Bases: HidTransportBase

Implements all Cython / HIDAPI transport methods

detect_devices()

Detect connected CMSIS-DAP devices, populating an internal list

Returns:

number of devices connected

hid_connect(device)

Make a HID connection to the debugger

Parameters:

device – USB device to connect to

hid_disconnect()

Disconnect from HID

hid_info()

Retrieve USB descriptor information

hid_read()

Reads HID data

Returns:

data read

hid_transfer(data_send)

Sends HID data and receives response

Parameters:

data_send –

Returns:

response

hid_write(data_send)

Sends HID data

Parameters:

data_send – data to send

Returns:

number of bytes sent

pyedbglib.hidtransport.hidtransportbase

Base class for all HID transport mechanisms.

class pyedbglib.hidtransport.hidtransportbase.HidTool(vendor_id, product_id, serial_number, product_string='', manufacturer_string='')

Bases: object

Holds transport and DAP properties of a CMSIS-DAP debugger.

Used to select the debugger to use if multiple debuggers are connected.

set_packet_size(packet_size)

Sets the packet size

Parameters:

packet_size – bytes per packet

set_product_string(product_string)

Sets the product string

Parameters:

product_string – product name string

class pyedbglib.hidtransport.hidtransportbase.HidTransportBase

Bases: object

Base class for HID transports

connect(serial_number=None, product=None)

Makes a HID connection to a debugger

Parameters:

• serial_number – instance serial number to connect to

• product – product type to connect to

Returns:

True if successfully connected to a tool, False if not

detect_devices()

Raise error as this method needs to be overridden.

disconnect()

Release the HID connection

get_matching_tools(serial_number_substring='', product=None)

Returns a list of tools matching the given serial_number_substring and product.

Parameters:

• serial_number_substring –

  can be an empty string or a subset of a serial number. Not case sensitive This function will do matching of the last part of the devices serial numbers to the serial_number_substring. Examples:

  • ’123’ will match “MCHP3252000000043123” but not “MCP32520001230000000”

  • ’’ will match any serial number

• product – product type to connect to. If None any tool matching the serial_number_substring will be returned

Returns:

List of matching tools

get_report_size()

Get the packet size in bytes

Returns:

bytes per packet/report

hid_connect(device)

Raise error as this method needs to be overridden.

hid_disconnect()

Raise error as this method needs to be overridden.

hid_info()

Raise error as this method needs to be overridden.

pyedbglib.hidtransport.hidtransportfactory

Factory for HID transport connections.

Currently supports only Cython/HIDAPI

pyedbglib.hidtransport.hidtransportfactory.hid_transport(library='hidapi')

Dispatch a transport layer for the OS in question

The transport layer is typically used to connect to a tool and then it is passed in as a parameter when creating protocol objects. An example where the transport layer is used to create an instance of the housekeepingprotocol for communication with the PKOB nano (nEDBG) debugger:

from pyedbglib.hidtransport.hidtransportfactory import hid_transport
transport = hid_transport()
connect_status = False
try:
    connect_status = transport.connect(serial_number='', product='nedbg')
except IOError as error:
    print("Unable to connect to USB device ({})".format(error))

if not connect_status:
    print("Unable to connect to USB device")

housekeeper = housekeepingprotocol.Jtagice3HousekeepingProtocol(transport)

Parameters:

library (string) – Transport library to use, currently only ‘hidapi’ is supported which will use the libusb hidapi

Returns:

Instance of transport layer object

Return type:

class:cyhidapi:CyHidApiTransport

Raises:

PyedbglibNotSupportedError – if library specified is not supported

pyedbglib.hidtransport.toolinfo

Gathering of all known Microchip CMSIS-DAP debuggers and default EP sizes

pyedbglib.hidtransport.toolinfo.TOOL_SHORTNAME_TO_USB_PRODUCT_STRING = {'atmelice': 'Atmel-ICE', 'edbg': 'EDBG', 'icd4': 'MPLAB ICD 4', 'ice4': 'MPLAB ICE 4', 'jtagice3': 'JTAGICE3', 'medbg': 'mEDBG', 'nedbg': 'nEDBG', 'pickit4': 'MPLAB PICkit 4', 'powerdebugger': 'Power Debugger', 'snap': 'MPLAB Snap'}

Some Atmel/Microchip ‘3G’ tools (EDBG, Atmel-ICE, PowerDebugger) have ‘dual configuration’ HID interfaces. The ‘default’ configuration has a 512-byte HID report size, while the ‘strict’ and ‘minimal’ configurations both have 64-byte report size. The switching mechanism is not implemented in a USB-standard way; it is managed using atprogram.exe (part of Microchip Studio 7) and the configuration is persistent in the tool.

The configuration currently in use can be determined by:

atprogram.exe parameters –get-ep-size

and the configuration can be altered by:

atprogram.exe parameters –set-ep-size [default|strict|minimal]

On Linux and Mac the configuration can be detected using usb.core, see:

def detect_hid_packet_size(product_id, serial_number):

On Windows the configuration is adjusted after connecting, see:

def adjust_hid_packet_size(transport, device):

pyedbglib.hidtransport.toolinfo.adjust_hid_packet_size(transport, device)

Active HIDAPI based HID packet size detection and adjustment

Detecting report size using the descriptor before connecting is not simple on Windows. Instead an active detection is done after connecting by sending a small packet to ask the tool for its frame size. This query frame is small enough to succeed on both 64- and 512-byte variants, and an adjustment can be made after detection since HIDAPI on Windows is tolerant to EP-size mismatches.

Parameters:

• transport – HID transport object, already connected

• device – device currently connected. Size is adjusted before returning

pyedbglib.hidtransport.toolinfo.detect_hid_packet_size(product_id, serial_number)

pyUSB based HID packet size detection

On Linux and Mac the configuration in use can easily be determined by inspecting the descriptor.

Parameters:

• product_id – USB PID to look for

• serial_number – USB serial number to match

Returns:

detected report size, or 0 if no match is found

pyedbglib.hidtransport.toolinfo.get_default_report_size(pid)

Retrieve default EP report size based on known PIDs

Parameters:

pid – product ID

Returns:

packet size

pyedbglib.hidtransport.toolinfo.tool_shortname_to_product_string_name(shortname)

Mapping for common short names of tools to product string name

The intention is that this function is always run on the tool name and that the conversion only happens if the name is a known shortname. If the shortname is not known of if the name provided is already a valid Product string name then the provided shortname parameter will just be returned unchanged. So if the name already is a correct Product string name it is still safe to run this conversion funtion on it.

Parameters:

shortname – shortname typically used by atbackend (powerdebugger, atmelice etc.)

Returns:

String to look for in USB product strings to identify the tool