Initial

CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+## [3.13] - May 2022
+
+## Added
+- DSG-3936 Fixed AVR ISP implementation and added commands (beta)
+- DSG-4172 github-10 Disable ACK response signature on serialUPDI block write (speed-up)
+- DSG-3951 github-8 Added --erase argument to erase device before write with single execution
+- DSG-3972 CLI help additions
+- DSG-3997 Added debugwire_disable() to Avr8Protocol
+
+## Fixed
+- DSG-3945, DSG-3938 Unable to write fuse byte 0 on Curiosity Nano ATtiny kits
+- DSG-4488 github-19 Return bytearray (not list) from serialUPDI read
+- DSG-4594 SAMD21 performance improvement (SAM-IoT provisioning)
+- DSG-4540 Fixed SAMD21 non-word-oriented read failure
+- DSG-3941 Improved feedback on verification failure
+- DSG-3944 Removed timeout warning for serialUPDI with a locked device
+- DSG-4419 Corrected AVR high voltage UPDI device data
+- DSG-3993 github-9 Corrected AVR signature sizes to make additional data available
+
+## [3.10] - October 2021
+
+### Added
+- DSG-2702 Add serialupdi backend for AVR EA
+- DSG-3633 github-3 Add missing AVR-DB devices
+- DSG-3635 github-4 Add missing ATtiny devices
+- DSG-3662 Add ascii-art for serialUPDI
+- DSG-3804 Add py39 metadata to package
+- DSG-3943 github-7 Add CLI documentation
+
+### Fixed
+- DSG-2859 github-1 serialUPDI write user_row on locked device fails
+- DSG-3538 github-2 Unable to write fuses on ATmega4809 using serialUPDI
+- DSG-3817 SAM D21 user row programming fails
+- DSG-3952 Incorrect size of FUSES on Dx, Ex devices
+
+## [3.9] - April 2021
+
+### Added
+- DSG-2920 Raise exception if device ID does not match
+- DSG-2918 SerialUPDI: error recovery if non-ascii characters are read in SIB
+- DSG-2861 Valid memory types are listed if an invalid one is specified
+
+### Fixed
+- DSG-3238 PIC16 eeprom displays incorrect address
+- DSG-3239 PIC16 eeprom verification does not work
+- DSG-2925 UPDI device revision not correctly parsed/displayed
+- DSG-2860 SerialUPDI: chip erase does not work on locked device
+- DSG-2857 SerialUPDI: crash when writing lockbits
+- DSG-2855 Verify action fails if hex file contains eeprom content
+- DSG-2854 User row excluded when reading to hex file
+- DSG-2850 UPDI device model fix (sram)
+
+### Changed
+- DSG-2862 Improved exception handling
+- DSG-3203 Improved exception handling
+- DSG-3178 Cosmetic changes for publication
+
+## [3.7.4] - December 2020
+
+### Added
+- DSG-1492 Added verify function
+- DSG-2039 Added all UPDI devices
+- DSG-2279 Added error codes
+- DSG-1550 Flash-only erase
+
+### Fixed
+- DSG-2470 No feedback when multiple kits are connected
+- DSG-2014 Error when reading using -m and -o but no -b
+- DSG-2738 Padding to page size when writing user row on locked device
+
+### Changed
+- DSG-2234 Logging using logging module
+- DSG-2034 prevent read using -b with no -m specified
+- DSG-2009 prevent writing from hexfile with memory type specified
+- DSG-2012 prevent writing from hexfile with offset specified
+- DSG-2458 documentation changes
+- DSG-2041 documentation changes
+- DSG-2042 documentation changes
+- DSG-2043 documentation changes
+- DSG-2011 documentation changes
+
+## [3.1.3] - June 2020
+- First public release to PyPi

LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2021 Microchip Technology Inc. and its subsidiaries.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

MANIFEST.in

@@ -0,0 +1,7 @@
+include pymcuprog/logging.yaml
+include images/microchip.png
+# These files are read in setup.py so they must be included in the source zip for pip to be able to install the zip
+# Note however that since the files are not a part of the package (not inside the pymcuprog sub folder)
+# they won't be included in the python wheel.
+include pypi.md
+include requirements.txt

README.md

@@ -0,0 +1,135 @@
+[![MCHP](images/microchip.png)](https://www.microchip.com)
+
+# pymcuprog - Python MCU programmer
+pymcuprog is a Python utility for programming various Microchip MCU devices using Microchip CMSIS-DAP based debuggers
+
+Install using pip from [pypi](https://pypi.org/project/pymcuprog):
+```bash
+pip install pymcuprog
+```
+
+Browse source code on [github](https://github.com/microchip-pic-avr-tools/pymcuprog)
+
+Read API documentation on [github](https://microchip-pic-avr-tools.github.io/pymcuprog)
+
+Read the changelog on [github](https://github.com/microchip-pic-avr-tools/pymcuprog/blob/main/CHANGELOG.md)
+
+## Usage
+pymcuprog can be used as a command-line interface or a library
+
+### CLI help
+For more help with using pymcuprog CLI see [help](./help.md)
+
+### CLI examples
+When installed using pip, pymcuprog CLI is located in the Python scripts folder.
+
+Test connectivity by reading the device ID using Curiosity Nano:
+```bash
+pymcuprog ping
+```
+
+Erase memories then write contents of an Intel(R) hex file to flash using Curiosity Nano (pymcuprog does NOT automatically erase before writing):
+```bash
+pymcuprog erase
+pymcuprog write -f app.hex
+```
+
+Erase memories and write an Intel hex file (using the --erase switch):
+```bash
+pymcuprog write -f app.hex --erase
+```
+
+Erase memories, write an Intel hex file and verify the content:
+```bash
+pymcuprog write -f app.hex --erase --verify
+```
+
+
+### Serial port UPDI (pyupdi)
+The AVR UPDI interface implements a UART protocol, which means that it can be used by simply connecting TX and RX pins of a serial port together with the UPDI pin; with a series resistor (eg: 1k) between TX and UPDI to handle contention.  (This configuration is also known as "pyupdi".)  Be sure to connect a common ground, and use a TTL serial adapter running at the same voltage as the AVR device.
+
+<pre>
+                        Vcc                     Vcc
+                        +-+                     +-+
+                         |                       |
+ +---------------------+ |                       | +--------------------+
+ | Serial port         +-+                       +-+  AVR device        |
+ |                     |      +----------+         |                    |
+ |                  TX +------+   1k     +---------+ UPDI               |
+ |                     |      +----------+    |    |                    |
+ |                     |                      |    |                    |
+ |                  RX +----------------------+    |                    |
+ |                     |                           |                    |
+ |                     +--+                     +--+                    |
+ +---------------------+  |                     |  +--------------------+
+                         +-+                   +-+
+                         GND                   GND
+</pre>
+
+pymcuprog includes this implementation as an alternative to USB/EDBG-based tools.  To connect via a serial port, use the "uart" tool type with the UART switch in addition.
+
+Example: checks connectivity by reading the device identity
+```bash
+pymcuprog ping -d avr128da48 -t uart -u com35
+```
+
+For more examples see [pymcuprog on pypi.org](https://pypi.org/project/pymcuprog/)
+
+### Library usage example
+pymcuprog can be used as a library using its backend API.  For example:
+```python
+"""
+Example usage of pymcuprog as a library to read the device ID
+"""
+# pymcuprog uses the Python logging module
+import logging
+logging.basicConfig(format="%(levelname)s: %(message)s", level=logging.WARNING)
+
+# Configure the session
+from pymcuprog.backend import SessionConfig
+sessionconfig = SessionConfig("atmega4808")
+
+# Instantiate USB transport (only 1 tool connected)
+from pymcuprog.toolconnection import ToolUsbHidConnection
+transport = ToolUsbHidConnection()
+
+# Instantiate backend
+from pymcuprog.backend import Backend
+backend = Backend()
+
+# Connect to tool using transport
+backend.connect_to_tool(transport)
+
+# Start the session
+backend.start_session(sessionconfig)
+
+# Read the target device_id
+device_id = backend.read_device_id()
+print ("Device ID is {0:06X}".format(int.from_bytes(device_id, byteorder="little")))
+```
+
+## Supported devices and tools
+pymcuprog is primarily intended for use with PKOB nano (nEDBG) debuggers which are found on Curiosity Nano kits and other development boards.  This means that it is continuously tested with a selection of AVR devices with UPDI interface as well as a selection of PIC devices.  However since the protocol is compatible between all EDBG-based debuggers (pyedbglib) it is possible to use pymcuprog with a wide range of debuggers and devices, although not all device families/interfaces have been implemented.
+
+### Debuggers / Tools
+pymcuprog 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)
+
+Although not all functionality is provided on all debuggers/boards.  See device support section below.
+
+### Devices
+pymcuprog supports:
+* All UPDI devices, whether mounted on kits or standalone
+* PIC devices mounted on Curiosity Nano kits, or similar board with PKOB nano (nEDBG) debugger
+
+Other devices (eg ATmega328P, ATsamd21e18a) may be partially supported for experimental purposes
+
+## 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

doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

doc/requirements.txt

@@ -0,0 +1 @@
+# No requirements - all are mocked.

doc/source/_templates/module.rst_t

@@ -0,0 +1,9 @@
+{%- if show_headings %}
+{{- basename | e | heading }}
+
+{% endif -%}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+   :{{ option }}:
+{%- endfor %}
+

doc/source/_templates/package.rst_t

@@ -0,0 +1,47 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+   :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- macro toctree(docnames) -%}
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+{%- endmacro %}
+
+{%- if is_namespace %}
+{{- [pkgname, "namespace"] | join(" ") | e | heading }}
+{% else %}
+{{- pkgname | e | heading }}
+{% endif %}
+
+{%- if modulefirst and not is_namespace %}
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
+
+{%- if subpackages %}
+
+{{ toctree(subpackages) }}
+{% endif %}
+
+{%- if submodules %}
+{% if separatemodules %}
+{{ toctree(submodules) }}
+{%- else %}
+{%- for submodule in submodules %}
+{% if show_headings %}
+{{- submodule | e | heading(2) }}
+{% endif %}
+{{ automodule(submodule, automodule_options) }}
+{% endfor %}
+{%- endif %}
+{% endif %}
+
+{%- if not modulefirst and not is_namespace %}
+
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}

doc/source/_templates/toc.rst_t

@@ -0,0 +1,8 @@
+{{ header | heading }}
+
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+