Metadata-Version: 2.4
Name: pyflashgui
Version: 0.2.0
Summary: Graphical flash programming tool: Arm Cortex-M with any probe pyOCD supports, and more through J-Link Commander
Author: davhodg
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/davhodg/pyflashgui
Project-URL: Documentation, https://github.com/davhodg/pyflashgui/blob/master/pyflashgui/help/manual.md
Project-URL: Repository, https://github.com/davhodg/pyflashgui
Project-URL: Issues, https://github.com/davhodg/pyflashgui/issues
Project-URL: Discussions, https://github.com/davhodg/pyflashgui/discussions
Project-URL: Releases, https://github.com/davhodg/pyflashgui/releases
Project-URL: Changelog, https://github.com/davhodg/pyflashgui/blob/master/pyflashgui/help/changelog.md
Keywords: flash,programmer,debug probe,SWD,CMSIS-DAP,ST-Link,J-Link,pyOCD,Cortex-M,microcontroller,embedded,firmware,Intel HEX,S-record,ELF,Qt
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: PySide6-Essentials>=6.8
Requires-Dist: pyocd>=0.45
Requires-Dist: bincopy>=20.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: ruff==0.16.*; extra == "dev"
Requires-Dist: trove-classifiers; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/davhodg/pyflashgui/master/pyflashgui/resources/pyflashgui.png" alt="pyflashgui icon: a chip with pins on every side and a flash across it" width="128">
</p>

# pyflashgui

[![CI](https://github.com/davhodg/pyflashgui/actions/workflows/ci.yml/badge.svg)](https://github.com/davhodg/pyflashgui/actions/workflows/ci.yml)
[![release](https://img.shields.io/github/v/release/davhodg/pyflashgui)](https://github.com/davhodg/pyflashgui/releases)
[![PyPI](https://img.shields.io/pypi/v/pyflashgui)](https://pypi.org/project/pyflashgui/)
![python](https://img.shields.io/badge/python-3.12+-blue)
![platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey)
![license](https://img.shields.io/badge/license-Apache--2.0-green)

A graphical flash programming tool. It works with any debug probe [pyOCD](https://pyocd.io) supports, for Arm Cortex-M targets: CMSIS-DAP probes such as the Raspberry Pi Debug Probe, DAPLink, NXP MCU-Link and Atmel-ICE, TI XDS110 and the probes built into many development boards, as well as ST-Link and J-Link. With a J-Link it can also use SEGGER's J-Link Commander, for the many other devices that supports.

![pyflashgui on its simulated probe: the Files pane with a firmware file and a read, the memory map under them, the bytes of the read beside them, and the Event Log below](https://raw.githubusercontent.com/davhodg/pyflashgui/master/pyflashgui/help/main-window.png)

## Install and run

To install it:

```
pip install pyflashgui
```

To run it (`python -m pyflashgui` does the same):

```
pyflashgui
```

To update it:

```
pip install --upgrade pyflashgui
```

**Python 3.15 on Windows is not supported yet:** libraries pyOCD needs there have not been released for 3.15. Use 3.14, 3.13 or 3.12 until they have.

On Linux, Qt needs a system library to draw the window, and Debian, Ubuntu, Linux Mint and the like often leave it out:

```
sudo apt install libxcb-cursor0
```

A probe is usable without root on Linux once a udev rule allows it; pyOCD publishes [a set of them](https://github.com/pyocd/pyOCD/tree/main/udev).

## What it does

- **Probe and target** in a bar across the top: the probe by its serial number, the target by name, the debug clock, and Connect -- through pyOCD, stopping the target or leaving it running.
- **Files**: ELF, Intel HEX, Motorola S-record and raw binary, in one list with what has been read from a target. A file is read again whenever a build writes it.
- **Device packs**: every Cortex-M device there is a CMSIS-Pack for, found by part number and installed from inside pyflashgui, with the address each pack comes from -- or added from a `.pack` file, for a computer with no internet.
- **Memory map**: where everything ticked will land on the chosen target, how full each flash region is and how much is erased, checked before anything is sent. A file built for another part, or two that write the same addresses, are found here.
- **Program and verify** in one press, with each half on its own beside it and **Program without erasing** for flash erased already, **Erase** of all the flash, some regions or a range, and **Reset**, by the reset pin or another way where a device needs it.
- **Read** any range of a target's memory back, shown as addresses, bytes and text, with a search for bytes or text and a way to an address. A read is saved as raw binary, Intel HEX or S-record, can be cropped to what is in use or to a range, and can be programmed like a file.
- **Compare** any two of them -- what is in the target against the file that should be, or one read against another -- with each difference marked.
- **Workspaces**: one for each board or project, holding its probe, target, files and layout.
- **A Python console** with the probe and the target as `flash`: read, write RAM, erase, program, verify and reset from a prompt or a script, each call waiting for its answer. *File > Run script...* runs one, and keeps the last five a click away.
- **A simulated probe and target**, to try all of it with no hardware.

The [manual](https://github.com/davhodg/pyflashgui/blob/master/pyflashgui/help/manual.md) covers each of these, and is also under **Help > Documentation** in the application.

## Probes and targets

Through [pyOCD](https://pyocd.io), any probe it supports, for Arm Cortex-M targets: CMSIS-DAP probes, ST-Link, and J-Link. The targets are those pyOCD has built in and those in CMSIS-Packs, which **Tools > pyOCD device packs** finds and installs.

Through SEGGER's J-Link Commander, a J-Link reaches the devices beyond Cortex-M that SEGGER's software supports -- Cortex-A and Cortex-R, RISC-V and others. SEGGER's software is not included: install it, and pyflashgui finds it.

The [README](https://github.com/davhodg/pyflashgui#probes) says which probes need which drivers.

## More

- [Source, issues and releases](https://github.com/davhodg/pyflashgui)
- [Standalone Windows installer](https://github.com/davhodg/pyflashgui/releases)
- [Questions and ideas](https://github.com/davhodg/pyflashgui/discussions)
- [Manual](https://github.com/davhodg/pyflashgui/blob/master/pyflashgui/help/manual.md)

## Safety notice and licence

pyflashgui talks to real equipment. It is intended only for people trained and experienced in working with microcontrollers, debug probes and the equipment they are part of. It is a tool for development and the bench, and is not meant for production programming.

Erasing and programming replace what a device holds, and cannot be undone. A device given the wrong file, or one that changes its protection or configuration, may not run, and may no longer be reachable through its debug port. Connecting, resetting and reading can stop or restart a device that is running, and with it whatever that device controls.

Like any software, pyflashgui can have faults, so do not rely on it alone to say that a device holds what was meant. Where a mistake could hurt someone or damage equipment, keep a way to stop that equipment within reach.

pyflashgui is provided under the Apache License 2.0, without warranty of any kind.
