vedderb/vesc_tool: the C++ source behind the VESC Project configuration app

What the repository actually contains

This is the source of VESC Tool, the application the VESC Project publishes as the official binary release, and the homepage given for the project is vesc-project.com. The primary language is C++, the licence is GPL-3.0, the default branch is `master`, and the last push to the repository was on 2026-10-15. There are no GitHub releases attached, which is deliberate rather than accidental.

The file layout describes a desktop application with several embedded targets. Alongside the familiar Qt-style pieces, `mainwindow.cpp` and `mainwindow.ui`, `boardsetupwindow.cpp` and `boardsetupwindow.ui`, there is a `QCodeEditor/` directory, a `display_tool/` directory, a `map/` directory, a `mobile/` directory, an `esp32/` directory, and an `ios/` directory. Firmware handling has its own files in `hexfile.cpp` and `hexfile.h`. A `bleuart.cpp` and `bleuart.h` pair sits next to `bleuartdummy.cpp` and `bleuartdummy.h`, which reads as the Bluetooth link to the controller and a stub implementation of it, used when the hardware support is not present. Configuration lives in `configparam.cpp`, `configparams.cpp` and `datatypes.h`, and the wire protocol in `packet.cpp` and `commands.cpp`.

For a developer the practical reading is that this is one application codebase that spans Linux, Windows, macOS, Android and iOS, plus a firmware build for ESP32 controllers, rather than a library with a clean API.

One build script per platform, and a Nix flake for reproducible setup

The top level of the repository is where the build story lives. There are separate scripts named `build_lin`, `build_win`, `build_macos` and `build_android`, plus `build_all` for the full sweep and `build_test_versions` for test builds. Two narrower scripts, `build_lin_original_only` and `build_win_original_only`, build the original flavour only, which suggests the project ships more than one build target for the desktop platforms.

Firmware is built by a different pair of scripts, `build_cp_fw` and `build_cp_esp_fw`, and the README notes that packaging the firmware is an additional step performed from a different repository, `vedderb/bldc`. That separation is the reason the README is strict about who may publish a binary: an outsider cannot easily verify that the firmware inside a repackaged app was built correctly, because the firmware build is not part of this repository.

For a reproducible development environment the tree includes `flake.nix`, `flake.lock` and `overlay.nix`. The presence of a Nix flake and an overlay means a contributor can describe the toolchain in one file instead of hand-assembling the same set of system packages on each machine, which matters for a project that has to build the same application on five platforms.

Two other entries deserve a mention. `checklist_release.txt` is a release checklist kept in the repository, and `cla_vesc_tool.md` is a contributor licence agreement document, which tells you that contributions are covered by a CLA rather than a plain inbound assignment.

The code and the name are two separate problems

The README spends more space on licensing than on features, and the reason is that a rewrite or a port touches two unrelated legal layers. The code is governed by the GPL, and the name and logos are governed by a trademark policy held by Benjamin Vedder, with VESC a registered trademark. The README states the boundary plainly: the GPL gives you freedom with the code and gives you no right to the VESC name or logos.

The code side means GPL-3.0-or-later obligations for anyone who translates the tool file by file, which in most jurisdictions makes the result a derivative work. The README spells out the expected practice for such a port: licence the new project GPL-3.0-or-later and ship the full licence text, keep every existing copyright notice from Vedder and contributors in the files you port, state clearly that the work is modified and from which upstream commit it was based, publish the complete source for every binary you distribute including build scripts, show an About screen with the copyright, licence and a no-warranty notice plus a link to the source, and use only GPLv3-compatible dependencies.

A clean-room reimplementation written purely from a protocol specification is treated as a different situation, though the README is honest that this is hard to prove once you have worked from the source. The bundled firmware from `bldc` is GPL as well, so shipping it carries the same source obligations.

What the trademark policy removes from a fork

The naming rules are specific enough to be worth quoting, because they are the part people trip over when they start a rewrite. A mark cannot be used as part of a product name, a domain name, a trade name or a company logo, and names that are confusingly similar are prohibited too. The README lists examples of names that would not work, such as a variant spelling of the tool name or a name that reads as the tool with a suffix, and the rule that the same applies to app store titles, listing titles, repository names, package names and domains. Compatibility belongs in the description, not in the title.

The technical identifiers are covered separately, and these are the strings you have to change in the codebase. The Android package is `com.vedder.vesc`, and the organisation name, domain, application name and settings paths all fall under the same rule. The visual identity is covered too. No VESC logos, and the application icon `VESC Favicon.iconset` is not to be reused, nor are the UI icons from `res/` without checking where each one came from. The README suggests drawing your own or using a clearly licensed icon set, and using your own colour palette, since an application that looks like the official one creates exactly the confusion the trademark exists to prevent.

One more removal is easy to overlook: the update checker that queries vesc-project.com and tells users to download VESC Tool. A fork that silently keeps relying on the VESC Project servers is not acceptable, and if you need those servers you have to ask first.

Contributing upstream instead of maintaining a fork

The README pushes hard on a single preference, and it is a preference about the ecosystem rather than about code quality. Missing features should be contributed back to the main VESC repositories so that there is one consistent and compatible release for everyone, managed by the people who write the vast majority of the development. The stated benefit is review: the upstream authors are the ones most familiar with the code and can check that a feature is as safe as possible and does not break other parts of the functionality.

Forks are not banned. The README explicitly allows using the GitHub fork function to contribute, on two grounds, that it is the most convenient way to make a contribution, and that a fork states clearly that it is a fork and points back to the main repository, which keeps the diff visible in a way that is lost in a binary release.

What is discouraged is a fork that publishes a binary release. Once a binary is downloaded, there is no way to tell it apart from the official release, and the firmware inside it cannot be verified. The README also handles the sensitive case of a fork with the branding removed. Removing all traces of the trademark does not break the trademark policies, but it is still discouraged because it is confusing to users and it diverts people away from the VESC Project, which the README notes receives the majority of its donations through VESC Tool downloads.

Custom hardware is a separate path. The README states it can be added to the official release by forking `vedderb/bldc` and opening a pull request, so hardware support lives upstream in the firmware repository rather than in the application.

Where the build and release path ends, and what it costs you

Several practical constraints come out of the README, and they are worth weighing before you commit to this codebase.

First, the binaries do not come from the repository. The stable binary is available for Linux, Windows, macOS, Android and iOS, while the development binary covers Linux, Windows and Android and is updated every few days. All are free of charge except iOS, which is distributed only through the Apple App Store because Apple does not allow another distribution channel. If you are on iOS, the source repository does not change that.

Second, the source tree carries vendored third-party code whose licences you must keep separate. The `heatshrink/`, `lzokay/`, `minimp3/` and `maddy/` directories are in the tree, and the README names heatshrink, minimp3, QCustomPlot and maddy as third-party code inside VESC Tool that keeps its own licence and should be credited if you port it. A rewrite that copies those files without their notices is a straightforward compliance failure.

Third, documentation is thin on the build side. The README does not list compiler versions, build dependencies, or a step by step for running `build_lin` or `build_macos`, and there is no changelog, rollback note or migration guide in the tree. The `flake.nix` and `overlay.nix` files are the best starting point for a working environment, and `checklist_release.txt` is the best description of what a release is expected to contain. The trade is that you get a mature, cross-platform application codebase and a clear legal framework, in exchange for doing the toolchain setup yourself.

Editorial conclusion

Adopt this repository as your source of truth if you work on VESC hardware and want to read or modify the tool that configures it, since the desktop, mobile and ESP32 code all live here and the build scripts cover every shipping platform. Do not fork it to publish your own branded binary, because the trademark policy forbids the name, the logos and the application identifiers, and the code itself is GPL-3.0-or-later, which means a port has to ship complete corresponding source. Before you start, check which of the third-party directories you actually carry across, since `heatshrink/`, `lzokay/`, `minimp3/`, `maddy/`, `QCodeEditor/` and the QCustomPlot mention each keep their own licence, and confirm that the `build_lin`, `build_macos`, `build_win` and `build_android` scripts match your own toolchain, because the README does not document how to run them.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. vedderb/vesc_tool on GitHub