Skip to content

Troubleshooting

Jump to bottom
Brian Rodriguez edited this page Dec 9, 2025 · 2 revisions

Troubleshooting Guide

Installation Issues

Python Version Error

Error: "Python 3.10 or higher is required"

Solution:

python --version
# If < 3.10, install newer Python
# Use python3.10 or python3.11 explicitly

Dependency Installation Fails

Error: "Could not find a version that satisfies the requirement"

Solution:

# Update pip
python -m pip install --upgrade pip

# Install with verbose output
pip install -r requirements.txt -v

# If still fails, try without cache
pip install -r requirements.txt --no-cache-dir

Serial Communication Issues

Permission Denied (Linux)

Error: "Permission denied: /dev/ttyUSB0"

Solution:

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

# Or run with sudo (not recommended)
sudo python app.py

Port Not Found

Error: "Serial port COM11 not found"

Solution:

  1. Check connected devices:

    • Windows: Device Manager → Ports
    • Linux: ls /dev/tty*
    • macOS: ls /dev/cu.*

  2. Update MODBUS_PORT in .env

  3. Verify USB-to-serial adapter is connected

No Response from Sensor

Error: "No response from slave 1"

Checklist:

  1. Verify sensor power (LED indicator)
  2. Check A/B wiring polarity (swap if needed)
  3. Confirm baudrate matches sensor (default 9600)
  4. Try different slave IDs (1, 2, or 247)
  5. Test with Modbus diagnostic tool first

Application Errors

Module Import Errors

Error: "ModuleNotFoundError: No module named 'dash'"

Solution:

# Activate virtual environment first
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Linux/macOS

# Verify activation
which python  # Should show .venv path

# Reinstall if needed
pip install -r requirements.txt

Database Errors

Error: "database is locked"

Solution:

# Close all connections
pkill -f app.py

# Check for lock file
rm sensor_data.db-wal sensor_data.db-shm

# Restart application
python app.py

Port Already in Use

Error: "Address already in use: 8050"

Solution:

# Find process using port 8050
netstat -ano | findstr :8050  # Windows
lsof -i :8050  # Linux/macOS

# Kill process
taskkill /PID <PID> /F  # Windows
kill -9 <PID>  # Linux/macOS

# Or change port in .env
PORT=8051

Data Issues

No Data in Graphs

Check:

  1. Terminal output for Modbus errors
  2. Database has data: sqlite3 sensor_data.db "SELECT COUNT(*) FROM data_2025_12;"
  3. Time period selection (try "All data")
  4. Browser console for JavaScript errors (F12)

Incorrect Values

Possible causes:

  1. Wrong register addresses in .env
  2. Sensor needs calibration
  3. Data format mismatch (division by 10)
  4. Electrical interference

Verification:

import minimalmodbus
instrument = minimalmodbus.Instrument('COM11', 1)
instrument.serial.baudrate = 9600
temp = instrument.read_register(1, 0, 4)
print(f"Raw value: {temp}, Actual: {temp/10}")

Data Gaps

Check:

  1. Terminal logs for connection errors during gap
  2. System logs for power events
  3. Serial cable quality (replace if old)
  4. USB power management settings (disable selective suspend)

Graphs Look "Smoothed" or Less Detailed

This is normal behavior when viewing long time ranges:

Adaptive downsampling automatically aggregates data for performance:

  • 6 hours: Shows 1-minute averages (~360 points)
  • 1 day: Shows 5-minute averages (~288 points)
  • 1 month: Shows 1-hour averages (~720 points)
  • 1 year: Shows 1-day averages (~365 points)

Why this happens:

  • Browser cannot efficiently render 1+ million points
  • Visual trends are preserved even with aggregation
  • Performance is instant regardless of data volume

To see more detail:

  • Select shorter time range (< 1 hour for full resolution)
  • Use historical replay slider for specific moments
  • Check DEBUG_LOGGING=True to see downsampling statistics

Example console output with DEBUG_LOGGING:

📊 Query voor laatste 360 minuten (vanaf 2025-12-09 08:00:00)
   → Aantal relevante tabellen: 1
   → Opgehaalde datapunten: 18720
   → Downsampled: 18720 → 360 punten (-98.1%)

Performance Issues

High CPU Usage

Solutions:

  1. Increase graph update interval in callbacks.py
  2. Reduce data retention period
  3. Use data aggregation for old data
  4. Close browser developer tools

Memory Leaks

Monitor memory:

# Windows
tasklist /FI "IMAGENAME eq python.exe"

# Linux
ps aux | grep python

If memory grows continuously:

  1. Restart application daily (cron job)
  2. Check for database bloat (VACUUM)
  3. Report issue on GitHub

Slow Database Queries

Optimization:

sqlite3 sensor_data.db
PRAGMA journal_mode=WAL;
PRAGMA synchronous=NORMAL;
ANALYZE;

Browser Issues

Dashboard Not Loading

Check:

  1. Application is running (check terminal)
  2. Correct URL: http://localhost:8050
  3. Firewall allows connection
  4. Try different browser
  5. Clear browser cache

Graphs Not Updating

Solutions:

  1. Hard refresh: Ctrl+F5
  2. Disable browser extensions
  3. Check browser console (F12) for errors
  4. Try incognito mode

Network Access Issues

Cannot Access from Other Devices

Checklist:

  1. HOST=0.0.0.0 in .env
  2. Firewall allows port 8050
  3. Server and client on same network
  4. Use server IP, not localhost
  5. Router allows local connections

Windows Firewall:

netsh advfirewall firewall add rule name="XY-MD02" dir=in action=allow protocol=TCP localport=8050

Getting Help

If issue persists:

  1. Check existing issues: https://github.com/CervezaStallone/XY-MD02_WebApp/issues
  2. Enable DEBUG=True in .env for detailed logs
  3. Create new issue with:
    • Python version
    • Operating system
    • Complete error message
    • Steps to reproduce
    • Terminal output

Clone this wiki locally