STM32CubeF1: the full firmware package for the STM32F1 series, minus the gated middleware

One package for the whole STM32F1 series

The description of this repository is dense, and it is worth unpacking because it tells you exactly what you get. It is the STM32Cube MCU Full Package for the STM32F1 series, combining HAL and LL drivers, CMSIS Core, CMSIS Device, middleware libraries, and a set of projects running on all the boards provided by ST, which the README names as Nucleo, Evaluation and Discovery kits. The README describes STM32Cube as an STMicroelectronics original initiative to reduce developers' effort, time and cost, covering the overall STM32 portfolio with a platform delivered per series. For an engineer, the practical value is consolidation. The abstraction layer with the HAL and LL drivers is offered as a set of APIs intended to maximise portability across the STM32 portfolio, the CMSIS modules match the ARM core in the part, and the board support drivers cover each evaluation, demonstration or Nucleo board. Instead of assembling that from separate downloads, the repository ships it as one tree with the examples next to the drivers they exercise.

The repository is assembled from git submodules, not plain files

The first thing the README tells you is that this repository has been created using the git submodule command, and that the How to use section must be followed for proper use. That single design decision explains several things you will otherwise trip over. The top-level entries include a .gitmodules file and directories such as Drivers, Middlewares, Projects, Utilities and Documentation, and those directories are separate sub-repositories rather than ordinary folders. The practical consequence is that a plain clone gives you empty or partial directories, and the README says so indirectly by requiring the --recursive option and by warning that if the GitHub Download ZIP option is used instead of git clone, the different submodules have to be collected and added manually. A contributor who skips the recursive step will not get a build failure so much as a missing tree, which is a confusing failure mode for firmware work.

Cloning, updating and pinning a firmware version

The README gives four numbered instructions, and each maps to a real workflow. To clone the repository along with the linked submodules, the --recursive option has to be specified:

git clone --recursive https://github.com/STMicroelectronics/STM32CubeF1.git

To get the latest updates on a machine that already has the repository, two commands are issued with the repository as the current working directory:

git pull
git submodule update --init --recursive

To use the same firmware version as the one available on st.com, you check out a specific tag after the clone or update steps have succeeded:

git checkout vX.Y.Z # Specify the targeted vX.Y.Z version

And to avoid those steps entirely, a shallow clone of a chosen tag does the job in one command:

git clone --recursive  --depth 1 --branch vX.Y.Z https://github.com/STMicroelectronics/STM32CubeF1.git

The README notes that the --depth 1 option is not mandatory and merely avoids downloading all previous commits up to the tagged one. The badge in the README shows the tag as v1.8.7.

The GitHub tag can be ahead of the firmware on st.com

A rolling release process is in play, and the README is explicit about the consequence. The latest version of the firmware available on GitHub may be ahead of the one available on st.com or via STM32CubeMX, and the README points to a discussion in the STM32Cube_MCU_Overall_Offer repository for details. This matters for teams that need to reproduce what a colleague, a customer or a distributor already has running. If someone sent you a bug report against firmware built from st.com, checking out the latest tag on GitHub is not the same thing as reproducing their build. The tagged versions named vX.Y.Z are the mechanism for alignment, and the clone and checkout instructions above exist precisely so you can pin to them rather than tracking master. The repository itself publishes no GitHub releases, so the tag list in git is the version inventory, and the release details live in Release_Notes.html at the root.

STemWin and the projects built on it are not in this tree

A note in the README states that some middleware libraries and the projects using them are unavailable in this repository. The library called out is ./Middlewares/ST/STemWin, and the README explains that it, along with the listed projects that use it, is subject to restrictive licence terms requiring user approval through a click-through procedure. The list of unavailable projects is kept in Projects/README.md. If you need them, the README says they are inside the full firmware package available on the website and downloadable from the st.com product page, where you are prompted to log in or register if you have no account. That is the single most consequential boundary in this repository for commercial work. A team building a product with a graphical interface may find that the examples they would have used as a starting point are the ones missing, and the substitute is a download that requires an account rather than a submodule reference.

Where the projects, boards and release details actually live

The projects are directly runnable on the STM32F1 series boards, and you find them in the Projects directories named per board, where each holds Applications, Demonstrations and Examples. The README lists the boards available for this series as the STM3210C-EVAL, the STM3210E-EVAL, the STM32VLDISCOVERY and the NUCLEO-F103RB, each with a link to its page on st.com. That list is what tells you whether a given board has an examples directory you can lean on, and it is short, so a project targeting something else, such as a custom board or a different part in the family, will need to adapt rather than adapt-and-run. Details about the content of a release are published in Release_Notes.html, which the README links through an HTML preview service, so the notes are readable in a browser without cloning. The repository root also carries package.xml, sbom_cdx.json and version-license.txt, which together describe the packaged contents, the software bill of materials and the licences of the components in the tree.

Licence handling that stops at the repository boundary

GitHub classifies the licence of this repository as Other, a custom licence the platform cannot map to a known identifier, and the root holds LICENSE.md along with the separate version-license.txt file that records licences for the components inside the package. The middleware situation described earlier is the clearest signal of how the licensing works in practice: components whose terms require an explicit click-through approval are not committed to the repository at all, while the rest are available to anyone who clones it. For a team shipping firmware, that split has to be checked component by component rather than assumed from the repository licence. The root also carries SECURITY.md, SW_Security_Level.md and CODE_OF_CONDUCT.md, and the README routes troubleshooting questions to CONTRIBUTING.md. Nothing here is legal advice, and the practical step is to read version-license.txt and the LICENSE.md file directly before deciding what you can redistribute, particularly for the board support packages and the middleware that ship with the drivers.

Editorial conclusion

STM32CubeF1 is the right source tree for a team that wants the reference drivers, the CMSIS layer and the board example projects for an STM32F1 board in one checkout, and the submodule workflow in the README is straightforward enough that the recursive clone is a small price for keeping the whole package together. It is the wrong starting point if your product needs STemWin or any of the projects that depend on it, since those are absent by design and only available through the full package on st.com, and it is the wrong choice if you need the exact firmware that ships on st.com, because the rolling release process on GitHub means the latest tag there can be ahead of the published one. Verify first which tagged version you need, check the version-license.txt file at the repository root for the licence of the components you plan to ship, and confirm that your board has a Projects directory before planning around its examples.

Frequently asked questions

Official sources

1. Issues
2. README
3. STMicroelectronics/STM32CubeF1 on GitHub