VESC Tool on your phone: Bluetooth connection, dashboard, and profiles
The VESC Tool is also available on mobile devices, for both Android and iOS. With a controller equipped with Bluetooth, it serves as a dashboard while riding, a diagnostic tool at the trackside, and a quick way to change profiles. It provides access to the same settings as the computer version, but it is not used in exactly the same way. Here's how to connect, what each tab contains, and the precautions to take.
The essentials
- The controller must have a Bluetooth Low Energy (BLE) module that is compatible with the VESC standard, either integrated or connected to its communication port.
- The connection is established through the VESC Tool (by searching for devices within the application), not through the Bluetooth settings on the phone.
- The pairing and module code restrict who can connect to your controller.
- The "RT Data" tab serves as a dashboard; the "Profiles" section allows you to change settings in seconds.
- Initial settings and updates: connecting the computer via USB remains the safest option.
Here's what you need to consider on the controller side:
Many VESC controllers do not have built-in Bluetooth. In such cases, a Bluetooth Low Energy module designed for VESC is added, and it is connected to the controller's serial communication port (UART). There are two main families within the open-source project: the modules based on the NRF chip, which are the older designs, and the VESC Express, a board based on the ESP32 that its official repository describes as a data logger and an input/output board with Wi-Fi and Bluetooth capabilities.
Regarding settings, the serial port must remain permanently active: this is the "Enable Permanent UART" parameter in App Settings, General. The help text clarifies that it can be disabled to prevent any access to the controller via Bluetooth.
Connect
- Install the VESC Tool from your phone's app store (official version, published by the VESC project team).
- Turn on the controller. Allow the application to use Bluetooth, and on Android, location services if prompted, for the search process.
- On the home page, tap Connect, then start the search (Scan...). The devices found will be displayed in the list.
- Choose your controller. The "Set Name" button allows you to give it a recognizable name, which is useful when multiple devices are within range.
For the initial connection to the computer, please refer to our guide for installing VESC Tool and connecting.
Secure access
A Bluetooth-enabled controller can be reconfigured by anyone who connects to it. Two types of protection are available:
- `Pairing: Once pairing is complete, a Bluetooth connection will only be accepted from an instance of the VESC Tool application that is paired with this controller (the `Pairing Done` parameter). On a computer, the `Connection` page offers `Pair` and `Unpair` options;`
- Module Code: For NRF modules, the "Setup Bluetooth Module" button on the home page opens the module configuration, with an "Update Name" field and a six-digit code (Update Pin).
Keep track of the paired device: if you change phones, you will need to re-pair it from an authorized connection.
The tabs in the application
| Tab | What is it used for? |
|---|---|
| Start | Connections, assistants (Setup Motors, Setup Input), Update Firmware, Backup Configs, Restore Configs, motor direction inversion, data logging |
| RT Data | Real-time data: speed, voltage, currents, temperatures, and active error messages |
| BMS (Battery Management System) | Data from a compatible Battery Management System (BMS) connected to the controller |
| Profiles | Limit settings (speed, current scale, power) that can be activated with a simple gesture |
| Terminal | The firmware includes text commands, including the ability to read the latest error codes |
| LispBM | Embedded scripts, for advanced users |
| Motor Configuration, App Configuration | All motor and input settings, just like on a computer |
Some controllers add their own interface tabs, provided by the hardware manufacturer.
The dashboard display while riding
The RT Data tab displays the main values. To ensure accurate speed and distance readings, enter the number of motor poles, the gear ratio, and the wheel diameter in the Motor Cfg section, under Additional Info. Otherwise, the application will not be able to correctly convert the motor's rotational speed.
Securely mount your phone and adjust everything while stationary. Looking at a screen while riding is distracting: on the road, a quick glance is all you need, and a dedicated display is more suitable. To keep track of your rides, the home page contains a section called "Realtime Data Logging": see our guide on VESC data logging.
The profiles
The Profiles tab allows you to create profiles with a Speed Limit (forward and reverse), a Motor Current Scale in percentage for acceleration and braking, and an optional power limit. A "gentle" profile for a novice passenger or wet ground, a "full" profile for the track: this is the most practical use of the application. Our guide on VESC speed limiting explains the modified parameters.
Here's what we try to avoid doing on our phones
- The initial motor detection process on an unfamiliar machine is now more comfortable and safer, thanks to the computer interface with its large screen.
- An on-the-road firmware update, low battery, or unstable connection.
- Modify a setting while riding.
Workshop tip
Pair the device upon initial setup, and save the configuration from your phone using "Backup Configs": the moment someone changes a setting, you can revert to the known state in just one minute. If you're looking for a system where the controller, display, telemetry, and app are designed together and can be configured from your phone, the RageLink range is coming soon (waiting list). For a Bluetooth module installation on your machine, our workshop offers services by the hour (https://rage-mechanics.com/en/our-products/1529-labor-30-minutes.html).
Frequently Asked Questions
My phone isn't finding the controller, why is that?
The controller may not have a Bluetooth module, the permanent serial port may be disabled, or the application may not have permission to use Bluetooth. Start the search from the VESC Tool, not from the phone's settings.
Does the mobile application provide access to all settings?
Yes, the "Motor Cfg" and "App Cfg" tabs contain the same parameters as the computer version. Navigation is simply less comfortable on a small screen.
Can both controllers of a dual-motor system be adjusted from a smartphone?
Yes: When connected to the main controller, the VESC Tool accesses the other controllers via the CAN bus. The home page also features "Multi Settings," which allows you to write certain groups of settings (limits, FOC settings, general settings) to all controllers simultaneously.
Can anyone else connect to my controller?
Without pairing or a code, yes, if it's within range. Perform the pairing process, and on an NRF module, change the six-digit code.
The displayed speed is incorrect. What settings should I adjust?
Enter the number of poles, the gear ratio, and the actual wheel diameter in the "Additional Info" section, then compare the results with a GPS.