Quickstart

Clone, build, and flash VESC firmware to your controller in a few steps.

Quickstart

This guide walks you through building VESC firmware from source and uploading it to your controller. You will need a supported hardware target — see Supported hardware for the full list.

Prerequisites

Ubuntu / Linux

Install the required system packages:

sudo apt install git build-essential libgl-dev libxcb-xinerama0 wget git-gui

Optionally, add udev rules so you can use an STLink v2 programmer without sudo:

wget vedder.se/Temp/49-stlinkv2.rules
sudo mv 49-stlinkv2.rules /etc/udev/rules.d/
sudo udevadm trigger

macOS

Install the required tools. If you plan to flash via SWD you will also need OpenOCD or stlink:

brew install stlink
brew install openocd

The ARM SDK installer (make arm_sdk_install) handles the compiler download automatically.

Windows

1. Install Chocolatey.
2. Install Git from git-scm.com/download/win. When prompted, enable the option to add Git to your PATH.
3. Open Windows PowerShell (do not run as Administrator — that will break the build).
4. Install make:

choco install make

Build the firmware

1. Clone the repository

   Linux / macOS

   Open a terminal and run:

   git clone http://github.com/vedderb/bldc.git
   cd bldc
   

   Windows

   Open PowerShell and run:

   git clone http://github.com/vedderb/bldc
   cd bldc
   
2. Check out the master branch

   git checkout origin/master
   
3. Install the ARM GCC toolchain

   The Makefile downloads and installs the GNU ARM GCC toolchain into the tools/ directory:

   make arm_sdk_install
   

   You only need to do this once.

4. Find your target board name

   Run make without arguments to see the full list of supported boards:

   make
   

   The output lists every available target under [Firmware]. Pick the one that matches your hardware. For example, a Trampa VESC 100/250 uses the target name 100_250.

   Target names map directly to the hw_*.h files in hwconf/. See Supported hardware for a grouped listing.

5. Build firmware for your target

   Pass your target name to make. Replace 100_250 with your actual target:

   make 100_250
   

   The compiled firmware is placed in build/100_250/. You will find both an ELF file and a .bin file there.

Flash the firmware

There are two ways to get the firmware onto your controller. Method 1 (SWD) is required for a fresh controller or a bricked device. Method 2 (VESC Tool USB) is more convenient for routine updates.

Method 1 — Flash via STLink SWD debugger

1. Flash the bootloader

   A SWD flash always requires the bootloader to be present first. Clone and build it from github.com/vedderb/bldc-bootloader, then flash it via SWD before proceeding.

2. Flash the firmware

   Use the _flash make target for your board. This invokes OpenOCD over SWD/JTAG:

   make 100_250_flash
   

   Substitute 100_250 with your target name.

Method 2 — Upload via VESC Tool over USB

Do not disconnect power or USB from your VESC during the upload process. Interrupting the upload can brick the controller. Only disconnect 10 seconds after the “FW Upload DONE” message appears and the progress bar completes.

1. Build the firmware

   Follow the build steps above. You need the .bin file from the build/<target>/ directory, for example build/100_250/100_250.bin.

2. Connect to your VESC in VESC Tool

   Open VESC Tool and connect to your controller over USB.

3. Navigate to the Firmware tab

   Select the Firmware tab from the left-side menu.

4. Select the custom firmware file

   Click the Custom file tab, then click the folder icon and select the .bin file you built.

5. Upload the firmware

   Click the upload button (downward arrow) in the bottom-right corner. The progress bar will advance as the firmware uploads.

   It is normal for the VESC to disconnect during the upload — do not panic.

6. Wait before disconnecting

   Wait 10 seconds after the progress bar completes before removing USB or power. The VESC will disconnect itself once the new firmware is fully written.

If your VESC becomes unresponsive after a failed upload, you will need an STLink SWD debugger to recover it. See Method 1 above.

Optional: Qt Creator IDE

If you prefer a graphical IDE, the repository includes a Qt Creator project:

1. Install Python dependencies

   pip install aqtinstall
   
2. Install Qt

   make qt_install
   
3. Open the project in Qt Creator

   Launch Qt Creator from tools/Qt/Tools/QtCreator/bin/qtcreator, then open Project/Qt Creator/vesc.pro.

   The active hardware target is shown at the bottom-left of the IDE panel and can be changed to any supported board.