doc/help/Troubleshooting.md
Quick solutions to common Serial Studio issues. If you can't find your problem here, check the Getting More Help section at the bottom.
Problem: Application won't launch, showing error about missing Visual C++ runtime DLLs.
Solution:
Problem: macOS prevents Serial Studio from opening due to security settings.
Solution:
For "damaged" error:
xattr -cr /Applications/Serial\ Studio.app
Run this in Terminal, then try opening again
For "unidentified developer":
Problem: Downloaded AppImage file won't execute.
Solution:
Make the AppImage executable:
chmod +x Serial-Studio-*.AppImage
Run it:
./Serial-Studio-*.AppImage
Problem: AppImage requires FUSE to run.
Solution: Install libfuse2:
Ubuntu/Debian:
sudo apt install libfuse2
Fedora:
sudo dnf install fuse-libs
Arch Linux:
sudo pacman -S fuse2
Problem: Serial Studio can't access serial ports (permission denied error).
Solution:
Add your user to the dialout group:
sudo usermod -a -G dialout $USER
Important: Log out and log back in for changes to take effect
Verify you're in the group:
groups $USER
You should see dialout in the list
Alternative (temporary, not recommended):
sudo chmod 666 /dev/ttyUSB0 # Replace with your port
Possible causes:
Solutions:
Verify device is connected:
Check device is recognized by OS:
Windows:
Linux:
ls /dev/tty* | grep -E 'ttyUSB|ttyACM'
macOS:
ls /dev/tty.*
Install driver if needed (Windows):
Fix permissions (Linux): See Linux serial port permission above
Close other applications using the port:
Possible causes:
Solutions:
Close competing applications:
Try reconnecting the device:
Check permissions (Linux): See permission fix above
Try different USB port
Restart Serial Studio
Possible causes:
Solutions:
Verify baud rate matches device:
Verify device is actually transmitting:
Serial.println() or equivalentDouble-check selected COM port:
Try toggling DTR signal:
Check frame delimiters:
Possible causes:
Solutions:
Verify IP address and port:
ping <ip-address>)Verify device is listening:
telnet <ip-address> <port>
Check firewall:
sudo ufw allow <port>Verify network connectivity:
ping <device-ip>Possible causes:
Solutions:
Verify device is sending to correct IP:
ipconfigifconfig or ip addrCheck firewall allows UDP:
Try listening on all interfaces:
Use network sniffer to verify packets:
Possible causes:
Solutions:
Verify Bluetooth is enabled:
Ensure device is advertising:
Check range:
Restart Bluetooth:
Possible causes:
Solutions:
Verify correct service and characteristic:
Ensure notifications are enabled:
Possible causes:
Solutions:
Check dataset indices:
Check console for JavaScript errors:
Add debugging to parser:
function parse(frame) {
console.log("Input frame:", frame);
let result = frame.split(',');
console.log("Parsed result:", result);
return result;
}
Verify frame format:
Possible causes:
Solutions:
Verify widget requirements:
Check widget type matches data:
For 3D widgets (Accelerometer, Gyroscope, 3D Plot):
Try recreating widget:
Possible causes:
Solutions:
Check release notes for breaking changes
Recreate project file:
Report issue if project file should be compatible
Problem: Console shows no frames being received, or frames not split correctly.
Debugging steps:
Verify delimiters match exactly:
Check raw console output:
Try "No Delimiters" mode:
Check for line ending issues:
\n (LF) - Linux/macOS\r\n (CRLF) - Windows\r (CR) - Old MacProblem: JavaScript parser returns errors or wrong data.
Debugging steps:
Check console for errors:
Add logging:
function parse(frame) {
console.log("=== PARSER START ===");
console.log("Type:", typeof frame);
console.log("Content:", frame);
console.log("Length:", frame.length);
// Your parsing logic
let result = frame.split(',');
console.log("Result:", result);
console.log("=== PARSER END ===");
return result;
}
Verify return value is array:
// CORRECT
return [1, 2, 3];
// WRONG
return "1,2,3"; // Must be array!
Test with simpler parser first:
function parse(frame) {
return frame.split(',');
}
Check decoder method:
frame is stringframe is hex stringframe is base64 stringframe is byte arrayPossible causes:
Solutions:
Optimize parser:
Reduce data rate:
Profile parser performance:
function parse(frame) {
let start = Date.now();
// Your parsing logic
let result = frame.split(',');
let elapsed = Date.now() - start;
if (elapsed > 1) {
console.log("Parse took", elapsed, "ms");
}
return result;
}
Possible causes:
Solutions:
Verify CSV format:
Check file encoding:
Try export from Serial Studio:
Possible causes:
Solutions:
Reduce playback speed:
Close other applications:
For very large files:
See: MQTT Integration - Troubleshooting
Common issues:
See: Protocol-Specific Setup Guides - Modbus
Common issues:
See: Protocol-Specific Setup Guides - CAN Bus
Common issues:
Problem: Pro features are grayed out or show "Requires Pro License".
Possible causes:
Solutions:
Check license status:
Activate license key:
Download official binary:
Check trial status:
Possible causes:
Solutions:
Reduce data rate:
Optimize parser:
Reduce widgets:
Close unused applications
Possible causes:
Solutions:
Check global variables in parser:
// CAREFUL: This array grows forever
let history = [];
function parse(frame) {
history.push(frame); // Memory leak!
return frame.split(',');
}
// BETTER: Limit size
let history = [];
function parse(frame) {
history.push(frame);
if (history.length > 1000) {
history.shift(); // Remove old entries
}
return frame.split(',');
}
Restart Serial Studio periodically for very long sessions
Reduce plot history:
Possible causes:
Solutions:
Reduce widget count:
Use fewer 3D widgets:
Reduce data rate:
Update graphics drivers
Close background applications
If you can't find a solution here, try these resources:
AI-powered Q&A for Serial Studio:
Someone may have already solved your problem:
Ask the community:
Think you found a bug? Report it:
For Pro license holders:
When reporting an issue, please include:
System Information:
Problem Description:
Additional Information:
Example Good Bug Report:
## Problem
Dashboard widgets show "NaN" instead of values
## System
- Serial Studio v3.1.0
- Windows 11 Pro
- Official binary installer
## Steps to Reproduce
1. Connect Arduino Uno via USB (COM3)
2. Configure: Baud 115200, delimiter: \n
3. Load attached project file
4. Open dashboard
## Expected
Gauges should show temperature values (20-30°C)
## Actual
All gauges show "NaN"
## Additional Info
- Console shows: "TypeError: Cannot read property 'split' of undefined"
- Attached: project.json, sample_data.csv
- Screenshot: screenshot.png
Still stuck? Don't hesitate to ask for help on GitHub Discussions. The community is here to help!