2016-06-18 14:19:09 +00:00
Open source version of the STMicroelectronics Stlink Tools
==========================================================
2017-01-28 12:08:30 +00:00
[![BSD licensed ](https://img.shields.io/badge/license-BSD-blue.svg )](https://raw.githubusercontent.com/hyperium/hyper/master/LICENSE)
2020-02-22 00:24:49 +00:00
[![GitHub release ](https://img.shields.io/github/release/texane/stlink.svg )](https://github.com/texane/stlink/releases/latest)
2020-02-20 01:08:49 +00:00
[![GitHub commits ](https://img.shields.io/github/commits-since/texane/stlink/v1.6.0.svg )](https://github.com/texane/stlink/releases/master)
2017-01-28 12:08:30 +00:00
[![Downloads ](https://img.shields.io/github/downloads/texane/stlink/total.svg )](https://github.com/texane/stlink/releases)
2016-06-18 14:19:09 +00:00
[![Linux Status ](https://img.shields.io/travis/texane/stlink/master.svg?label=linux )](https://travis-ci.org/texane/stlink)
2020-02-19 20:20:10 +00:00
[![macOS Status ](https://img.shields.io/travis/texane/stlink/master.svg?label=osx )](https://travis-ci.org/texane/stlink)
2016-06-18 14:19:09 +00:00
2020-02-22 00:24:49 +00:00
Recent new features and bugfixes can be found in the [Changelog ](CHANGELOG.md ) of this software project.
## Introduction
2019-08-17 08:42:14 +00:00
2020-02-22 00:24:49 +00:00
This stlink toolset supports several so called stlink programmer boards (and clones thereof) which use a microcontroller chip to translate commands from USB to JTAG.
2016-06-18 14:19:09 +00:00
2020-02-22 00:24:49 +00:00
These programmer boards are available in four versions:
2016-06-18 14:19:09 +00:00
2020-02-19 20:20:10 +00:00
* **STLINKv1:**
- transport layer: SCSI passthru commands over USB
- present on STM32VL discovery kits
* **STLINKv2:**
* transport layer: raw USB commands
* present on STM32L discovery and nucleo and later kits
* **STLINKv2-1:**
* transport layer: raw USB commands
* present on some STM32 nucleo boards
* **STLINKv3:**
2020-02-22 00:24:49 +00:00
* _not yet supported by this toolset (but planned)_
## Supported hardware combinations
2020-04-02 00:18:49 +00:00
Currently known working combinations of programmers and targets are listed in [doc/devices_boards.md ](doc/tested-boards.md ).
2016-06-18 14:19:09 +00:00
2016-10-22 08:18:33 +00:00
## Installation
2016-06-18 14:19:09 +00:00
2020-02-22 00:24:49 +00:00
**Windows**: download [v1.6.0 ](https://github.com/texane/stlink/releases/tag/v1.6.0 ) from the releases page.
2020-03-24 20:11:38 +00:00
Windows pre-compiled binaries are available at http://www.emb4fun.de/archive/stlink/index.html (outdated, not recommended for use)
2020-02-26 19:47:25 +00:00
2020-02-22 00:24:49 +00:00
**macOS**: install [from homebrew ](http://brewformulas.org/Stlink ) or download [v1.6.0 ](https://github.com/texane/stlink/releases/tag/v1.6.0 ) from the releases page.
2017-01-29 08:20:20 +00:00
2020-02-22 00:24:49 +00:00
**Linux**:
2016-06-18 14:19:09 +00:00
2020-02-22 00:24:49 +00:00
We recommend to install `stlink-tools` from the package repository of the used distribution:
2019-07-26 11:19:32 +00:00
2020-02-22 00:24:49 +00:00
* Debian Linux: [(Link) ](https://packages.debian.org/buster/stlink-tools )
* Ubuntu Linux: [(Link) ](https://packages.ubuntu.com/stlink-tools )
* Arch Linux: [(Link) ](https://www.archlinux.org/packages/community/x86_64/stlink )
* Alpine Linux: [(Link) ](https://pkgs.alpinelinux.org/packages?name=stlink )
* Fedora: [(Link) ](https://src.fedoraproject.org/rpms/stlink )
* Gentoo Linux: [(Link) ](https://packages.gentoo.org/packages/dev-embedded/stlink )
2016-06-18 14:19:09 +00:00
2020-02-22 00:24:49 +00:00
**Other Operating Systems**:
2016-06-18 14:19:09 +00:00
2020-02-22 00:24:49 +00:00
* RedHat/CentOS 7: Users can install [from EPEL repository ](https://src.fedoraproject.org/rpms/stlink/branch/epel7 )
* FreeBSD: Users can install [from freshports ](https://www.freshports.org/devel/stlink )
* OpenBSD: Users need to install [from source ](doc/compiling.md ).
2017-02-01 22:12:39 +00:00
2017-09-07 10:59:49 +00:00
2020-02-22 00:24:49 +00:00
## Installation from source (advanced users)
2017-09-07 10:59:49 +00:00
2020-02-22 00:24:49 +00:00
When there is no executable available for your platform or you need the latest (possible unstable) version you need to compile the toolset yourself. This procedure is explained in the [compiling manual ](doc/compiling.md ).
2017-07-27 12:14:35 +00:00
2016-06-18 14:19:09 +00:00
2020-02-22 00:24:49 +00:00
## Contributing and versioning
2017-01-14 14:48:22 +00:00
2020-02-22 00:24:49 +00:00
* The semantic versioning scheme is used. Read more at [semver.org ](http://semver.org )
* Before creating a pull request, please _ALWAYS_ open a new issue for the discussion of the intended new features. Bugfixes don't require a discussion via a ticket-issue. However they should always be described in a few words as soon as they appear to help others as well.
* Contributors and/or maintainers may submit comments or request changes to patch-proposals and/or pull-requests.
2020-02-24 21:55:29 +00:00
* **ATTENTION: _NEVER EVER_ use the '#' character to count-up single points within a listing as '#' is _exclusively_ reserved for referencing github issues and pull-requests. Otherwise you accidentally introduce false cross references within the project.**
2020-02-26 19:32:55 +00:00
* Please start new forks from the develop branch if possible as pull requests will go into this branch as well.
2020-02-19 20:20:10 +00:00
2016-06-18 14:19:09 +00:00
2020-02-22 00:24:49 +00:00
## License
The stlink library and tools are licensed under the [BSD license ](LICENSE.md ).
The flashloaders/stm32l0x.s and flashloaders/stm32lx.s source files are licensed under the GPLv2+.
2020-02-19 20:20:10 +00:00
2016-09-18 08:52:03 +00:00
2020-02-22 00:24:49 +00:00
# Current state of the project
## Known missing features
Some features are currently missing from the `texane/stlink` toolset.
Here we would appreciate any help and would love to welcome new contributors who want to get involved:
* Instrumentation Trace Macro (ITM) Cell ([#136](https://github.com/texane/stlink/issues/136))
2020-03-24 12:33:32 +00:00
* OTP & EEPROM area programming ([#202](https://github.com/texane/stlink/issues/202), [#333 ](https://github.com/texane/stlink/issues/333 ), [#686 ](https://github.com/texane/stlink/issues/686 ))
2020-02-22 00:24:49 +00:00
* Protection bits area reading ([#346](https://github.com/texane/stlink/issues/346))
* Writing external memory connected to an STM32 controller (e.g Quad SPI NOR flash) ([#412](https://github.com/texane/stlink/issues/412))
* MCU hotplug ([#449](https://github.com/texane/stlink/issues/449))
* Writing options bytes (region) ([#458](https://github.com/texane/stlink/issues/458))
* Support for STLINKv3 programmer ([#820](https://github.com/texane/stlink/issues/820))