Saving and reading VESC data: real-time monitoring, log files, and analysis
A VESC controller continuously measures voltage, current, temperature, motor speed, and detects faults. The VESC Tool can display these values in real-time and save them to files for later review. This is the most useful tool for tuning a machine and understanding failures: instead of guessing, you can see what actually happened. Here's how to record data on a computer and on a phone, and how to interpret the results.
The essentials
- On a computer, the "Realtime Data" page displays graphs and saves the data to a CSV file.
- On the phone, the "Realtime Data Logging" section of the home page records data while you are riding.
- Each time the recording feature is activated, a new, date-stamped file is created.
- The "Log Analysis" page reads the log files, plots graphs, and, with a GPS, displays the trajectory.
- The recorded speed is the electrical speed (ERPM): you need to divide it by the number of pole pairs.
View live data
Once connected, enable the real-time data transmission using the corresponding button in the VESC Tool toolbar. The "Realtime Data" page, located in the "Data Analysis" section, will then display graphs showing: current, voltage, duty cycle, speed, MOSFET and motor temperatures, and, in FOC mode, the position as seen by the observer.
For many checks, a direct connection is sufficient, whether the wheel is raised or on a test stand: is the motor temperature reasonable, does the current increase as expected, does the battery voltage drop under load? For actual riding, data logging is essential.
Save to computer
On the Realtime Data page, the record button (Log Realtime Data to File) writes the data to a CSV file. The destination folder is selected in the Settings section, under Paths. An embedded laptop is not very practical on an electric scooter: on a computer, you mainly record tests on a test bench or with the wheel raised.
Save to phone
In the mobile application, the home page contains a section called "Realtime Data Logging". You select a folder, then check the box "Enable RT Data Logging". According to the software's help documentation, each time the box is checked, a new file is created with the date and time. Unchecking and then rechecking the box allows you to segment the recordings, for example, one file per riding session. The phone must remain connected via Bluetooth throughout the ride: see our guide VESC Tool on phone.
There are also cards that can record data without a phone. For example, the VESC Express is described by its official repository as a data logger with Wi-Fi and Bluetooth capabilities. The "Log Analysis" page in the VESC Tool can also browse files from a connected device, in addition to local files.
What a file contains
The VESC Tool help documentation describes the format: one line per measurement, with columns separated by semicolons. The most useful measurements are:
| Column | Meaning | What people are looking for in this |
|---|---|---|
| v_in | Input voltage (battery) | Voltage drop under load, and voltage at the end of the ride |
| current_in | Battery current | What we are truly demanding from the battery and the BMS (Battery Management System) |
| current_motor | Motor current | Requested torque, limits reached |
| id, iq | Currents on the D and Q axes (FOC) | Demagnetization current (Id), torque current (Iq) |
| temp_mos, temp_motor | MOSFET and motor temperatures, in °C | Temperature increase, power reduction |
| rpm (revolutions per minute) | Electric speed | Divide by the number of pole pairs |
| duty_now | Cycle ratio, from -1 to 1 | Close to its limit, the motor is operating at its maximum speed |
| amp-hours, watt-hours | Energy consumed (and recovered, as indicated in the "charged" columns) | The actual power consumption during a ride |
| fault_code | Error in progress | The precise timing of the cutoff |
| vesc_id | CAN identifier of the controller | Distinguishing controllers for a dual-motor system |
A clarification regarding the data: the timestamp for each line of data is recorded by the VESC Tool upon reception, not by the controller itself. The interval between two lines of data may vary slightly depending on the quality of the connection.
Please review and analyze
The "Log Analysis" page in VESC Tool allows you to open CSV files (Open CSV file...), plot selected columns as graphs, display statistics, and, if the data contains GPS coordinates, display the trajectory on a map. You can export the graphs as images or PDFs. Because the file is a simple CSV, a spreadsheet program can also open it.
Three readings that are always relevant
- Sudden power loss during acceleration: Observe `v_in` and `current_in` just before the event. A voltage drop followed by a complete shutdown points to a problem with the battery or the BMS (Battery Management System); a `fault_code` appearing indicates an issue with the controller.
- Progressive power loss: Observe the `temp_mos` and `temp_motor` values. If they reach the reduction thresholds, it indicates thermal protection is being triggered.
- Current Setting: Compare the `current_motor` value to the set limit. If the current never reaches the limit, it means another limit (battery, temperature, voltage) is being reached first. See our guide on VESC current limits.
Going further: Telemetry
The VESC Tool logging feature is an excellent workshop tool. When racing, we also aim to correlate the data with the position on the track, the lap, and the sector: this is the role of telemetry, explained in our guide on telemetry in racing. For a SmartDisplay, our EB6 GPS module (10/25 Hz) connects to the CAN bus and provides precise positioning. To learn more about racing on circuits, also see the page for our team E'trott Racing.
Workshop tip
Record a "normal" run when the machine is operating correctly and save the file. When a problem arises, comparing two files from the same route will immediately reveal what has changed: a voltage drop that is more significant, a motor that heats up faster, or a current that reaches its limit sooner.
Frequently Asked Questions
Where are the files saved?
On a computer, you can find it in the folder you selected in the "Settings" section, under "Paths." On a phone, it's located in the folder you chose in the "Realtime Data Logging" section of the home page.
Why does the RPM column display such large values?
This is the electrical speed. Divide it by the number of motor pole pairs to obtain the actual revolutions per minute (RPM).
Can both controllers of a dual-motor system be recorded?
The files contain a "vesc_id" column that identifies the controller. The data that is recorded depends on the tool and connection used; check the first file to ensure that both identifiers are present if you need them.
The Bluetooth connection is dropping during recording. What can be done?
Bring the phone closer to the module, ensuring it's positioned away from the power cables, and cut the recordings into shorter files to avoid losing everything.
Can I open these files in a spreadsheet program?
Yes, these are CSV files with semicolons as separators.