Troubleshooting

Quick solutions to common Serial Studio issues. If you can't find your problem here, check the Getting More Help section at the bottom.

Table of Contents

• Installation Issues
• Connection Issues
• Dashboard & Visualization Issues
• Frame Parsing Issues
• CSV Player Issues
• Pro Feature Issues
• Performance Issues
• Getting More Help

Installation Issues

Windows: "Missing VCRUNTIME140.dll" or similar error

Problem: Application won't launch, showing error about missing Visual C++ runtime DLLs.

Solution:

1. Download and install the Microsoft Visual C++ Redistributable
2. Get it from: Microsoft's official download page
3. Install both x64 and x86 versions if unsure
4. Restart Serial Studio

macOS: "App is damaged and can't be opened" or "Unidentified developer"

Problem: macOS prevents Serial Studio from opening due to security settings.

Solution:

1. For "damaged" error:

   xattr -cr "/Applications/Serial-Studio-Pro.app"
   

   Run this in Terminal, then try opening again. Substitute the exact bundle name shown in /Applications (for example "Serial-Studio-GPL3.app" for the GPL build).

2. For "unidentified developer":

   • Go to System Settings > Privacy & Security
   • Click "Open Anyway" button next to Serial Studio message
   • Or right-click Serial Studio and select "Open"

Linux: AppImage won't run ("Permission denied")

Problem: Downloaded AppImage file won't execute.

Solution:

1. Make the AppImage executable:

   chmod +x Serial-Studio-*.AppImage
   

2. Run it:

   ./Serial-Studio-*.AppImage
   

Linux: AppImage error "fuse: failed to exec fusermount"

Problem: The AppImage mounts itself through FUSE and the host has no working FUSE setup.

Solution: Extract the AppImage and run the contents directly:

./Serial-Studio-Pro-*.AppImage --appimage-extract
./squashfs-root/AppRun

Linux: Serial port permission denied

Problem: Serial Studio can't access serial ports (permission denied error).

Solution:

1. Add your user to the dialout group:

   sudo usermod -a -G dialout $USER
   

2. Important: Log out and log back in for changes to take effect

3. 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

Connection Issues

Serial Port

Port not visible in dropdown

Possible causes:

• Device not connected
• Driver not installed (Windows)
• Permission issues (Linux/macOS)
• Port already in use

Solutions:

1. Verify device is connected:

   • Check USB cable is plugged in
   • Try a different USB port
   • Check device has power (LED indicators)

2. Check device is recognized by OS:

   Windows:

   • Open Device Manager (Win+X → Device Manager)
   • Look under "Ports (COM & LPT)"
   • If you see a yellow warning icon, driver is missing

   Linux:

   ls /dev/tty* | grep -E 'ttyUSB|ttyACM'
   

   macOS:

   ls /dev/tty.*
   

3. Install driver if needed (Windows):

   • CH340/CH341: CH340 driver
   • FTDI: FTDI driver
   • CP210x: Silicon Labs driver

4. Fix permissions (Linux): See Linux serial port permission above

5. Close other applications using the port:

   • Arduino IDE
   • PuTTY / Screen / Minicom
   • Other Serial Studio instances

"Failed to open port" error

Possible causes:

• Port already in use by another application
• Incorrect permissions
• Device disconnected after selection

Solutions:

1. Close competing applications:

   • Arduino IDE Serial Monitor
   • PuTTY, Screen, Minicom, Tera Term
   • Other terminal programs

2. Try reconnecting the device:

   • Unplug USB cable
   • Wait 5 seconds
   • Plug back in
   • Refresh port list in Serial Studio

3. Check permissions (Linux): See permission fix above

4. Try different USB port

5. Restart Serial Studio

Connected but no data appearing

Possible causes:

• Baud rate mismatch
• Device not transmitting
• Wrong COM port selected
• DTR/RTS signal issues

Solutions:

1. Verify baud rate matches device:

   • Common rates: 9600, 115200
   • Check your device's code or documentation
   • Try common baud rates: 9600, 19200, 38400, 57600, 115200

2. Verify device is transmitting:

   • Use Arduino IDE Serial Monitor or another terminal to confirm data output
   • Check device code has Serial.println() or equivalent
   • Verify device is powered and running (LED blink, etc.)

3. Double-check selected COM port:

   • Disconnect device and see which port disappears
   • Reconnect and select that port

4. Try toggling the DTR signal:

   • Setup Panel → turn off Send DTR Signal
   • Some devices reset when DTR is asserted

5. Check frame delimiters:

   • Verify delimiters match what device sends
   • Try "No Delimiters" mode temporarily

Garbled or unreadable console output

Data arrives, but the console shows nonsense instead of readable text. Two different causes look similar but need different fixes:

• Baud rate mismatch: random accented characters, or a scatter of U+FFFD replacement marks (�) mixed with otherwise readable text. Every byte is misread because the UART clock and the device disagree on bit timing. Fix by matching the baud rate exactly to what the device sends.
• Wrong text encoding: the same characters are wrong in the same places every time (for example, a degree symbol always renders as two garbage bytes). The bytes themselves are correct, but the console is decoding them as the wrong charset. Fix from the console's encoding/format setting, not the baud rate.

If toggling the baud rate through the common values doesn't help, suspect encoding instead.

Network Socket (TCP/UDP)

Cannot connect to TCP socket

Possible causes:

• Wrong IP address or port
• Device not listening
• Firewall blocking connection
• Network connectivity issues

Solutions:

1. Verify IP address and port:

   • Double-check device's IP address (try ping <ip-address>)
   • Verify port number matches device configuration
   • Common mistake: Mixing up TCP and UDP

2. Verify device is listening:

   • Use telnet to test:

     telnet <ip-address> <port>
     

   • If "Connection refused", device isn't listening
   • If it hangs, firewall might be blocking

3. Check firewall:

   • Windows: Windows Defender Firewall → Allow an app
   • macOS: System Settings → Privacy & Security → Firewall
   • Linux: sudo ufw allow <port>

4. Verify network connectivity:

   • Make sure computer and device are on same network
   • Try ping <device-ip>

UDP not receiving data

Possible causes:

• Device sending to wrong IP/port
• Firewall blocking UDP
• Network issues

Solutions:

1. Verify device is sending to correct IP:

   • Check device configuration
   • Computer's IP address might have changed (DHCP)
   • Find your IP:
     • Windows: ipconfig
     • Linux/macOS: ifconfig or ip addr

2. Check firewall allows UDP:

   • UDP is more likely to be blocked than TCP
   • Allow Serial Studio in firewall

3. Try listening on all interfaces:

   • Use 0.0.0.0 as listening address (if available)

4. Use network sniffer to verify packets:

   • Wireshark can show if UDP packets are arriving

Bluetooth LE

BLE device not found during scan

Possible causes:

• Device not advertising
• Device already connected to another app
• Bluetooth disabled
• Out of range

Solutions:

1. Verify Bluetooth is enabled:

   • Check OS Bluetooth settings
   • Ensure Bluetooth adapter is present

2. Ensure device is advertising:

   • Reset/power cycle BLE device
   • Check device isn't already connected (phone app, etc.)
   • Many BLE devices stop advertising once connected

3. Check range:

   • Move device closer to computer (within 1-2 meters for testing)

4. Restart Bluetooth:

   • Turn Bluetooth off and on
   • Or restart computer

Connected to BLE but no data

Possible causes:

• Wrong BLE service/characteristic
• Device not sending notifications
• Need to enable notifications

Solutions:

1. Verify correct service and characteristic:

   • Check device documentation for UUIDs
   • Use BLE scanner app to verify service/characteristic

2. Ensure notifications are enabled:

   • Serial Studio should automatically enable notifications
   • Try disconnecting and reconnecting

Dashboard & Visualization Issues

Data shows as "0" or "NaN"

Possible causes:

• Dataset index mismatch
• Parser function error
• Data format incorrect

Solutions:

1. Check dataset indices:

   • Dataset index 1 = array position 0
   • Dataset index 2 = array position 1, etc.
   • Make sure indices match your parser's return array

2. Check console for JavaScript errors:

   • Look for red error messages
   • Fix any syntax errors in parser function

3. Add debugging to parser:

   function parse(frame) {
       console.log("Input frame:", frame);
       let result = frame.split(',');
       console.log("Parsed result:", result);
       return result;
   }
   

4. Verify frame format:

   • Use console output to see raw frames
   • Ensure format matches expectations

Widgets not displaying or showing errors

Possible causes:

• Wrong widget type for data
• Missing required datasets
• Project file corruption

Solutions:

1. Verify widget requirements:

   • Accelerometer widget needs exactly 3 datasets (X, Y, Z)
   • GPS widget needs latitude and longitude datasets
   • See Widget Reference for requirements

2. Check widget type matches data:

   • Don't use gauge for text data
   • Don't use bar for unbounded values

3. Try recreating widget:

   • Delete widget from project
   • Add it again with fresh configuration

Dashboard layout broken after update

Possible causes:

• Project file format changes between versions
• Widget API changes

Solutions:

1. Check release notes for breaking changes

2. Recreate project file:

   • Export CSV of working session
   • Create new project from scratch
   • Test with CSV Player

3. Report issue if project file should be compatible

Frame Parsing Issues

Frames not being detected

Problem: Console shows no frames being received, or frames not split correctly.

Debugging steps:

1. Verify delimiters match exactly:

   • Check delimiters are case-sensitive
   • No extra spaces
   • Use hex view in console to see hidden characters

2. Check raw console output:

   • Look at actual bytes being received
   • Verify delimiters are present in stream

3. Try "No Delimiters" mode:

   • Use custom parser to extract frames
   • Useful for binary protocols

4. Check for line ending issues:

   • Different systems use different line endings:
     • \n (LF) - Linux/macOS
     • \r\n (CRLF) - Windows
     • \r (CR) - Old Mac
   • Try different delimiter combinations

Parser function not working

Problem: JavaScript parser returns errors or wrong data.

Debugging steps:

1. Check console for errors:

   • Look for "SyntaxError", "TypeError", etc.
   • Fix JavaScript syntax errors

2. 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;
   }
   

3. Verify return value is array:

   // CORRECT
   return [1, 2, 3];
   
   // WRONG
   return "1,2,3";  // Must be array!
   

4. Test with simpler parser first:

   function parse(frame) {
       return frame.split(',');
   }
   

5. Check decoder method:

   • Plain Text: frame is string
   • Hexadecimal: frame is hex string
   • Base64: frame is base64 string
   • Binary (Direct): frame is byte array

Parse error: "string expected, got table" / "frame.split is not a function"

Problem: The console repeats one of these on every frame:

• Lua: bad argument #1 to 'byte' (string expected, got table)
• Lua: attempt to index a table value (local 'frame')
• JavaScript: TypeError: frame.split is not a function (or frame.match, frame.charCodeAt)

Cause: The source uses the Binary (Direct) decoder, which hands parse() the frame as raw byte values (a 1-indexed table in Lua, an array in JavaScript), but the parser code was written for a string input.

Solutions:

1. Index the bytes directly instead of using string functions:

   -- Lua: frame[1] is the first byte (1-indexed)
   function parse(frame)
     if #frame < 4 then return {} end
     return { bit.bor(bit.lshift(frame[1], 8), frame[2]), bit.bor(bit.lshift(frame[3], 8), frame[4]) }
   end
   

   // JavaScript: frame[0] is the first byte (0-indexed)
   function parse(frame) {
       if (frame.length < 4) return [];
       return [(frame[0] << 8) | frame[1], (frame[2] << 8) | frame[3]];
   }
   

2. Need multi-byte or float fields? LuaJIT has no string.pack/string.unpack. Decode directly from the byte table with the bit library and arithmetic:

   function parse(frame)
     if #frame < 4 then return {} end
     local value = bit.lshift(frame[1], 8) + frame[2]  -- big-endian uint16
     return { value }
   end
   

3. Or switch the decoder to Plain Text/Hexadecimal in the Project Editor if the device sends text — the decoder and the parser must agree on the frame type. See the decoder table in Frame Parser Scripting.

Dataset transform not working

Problem: You applied a transform(value) function but the dashboard still shows raw values.

Debugging steps:

1. Check the function is named transform. It has to be exactly function transform(value) (Lua) or function transform(value) { (JavaScript). The name is case-sensitive.

2. Click Apply in the transform editor. Changes are only saved when you click Apply. Closing the dialog without Apply discards changes.

3. Test with the built-in Test area. Enter a raw value in the Input field and click Test. If you see an error, fix the function before applying.

4. Handle non-numeric datasets. The transform receives the raw value as a number when it parses as numeric, otherwise as a string. A non-numeric value like "N/A" is passed to transform() as a string, not skipped, so make sure your function handles the string case.

5. Check the console for errors. Compilation errors are logged at connect time. Look for [FrameBuilder] Transform compile error messages.

6. Save and reload the project. If the transform was applied during a live session, saving makes sure it persists. After reload, transforms are recompiled automatically.

See Dataset Value Transforms for the complete reference.

Parsing slow/laggy

Possible causes:

• Complex parser function
• Very high data rate
• Large frames

Solutions:

1. Optimize parser:

   • Avoid unnecessary operations
   • Use string.split() instead of regex where possible
   • Don't create objects, return simple arrays

2. Reduce data rate:

   • Slow down device transmission
   • Increase frame interval

3. 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;
   }
   

CSV Player Issues

Cannot open CSV file

Possible causes:

• File format incorrect
• File corrupted
• Wrong encoding

Solutions:

1. Verify CSV format:

   • First row should be headers
   • Comma-separated values
   • Timestamps in first column

2. Check file encoding:

   • Should be UTF-8
   • Try opening in text editor to verify

3. Try export from Serial Studio:

   • Record a short session
   • Export to CSV
   • Compare format with your file

Playback is choppy

Possible causes:

• Very large file
• High data rate
• System performance

Solutions:

The CSV Player replays at the original capture speed; there is no playback-speed control.

1. Close other applications:

   • Free up system resources

2. For very large or high-rate files:

   • Split the file into smaller segments
   • Export only the columns you need

Pro Feature Issues

MQTT connection fails

See: MQTT Subscriber and MQTT Publisher. Run Test Connection on the Publisher form to probe broker reachability without disturbing live publishing.

Common issues:

• Broker address/port incorrect
• Authentication credentials wrong
• Firewall blocking connection
• TLS/SSL certificate issues
• Client-ID collision between two instances or two sources

Modbus connection fails

See: Protocol-Specific Setup Guides - Modbus

Common issues:

• Wrong slave ID
• Incorrect function code
• Baud rate mismatch (RTU)
• IP/port wrong (TCP)

CAN Bus issues

See: Protocol-Specific Setup Guides - CAN Bus

Common issues:

• Bitrate mismatch
• Missing termination resistors
• Adapter not recognized
• DBC file format errors

Pro features show as locked

Problem: Pro features are grayed out or show a Buy License / Activate prompt.

Possible causes:

• Trial expired
• License key not activated
• Using GPL build instead of official binary

Solutions:

1. Check license status:

   • Click Activate in the toolbar to open the Licensing dialog
   • It shows whether a Pro license or trial is active

2. Activate license key:

   • In the Licensing dialog, paste your license key and click Activate
   • Internet connection required for activation

3. Download official binary:

   • If you compiled from source with GPL-only modules, download the official binary from serial-studio.com
   • The official binary includes Pro features (locked behind license)

4. Check trial status:

   • Trial is 14 days, one trial per version per hardware
   • A new Serial Studio release starts a fresh trial
   • Based on hardware ID (can't reset by reinstalling)

Performance Issues

High CPU usage

Possible causes:

• High data rate
• Complex parser function
• Too many widgets
• Large plot history

Solutions:

1. Reduce data rate:

   • Slow down device transmission
   • Increase frame interval on device

2. Optimize parser:

   • Avoid complex calculations
   • Use efficient string operations

3. Reduce widgets:

   • Use fewer plots
   • Reduce plot history length

4. Close unused applications

Memory usage growing over time

Possible causes:

• Memory leak in parser (global variables)
• Very long session with plot history
• Large CSV logging

Solutions:

1. 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(',');
   }
   

2. Restart Serial Studio periodically for very long sessions

3. Reduce plot history:

   • Shorter time windows
   • Lower sample rate

Slow frame rate / laggy dashboard

Possible causes:

• System performance
• Too many widgets
• High data rate
• Many 3D widgets on a slow CPU

Solutions:

1. Reduce widget count:

   • Serial Studio aims for 60 FPS
   • More widgets = more rendering

2. Use fewer 3D widgets:

   • Accelerometer, Gyroscope, and 3D Plot are among the more CPU-intensive widgets
   • 3D Plot is the only one rendering an actual 3D scene; swap it for Plot or a Gauge where a full 3D view isn't needed

3. Reduce data rate:

   • Dashboard widgets redraw on a fixed timer (60 Hz by default, adjustable in Settings), but a very high data rate still adds CPU load parsing and updating datasets between redraws

4. Update graphics drivers

5. Close background applications

Getting More Help

If you can't find a solution here, try these resources:

1. DeepWiki

AI-powered Q&A for Serial Studio:

• DeepWiki for Serial Studio
• Ask natural language questions
• Get instant AI-generated answers based on documentation

2. Search GitHub Issues

Someone may have already solved your problem:

• Serial Studio Issues
• Use search bar to find similar issues
• Check both open and closed issues

3. GitHub Discussions

Ask the community:

• Serial Studio Discussions
• Post questions, share solutions
• Get help from other users

4. Report a Bug

Think you found a bug? Report it:

• Create new issue
• See Reporting Bugs Effectively below

5. Contact Support

For Pro license holders:

• Email: alex@serial-studio.com
• Include license key and detailed problem description

Reporting Bugs Effectively

When reporting an issue, please include:

System Information:

• Serial Studio version (Help → About)
• Operating system and version
• How you installed (official binary, compiled from source, AppImage, etc.)

Problem Description:

• Clear description of the problem
• Steps to reproduce (numbered list)
• Expected behavior
• Actual behavior

Additional Information:

• Screenshots or screen recording (if applicable)
• Console output (copy from console panel)
• Sample project file (if project-specific)
• Sample data (a few frames or CSV file)

Example Good Bug Report:

## Problem
Dashboard widgets show "NaN" instead of values

## System
- Serial Studio v4.0.3
- 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

See Also

• Getting Started - First-time setup guide
• Data Sources - Connection configuration
• Data Flow - Understanding how parsing works
• Frame Parser Scripting - Lua and JavaScript parser reference
• Widget Reference - Widget requirements and usage
• FAQ - Frequently asked questions

Still stuck? Ask for help on GitHub Discussions. The community is there to help.