Skip to content

Commit 593afdc

Browse files
author
buildmaster
committed
Initial
0 parents  commit 593afdc

File tree

233 files changed

+48383
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

233 files changed

+48383
-0
lines changed

‎CHANGELOG.md

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Changelog
2+
3+
## [3.14] - October 2022
4+
5+
### Added
6+
- DSG-5158 github-28 Added CLI switch for serial port read timeout
7+
- DSG-5421 Added support for AVR DU and additional AVR DD devices
8+
9+
### Changed
10+
- DSG-5418 Added Python 3.10 metadata tag
11+
- DSG-5543 Removed Python 3.6 metadata tag
12+
- DSG-5417 Removed distutils usage
13+
14+
### Fixed
15+
- DSG-5157 github-29 Fixed return value on error
16+
- DSG-4836 Corrected flash offset compensation for avrdebugger
17+
18+
## [3.13] - May 2022
19+
20+
### Added
21+
- DSG-3936 Fixed AVR ISP implementation and added commands (beta)
22+
- DSG-4172 github-10 Disable ACK response signature on serialUPDI block write (speed-up)
23+
- DSG-3951 github-8 Added --erase argument to erase device before write with single execution
24+
- DSG-3972 CLI help additions
25+
- DSG-3997 Added debugwire_disable() to Avr8Protocol
26+
27+
### Fixed
28+
- DSG-3945, DSG-3938 Unable to write fuse byte 0 on Curiosity Nano ATtiny kits
29+
- DSG-4488 github-19 Return bytearray (not list) from serialUPDI read
30+
- DSG-4594 SAMD21 performance improvement (SAM-IoT provisioning)
31+
- DSG-4540 Fixed SAMD21 non-word-oriented read failure
32+
- DSG-3941 Improved feedback on verification failure
33+
- DSG-3944 Removed timeout warning for serialUPDI with a locked device
34+
- DSG-4419 Corrected AVR high voltage UPDI device data
35+
- DSG-3993 github-9 Corrected AVR signature sizes to make additional data available
36+
37+
## [3.10] - October 2021
38+
39+
### Added
40+
- DSG-2702 Add serialupdi backend for AVR EA
41+
- DSG-3633 github-3 Add missing AVR-DB devices
42+
- DSG-3635 github-4 Add missing ATtiny devices
43+
- DSG-3662 Add ascii-art for serialUPDI
44+
- DSG-3804 Add py39 metadata to package
45+
- DSG-3943 github-7 Add CLI documentation
46+
47+
### Fixed
48+
- DSG-2859 github-1 serialUPDI write user_row on locked device fails
49+
- DSG-3538 github-2 Unable to write fuses on ATmega4809 using serialUPDI
50+
- DSG-3817 SAM D21 user row programming fails
51+
- DSG-3952 Incorrect size of FUSES on Dx, Ex devices
52+
53+
## [3.9] - April 2021
54+
55+
### Added
56+
- DSG-2920 Raise exception if device ID does not match
57+
- DSG-2918 SerialUPDI: error recovery if non-ascii characters are read in SIB
58+
- DSG-2861 Valid memory types are listed if an invalid one is specified
59+
60+
### Fixed
61+
- DSG-3238 PIC16 eeprom displays incorrect address
62+
- DSG-3239 PIC16 eeprom verification does not work
63+
- DSG-2925 UPDI device revision not correctly parsed/displayed
64+
- DSG-2860 SerialUPDI: chip erase does not work on locked device
65+
- DSG-2857 SerialUPDI: crash when writing lockbits
66+
- DSG-2855 Verify action fails if hex file contains eeprom content
67+
- DSG-2854 User row excluded when reading to hex file
68+
- DSG-2850 UPDI device model fix (sram)
69+
70+
### Changed
71+
- DSG-2862 Improved exception handling
72+
- DSG-3203 Improved exception handling
73+
- DSG-3178 Cosmetic changes for publication
74+
75+
## [3.7.4] - December 2020
76+
77+
### Added
78+
- DSG-1492 Added verify function
79+
- DSG-2039 Added all UPDI devices
80+
- DSG-2279 Added error codes
81+
- DSG-1550 Flash-only erase
82+
83+
### Fixed
84+
- DSG-2470 No feedback when multiple kits are connected
85+
- DSG-2014 Error when reading using -m and -o but no -b
86+
- DSG-2738 Padding to page size when writing user row on locked device
87+
88+
### Changed
89+
- DSG-2234 Logging using logging module
90+
- DSG-2034 prevent read using -b with no -m specified
91+
- DSG-2009 prevent writing from hexfile with memory type specified
92+
- DSG-2012 prevent writing from hexfile with offset specified
93+
- DSG-2458 documentation changes
94+
- DSG-2041 documentation changes
95+
- DSG-2042 documentation changes
96+
- DSG-2043 documentation changes
97+
- DSG-2011 documentation changes
98+
99+
## [3.1.3] - June 2020
100+
- First public release to PyPi

‎LICENSE.txt

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

‎MANIFEST.in

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
include pymcuprog/logging.yaml
2+
include images/microchip.png
3+
# 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
4+
# Note however that since the files are not a part of the package (not inside the pymcuprog sub folder)
5+
# they won't be included in the python wheel.
6+
include pypi.md
7+
include requirements.txt

‎README.md

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
[![MCHP](images/microchip.png)](https://www.microchip.com)
2+
3+
# pymcuprog - Python MCU programmer
4+
pymcuprog is a Python utility for programming various Microchip MCU devices using Microchip CMSIS-DAP based debuggers
5+
6+
Install using pip from [pypi](https://pypi.org/project/pymcuprog):
7+
```bash
8+
pip install pymcuprog
9+
```
10+
11+
Browse source code on [github](https://github.com/microchip-pic-avr-tools/pymcuprog)
12+
13+
Read API documentation on [github](https://microchip-pic-avr-tools.github.io/pymcuprog)
14+
15+
Read the changelog on [github](https://github.com/microchip-pic-avr-tools/pymcuprog/blob/main/CHANGELOG.md)
16+
17+
## Usage
18+
pymcuprog can be used as a command-line interface or a library
19+
20+
### CLI help
21+
For more help with using pymcuprog CLI see [help](./help.md)
22+
23+
### CLI examples
24+
When installed using pip, pymcuprog CLI is located in the Python scripts folder.
25+
26+
Test connectivity by reading the device ID using Curiosity Nano:
27+
```bash
28+
pymcuprog ping
29+
```
30+
31+
Erase memories then write contents of an Intel(R) hex file to flash using Curiosity Nano (pymcuprog does NOT automatically erase before writing):
32+
```bash
33+
pymcuprog erase
34+
pymcuprog write -f app.hex
35+
```
36+
37+
Erase memories and write an Intel hex file (using the --erase switch):
38+
```bash
39+
pymcuprog write -f app.hex --erase
40+
```
41+
42+
Erase memories, write an Intel hex file and verify the content:
43+
```bash
44+
pymcuprog write -f app.hex --erase --verify
45+
```
46+
47+
48+
### Serial port UPDI (pyupdi)
49+
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.
50+
51+
<pre>
52+
Vcc Vcc
53+
+-+ +-+
54+
| |
55+
+---------------------+ | | +--------------------+
56+
| Serial port +-+ +-+ AVR device |
57+
| | +----------+ | |
58+
| TX +------+ 1k +---------+ UPDI |
59+
| | +----------+ | | |
60+
| | | | |
61+
| RX +----------------------+ | |
62+
| | | |
63+
| +--+ +--+ |
64+
+---------------------+ | | +--------------------+
65+
+-+ +-+
66+
GND GND
67+
</pre>
68+
69+
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.
70+
71+
Example: checks connectivity by reading the device identity
72+
```bash
73+
pymcuprog ping -d avr128da48 -t uart -u com35
74+
```
75+
76+
When using serial port UPDI it is optional to use:
77+
* --clk BAUD to specify the baud rate (defaults to 115200)
78+
* --uart-timeout TIMEOUT to specify the uart read timeout (defaults to 1.0s)
79+
80+
Increasing the baud rate can decrease programming time. Decreasing the timeout can decrease the initial connection latency when UPDI is disabled and does not respond. These parameters can be tweaked to suit the serial port adapter in use.
81+
82+
For more examples see [pymcuprog on pypi.org](https://pypi.org/project/pymcuprog/)
83+
84+
### Library usage example
85+
pymcuprog can be used as a library using its backend API. For example:
86+
```python
87+
"""
88+
Example usage of pymcuprog as a library to read the device ID
89+
"""
90+
# pymcuprog uses the Python logging module
91+
import logging
92+
logging.basicConfig(format="%(levelname)s: %(message)s", level=logging.WARNING)
93+
94+
# Configure the session
95+
from pymcuprog.backend import SessionConfig
96+
sessionconfig = SessionConfig("atmega4808")
97+
98+
# Instantiate USB transport (only 1 tool connected)
99+
from pymcuprog.toolconnection import ToolUsbHidConnection
100+
transport = ToolUsbHidConnection()
101+
102+
# Instantiate backend
103+
from pymcuprog.backend import Backend
104+
backend = Backend()
105+
106+
# Connect to tool using transport
107+
backend.connect_to_tool(transport)
108+
109+
# Start the session
110+
backend.start_session(sessionconfig)
111+
112+
# Read the target device_id
113+
device_id = backend.read_device_id()
114+
print ("Device ID is {0:06X}".format(int.from_bytes(device_id, byteorder="little")))
115+
```
116+
117+
## Supported devices and tools
118+
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.
119+
120+
### Debuggers / Tools
121+
pymcuprog supports:
122+
* PKOB nano (nEDBG) - on-board debugger on Curiosity Nano
123+
* MPLAB PICkit 4 In-Circuit Debugger (when in 'AVR mode')
124+
* MPLAB Snap In-Circuit Debugger (when in 'AVR mode')
125+
* Atmel-ICE
126+
* Power Debugger
127+
* EDBG - on-board debugger on Xplained Pro/Ultra
128+
* mEDBG - on-board debugger on Xplained Mini/Nano
129+
* JTAGICE3 (firmware version 3.0 or newer)
130+
131+
Although not all functionality is provided on all debuggers/boards. See device support section below.
132+
133+
### Devices
134+
pymcuprog supports:
135+
* All UPDI devices, whether mounted on kits or standalone
136+
* PIC devices mounted on Curiosity Nano kits, or similar board with PKOB nano (nEDBG) debugger
137+
138+
Other devices (eg ATmega328P, ATsamd21e18a) may be partially supported for experimental purposes
139+
140+
## Notes for Linux® systems
141+
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

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎doc/make.bat

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
if "%1" == "" goto help
14+
15+
%SPHINXBUILD% >NUL 2>NUL
16+
if errorlevel 9009 (
17+
echo.
18+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
19+
echo.installed, then set the SPHINXBUILD environment variable to point
20+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
21+
echo.may add the Sphinx directory to PATH.
22+
echo.
23+
echo.If you don't have Sphinx installed, grab it from
24+
echo.http://sphinx-doc.org/
25+
exit /b 1
26+
)
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎doc/requirements.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# No requirements - all are mocked.

‎doc/source/_static/.keep

Whitespace-only changes.

‎doc/source/_templates/module.rst_t

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{%- if show_headings %}
2+
{{- basename | e | heading }}
3+
4+
{% endif -%}
5+
.. automodule:: {{ qualname }}
6+
{%- for option in automodule_options %}
7+
:{{ option }}:
8+
{%- endfor %}
9+

‎doc/source/_templates/package.rst_t

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
{%- macro automodule(modname, options) -%}
2+
.. automodule:: {{ modname }}
3+
{%- for option in options %}
4+
:{{ option }}:
5+
{%- endfor %}
6+
{%- endmacro %}
7+
8+
{%- macro toctree(docnames) -%}
9+
.. toctree::
10+
:maxdepth: {{ maxdepth }}
11+
{% for docname in docnames %}
12+
{{ docname }}
13+
{%- endfor %}
14+
{%- endmacro %}
15+
16+
{%- if is_namespace %}
17+
{{- [pkgname, "namespace"] | join(" ") | e | heading }}
18+
{% else %}
19+
{{- pkgname | e | heading }}
20+
{% endif %}
21+
22+
{%- if modulefirst and not is_namespace %}
23+
{{ automodule(pkgname, automodule_options) }}
24+
{% endif %}
25+
26+
{%- if subpackages %}
27+
28+
{{ toctree(subpackages) }}
29+
{% endif %}
30+
31+
{%- if submodules %}
32+
{% if separatemodules %}
33+
{{ toctree(submodules) }}
34+
{%- else %}
35+
{%- for submodule in submodules %}
36+
{% if show_headings %}
37+
{{- submodule | e | heading(2) }}
38+
{% endif %}
39+
{{ automodule(submodule, automodule_options) }}
40+
{% endfor %}
41+
{%- endif %}
42+
{% endif %}
43+
44+
{%- if not modulefirst and not is_namespace %}
45+
46+
{{ automodule(pkgname, automodule_options) }}
47+
{% endif %}

0 commit comments

Comments
 (0)