Skip to content

Troubleshooting

Jump to bottom
Lloyd edited this page Nov 25, 2025 · 1 revision

Troubleshooting Guide

Common issues and solutions for pyMC Repeater.

Quick Diagnostics

# Check service status
sudo systemctl status pymc-repeater

# View recent logs
journalctl -u pymc-repeater -n 100

# Live log monitoring
journalctl -u pymc-repeater -f

# Check configuration
yq eval '.' /etc/pymc_repeater/config.yaml

# Verify SPI
ls -l /dev/spidev*

Service Issues

Service Won't Start

Symptoms:

● pymc-repeater.service - failed

Check logs:

journalctl -u pymc-repeater -n 50

Common causes:

  1. SPI Not Enabled

    sudo raspi-config
# Interface Options → SPI → Enable
sudo reboot

  2. Wrong GPIO Configuration

    • Verify sx1262 section in /etc/pymc_repeater/config.yaml
    • Check BCM pin numbers match your hardware

  3. Missing Dependencies

    cd /opt/pymc_repeater
sudo pip install --break-system-packages -e .

  4. Permission Issues

    sudo chown -R repeater:repeater /opt/pymc_repeater /etc/pymc_repeater /var/lib/pymc_repeater
sudo usermod -a -G gpio,spi repeater

Service Crashes/Restarts

Check for issues:

# Recent crashes
journalctl -u pymc-repeater --since "1 hour ago"

Solutions:

  • Reduce logging.level from DEBUG to INFO
  • Add cooling (heatsink/fan)
  • Check power supply capacity
  • Review configuration for errors

Radio/Hardware Issues

Radio Not Detected

Error: Failed to initialize radio hardware

Solutions:

  1. Verify SPI enabled:

    lsmod | grep spi
ls -l /dev/spidev*

  2. Check GPIO configuration:

    sx1262:
  cs_pin: 21
  reset_pin: 18
  busy_pin: 20
  irq_pin: 16

  3. Test with different pins if custom wiring

  4. Verify 3.3V power to module

  5. Check for loose connections

No Packets Received

Symptoms: Service running, but no packets in logs/dashboard

Check:

  1. Radio settings match network:

    radio:
  frequency: 869618000  # Must match other nodes
  spreading_factor: 8
  bandwidth: 62500
  coding_rate: 8
  sync_word: 13380

  2. Antenna connected properly

  3. Check TX power:

    radio:
  tx_power: 14  # Try increasing to 20

  4. Verify other nodes are transmitting

  5. Check logs for received packets:

    journalctl -u pymc-repeater

Poor Signal Quality

Symptoms: Low RSSI, high packet loss

Solutions:

  1. Check antenna:

    • Proper 868/915 MHz antenna
    • Secure connection
    • Vertical orientation
    • Away from metal

  2. Increase TX power:

    radio:
  tx_power: 20  # Maximum for most modules

  3. Optimize placement:

    • Higher location
    • Clear line of sight
    • Away from interference sources

  4. Monitor signal:

    # Watch RSSI/SNR in logs
journalctl -u pymc-repeater -f | grep -i rssi

Network/Connectivity Issues

Can't Access Web Interface

Check service is running:

sudo systemctl status pymc-repeater

Verify port 8000 listening:

sudo netstat -tulpn | grep 8000

Test from Pi itself:

curl http://localhost:8000

Check firewall (if enabled):

sudo ufw status
sudo ufw allow 8000/tcp

Find Pi's IP address:

ip add

LetsMesh Not Connecting

Symptoms: No status updates on LetsMesh dashboard

Check configuration:

letsmesh:
  enabled: true
  iata_code: "NYC"  # Set your location code
  broker_index: 0   # 0=EU, 1=US
  status_interval: 60

Verify internet connectivity:

ping -c 4 mqtt-eu-v1.letsmesh.net
curl -I https://analyzer.letsmesh.sh

Check logs for errors:

journalctl -u pymc-repeater | grep -i letsmesh

Common errors:

  1. JWT token errors - Fixed in v1.0.5+
  2. Wrong broker - Check broker_index
  3. Network blocked - Check firewall for port 443

MQTT Not Publishing

Check configuration:

storage:
  mqtt:
    enabled: true
    broker: "localhost"
    port: 1883

Test MQTT broker:

# Install mosquitto-clients
sudo apt-get install mosquitto-clients

# Subscribe to test
mosquitto_sub -h localhost -t "meshcore/#" -v

Check broker running:

sudo systemctl status mosquitto

Configuration Issues

Invalid YAML Syntax

Error: Error parsing config.yaml

Test syntax:

yq eval '.' /etc/pymc_repeater/config.yaml

Common mistakes:

  • Missing colons after keys
  • Wrong indentation (use 2 spaces)
  • Tabs instead of spaces
  • Unquoted special characters

Configuration Not Applied

After editing config, restart service:

sudo systemctl restart pymc-repeater

Verify config loaded:

journalctl -u pymc-repeater -n 50 | grep -i config

Settings Reverting After Upgrade

Use manage script for upgrades:

sudo bash manage.sh upgrade

This preserves your configuration while adding new options.

Performance Issues

High CPU Usage

Check current usage:

top -u repeater

Common causes:

  1. DEBUG logging

    logging:
  level: INFO  # Change from DEBUG

  2. High packet rate - Normal for busy networks

  3. Database operations - Check SQLite file size

Monitor:

# CPU temperature
vcgencmd measure_temp

# Process stats
ps aux | grep repeater

High Memory Usage

Check memory:

free -h

Solutions:

  • Reduce repeater.cache_ttl
  • Clean up old database records
  • Restart service periodically

Disk Space Issues

Check disk usage:

df -h
du -sh /var/lib/pymc_repeater/*

Clean up old data:

storage:
  retention:
    sqlite_cleanup_days: 7  # Reduce from 31

Manual cleanup:

# Delete old SQLite records
sqlite3 /var/lib/pymc_repeater/repeater.db "DELETE FROM packets WHERE timestamp < strftime('%s', 'now', '-7 days')"

# Vacuum database
sqlite3 /var/lib/pymc_repeater/repeater.db "VACUUM"

Upgrade Issues

Config Merge Errors

Symptoms: Configuration lost or broken after upgrade

Solution:

# Restore from backup
sudo cp /etc/pymc_repeater.backup.*/config.yaml /etc/pymc_repeater/

# Restart service
sudo systemctl restart pymc-repeater

Manual merge:

# Compare old and new
diff /etc/pymc_repeater.backup.*/config.yaml /etc/pymc_repeater/config.yaml.example

Service Fails After Upgrade

Check Python dependencies:

cd /opt/pymc_repeater
sudo pip install --break-system-packages -e . --force-reinstall

Verify systemd service:

sudo systemctl daemon-reload
sudo systemctl restart pymc-repeater

Data/Database Issues

Database Corruption

Symptoms: Service crashes, database errors in logs

Check integrity:

sqlite3 /var/lib/pymc_repeater/repeater.db "PRAGMA integrity_check"

Backup and repair:

# Stop service
sudo systemctl stop pymc-repeater

# Backup
sudo cp /var/lib/pymc_repeater/repeater.db /var/lib/pymc_repeater/repeater.db.backup

# Repair
sqlite3 /var/lib/pymc_repeater/repeater.db ".recover" | sqlite3 /var/lib/pymc_repeater/repeater_new.db
sudo mv /var/lib/pymc_repeater/repeater_new.db /var/lib/pymc_repeater/repeater.db

# Restart
sudo systemctl start pymc-repeater

Missing Statistics

Symptoms: No RRD graphs, missing historical data

Check RRD files:

ls -lh /var/lib/pymc_repeater/*.rrd

Recreate if missing:

# Service will auto-create on next start
sudo systemctl restart pymc-repeater

Getting More Help

Enable Debug Logging

logging:
  level: DEBUG
sudo systemctl restart pymc-repeater
journalctl -u pymc-repeater -f

⚠️ Remember to set back to INFO after debugging

Collect Diagnostic Info

# System info
uname -a
cat /etc/os-release

# Service status
sudo systemctl status pymc-repeater

# Recent logs
journalctl -u pymc-repeater -n 200 > pymc-repeater.log

# Configuration
cat /etc/pymc_repeater/config.yaml > config.txt

# Hardware
gpio readall
ls -l /dev/spidev*

Report Issues

When reporting issues on GitHub:

  1. Describe the problem clearly
  2. Include logs (use DEBUG level)
  3. Share configuration (remove sensitive data)
  4. List hardware (Pi model, LoRa module)
  5. Mention version (cat /opt/pymc_repeater/pyproject.toml)

Additional Resources

Clone this wiki locally