> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vedderb/bldc/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/supported-hardware) for the full list.

## Prerequisites

<Tabs>
  <Tab title="Ubuntu / Linux">
    Install the required system packages:

    ```bash theme={null}
    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`:

    ```bash theme={null}
    wget vedder.se/Temp/49-stlinkv2.rules
    sudo mv 49-stlinkv2.rules /etc/udev/rules.d/
    sudo udevadm trigger
    ```
  </Tab>

  <Tab title="macOS">
    Install the required tools. If you plan to flash via SWD you will also need OpenOCD or stlink:

    ```bash theme={null}
    brew install stlink
    brew install openocd
    ```

    The ARM SDK installer (`make arm_sdk_install`) handles the compiler download automatically.
  </Tab>

  <Tab title="Windows">
    1. Install [Chocolatey](https://chocolatey.org/install).
    2. Install Git from [git-scm.com/download/win](https://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`:

    ```powershell theme={null}
    choco install make
    ```
  </Tab>
</Tabs>

## Build the firmware

<Steps>
  <Step title="Clone the repository">
    <Tabs>
      <Tab title="Linux / macOS">
        Open a terminal and run:

        ```bash theme={null}
        git clone http://github.com/vedderb/bldc.git
        cd bldc
        ```
      </Tab>

      <Tab title="Windows">
        Open PowerShell and run:

        ```powershell theme={null}
        git clone http://github.com/vedderb/bldc
        cd bldc
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Check out the master branch">
    ```bash theme={null}
    git checkout origin/master
    ```
  </Step>

  <Step title="Install the ARM GCC toolchain">
    The Makefile downloads and installs the GNU ARM GCC toolchain into the `tools/` directory:

    ```bash theme={null}
    make arm_sdk_install
    ```

    You only need to do this once.
  </Step>

  <Step title="Find your target board name">
    Run `make` without arguments to see the full list of supported boards:

    ```bash theme={null}
    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`.

    <Tip>
      Target names map directly to the `hw_*.h` files in `hwconf/`. See [Supported hardware](/supported-hardware) for a grouped listing.
    </Tip>
  </Step>

  <Step title="Build firmware for your target">
    Pass your target name to `make`. Replace `100_250` with your actual target:

    ```bash theme={null}
    make 100_250
    ```

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

## 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

<Steps>
  <Step title="Flash the bootloader">
    A SWD flash always requires the bootloader to be present first. Clone and build it from [github.com/vedderb/bldc-bootloader](https://github.com/vedderb/bldc-bootloader), then flash it via SWD before proceeding.
  </Step>

  <Step title="Flash the firmware">
    Use the `_flash` make target for your board. This invokes OpenOCD over SWD/JTAG:

    ```bash theme={null}
    make 100_250_flash
    ```

    Substitute `100_250` with your target name.
  </Step>
</Steps>

### Method 2 — Upload via VESC Tool over USB

<Warning>
  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.
</Warning>

<Steps>
  <Step title="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`.
  </Step>

  <Step title="Connect to your VESC in VESC Tool">
    Open VESC Tool and connect to your controller over USB.
  </Step>

  <Step title="Navigate to the Firmware tab">
    Select the **Firmware** tab from the left-side menu.
  </Step>

  <Step title="Select the custom firmware file">
    Click the **Custom file** tab, then click the folder icon and select the `.bin` file you built.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  If your VESC becomes unresponsive after a failed upload, you will need an STLink SWD debugger to recover it. See [Method 1](#method-1--flash-via-stlink-swd-debugger) above.
</Note>

## Optional: Qt Creator IDE

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

<Steps>
  <Step title="Install Python dependencies">
    ```bash theme={null}
    pip install aqtinstall
    ```
  </Step>

  <Step title="Install Qt">
    ```bash theme={null}
    make qt_install
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>