Troubleshooting

Troubleshooting & FAQ

Common issues and solutions for BenchMesh.

Connection Issues

Device Won't Connect

Symptom: Device shows as "disconnected" in dashboard

Solutions:

Check serial port permissions (Linux):

# Check current permissions
ls -l /dev/ttyUSB0

# Add user to dialout group
sudo usermod -a -G dialout $USER

# Log out and back in for changes to take effect
newgrp dialout

# Verify group membership
groups

Verify port path:

# Linux - List USB serial devices
ls -l /dev/ttyUSB*
ls -l /dev/ttyACM*

# Show device info
dmesg | grep tty

# Use udevadm for detailed info
udevadm info --name=/dev/ttyUSB0 --attribute-walk

REM Windows - Check Device Manager
devmgmt.msc
REM Look under "Ports (COM & LPT)"

Check if port is already in use:

# Linux
lsof | grep ttyUSB0

# Kill process using port
sudo pkill -9 -f ttyUSB0

Verify device is powered on and cable is properly connected

Check baud rate matches device specifications:

# config.yaml
devices:
  - id: my-device
    baud: 9600  # Must match device settings

Permission Denied Errors

Error: PermissionError: [Errno 13] Permission denied: '/dev/ttyUSB0'

Solutions:

Add user to dialout group (most common):

sudo usermod -a -G dialout $USER
logout  # Or reboot

Temporary permission (not recommended):
```
sudo chmod 666 /dev/ttyUSB0
```

Create udev rule for persistent permissions:

# Create rule file
sudo nano /etc/udev/rules.d/99-benchmesh.rules

# Add rule (replace with your vendor/product ID)
SUBSYSTEM=="tty", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", MODE="0666", GROUP="dialout"

# Reload rules
sudo udevadm control --reload-rules
sudo udevadm trigger

Find vendor/product ID:

lsusb
# Output: Bus 001 Device 004: ID 1a86:7523 QinHeng Electronics CH340

Device Keeps Disconnecting

Symptom: Device connects then disconnects repeatedly

Solutions:

Check cable quality - Use high-quality USB cables
Check power supply - Device may be underpowered

Disable USB autosuspend (Linux):

# Temporarily disable
echo -1 | sudo tee /sys/module/usbcore/parameters/autosuspend

# Or disable for specific device
echo 'on' | sudo tee /sys/bus/usb/devices/1-1/power/control

Check logs for error patterns:

# Watch logs in real-time
tail -f logs/benchmesh_service.log

# Search for errors
grep ERROR logs/benchmesh_service.log

Increase reconnect timeout in code (if needed)

Multiple Devices on Same Port

Error: SerialException: [Errno 16] Resource busy

Solutions:

Check for other processes:
```
lsof | grep ttyUSB0
```

Stop conflicting services:

sudo systemctl stop modemmanager  # Often interferes with serial devices

Verify config.yaml doesn't have duplicate port entries

Device Communication

Device Not Responding

Symptom: Commands sent but no response received

Solutions:

Verify EOL characters in manifest:
```
{
  "connection": {
    "seol": "\r\n",  // Send EOL
    "reol": "\r\n"   // Receive EOL
  }
}
```
Common EOL combinations:
- \r\n (CRLF) - Most common
- \n (LF) - Unix style
- \r (CR) - Mac style
- "" (empty) - No EOL

Test with driver CLI:

PYTHONPATH=benchmesh-serial-service/src \
python -m benchmesh_service.tools.driver_cli call \
    --id device-1 \
    --method query_identify \
    --config config.yaml

Check timeout settings - Some devices are slow to respond
Verify command syntax matches device manual

Enable debug logging:

PYTHONPATH=benchmesh-serial-service/src \
BENCHMESH_LOG_LEVEL=DEBUG \
python -m benchmesh_service.main --config config.yaml

Garbled or Incorrect Responses

Solutions:

Verify baud rate matches device:

baud: 9600  # Common rates: 9600, 19200, 38400, 57600, 115200

Check serial format (data bits, parity, stop bits):

serial: 8N1  # 8 data bits, No parity, 1 stop bit
# Other formats: 7E1, 7O1, 8E1, 8N2, etc.

Test with serial terminal:

# Install minicom
sudo apt-get install minicom

# Open port
minicom -D /dev/ttyUSB0 -b 9600

# Type commands manually to verify device works
*IDN?

Check for flow control - Some devices need RTS/CTS

IDN Not Matching

Symptom: Device connects but shows wrong identification

Solutions:

Check ID patterns in manifest:

{
  "models": {
    "MY-MODEL": {
      "id_patterns": [
        "ACME PowerPro 3000"  // Must match actual *IDN? response
      ]
    }
  }
}

*Verify IDN? command is correct for your device:

# Some devices use different commands
def query_identify(self):
    self.t.write_line('ID?')  # Not *IDN?
    return self.t.read_until_reol(1024)

Check model override in config:

devices:
  - id: device-1
    model: MY-MODEL  # Force specific model

UI Problems

UI Not Loading

Solutions:

Check backend is running:
```
curl http://localhost:57666/status
```
Verify port is correct - Default is 57666

Check firewall:

# Linux - Allow port
sudo ufw allow 57666

# Check if port is listening
ss -tulpn | grep 57666

Clear browser cache and reload
Check browser console for errors (F12)

WebSocket Not Connecting

Error: "WebSocket connection failed"

Solutions:

Verify WebSocket endpoint is accessible:
```
// Should be ws://localhost:57666/ws
```
Check for proxy issues - Some proxies block WebSockets
Verify backend logs for connection errors

Test with websocat:

# Install websocat
cargo install websocat

# Test connection
websocat ws://localhost:57666/ws

UI Not Updating

Symptom: Device status not refreshing in real-time

Solutions:

Check WebSocket connection in browser dev tools
Verify polling is running in backend logs
Refresh browser (Ctrl+F5 for hard refresh)
Check device is connected and responding

API Issues

404 Not Found

Error: GET /instruments/PSU/device-1/voltage returns 404

Solutions:

Verify device ID matches config:
```
curl http://localhost:57666/instruments
```
Check device class is correct (PSU, DMM, etc.)

Verify method exists on driver:

python -m benchmesh_service.tools.driver_cli methods \
    --id device-1 --config config.yaml

Check URL format:

GET  /instruments/{class}/{id}/{channel}/{method}
POST /instruments/{class}/{id}/{channel}/{method}/{value}

Method Not Found

Error: Method 'voltage' not found on driver

Solutions:

Use correct method prefix:

GET requests need query_ methods
POST requests need set_ methods

# GOOD
def query_voltage(self, channel: int):
    pass

# BAD
def get_voltage(self, channel: int):  # Wrong prefix
    pass

Check API documentation:
```
open http://localhost:57666/docs
```

Authentication Errors

BenchMesh currently has no authentication. If you need security:

Use reverse proxy with auth:

# nginx.conf
location / {
    proxy_pass http://localhost:57666;
    auth_basic "BenchMesh";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

Use SSH tunnel for remote access:

ssh -L 57666:localhost:57666 user@remote-host

Performance

Slow Response Times

Solutions:

Reduce polling frequency in manifest:

{
  "polling": {
    "interval": 5.0  // Increase from 2.0 to 5.0 seconds
  }
}

Disable unnecessary polling:

{
  "polling": {
    "methods": []  // Disable automatic polling
  }
}

Check device response times - Some devices are slow
Use faster serial port if supported (higher baud rate)

High CPU Usage

Solutions:

Check for polling loops in logs
Reduce polling frequency (see above)
Check for stuck threads:
```
# Get thread dump
kill -SIGUSR1 <pid>
```

Profile with cProfile:

python -m cProfile -o profile.stats \
    benchmesh-serial-service/src/benchmesh_service/main.py

Memory Leaks

Solutions:

Restart service periodically (temporary fix)
Check for unclosed connections

Profile memory usage:

import tracemalloc
tracemalloc.start()
# ... run service ...
snapshot = tracemalloc.take_snapshot()
top_stats = snapshot.statistics('lineno')
for stat in top_stats[:10]:
    print(stat)

Installation Problems

pip Install Fails

Error: ERROR: Could not find a version that satisfies the requirement...

Solutions:

Update pip:
```
pip install --upgrade pip
```
Use Python 3.8+:
```
python3 --version
```

Install from requirements.txt:

pip install -r benchmesh-serial-service/requirements.txt

Check Python virtual environment:

python3 -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

npm Install Fails

Solutions:

Use Node.js 16+:
```
node --version
```

Clear npm cache:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Use npm ci instead of npm install:
```
npm ci
```

Import Errors

Error: ModuleNotFoundError: No module named 'benchmesh_service'

Solutions:

Set PYTHONPATH:

export PYTHONPATH=benchmesh-serial-service/src

Install in editable mode:
```
pip install -e benchmesh-serial-service
```
Run from correct directory:
```
cd /path/to/BenchMesh
./start.sh
```

FAQ

General

Q: What devices are supported?

A: BenchMesh supports any serial device with a driver. Included drivers:

TENMA 72-series Power Supplies
OWON SPM3000 Series Power Meters
OWON XDM Series Multimeters
OWON OEL Series Electronic Loads
OWON DGE Series Function Generators

New drivers can be added - see Driver Development.

Q: Can I use BenchMesh remotely?

A: Yes, but use SSH tunneling or VPN for security:

ssh -L 57666:localhost:57666 user@lab-server
# Access via http://localhost:57666

Q: Does BenchMesh work on Windows?

A: Yes. Change port names to COM3, COM4, etc. in config.yaml.

Q: Can I control multiple devices simultaneously?

A: Yes. Add all devices to config.yaml. Each runs in its own thread.

Q: Does BenchMesh save measurements?

A: No. BenchMesh is for control and monitoring. Use Node-RED for data logging:

// Node-RED function node
msg.payload = {
    timestamp: Date.now(),
    voltage: msg.payload.voltage,
    current: msg.payload.current
};
return msg;

Configuration

Q: How do I find my serial port?

# Linux
ls -l /dev/ttyUSB* /dev/ttyACM*
dmesg | grep tty

# Mac
ls -l /dev/cu.*

# Windows
# Check Device Manager > Ports (COM & LPT)

Q: What baud rate should I use?

A: Check your device manual. Common rates: 9600, 19200, 38400, 57600, 115200.

Q: Do I need to restart after changing config?

A: Yes. Changes to config.yaml require backend restart.

Q: Can I have multiple devices on one physical port?

A: No. Each device needs its own serial port.

Development

Q: How do I add a new device driver?

A: See Driver Development Guide.

Q: Can I use BenchMesh as a library?

A: Yes:

from benchmesh_service.serial_manager import SerialManager

config = {...}  # Load config
manager = SerialManager(config)
manager.start()

# Use devices
status = manager.get_device_status('device-1')

Q: How do I contribute?

A: See Contributing Guide. We welcome:

New device drivers
Bug fixes
Documentation improvements
Feature requests

Q: Can I use BenchMesh commercially?

A: Yes. BenchMesh is MIT licensed. See LICENSE.

Automation

Q: How do I automate measurements?

A: Use Node-RED for automation. See Automation Guide.

Q: Can I call the API from Python/JavaScript?

A: Yes:

import requests

# Get device status
r = requests.get('http://localhost:57666/instruments')
devices = r.json()

# Set voltage
r = requests.post('http://localhost:57666/instruments/PSU/psu-1/1/voltage/12.0')

// Get device status
const response = await fetch('http://localhost:57666/instruments');
const devices = await response.json();

// Set voltage
await fetch('http://localhost:57666/instruments/PSU/psu-1/1/voltage/12.0', {
  method: 'POST'
});

Q: Can I schedule automated tests?

A: Yes, use cron with Node-RED flows or direct API calls:

# crontab -e
0 * * * * curl -X POST http://localhost:57666/instruments/PSU/psu-1/1/output/true