pydgilib package

Submodules

pydgilib.dgilib module

This module provides Python bindings for DGILib.

class pydgilib.dgilib.DGILib(*args, **kwargs)

Bases: object

Python bindings for DGILib.

DGILib is a Dynamic-Link Library (DLL) to help software applications communicate with Data Gateway Interface (DGI) devices. See the Data Gateway Interface user guide for further details. DGILib handles the low-level USB communication and adds a level of buffering for minimizing the chance of overflows. The library helps parse data streams of high complexity. The timestamp interface is parsed and split into separate buffers for each data source. The power interface is optionally parsed and calibrated using an auxiliary API.

Example

>>> with DGILib() as dgilib:
...     dgilib.get_major_version()
5

__init__.

Parameters

• dgilib_path (str) – Path to dgilib.dll (More info at: https://www.microchip.com/developmenttools/ProductDetailsATPOWERDEBUGGER)

• device_index (int or None) – Index of the device to use, only useful if multiple devices are connected (default is None, will resolve to 0)

• device_sn (str or None) – The serial number of the device to use. Has higher priority than device_index (default is None, will resolve to serial number of device 0)

• verbose (int) – Set to a positive number to print more status messages (default is 0)

Raises

DLLError – TODO: Not documented yet.

__enter__()

For usage in with DGILib() as dgilib: syntax.

__exit__(exc_type, exc_value, traceback)

For usage in with DGILib() as dgilib: syntax.

auxiliary_power_calibration_is_valid()

auxiliary_power_calibration_is_valid.

Checks the status of the stored calibration.

Returns true if the calibration is valid, false otherwise. Unity gain and offset will be used.

bool auxiliary_power_calibration_is_valid(uint32_t power_hndl)

Returns

True if the calibration is valid, False otherwise

Return type

bool

auxiliary_power_copy_data(channel=0, power_type=0, max_count=10000000)

auxiliary_power_copy_data.

Copies parsed power data into the specified buffer. Remember to lock the buffers first. If the count parameter is the same as max_count there is probably more data to be read. Do another read to get the remaining data.

int auxiliary_power_copy_data(uint32_t power_hndl, float* buffer, double* timestamp, size_t* count, size_t max_count, int channel, int type)

copied | | max_count | Maximum number of elements that the buffer can hold | | channel | Power channel for this buffer: A = 0, B = 1 (Power Debugger specific) | | type | Type of power data: Current = 0, Voltage = 1, Range = 2 | +————+————+

Parameters

• channel (int) – Power channel for this buffer: A = 0, B = 1 (defaults to 0)

• power_type (int) – Type of power data: Current = 0, Voltage = 1, Range = 2 (defaults to 0)

• max_count (int) – Maximum number of elements that the buffer can hold (defaults to BUFFER_SIZE)

Returns

Tuple of a list of samples and a list of the timestamps for the samples

Return type

tuple(list(int), list(int))

Raises

DeviceReturnError

auxiliary_power_free_data()

auxiliary_power_free_data.

Clears the power data buffers and allows the power parser to continue.

int auxiliary_power_free_data(uint32_t power_hndl)

Raises

DeviceReturnError

auxiliary_power_get_calibration(length=255)

auxiliary_power_get_calibration.

Gets the raw calibration read from the tool.

int auxiliary_power_get_calibration(uint32_t power_hndl, uint8_t* data, size_t length)

Note: actually returns the number of calibration samples, not an error if non-zero. The length argument is not used.

documentation for number of bytes. | +————+————+

Parameters

length (int) – Number of raw calibration bytes to fetch. See the DGI documentation for number of bytes. (defaults to NUM_CALIBRATION)

Returns

List of the read raw calibration data

Return type

list(int)

Raises

DeviceReturnError

auxiliary_power_get_circuit_type()

auxiliary_power_get_circuit_type.

Gets the type of power circuit.

int auxiliary_power_get_circuit_type(uint32_t power_hndl, int* circuit)

OLD_XAM = 0x00, XAM = 0x10, PAM = 0x11, UNKNOWN = 0xFF | +————+————+

Returns

The circuit type: OLD_XAM = 0x00, XAM = 0x10, PAM = 0x11, UNKNOWN = 0xFF

Return type

int

Raises

DeviceReturnError

auxiliary_power_get_status()

auxiliary_power_get_status.

Gets the status of the power parser.

Return codes: - IDLE = 0x00 - RUNNING = 0x01 - DONE = 0x02 - CALIBRATING = 0x03 - INIT_FAILED = 0x10 - OVERFLOWED = 0x11 - USB_DISCONNECTED = 0x12 - CALIBRATION_FAILED = 0x20

int auxiliary_power_get_status(uint32_t power_hndl)

Returns

The status of the power parser: - IDLE = 0x00 - RUNNING = 0x01 - DONE = 0x02 - CALIBRATING = 0x03 - INIT_FAILED = 0x10 - OVERFLOWED = 0x11 - USB_DISCONNECTED = 0x12 - CALIBRATION_FAILED = 0x20

Return type

int

auxiliary_power_initialize()

auxiliary_power_initialize.

Initializes the power parser.

int auxiliary_power_initialize(uint32_t* power_hndl_p, uint32_t dgi_hndl)

the power parser | | dgi_hndl | Handle of the connection | +————+————+

Returns

Handle of the power parser

Return type

c_uint()

Raises

DeviceReturnError

auxiliary_power_lock_data_for_reading()

auxiliary_power_lock_data_for_reading.

Blocks the parsing thread from accessing all the buffers. This must be called before the user application code accesses the buffers, or a call to auxiliary_power_copy_data is made. Afterwards auxiliary_power_free_data must be called. Minimize the amount of time between locking and freeing to avoid buffer overflows.

int auxiliary_power_lock_data_for_reading(uint32_t power_hndl)

Raises

DeviceReturnError

auxiliary_power_register_buffer_pointers(channel=0, power_type=0, max_count=10000000)

auxiliary_power_register_buffer_pointers.

Registers a set of pointers to be used for storing the calibrated power data. The buffers can then be locked by auxiliary_power_lock_data_for_reading, and the data directly read from the specified buffers. Zero-pointers can be specified to get the buffers allocated within DGILib. This requires the data to be fetched using auxiliary_power_copy_data.

int auxiliary_power_register_buffer_pointers(uint32_t power_hndl, float* buffer, double* timestamp, size_t* count, size_t max_count, int channel, int type)

automatically allocated. | | timestamp | Buffer that will hold the timestamp for the samples. Set to 0 for automatically allocated. | | count | Pointer to a variable that will hold the count of samples. Set to 0 for automatically allocated. | | max_count | Number of samples that can fit into the specified buffers. Or size of automatically allocated buffers. | | channel | Power channel for this buffer: A = 0, B = 1 (Power Debugger specific) | | type | Type of power data: Current = 0, Voltage = 1, Range = 2 | +————+————+

Parameters

• channel (int) – Power channel for this buffer: A = 0, B = 1 (defaults to 0)

• power_type (int) – Type of power data: Current = 0, Voltage = 1, Range = 2 (defaults to 0)

• max_count (int) – Number of samples that can fit into the specified buffers (defaults to BUFFER_SIZE)

Raises

DeviceReturnError

auxiliary_power_start(mode=0, parameter=0)

auxiliary_power_start.

Starts parsing of power data. The power and power sync interfaces are enabled automatically, but note that it is necessary to start the polling separately. This only starts the parser that consumes data from the DGILib buffer.

int auxiliary_power_start(uint32_t power_hndl, int mode, int parameter)

consume the data. | | | 1 - oneshot capturing that captures data until the buffer has been read once, has been filled or the time from the first received sample in seconds equals the specified parameter. | | parameter | Mode specific | +————+————+

Parameters

• mode (int) –

  Sets the mode of capture (defaults to 0) - 0: continuous capturing which requires the user to periodically

  consume the data

  • 1: oneshot capturing that captures data until the buffer has

  been read once, has been filled or the time from the first

  received sample in seconds equals the specified parameter

• parameter (int or None) – Mode specific (defaults to 0)

Raises

DeviceReturnError

auxiliary_power_stop()

auxiliary_power_stop.

Stops parsing of power data.

int auxiliary_power_stop(uint32_t power_hndl)

Raises

DeviceReturnError

auxiliary_power_trigger_calibration(circuit_type=16)

auxiliary_power_trigger_calibration.

Triggers a calibration of the specified type. This can take some time, so use auxiliary_power_get_status to check for completion.

`int auxiliary_power_trigger_calibration(uint32_t power_hndl, int type) `

for details. | +————+————+

Parameters

circuit_type (int) – Type of calibration to trigger (defaults to XAM)

Raises

DeviceReturnError

auxiliary_power_uninitialize()

auxiliary_power_uninitialize.

Uninitializes the power parser.

int auxiliary_power_uninitialize(uint32_t power_hndl)

Raises

DeviceReturnError

auxiliary_power_unregister_buffer_pointers(channel=0, power_type=0)

auxiliary_power_unregister_buffer_pointers.

Unregisters the pointers for the specified power channel.

int auxiliary_power_unregister_buffer_pointers(uint32_t power_hndl, int channel, int type)

Debugger specific) | | type | Type of power data: Current = 0, Voltage = 1, Range = 2 | +————+————+

Parameters

• channel (int) – Power channel for this buffer: A = 0, B = 1 (defaults to 0)

• power_type (int) – Type of power data: Current = 0, Voltage = 1, Range = 2 (defaults to 0)

Raises

DeviceReturnError

connect(device_sn)

connect.

Opens a connection to the specified device. This function must be called prior to any function requiring the connection handle.

int connect(char* sn, uint32_t* dgi_hndl_p)

connection to | | dgi_hndl_p | Pointer to a variable that will hold the handle of the connection | +————+————+

Parameters

device_sn (str) – Serial number of the device

Returns

Variable that holds the handle of the connection

Return type

c_uint()

Raises

DeviceReturnError

connection_status()

connection_status.

Verifies that the specified connection is still open.

int connection_status(uint32_t* dgi_hndl)

Returns

A non-zero return value indicates a connection error.

Return type

int

disconnect()

disconnect.

Closes the specified connection.

int disconnect(uint32_t dgi_hndl)

Raises

DeviceReturnError

discover()

discover.

Triggers a scan to find available devices in the system. The result will be immediately available through the get_device_count, get_device_name and get_device_serial functions.

void discover(void)

get_build_number()

get_build_number.

Get the major version of the DGI library.

Returns the build number of DGILib. If not supported, returns 0.

int get_build_number(void)

Returns

The build number of DGILib. If not supported, returns 0.

Return type

int

get_device_count()

get_device_count.

Returns the number of devices detected.

int get_device_count(void)

Returns

The number of devices detected

Return type

int

get_device_name(index=0)

get_device_name.

Gets the name of a detected device.

int get_device_name(int index, char* name)

or more bytes must be allocated | +————+————+

Parameters

index (int) – Index of device ranges from 0 to get_device_count - 1

Returns

The name of a detected device

Return type

str

Raises

DeviceReturnError

get_device_serial(index=0)

get_device_serial.

Gets the serial number of a detected device.

int get_device_serial(int index, char* sn)

be stored. 100 or more bytes must be allocated. This is used when connecting to a device | +————+————+

Parameters

index (int) – Index of device ranges from 0 to get_device_count - 1

Returns

The serial number of a detected device

Return type

str

Raises

DeviceReturnError

get_fw_version()

get_fw_version.

Gets the firmware version of the DGI device connected. Note that this is the version of the DGI device, and not the tool.

int get_fw_version(uint32_t dgi_hndl, unsigned char* major, unsigned char* minor)

stored | | minor | Pointer to a variable where the minor version will be stored | +————+————+

Returns

Version information of the DGI device: - major_fw: the major firmware version of the DGI device connected - minor_fw: the minor firmware version of the DGI device connected

Return type

tuple(int, int)

get_major_version()

get_major_version.

Get the major version of the DGI library.

int get_major_version(void)

Returns

The major version of the DGI library

Return type

int

get_minor_version()

get_minor_version.

Get the minor version of the DGI library.

int get_minor_version(void)

Returns

The minor version of the DGI library

Return type

int

interface_clear_buffer(interface_id)

interface_clear_buffer.

Clears the data in the buffers for the specified interface.

int interface_clear_buffer(uint32_t dgi_hndl, int interface_id)

Parameters

interface_id (int) – The ID of the interface

Raises

DeviceReturnError

interface_disable(interface_id)

interface_disable.

Disables the specified interface.

int interface_disable(uint32_t dgi_hndl, int interface_id)

Parameters

interface_id (int) – The ID of the interface to disable

Raises

DeviceReturnError

interface_enable(interface_id, timestamp=True)

interface_enable.

Enables the specified interface. Note that no data acquisition will begin until a session has been started.

int interface_enable(uint32_t dgi_hndl, int interface_id, bool timestamp)

timestamping. Consult the DGI documentation for details on the timestamping option. | +————+————+

Parameters

• interface_id (int) – The ID of the interface to enable

• timestamp (bool) – Setting this to true will make the interface use timestamping (defaults to True)

Raises

DeviceReturnError

interface_get_configuration(interface_id)

interface_get_configuration.

Gets the configuration associated with the specified interface. Consult the DGI documentation for details.

int interface_get_configuration(uint32_t dgi_hndl, int interface_id, unsigned int* config_id, unsigned int* config_value, unsigned int* config_cnt)

configuration item | | config_value | Buffer that will hold the value field for the configuration item | | config_cnt | Pointer to variable that will hold the count of stored configuration items | +————+————+

Parameters

interface_id (int) – The ID of the interface

Returns

Tuple of a list of configuration IDs and a list of configuration values

Return type

tuple(list(int), list(int))

Raises

DeviceReturnError

interface_list()

interface_list.

Queries the connected DGI device for available interfaces. Refer to the DGI documentation to resolve the ID.

int interface_list(uint32_t dgi_hndl, unsigned char* interfaces, unsigned char* count)

Should be able to hold minimum 10 elements, but a larger count should be used to be future proof. | | count | Pointer to a variable that will be set to the number of interfaces registered in buffer. | +————+————+

Returns

List of available interfaces

Return type

list(int)

Raises

DeviceReturnError

interface_read_data(interface_id)

interface_read_data.

Reads the data received on the specified interface. This should be called regularly to avoid overflows in the system. DGILib can buffer 10M samples.

int interface_read_data(uint32_t dgi_hndl, int interface_id, unsigned char* buffer, unsigned long long* timestamp, int* length, unsigned int* ovf_index, unsigned int* ovf_length, unsigned int* ovf_entry_count)

have allocated 10M elements. | | timestamp | If timestamp is enabled for the interface, the buffer that will hold the received data. The buffer must have allocated 10M elements. Otherwise send 0. | | length | Pointer to a variable that will hold the count of elements received | | ovf_index | Reserved. Set to 0. | | ovf_length | Reserved. Set to 0. | | ovf_entry_count | Reserved. Set to 0. Could be set to a pointer to a variable that can be used as an indicator of overflows. Overflow would be indicated by non-zero value. | +————+————+

Parameters

interface_id (int) – The ID of the interface

Returns

Tuple of a list of received values and a list of ticks

Return type

tuple(list(int), list(int))

Raises

DeviceReturnError

interface_set_configuration(interface_id, config_id, config_value)

interface_set_configuration.

Sets the given configuration fields for the specified interface. Consult the DGI documentation for details.

int interface_set_configuration(uint32_t dgi_hndl, int interface_id, unsigned int* config_id, unsigned int* config_value, unsigned int config_cnt)

items to set | | config_value | Buffer that holds the value field for the configuration items to set | | config_cnt | Number of items to set | +————+————+

Parameters

• interface_id (int) – The ID of the interface

• config_id (list(int)) – List that holds the ID field for the configuration items to set

• config_value – List that holds the value field for the configuration items to set (must have the same number of elements

as config_id) :type config_value: list(int) :raises: DeviceArgumentError :raises: DeviceReturnError

interface_write_data(interface_id, buffer)

interface_write_data.

Writes data to the specified interface. A maximum of 255 elements can be written each time. An error return code will be given if data hasn’t been written yet.

TODO: A non-zero return value indicates an error. An error will be returned if the interface is still in the process of writing data. Wait a while and try again. The function get_connection_status can be used to verify if there is an error condition.

int interface_write_data(uint32_t dgi_hndl, int interface_id, unsigned char* buffer, int* length)

allocated 10M elements | | length | Pointer to a variable that will hold the count of elements received | +————+————+

Parameters

• interface_id (int) – The ID of the interface

• buffer (int) – Buffer that holds the data to write (defaults to None)

Raises

DeviceReturnError

is_msd_mode(device_sn)

is_msd_mode.

EDBG devices can be set to a mass storage mode where the DGI is unavailable. In such cases the device is still detected by DGILib, but it won’t be possible to directly connect to it. This command is used to check if the device is in such a mode.

A non-zero return value indicates that the mode must be changed by set_mode before proceeding.

int is_msd_mode(char* sn)

Parameters

device_sn (str or None) – Serial number of the device to check (defaults to self.device_sn)

Returns

A non-zero return value indicates that the mode must be changed by set_mode before proceeding.

Return type

int

set_mode(device_sn, nmbed=1)

set_mode.

This function is used to temporarily set the EDBG to a specified mode.

int set_mode(char* sn, int nmbed)

Parameters

• device_sn (str) – Serial number of the device to set

• nmbed (int) – 0 - Set to mbed mode. 1 - Set to DGI mode (defaults to DGI mode)

Raises

DeviceReturnError

start_polling()

start_polling.

This function will start the polling system and start acquisition on enabled interfaces. It is possible to enable/disable interfaces both before and after the polling has been started. However, no data will be transferred until the polling is started.

int start_polling(uint32_t dgi_hndl)

Parameters

dgi_hndl (c_uint()) – Handle of the connection

Raises

DeviceReturnError

stop_polling()

stop_polling.

This function will stop the polling system and stop acquisition on all interfaces.

int stop_polling(uint32_t dgi_hndl)

Parameters

dgi_hndl (c_uint()) – Handle of the connection

Raises

DeviceReturnError

target_reset(hold_reset)

target_reset.

This function is used to control the state of the reset line connected to the target, if available.

int target_reset(uint32_t dgi_hndl, bool hold_reset)

Parameters

hold_reset (bool) – True will assert reset, False will release it

Raises

DeviceReturnError

pydgilib.dgilib_auxiliary module

This module provides Python bindings for the Auxiliary API of DGILib.

class pydgilib.dgilib_auxiliary.DGILibAuxiliary

Bases: object

Python bindings for DGILib Auxiliary.

DGILib is a Dynamic-Link Library (DLL) to help software applications communicate with Data Gateway Interface (DGI) devices. See the Data Gateway Interface user guide for further details. DGILib handles the low-level USB communication and adds a level of buffering for minimizing the chance of overflows. The library helps parse data streams of high complexity. The timestamp interface is parsed and split into separate buffers for each data source. The power interface is optionally parsed and calibrated using an auxiliary API.

Power The power interface (as found on some EDBG kits and Power Debugger) uses a protocol stream and calibration scheme that can be tricky to get right. The data rates are also relatively high and the calibration procedure could cause issues if not handled efficiently. Therefore some auxiliary functions to help with this have been made to perform parsing and calibration.

auxiliary_power_calibration_is_valid()

auxiliary_power_calibration_is_valid.

Checks the status of the stored calibration.

Returns true if the calibration is valid, false otherwise. Unity gain and offset will be used.

bool auxiliary_power_calibration_is_valid(uint32_t power_hndl)

Returns

True if the calibration is valid, False otherwise

Return type

bool

auxiliary_power_copy_data(channel=0, power_type=0, max_count=10000000)

auxiliary_power_copy_data.

Copies parsed power data into the specified buffer. Remember to lock the buffers first. If the count parameter is the same as max_count there is probably more data to be read. Do another read to get the remaining data.

int auxiliary_power_copy_data(uint32_t power_hndl, float* buffer, double* timestamp, size_t* count, size_t max_count, int channel, int type)

copied | | max_count | Maximum number of elements that the buffer can hold | | channel | Power channel for this buffer: A = 0, B = 1 (Power Debugger specific) | | type | Type of power data: Current = 0, Voltage = 1, Range = 2 | +————+————+

Parameters

• channel (int) – Power channel for this buffer: A = 0, B = 1 (defaults to 0)

• power_type (int) – Type of power data: Current = 0, Voltage = 1, Range = 2 (defaults to 0)

• max_count (int) – Maximum number of elements that the buffer can hold (defaults to BUFFER_SIZE)

Returns

Tuple of a list of samples and a list of the timestamps for the samples

Return type

tuple(list(int), list(int))

Raises

DeviceReturnError

auxiliary_power_free_data()

auxiliary_power_free_data.

Clears the power data buffers and allows the power parser to continue.

int auxiliary_power_free_data(uint32_t power_hndl)

Raises

DeviceReturnError

auxiliary_power_get_calibration(length=255)

auxiliary_power_get_calibration.

Gets the raw calibration read from the tool.

int auxiliary_power_get_calibration(uint32_t power_hndl, uint8_t* data, size_t length)

Note: actually returns the number of calibration samples, not an error if non-zero. The length argument is not used.

documentation for number of bytes. | +————+————+

Parameters

length (int) – Number of raw calibration bytes to fetch. See the DGI documentation for number of bytes. (defaults to NUM_CALIBRATION)

Returns

List of the read raw calibration data

Return type

list(int)

Raises

DeviceReturnError

auxiliary_power_get_circuit_type()

auxiliary_power_get_circuit_type.

Gets the type of power circuit.

int auxiliary_power_get_circuit_type(uint32_t power_hndl, int* circuit)

OLD_XAM = 0x00, XAM = 0x10, PAM = 0x11, UNKNOWN = 0xFF | +————+————+

Returns

The circuit type: OLD_XAM = 0x00, XAM = 0x10, PAM = 0x11, UNKNOWN = 0xFF

Return type

int

Raises

DeviceReturnError

auxiliary_power_get_status()

auxiliary_power_get_status.

Gets the status of the power parser.

Return codes: - IDLE = 0x00 - RUNNING = 0x01 - DONE = 0x02 - CALIBRATING = 0x03 - INIT_FAILED = 0x10 - OVERFLOWED = 0x11 - USB_DISCONNECTED = 0x12 - CALIBRATION_FAILED = 0x20

int auxiliary_power_get_status(uint32_t power_hndl)

Returns

The status of the power parser: - IDLE = 0x00 - RUNNING = 0x01 - DONE = 0x02 - CALIBRATING = 0x03 - INIT_FAILED = 0x10 - OVERFLOWED = 0x11 - USB_DISCONNECTED = 0x12 - CALIBRATION_FAILED = 0x20

Return type

int

auxiliary_power_initialize()

auxiliary_power_initialize.

Initializes the power parser.

int auxiliary_power_initialize(uint32_t* power_hndl_p, uint32_t dgi_hndl)

the power parser | | dgi_hndl | Handle of the connection | +————+————+

Returns

Handle of the power parser

Return type

c_uint()

Raises

DeviceReturnError

auxiliary_power_lock_data_for_reading()

auxiliary_power_lock_data_for_reading.

Blocks the parsing thread from accessing all the buffers. This must be called before the user application code accesses the buffers, or a call to auxiliary_power_copy_data is made. Afterwards auxiliary_power_free_data must be called. Minimize the amount of time between locking and freeing to avoid buffer overflows.

int auxiliary_power_lock_data_for_reading(uint32_t power_hndl)

Raises

DeviceReturnError

auxiliary_power_register_buffer_pointers(channel=0, power_type=0, max_count=10000000)

auxiliary_power_register_buffer_pointers.

Registers a set of pointers to be used for storing the calibrated power data. The buffers can then be locked by auxiliary_power_lock_data_for_reading, and the data directly read from the specified buffers. Zero-pointers can be specified to get the buffers allocated within DGILib. This requires the data to be fetched using auxiliary_power_copy_data.

int auxiliary_power_register_buffer_pointers(uint32_t power_hndl, float* buffer, double* timestamp, size_t* count, size_t max_count, int channel, int type)

automatically allocated. | | timestamp | Buffer that will hold the timestamp for the samples. Set to 0 for automatically allocated. | | count | Pointer to a variable that will hold the count of samples. Set to 0 for automatically allocated. | | max_count | Number of samples that can fit into the specified buffers. Or size of automatically allocated buffers. | | channel | Power channel for this buffer: A = 0, B = 1 (Power Debugger specific) | | type | Type of power data: Current = 0, Voltage = 1, Range = 2 | +————+————+

Parameters

• channel (int) – Power channel for this buffer: A = 0, B = 1 (defaults to 0)

• power_type (int) – Type of power data: Current = 0, Voltage = 1, Range = 2 (defaults to 0)

• max_count (int) – Number of samples that can fit into the specified buffers (defaults to BUFFER_SIZE)

Raises

DeviceReturnError

auxiliary_power_start(mode=0, parameter=0)

auxiliary_power_start.

Starts parsing of power data. The power and power sync interfaces are enabled automatically, but note that it is necessary to start the polling separately. This only starts the parser that consumes data from the DGILib buffer.

int auxiliary_power_start(uint32_t power_hndl, int mode, int parameter)

consume the data. | | | 1 - oneshot capturing that captures data until the buffer has been read once, has been filled or the time from the first received sample in seconds equals the specified parameter. | | parameter | Mode specific | +————+————+

Parameters

• mode (int) –

  Sets the mode of capture (defaults to 0) - 0: continuous capturing which requires the user to periodically

  consume the data

  • 1: oneshot capturing that captures data until the buffer has

  been read once, has been filled or the time from the first

  received sample in seconds equals the specified parameter

• parameter (int or None) – Mode specific (defaults to 0)

Raises

DeviceReturnError

auxiliary_power_stop()

auxiliary_power_stop.

Stops parsing of power data.

int auxiliary_power_stop(uint32_t power_hndl)

Raises

DeviceReturnError

auxiliary_power_trigger_calibration(circuit_type=16)

auxiliary_power_trigger_calibration.

Triggers a calibration of the specified type. This can take some time, so use auxiliary_power_get_status to check for completion.

`int auxiliary_power_trigger_calibration(uint32_t power_hndl, int type) `

for details. | +————+————+

Parameters

circuit_type (int) – Type of calibration to trigger (defaults to XAM)

Raises

DeviceReturnError

auxiliary_power_uninitialize()

auxiliary_power_uninitialize.

Uninitializes the power parser.

int auxiliary_power_uninitialize(uint32_t power_hndl)

Raises

DeviceReturnError

auxiliary_power_unregister_buffer_pointers(channel=0, power_type=0)

auxiliary_power_unregister_buffer_pointers.

Unregisters the pointers for the specified power channel.

int auxiliary_power_unregister_buffer_pointers(uint32_t power_hndl, int channel, int type)

Debugger specific) | | type | Type of power data: Current = 0, Voltage = 1, Range = 2 | +————+————+

Parameters

• channel (int) – Power channel for this buffer: A = 0, B = 1 (defaults to 0)

• power_type (int) – Type of power data: Current = 0, Voltage = 1, Range = 2 (defaults to 0)

Raises

DeviceReturnError

dgi_hndl = None

dgilib = None

power_hndl = None

verbose = None

pydgilib.dgilib_config module

pydgilib.dgilib_discovery module

This module provides Python bindings for the Discovery API of DGILib.

class pydgilib.dgilib_discovery.DGILibDiscovery

Bases: object

Python bindings for DGILib Discovery.

DGILib is a Dynamic-Link Library (DLL) to help software applications communicate with Data Gateway Interface (DGI) devices. See the Data Gateway Interface user guide for further details. DGILib handles the low-level USB communication and adds a level of buffering for minimizing the chance of overflows.

TODO? 2.1.1. initialize_status_change_notification Initializes the system necessary for using the status change notification callback mechanisms. A handle will be created to keep track of the registered callbacks. This function must always be called before registering and unregistering notification callbacks. Function definition void initialize_status_change_notification(uint32_t* handlep) Parameters handlep Pointer to a variable that will hold the handle 2.1.2. uninitialize_status_change_notification Uninitializes the status change notification callback mechanisms. This function must be called when shutting down to clean up memory allocations. Function definition void uninitialize_status_change_notification(uint32_t handle) Parameters handle Handle to uninitialize 2.1.3. register_for_device_status_change_notifications Registers provided function pointer with the device status change mechanism. Whenever there is a change (device connected or disconnected) the callback will be executed. Note that it is not allowed to connect to a device in the context of the callback function. The callback function has the following definition: typedef void (DeviceStatusChangedCallBack)(char device_name, char* device_serial, BOOL connected) Function definition void register_for_device_status_change_notifications(uint32_t handle, DeviceStatusChangedCallBack deviceStatusChangedCallBack) Parameters handle Handle to change notification mechanisms deviceStatusChangedCallBack Function pointer that will be called when the devices change 2.1.4. unregister_for_device_status_change_notifications Unregisters previously registered function pointer from the device status change mechanism. Function definition void unregister_for_device_status_change_notifications(uint32_t handle, DeviceStatusChangedCallBack deviceStatusChangedCallBack) Parameters handle Handle to change notification mechanisms deviceStatusChangedCallBack Function pointer that will be removed

dgilib = None

discover()

discover.

Triggers a scan to find available devices in the system. The result will be immediately available through the get_device_count, get_device_name and get_device_serial functions.

void discover(void)

get_device_count()

get_device_count.

Returns the number of devices detected.

int get_device_count(void)

Returns

The number of devices detected

Return type

int

get_device_name(index=0)

get_device_name.

Gets the name of a detected device.

int get_device_name(int index, char* name)

or more bytes must be allocated | +————+————+

Parameters

index (int) – Index of device ranges from 0 to get_device_count - 1

Returns

The name of a detected device

Return type

str

Raises

DeviceReturnError

get_device_serial(index=0)

get_device_serial.

Gets the serial number of a detected device.

int get_device_serial(int index, char* sn)

be stored. 100 or more bytes must be allocated. This is used when connecting to a device | +————+————+

Parameters

index (int) – Index of device ranges from 0 to get_device_count - 1

Returns

The serial number of a detected device

Return type

str

Raises

DeviceReturnError

is_msd_mode(device_sn)

is_msd_mode.

EDBG devices can be set to a mass storage mode where the DGI is unavailable. In such cases the device is still detected by DGILib, but it won’t be possible to directly connect to it. This command is used to check if the device is in such a mode.

A non-zero return value indicates that the mode must be changed by set_mode before proceeding.

int is_msd_mode(char* sn)

Parameters

device_sn (str or None) – Serial number of the device to check (defaults to self.device_sn)

Returns

A non-zero return value indicates that the mode must be changed by set_mode before proceeding.

Return type

int

set_mode(device_sn, nmbed=1)

set_mode.

This function is used to temporarily set the EDBG to a specified mode.

int set_mode(char* sn, int nmbed)

Parameters

• device_sn (str) – Serial number of the device to set

• nmbed (int) – 0 - Set to mbed mode. 1 - Set to DGI mode (defaults to DGI mode)

Raises

DeviceReturnError

verbose = None

pydgilib.dgilib_exceptions module

Custom Exceptions for DGILib.

exception pydgilib.dgilib_exceptions.DLLError(msg)

Bases: pydgilib.dgilib_exceptions.Error

Exception raised opening dgilib.dll.

dgilib.dll could not be found in the specified path.

__init__.

exception pydgilib.dgilib_exceptions.DeviceArgumentError(msg)

Bases: pydgilib.dgilib_exceptions.Error

Exception raised parsing arguments.

__init__.

exception pydgilib.dgilib_exceptions.DeviceConnectionError(msg)

Bases: pydgilib.dgilib_exceptions.Error

Exception raised: Could not connect to the device.

__init__.

exception pydgilib.dgilib_exceptions.DeviceIndexError(msg)

Bases: pydgilib.dgilib_exceptions.Error

Exception raised selecting device.

The device_index exceeds the device_count.

__init__.

exception pydgilib.dgilib_exceptions.DeviceReturnError(msg)

Bases: pydgilib.dgilib_exceptions.Error

Exception raised: DGILib returned non-zero value.

__init__.

exception pydgilib.dgilib_exceptions.Error(msg)

Bases: Exception

Base class for exceptions in this module.

Parameters

msg (str) – Error message associated with the exception

Variables

msg – Error message associated with the exception

__init__.

__str__()

__str__.

pydgilib.dgilib_housekeeping module

This module provides Python bindings for the Housekeeping API of DGILib.

class pydgilib.dgilib_housekeeping.DGILibHousekeeping

Bases: object

Python bindings for DGILib Housekeeping.

DGILib is a Dynamic-Link Library (DLL) to help software applications communicate with Data Gateway Interface (DGI) devices. See the Data Gateway Interface user guide for further details. DGILib handles the low-level USB communication and adds a level of buffering for minimizing the chance of overflows. The library helps parse data streams of high complexity.

connect(device_sn)

connect.

Opens a connection to the specified device. This function must be called prior to any function requiring the connection handle.

int connect(char* sn, uint32_t* dgi_hndl_p)

connection to | | dgi_hndl_p | Pointer to a variable that will hold the handle of the connection | +————+————+

Parameters

device_sn (str) – Serial number of the device

Returns

Variable that holds the handle of the connection

Return type

c_uint()

Raises

DeviceReturnError

connection_status()

connection_status.

Verifies that the specified connection is still open.

int connection_status(uint32_t* dgi_hndl)

Returns

A non-zero return value indicates a connection error.

Return type

int

dgi_hndl = None

dgilib = None

disconnect()

disconnect.

Closes the specified connection.

int disconnect(uint32_t dgi_hndl)

Raises

DeviceReturnError

get_build_number()

get_build_number.

Get the major version of the DGI library.

Returns the build number of DGILib. If not supported, returns 0.

int get_build_number(void)

Returns

The build number of DGILib. If not supported, returns 0.

Return type

int

get_fw_version()

get_fw_version.

Gets the firmware version of the DGI device connected. Note that this is the version of the DGI device, and not the tool.

int get_fw_version(uint32_t dgi_hndl, unsigned char* major, unsigned char* minor)

stored | | minor | Pointer to a variable where the minor version will be stored | +————+————+

Returns

Version information of the DGI device: - major_fw: the major firmware version of the DGI device connected - minor_fw: the minor firmware version of the DGI device connected

Return type

tuple(int, int)

get_major_version()

get_major_version.

Get the major version of the DGI library.

int get_major_version(void)

Returns

The major version of the DGI library

Return type

int

get_minor_version()

get_minor_version.

Get the minor version of the DGI library.

int get_minor_version(void)

Returns

The minor version of the DGI library

Return type

int

start_polling()

start_polling.

This function will start the polling system and start acquisition on enabled interfaces. It is possible to enable/disable interfaces both before and after the polling has been started. However, no data will be transferred until the polling is started.

int start_polling(uint32_t dgi_hndl)

Parameters

dgi_hndl (c_uint()) – Handle of the connection

Raises

DeviceReturnError

stop_polling()

stop_polling.

This function will stop the polling system and stop acquisition on all interfaces.

int stop_polling(uint32_t dgi_hndl)

Parameters

dgi_hndl (c_uint()) – Handle of the connection

Raises

DeviceReturnError

target_reset(hold_reset)

target_reset.

This function is used to control the state of the reset line connected to the target, if available.

int target_reset(uint32_t dgi_hndl, bool hold_reset)

Parameters

hold_reset (bool) – True will assert reset, False will release it

Raises

DeviceReturnError

verbose = None

pydgilib.dgilib_interface_communication module

This module provides Python bindings for the Interface Communication API of DGILib.

class pydgilib.dgilib_interface_communication.DGILibInterfaceCommunication

Bases: object

Python bindings for DGILib Interface Communication.

DGILib is a Dynamic-Link Library (DLL) to help software applications communicate with Data Gateway Interface (DGI) devices. See the Data Gateway Interface user guide for further details. DGILib handles the low-level USB communication and adds a level of buffering for minimizing the chance of overflows. The library helps parse data streams of high complexity. The timestamp interface is parsed and split into separate buffers for each data source.

dgi_hndl = None

dgilib = None

interface_clear_buffer(interface_id)

interface_clear_buffer.

Clears the data in the buffers for the specified interface.

int interface_clear_buffer(uint32_t dgi_hndl, int interface_id)

Parameters

interface_id (int) – The ID of the interface

Raises

DeviceReturnError

interface_disable(interface_id)

interface_disable.

Disables the specified interface.

int interface_disable(uint32_t dgi_hndl, int interface_id)

Parameters

interface_id (int) – The ID of the interface to disable

Raises

DeviceReturnError

interface_enable(interface_id, timestamp=True)

interface_enable.

Enables the specified interface. Note that no data acquisition will begin until a session has been started.

int interface_enable(uint32_t dgi_hndl, int interface_id, bool timestamp)

timestamping. Consult the DGI documentation for details on the timestamping option. | +————+————+

Parameters

• interface_id (int) – The ID of the interface to enable

• timestamp (bool) – Setting this to true will make the interface use timestamping (defaults to True)

Raises

DeviceReturnError

interface_get_configuration(interface_id)

interface_get_configuration.

Gets the configuration associated with the specified interface. Consult the DGI documentation for details.

int interface_get_configuration(uint32_t dgi_hndl, int interface_id, unsigned int* config_id, unsigned int* config_value, unsigned int* config_cnt)

configuration item | | config_value | Buffer that will hold the value field for the configuration item | | config_cnt | Pointer to variable that will hold the count of stored configuration items | +————+————+

Parameters

interface_id (int) – The ID of the interface

Returns

Tuple of a list of configuration IDs and a list of configuration values

Return type

tuple(list(int), list(int))

Raises

DeviceReturnError

interface_list()

interface_list.

Queries the connected DGI device for available interfaces. Refer to the DGI documentation to resolve the ID.

int interface_list(uint32_t dgi_hndl, unsigned char* interfaces, unsigned char* count)

Should be able to hold minimum 10 elements, but a larger count should be used to be future proof. | | count | Pointer to a variable that will be set to the number of interfaces registered in buffer. | +————+————+

Returns

List of available interfaces

Return type

list(int)

Raises

DeviceReturnError

interface_read_data(interface_id)

interface_read_data.

Reads the data received on the specified interface. This should be called regularly to avoid overflows in the system. DGILib can buffer 10M samples.

int interface_read_data(uint32_t dgi_hndl, int interface_id, unsigned char* buffer, unsigned long long* timestamp, int* length, unsigned int* ovf_index, unsigned int* ovf_length, unsigned int* ovf_entry_count)

have allocated 10M elements. | | timestamp | If timestamp is enabled for the interface, the buffer that will hold the received data. The buffer must have allocated 10M elements. Otherwise send 0. | | length | Pointer to a variable that will hold the count of elements received | | ovf_index | Reserved. Set to 0. | | ovf_length | Reserved. Set to 0. | | ovf_entry_count | Reserved. Set to 0. Could be set to a pointer to a variable that can be used as an indicator of overflows. Overflow would be indicated by non-zero value. | +————+————+

Parameters

interface_id (int) – The ID of the interface

Returns

Tuple of a list of received values and a list of ticks

Return type

tuple(list(int), list(int))

Raises

DeviceReturnError

interface_set_configuration(interface_id, config_id, config_value)

interface_set_configuration.

Sets the given configuration fields for the specified interface. Consult the DGI documentation for details.

int interface_set_configuration(uint32_t dgi_hndl, int interface_id, unsigned int* config_id, unsigned int* config_value, unsigned int config_cnt)

items to set | | config_value | Buffer that holds the value field for the configuration items to set | | config_cnt | Number of items to set | +————+————+

Parameters

• interface_id (int) – The ID of the interface

• config_id (list(int)) – List that holds the ID field for the configuration items to set

• config_value – List that holds the value field for the configuration items to set (must have the same number of elements

as config_id) :type config_value: list(int) :raises: DeviceArgumentError :raises: DeviceReturnError

interface_write_data(interface_id, buffer)

interface_write_data.

Writes data to the specified interface. A maximum of 255 elements can be written each time. An error return code will be given if data hasn’t been written yet.

TODO: A non-zero return value indicates an error. An error will be returned if the interface is still in the process of writing data. Wait a while and try again. The function get_connection_status can be used to verify if there is an error condition.

int interface_write_data(uint32_t dgi_hndl, int interface_id, unsigned char* buffer, int* length)

allocated 10M elements | | length | Pointer to a variable that will hold the count of elements received | +————+————+

Parameters

• interface_id (int) – The ID of the interface

• buffer (int) – Buffer that holds the data to write (defaults to None)

Raises

DeviceReturnError

verbose = None

Module contents

This module provides Python bindings for DGILib.