2020-04-10 21:38:17 +00:00
Open source version of the STMicroelectronics STlink Tools
2016-06-18 14:19:09 +00:00
==========================================================
2017-01-28 12:08:30 +00:00
[](https://raw.githubusercontent.com/hyperium/hyper/master/LICENSE)
2020-04-12 16:26:46 +00:00
[](https://github.com/stlink-org/stlink/releases/latest)
[](https://github.com/stlink-org/stlink/releases/master)
[](https://github.com/stlink-org/stlink/releases)
[](https://travis-ci.org/stlink-org/stlink)
[](https://travis-ci.org/stlink-org/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.
2020-04-10 21:38:17 +00:00
#### License
The stlink library and tools are licensed under the ** [BSD-3 License ](LICENSE.md )**.< br />
The source files **stm32l0x.s** and **stm32lx.s** found in the subdirectory `/flashloaders/`
are licensed under the **General Public License (GPL v2+)** .
2020-02-22 00:24:49 +00:00
## Introduction
2019-08-17 08:42:14 +00:00
2020-04-14 19:01:52 +00:00
STLink is an open source toolset to program and debug STM32 devices and boards manufactured by STMicroelectronics.
It supports several so called STLINK programmer boards (and clones thereof) which use a microcontroller chip
to translate commands from USB to JTAG/SWD. There are four generations available on the market:
2016-06-18 14:19:09 +00:00
2020-04-14 19:01:52 +00:00
* **STLINK/v1** _(obsolete as of 21-11-2019)_
2020-02-19 20:20:10 +00:00
- transport layer: SCSI passthru commands over USB
2020-04-14 19:01:52 +00:00
- stand-alone programmer and present on STM32VL Discovery boards
* **STLINK/v2**
- transport layer: raw USB commands
- stand-alone programmer and present on STM32L Discovery and Nucleo boards
* **STLINK/v2-1**
- transport layer: raw USB commands
- present on some STM32 Nucleo boards
* **STLINK/v3**
- transport layer: raw USB commands
- stand-alone programmer
On the user level there is no difference in handling or operation between these different revisions.
The STlink toolset includes:
* a communication library (libstlink.a),
* a programmer and chip information tool (st-info),
* a flash manipulation tool (st-flash),
* a GDB server (st-util) and
* a GUI-Interface (stlink-gui) _[optional]_
2020-02-22 00:24:49 +00:00
## Supported hardware combinations
2020-04-03 09:49:31 +00:00
Currently known working combinations of programmers and targets are listed in [devices_boards.md ](doc/devices_boards.md ).
## Tutorial & HOWTO
Our [tutorial.md](doc/tutorial.md may help you along with some advanced tasks and additional info.
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-04-07 15:01:26 +00:00
**Windows**:
2020-02-22 00:24:49 +00:00
2020-04-07 15:01:26 +00:00
Please compile and install from source as described in our [compiling manual ](doc/compiling.md#Windows ).
2020-02-26 19:47:25 +00:00
2020-04-07 15:01:26 +00:00
Long awaited binaries will be available soon...
**macOS**:
We recommend to install from:
* [homebrew ](https://formulae.brew.sh/formula/stlink ) or
* [MacPorts ](https://ports.macports.org/port/stlink )
Alternatively one can compile and install from source as described in our [compiling manual ](doc/compiling.md#macOS ).
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-04-07 15:01:26 +00:00
* RedHat/CentOS 8: Users can install from [EPEL repository ](https://src.fedoraproject.org/rpms/stlink/branch/epel8 )
* FreeBSD: Users can install from [freshports ](https://www.freshports.org/devel/stlink )
* OpenBSD: Users need to compile and install from source as described in our [compiling manual ](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
# 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))
