pyedbglib

Name	pyedbglib JSON
Version	2.24.2.18 JSON
	download
home_page	None
Summary	Low-level protocol library for communicating with Microchip CMSIS-DAP based debuggers
upload_time	2024-03-22 06:39:47
maintainer	None
docs_url	None
author	Microchip Technology
requires_python	>=2.7
license	MIT
keywords	microchip avr edbg protocol
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # pyedbglib - Python EDBG protocol library
pyedbglib is a low-level protocol library for communicating with Microchip CMSIS-DAP based debuggers

![PyPI - Format](https://img.shields.io/pypi/format/pyedbglib)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pyedbglib)
![PyPI - License](https://img.shields.io/pypi/l/pyedbglib)

## Overview
pyedbglib is available:

* install using pip from pypi: https://pypi.org/project/pyedbglib
* browse source code on github: https://github.com/microchip-pic-avr-tools/pyedbglib
* read API documentation on github: https://microchip-pic-avr-tools.github.io/pyedbglib

## Usage
pyedbglib is a library which can be used by Python applications to communicate with Microchip microcontrollers via Microchip CMSIS-DAP based debuggers.

The protocol is documented in the [EDBG communication protocol](https://onlinedocs.microchip.com/pr/GUID-33422CDF-8B41-417C-9C31-E4521ADAE9B4-en-US-2/index.html).

## Supported debuggers
pyedbglib supports:
* PKOB nano (nEDBG) - on-board debugger on Curiosity Nano
* MPLAB PICkit 4 In-Circuit Debugger (when in 'AVR mode')
* MPLAB Snap In-Circuit Debugger (when in 'AVR mode')
* Atmel-ICE
* Power Debugger
* EDBG - on-board debugger on Xplained Pro/Ultra
* mEDBG - on-board debugger on Xplained Mini/Nano
* JTAGICE3 (firmware version 3.0 or newer)

Note: Each debugger may implement a subset of protocols and commands.

## Example
```python
"""
Example usage of pyedbglib to read debugger firmware version and target voltage
"""
from pyedbglib.hidtransport.hidtransportfactory import hid_transport
from pyedbglib.protocols.housekeepingprotocol import Jtagice3HousekeepingProtocol
from pyedbglib import __version__ as pyedbglib_version

# Report library version
print("pyedbglib version {}".format(pyedbglib_version))

# Make a connection using HID transport
transport = hid_transport()
transport.connect()

# Create a housekeeper
housekeeper = Jtagice3HousekeepingProtocol(transport)
housekeeper.start_session()

# Read out debugger firmware version
major = housekeeper.get_byte(Jtagice3HousekeepingProtocol.HOUSEKEEPING_CONTEXT_CONFIG,
                             Jtagice3HousekeepingProtocol.HOUSEKEEPING_CONFIG_FWREV_MAJ)
minor = housekeeper.get_byte(Jtagice3HousekeepingProtocol.HOUSEKEEPING_CONTEXT_CONFIG,
                             Jtagice3HousekeepingProtocol.HOUSEKEEPING_CONFIG_FWREV_MIN)
build = housekeeper.get_le16(Jtagice3HousekeepingProtocol.HOUSEKEEPING_CONTEXT_CONFIG,
                             Jtagice3HousekeepingProtocol.HOUSEKEEPING_CONFIG_BUILD)
print ("Debugger firmware is version {}.{}.{}".format(major, minor,build))

# Read out target voltage
target_voltage = housekeeper.get_le16(Jtagice3HousekeepingProtocol.HOUSEKEEPING_CONTEXT_ANALOG,
                                      Jtagice3HousekeepingProtocol.HOUSEKEEPING_ANALOG_VTREF)
print ("Target voltage is {:.02f}V".format(target_voltage/1000.0))

# Tear down
housekeeper.end_session()
transport.disconnect()
```

## Notes for Linux® systems
HIDAPI needs to build using packages: libusb-1.0.0-dev, libudev-dev

USB devices need udev rules to be added to a file in /etc/udev/rules.d

Example of udev rules for supported debuggers:
```bash
# HIDAPI/libusb:

# JTAGICE3
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2140", MODE="0666"
# Atmel-ICE
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2141", MODE="0666"
# Power Debugger
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2144", MODE="0666"
# EDBG - debugger on Xplained Pro
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2111", MODE="0666"
# EDBG - debugger on Xplained Pro (MSD mode)
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2169", MODE="0666"
# mEDBG - debugger on Xplained Mini
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2145", MODE="0666"
# PKOB nano (nEDBG) - debugger on Curiosity Nano
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2175", MODE="0666"
# PKOB nano (nEDBG) in DFU mode - bootloader of debugger on Curiosity Nano
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2fc0", MODE="0666"
# MPLAB PICkit 4 In-Circuit Debugger
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2177", MODE="0666"
# MPLAB Snap In-Circuit Debugger
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2180", MODE="0666"
```

pyedbglib also provides helper functions for accessing serial ports.  The user has to be part of the 'dialout' group to allow this.  This can be done by executing:
```bash
sudo adduser $USER dialout
```

It may also be necessary to grant read+write permission to the port, for example:
```bash
sudo chmod a+rw /dev/ttyACM0
```

# Changelog

## [2.24.2] - March 2024

### Added
- DSG-7090 Added support for converting Intel(R) Hex to UF2 format

### Changed
- DSG-6539 Migrated pyedbglib to new project configuration format

## [2.23.0] - September 2023

### Added
- DSG-6057 Added support for Boot Row memory type

## [2.22.0] - October 2022

### Changed
- DSG-5445 Added metadata tag for Python 3.10
- DSG-5542 Removed metadata tag for Python 3.6

### Fixed
- DSG-4403 Fixed detection of configurable endpoint size for Atmel-ICE and Power Debugger
- DSG-5624 Fixed detection of serial ports, using pyserial for all operating systems (updated pyserial requirement)

## [2.20.3] - May 2022

### Added
- DSG-3994 Added more ATmega328P AVR ISP protocol commands (beta)
- DSG-4533 Added TPI protocol (alpha) for test purposes
- DSG-3934 Added PID for EDBG in mass-storage mode
- DSG-4291 Added Curiosity Nano DFU to udev rules
- DSG-4864 Raise exception on HID write error

## [2.19.3] - October 2021

### Added
- DSG-3270 Added argument range checks for LE16, LE32
- DSG-3804 Added py39 to setup metadata

### Fixed
- DSG-3327 Fixed crash caused by logging device ID 'None'
- DSG-3817 Fixed SAM D21 user row programming

### Changed
- DSG-3272 Removed makefile
- DSG-3319 Documentation tweaks
- DSG-3324 Removed readthedocs yaml
- DSG-3816 Device detection filters by Atmel VID and 'CMSIS-DAP' string

## [2.18.3] - April 2021

### Changed
- DSG 3317 Tweaks to docstrings

## [2.18.2] - March 2021

### Added
- DSG-3109 Added missing constants

### Fixed
- DSG-2997 Typo fix in function name: find_matching_tools_ports
- DSG-2998 Removed blanket exception catches

### Changed
- DSG-3145 Switched from proprietary to MIT license

## [2.17.7] - December 2020

### Added
- DSG-2496 Added serial port test function
- DSG-2519 Added hint at missing udev rules
- DSG-2575 Added help for dialout group
- DSG-2775 Added requirements.txt

### Fixed
- DSG-2230 Naming consistency
- DSG-2596 Improved documentation
- DSG-2838 Docstring escape character

## [2.15.2] - October 2020

### Fixed
- DSG-2046 Python 3.8 support
- DSG-2233 Logging improvements - correct usage of logging module

## [2.10.0] - June 2020
- First public release to PyPi

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "pyedbglib",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=2.7",
    "maintainer_email": null,
    "keywords": "Microchip, AVR, EDBG, protocol",
    "author": "Microchip Technology",
    "author_email": "support@microchip.com",
    "download_url": null,
    "platform": null,
    "description": "# pyedbglib - Python EDBG protocol library\npyedbglib is a low-level protocol library for communicating with Microchip CMSIS-DAP based debuggers\n\n![PyPI - Format](https://img.shields.io/pypi/format/pyedbglib)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pyedbglib)\n![PyPI - License](https://img.shields.io/pypi/l/pyedbglib)\n\n## Overview\npyedbglib is available:\n\n* install using pip from pypi: https://pypi.org/project/pyedbglib\n* browse source code on github: https://github.com/microchip-pic-avr-tools/pyedbglib\n* read API documentation on github: https://microchip-pic-avr-tools.github.io/pyedbglib\n\n## Usage\npyedbglib is a library which can be used by Python applications to communicate with Microchip microcontrollers via Microchip CMSIS-DAP based debuggers.\n\nThe protocol is documented in the [EDBG communication protocol](https://onlinedocs.microchip.com/pr/GUID-33422CDF-8B41-417C-9C31-E4521ADAE9B4-en-US-2/index.html).\n\n## Supported debuggers\npyedbglib supports:\n* PKOB nano (nEDBG) - on-board debugger on Curiosity Nano\n* MPLAB PICkit 4 In-Circuit Debugger (when in 'AVR mode')\n* MPLAB Snap In-Circuit Debugger (when in 'AVR mode')\n* Atmel-ICE\n* Power Debugger\n* EDBG - on-board debugger on Xplained Pro/Ultra\n* mEDBG - on-board debugger on Xplained Mini/Nano\n* JTAGICE3 (firmware version 3.0 or newer)\n\nNote: Each debugger may implement a subset of protocols and commands.\n\n## Example\n```python\n\"\"\"\nExample usage of pyedbglib to read debugger firmware version and target voltage\n\"\"\"\nfrom pyedbglib.hidtransport.hidtransportfactory import hid_transport\nfrom pyedbglib.protocols.housekeepingprotocol import Jtagice3HousekeepingProtocol\nfrom pyedbglib import __version__ as pyedbglib_version\n\n# Report library version\nprint(\"pyedbglib version {}\".format(pyedbglib_version))\n\n# Make a connection using HID transport\ntransport = hid_transport()\ntransport.connect()\n\n# Create a housekeeper\nhousekeeper = Jtagice3HousekeepingProtocol(transport)\nhousekeeper.start_session()\n\n# Read out debugger firmware version\nmajor = housekeeper.get_byte(Jtagice3HousekeepingProtocol.HOUSEKEEPING_CONTEXT_CONFIG,\n                             Jtagice3HousekeepingProtocol.HOUSEKEEPING_CONFIG_FWREV_MAJ)\nminor = housekeeper.get_byte(Jtagice3HousekeepingProtocol.HOUSEKEEPING_CONTEXT_CONFIG,\n                             Jtagice3HousekeepingProtocol.HOUSEKEEPING_CONFIG_FWREV_MIN)\nbuild = housekeeper.get_le16(Jtagice3HousekeepingProtocol.HOUSEKEEPING_CONTEXT_CONFIG,\n                             Jtagice3HousekeepingProtocol.HOUSEKEEPING_CONFIG_BUILD)\nprint (\"Debugger firmware is version {}.{}.{}\".format(major, minor,build))\n\n# Read out target voltage\ntarget_voltage = housekeeper.get_le16(Jtagice3HousekeepingProtocol.HOUSEKEEPING_CONTEXT_ANALOG,\n                                      Jtagice3HousekeepingProtocol.HOUSEKEEPING_ANALOG_VTREF)\nprint (\"Target voltage is {:.02f}V\".format(target_voltage/1000.0))\n\n# Tear down\nhousekeeper.end_session()\ntransport.disconnect()\n```\n\n## Notes for Linux\u00ae systems\nHIDAPI needs to build using packages: libusb-1.0.0-dev, libudev-dev\n\nUSB devices need udev rules to be added to a file in /etc/udev/rules.d\n\nExample of udev rules for supported debuggers:\n```bash\n# HIDAPI/libusb:\n\n# JTAGICE3\nSUBSYSTEM==\"usb\", ATTRS{idVendor}==\"03eb\", ATTRS{idProduct}==\"2140\", MODE=\"0666\"\n# Atmel-ICE\nSUBSYSTEM==\"usb\", ATTRS{idVendor}==\"03eb\", ATTRS{idProduct}==\"2141\", MODE=\"0666\"\n# Power Debugger\nSUBSYSTEM==\"usb\", ATTRS{idVendor}==\"03eb\", ATTRS{idProduct}==\"2144\", MODE=\"0666\"\n# EDBG - debugger on Xplained Pro\nSUBSYSTEM==\"usb\", ATTRS{idVendor}==\"03eb\", ATTRS{idProduct}==\"2111\", MODE=\"0666\"\n# EDBG - debugger on Xplained Pro (MSD mode)\nSUBSYSTEM==\"usb\", ATTRS{idVendor}==\"03eb\", ATTRS{idProduct}==\"2169\", MODE=\"0666\"\n# mEDBG - debugger on Xplained Mini\nSUBSYSTEM==\"usb\", ATTRS{idVendor}==\"03eb\", ATTRS{idProduct}==\"2145\", MODE=\"0666\"\n# PKOB nano (nEDBG) - debugger on Curiosity Nano\nSUBSYSTEM==\"usb\", ATTRS{idVendor}==\"03eb\", ATTRS{idProduct}==\"2175\", MODE=\"0666\"\n# PKOB nano (nEDBG) in DFU mode - bootloader of debugger on Curiosity Nano\nSUBSYSTEM==\"usb\", ATTRS{idVendor}==\"03eb\", ATTRS{idProduct}==\"2fc0\", MODE=\"0666\"\n# MPLAB PICkit 4 In-Circuit Debugger\nSUBSYSTEM==\"usb\", ATTRS{idVendor}==\"03eb\", ATTRS{idProduct}==\"2177\", MODE=\"0666\"\n# MPLAB Snap In-Circuit Debugger\nSUBSYSTEM==\"usb\", ATTRS{idVendor}==\"03eb\", ATTRS{idProduct}==\"2180\", MODE=\"0666\"\n```\n\npyedbglib also provides helper functions for accessing serial ports.  The user has to be part of the 'dialout' group to allow this.  This can be done by executing:\n```bash\nsudo adduser $USER dialout\n```\n\nIt may also be necessary to grant read+write permission to the port, for example:\n```bash\nsudo chmod a+rw /dev/ttyACM0\n```\n\n# Changelog\n\n## [2.24.2] - March 2024\n\n### Added\n- DSG-7090 Added support for converting Intel(R) Hex to UF2 format\n\n### Changed\n- DSG-6539 Migrated pyedbglib to new project configuration format\n\n## [2.23.0] - September 2023\n\n### Added\n- DSG-6057 Added support for Boot Row memory type\n\n## [2.22.0] - October 2022\n\n### Changed\n- DSG-5445 Added metadata tag for Python 3.10\n- DSG-5542 Removed metadata tag for Python 3.6\n\n### Fixed\n- DSG-4403 Fixed detection of configurable endpoint size for Atmel-ICE and Power Debugger\n- DSG-5624 Fixed detection of serial ports, using pyserial for all operating systems (updated pyserial requirement)\n\n## [2.20.3] - May 2022\n\n### Added\n- DSG-3994 Added more ATmega328P AVR ISP protocol commands (beta)\n- DSG-4533 Added TPI protocol (alpha) for test purposes\n- DSG-3934 Added PID for EDBG in mass-storage mode\n- DSG-4291 Added Curiosity Nano DFU to udev rules\n- DSG-4864 Raise exception on HID write error\n\n## [2.19.3] - October 2021\n\n### Added\n- DSG-3270 Added argument range checks for LE16, LE32\n- DSG-3804 Added py39 to setup metadata\n\n### Fixed\n- DSG-3327 Fixed crash caused by logging device ID 'None'\n- DSG-3817 Fixed SAM D21 user row programming\n\n### Changed\n- DSG-3272 Removed makefile\n- DSG-3319 Documentation tweaks\n- DSG-3324 Removed readthedocs yaml\n- DSG-3816 Device detection filters by Atmel VID and 'CMSIS-DAP' string\n\n## [2.18.3] - April 2021\n\n### Changed\n- DSG 3317 Tweaks to docstrings\n\n## [2.18.2] - March 2021\n\n### Added\n- DSG-3109 Added missing constants\n\n### Fixed\n- DSG-2997 Typo fix in function name: find_matching_tools_ports\n- DSG-2998 Removed blanket exception catches\n\n### Changed\n- DSG-3145 Switched from proprietary to MIT license\n\n## [2.17.7] - December 2020\n\n### Added\n- DSG-2496 Added serial port test function\n- DSG-2519 Added hint at missing udev rules\n- DSG-2575 Added help for dialout group\n- DSG-2775 Added requirements.txt\n\n### Fixed\n- DSG-2230 Naming consistency\n- DSG-2596 Improved documentation\n- DSG-2838 Docstring escape character\n\n## [2.15.2] - October 2020\n\n### Fixed\n- DSG-2046 Python 3.8 support\n- DSG-2233 Logging improvements - correct usage of logging module\n\n## [2.10.0] - June 2020\n- First public release to PyPi\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Low-level protocol library for communicating with Microchip CMSIS-DAP based debuggers",
    "version": "2.24.2.18",
    "project_urls": null,
    "split_keywords": [
        "microchip",
        " avr",
        " edbg",
        " protocol"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "4a1af5e5639677b587ae1385de7d7d742870dfd2a37819e5da000f54d224b1d8",
                "md5": "f7520bec00e65aa43efe4de16508923e",
                "sha256": "3fee579bad04c71da85de4a2ec68f6f3d4bd8bacded7fb3b671c8831ed3366c2"
            },
            "downloads": -1,
            "filename": "pyedbglib-2.24.2.18-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "f7520bec00e65aa43efe4de16508923e",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=2.7",
            "size": 70163,
            "upload_time": "2024-03-22T06:39:47",
            "upload_time_iso_8601": "2024-03-22T06:39:47.965912Z",
            "url": "https://files.pythonhosted.org/packages/4a/1a/f5e5639677b587ae1385de7d7d742870dfd2a37819e5da000f54d224b1d8/pyedbglib-2.24.2.18-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-03-22 06:39:47",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "pyedbglib"
}