From 8404309c5026e15a88c7fba30a2f37f49b41d85b Mon Sep 17 00:00:00 2001 From: Lloyd Date: Tue, 25 Nov 2025 15:00:36 +0000 Subject: [PATCH] Add documentation for pyMC Repeater setup and configuration --- .DS_Store | Bin 0 -> 6148 bytes Hardware-Setup.md | 339 +++++++++++++++++++++ Home.md | 119 +++++++- Installation.md | 263 ++++++++++++++++ Troubleshooting.md | 505 +++++++++++++++++++++++++++++++ config-YAML.md => config-file.md | 22 +- 6 files changed, 1236 insertions(+), 12 deletions(-) create mode 100644 .DS_Store create mode 100644 Hardware-Setup.md create mode 100644 Installation.md create mode 100644 Troubleshooting.md rename config-YAML.md => config-file.md (97%) diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..b6edefff9c1b8b67f387b83f0a944a5ca622852d GIT binary patch literal 6148 zcmeHKF;2r!47DLcB$keh{{%=~nLbr|g3d^&R4SlW=}^W>*|c{-y1xQy+@`u`k$X8s?NxT6A8;7=)_ zRkLVjc%{-?M=xi+Ho+g@Uxr#Q$KtIR=&cwVYsJ^Sx@6bL=Yn0J(-C(%kUs*Z3yli= Gh610CQYu{l literal 0 HcmV?d00001 diff --git a/Hardware-Setup.md b/Hardware-Setup.md new file mode 100644 index 0000000..12864d2 --- /dev/null +++ b/Hardware-Setup.md @@ -0,0 +1,339 @@ +# Hardware Setup Guide + +Complete guide to connecting your SX1262 LoRa module to your Raspberry Pi. + +--- + +## Overview + +pyMC Repeater requires an SX1262 LoRa radio module connected via SPI. This guide covers GPIO wiring, supported hardware, and configuration. + +--- + +## Supported Hardware + +### Raspberry Pi Models +- **Raspberry Pi Zero W** - Compact, low power +- **Raspberry Pi 3** - Good balance of performance and power +- **Raspberry Pi 4** - Best performance +- **Raspberry Pi 5** - Latest, most powerful + +### LoRa Modules (SX1262) +- **Waveshare LoRa HAT** - Direct plug-and-play +- **Ebyte E22** series modules +- **Generic SX1262 breakout boards** +- **Custom boards** with SX1262 chipset + +--- + +## GPIO Pin Mapping + +### Standard Configuration (BCM Numbering) + +| Function | GPIO (BCM) | Physical Pin | +|----------|------------|--------------| +| CS (Chip Select) | GPIO 21 | Pin 40 | +| RESET | GPIO 18 | Pin 12 | +| BUSY | GPIO 20 | Pin 38 | +| IRQ (DIO1) | GPIO 16 | Pin 36 | +| MOSI (SPI) | GPIO 10 | Pin 19 | +| MISO (SPI) | GPIO 9 | Pin 21 | +| SCK (SPI) | GPIO 11 | Pin 23 | +| GND | GND | Pin 6, 9, 14, 20, etc. | +| 3.3V | 3.3V | Pin 1 or 17 | + +### Optional Pins + +| Function | GPIO (BCM) | Usage | +|----------|------------|-------| +| TXEN | -1 (disabled) | TX enable (some modules) | +| RXEN | -1 (disabled) | RX enable (some modules) | +| TX LED | -1 (disabled) | TX activity indicator | +| RX LED | -1 (disabled) | RX activity indicator | + +--- + +## Wiring Diagrams + +### Waveshare LoRa HAT + +The Waveshare SX1262 HAT plugs directly onto the Raspberry Pi GPIO header. No wiring required! + +**Default Pin Configuration:** +```yaml +sx1262: + cs_pin: 21 + reset_pin: 18 + busy_pin: 20 + irq_pin: 16 +``` + +### Generic SX1262 Module + +For generic modules, wire as follows: + +``` +SX1262 Module Raspberry Pi +───────────── ──────────── +VCC (3.3V) ────── Pin 1 (3.3V) +GND ────── Pin 6 (GND) +MOSI ────── Pin 19 (GPIO 10) +MISO ────── Pin 21 (GPIO 9) +SCK ────── Pin 23 (GPIO 11) +NSS/CS ────── Pin 40 (GPIO 21) +RESET ────── Pin 12 (GPIO 18) +BUSY ────── Pin 38 (GPIO 20) +DIO1/IRQ ────── Pin 36 (GPIO 16) +``` + +**⚠️ Important:** +- Never connect 5V to the module (will damage it) +- Double-check pin numbers before powering on +- Use short wires to minimize interference + +--- + +## Configuration + +### Basic Configuration + +Edit `/etc/pymc_repeater/config.yaml`: + +```yaml +sx1262: + # SPI bus configuration + bus_id: 0 + cs_id: 0 + + # GPIO pins (BCM numbering) + cs_pin: 21 + reset_pin: 18 + busy_pin: 20 + irq_pin: 16 + + # Optional features + txen_pin: -1 + rxen_pin: -1 + txled_pin: -1 + rxled_pin: -1 + + # Hardware flags + use_dio3_tcxo: false + is_waveshare: false +``` + +### Waveshare HAT Configuration + +If using Waveshare HAT, enable the flag: + +```yaml +sx1262: + is_waveshare: true + use_dio3_tcxo: false +``` + +### Custom Pin Configuration + +If using different GPIO pins: + +```yaml +sx1262: + cs_pin: 8 # Your custom CS pin + reset_pin: 25 # Your custom RESET pin + busy_pin: 24 # Your custom BUSY pin + irq_pin: 23 # Your custom IRQ pin +``` + +--- + +## Antenna Connection + +### Antenna Types + +**868 MHz (EU):** +- Quarter-wave: ~8.2 cm +- Half-wave: ~16.4 cm +- Commercial 868 MHz antennas + +**915 MHz (US/AU):** +- Quarter-wave: ~7.8 cm +- Half-wave: ~15.6 cm +- Commercial 915 MHz antennas + +### Connection + +1. **Use proper connector** - Usually U.FL or SMA +2. **Check polarity** - Match antenna to module connector +3. **Secure connection** - Loose connections reduce range +4. **Never transmit without antenna** - Can damage radio! + +### Antenna Placement + +- **Vertical orientation** for best omni-directional coverage +- **Clear line of sight** when possible +- **Away from metal objects** (at least 5-10 cm) +- **Higher is better** for maximum range + +--- + +## Testing Hardware + +### Check SPI is Enabled + +```bash +ls -l /dev/spidev* +``` + +Should show: +``` +/dev/spidev0.0 +/dev/spidev0.1 +``` + +### Verify GPIO Access + +```bash +# As repeater user +sudo -u repeater gpio readall +``` + +### Test Service Start + +```bash +sudo systemctl start pymc-repeater +sudo systemctl status pymc-repeater +``` + +Check logs for radio initialization: +```bash +journalctl -u pymc-repeater -n 50 | grep -i radio +``` + +Should see: +``` +Radio hardware initialized +Radio config - Freq: 869.6MHz +Radio config - SF: 8 +``` + +--- + +## Common Hardware Issues + +### Radio Not Detected + +**Symptoms:** Service fails with "Radio initialization failed" + +**Solutions:** +1. Verify SPI is enabled: `lsmod | grep spi` +2. Check GPIO pin numbers in config +3. Verify physical connections +4. Try reseating the HAT or checking wire connections +5. Check module has power (3.3V) + +### Poor Signal/No Reception + +**Symptoms:** Low RSSI, no packets received + +**Solutions:** +1. Check antenna connection +2. Verify antenna matches frequency (868/915 MHz) +3. Move antenna away from metal objects +4. Try different antenna orientation +5. Check TX power setting in config + +### Intermittent Connection + +**Symptoms:** Radio works then stops + +**Solutions:** +1. Check for loose connections +2. Verify power supply is adequate (2.5A+ for Pi 4) +3. Check for overheating (add heatsinks/cooling) +4. Review logs for error patterns +5. Check duty cycle limits aren't being hit + +### Wrong Frequency Detection + +**Symptoms:** "Frequency mismatch" errors + +**Solutions:** +1. Verify `radio.frequency` in config matches antenna +2. Check regional regulations +3. Ensure all network nodes use same frequency + +--- + +## Hardware Compatibility List + +### Tested Configurations + +| Raspberry Pi | LoRa Module | Status | Notes | +|--------------|-------------|--------|-------| +| Pi Zero W | Waveshare HAT | ✅ | supported | +| Pi 3B+ | Waveshare HAT | ✅ | Supported| +| Pi 4 (2GB) | Waveshare HAT | ✅ | Best performance | +| Pi 4 (4GB+) | Waveshare HAT | ✅ | Overkill but works | +| Pi 5 | Waveshare HAT | ✅ | Latest hardware | +| Pi 3B | Generic SX1262 | ✅ | +| Pi Zero W | Ebyte E22 | ✅ | + +### Power Requirements + +| Model | Idle | Active (TX) | Recommended PSU | +|-------|------|-------------|-----------------| +| Pi Zero W | ~120 mA | ~200 mA | 1A | +| Pi 3B+ | ~400 mA | ~600 mA | 2.5A | +| Pi 4 | ~600 mA | ~900 mA | 3A | +| Pi 5 | ~800 mA | ~1.2A | 5A (USB-C PD) | + +--- + +## Advanced Topics + +### TX/RX Enable Pins + +Some modules require TXEN/RXEN pins for power amplifier control: + +```yaml +sx1262: + txen_pin: 13 # Enable when transmitting + rxen_pin: 19 # Enable when receiving +``` + +### LED Indicators + +Add status LEDs: + +```yaml +sx1262: + txled_pin: 5 # Lights when transmitting + rxled_pin: 6 # Lights when receiving +``` + +Wire LEDs with current-limiting resistors (~330Ω for 3.3V). + +### TCXO Configuration + +For modules with DIO3-powered TCXO: + +```yaml +sx1262: + use_dio3_tcxo: true +``` + +--- + +## Next Steps + +1. **[Configuration Guide](Configuration)** - Configure radio parameters +2. **[First Boot](First-Boot)** - Test your hardware +3. **[Troubleshooting](Troubleshooting)** - Fix common issues + +--- + +## Additional Resources + +- [Raspberry Pi GPIO Pinout](https://pinout.xyz/) +- [SX1262 Datasheet](https://www.semtech.com/products/wireless-rf/lora-connect/sx1262) +- [Waveshare Wiki](https://www.waveshare.com/wiki/Main_Page) diff --git a/Home.md b/Home.md index 8719cc9..d0adf86 100644 --- a/Home.md +++ b/Home.md @@ -1 +1,118 @@ -Welcome to the pyMC_Repeater wiki! +# pyMC Repeater Wiki + +Welcome to the **pyMC Repeater** documentation! This wiki provides comprehensive guides for setting up, configuring, and operating your LoRa mesh network repeater. + +--- + +## Quick Start + +New to pyMC Repeater? Start here: + +1. **[Installation Guide](Installation)** - Get your repeater up and running +2. **[Hardware Setup](Hardware-Setup)** - Connect your LoRa radio module +3. **[Configuration Guide](Configuration)** - Configure your repeater settings +4. **[First Boot](First-Boot)** - Verify everything works + +--- + +## Documentation + +### Setup & Configuration +- **[Configuration Reference](Configuration)** - Complete `config.yaml` documentation +- [Hardware Setup](Hardware-Setup) - GPIO wiring and hardware configuration +- [Radio Settings](Radio-Settings) - LoRa parameter tuning guide +- [Network Planning](Network-Planning) - Deployment best practices + +### Features +- [Web Dashboard](Web-Dashboard) - Using the built-in web interface +- [LetsMesh Integration](LetsMesh-Integration) - Cloud monitoring setup +- [MQTT Publishing](MQTT-Publishing) - Local MQTT broker integration +- [Transport Keys](Transport-Keys) - Advanced flood control + +### Operation +- [Monitoring & Logs](Monitoring) - System health and diagnostics +- [Troubleshooting](Troubleshooting) - Common issues and solutions +- [Performance Tuning](Performance-Tuning) - Optimization tips +- [Upgrading](Upgrading) - Update to latest version + +### Advanced Topics +- [Duty Cycle Management](Duty-Cycle) - Regulatory compliance +- [Database Management](Database) - SQLite and RRD data +- [API Reference](API-Reference) - HTTP API endpoints +- [Development](Development) - Contributing to the project + +--- + +## Hardware Support + +pyMC Repeater supports various LoRa hardware: + +- **Raspberry Pi** (Zero W, 3, 4, 5) + SX1262 modules +- **Waveshare LoRa HAT** (SX1262) +- **Custom SX1262 boards** via GPIO configuration + +See [Hardware Compatibility](Hardware-Compatibility) for full list. + +--- + +## Community & Support + +- **GitHub Issues**: [Report bugs or request features](https://github.com/rightup/pyMC_Repeater/issues) +- **Discussions**: [Ask questions and share ideas](https://github.com/rightup/pyMC_Repeater/discussions) +- **LetsMesh Network**: [View live network map](https://analyzer.letsmesh.sh/) + +--- + +## Key Resources + +### Essential Guides +- **[Configuration Reference](Configuration)** - Complete config.yaml guide +- [Installation](Installation) - Step-by-step setup +- [Troubleshooting](Troubleshooting) - Fix common issues + +### Related Projects +- [pyMC_core](https://github.com/rightup/pyMC_core) - MeshCore protocol library +- [pyMC_API](https://github.com/rightup/pyMC_API) - REST API server +- [MeshCore](https://github.com/rightup/MeshCore) - Embedded firmware + +--- + +## What's New + +**Latest Release: v1.0.5** +- JWT token refresh for LetsMesh (no more disconnections!) +- Improved configuration merge on upgrade +- Enhanced trace packet handling +- Performance optimizations + +See [Changelog](Changelog) for full release history. + +--- + +## Quick Links + +| Topic | Description | +|-------|-------------| +| [Configuration](Configuration) | Complete config.yaml reference | +| [Installation](Installation) | Install pyMC Repeater | +| [Hardware Setup](Hardware-Setup) | Wire your LoRa module | +| [Troubleshooting](Troubleshooting) | Common issues & fixes | +| [API Reference](API-Reference) | HTTP API documentation | +| [LetsMesh Setup](LetsMesh-Integration) | Cloud monitoring | + +--- + +## Getting Help + +Having issues? Check these resources: + +1. **[Troubleshooting Guide](Troubleshooting)** - Common problems and solutions +2. **[Configuration Reference](Configuration)** - Verify your settings +3. **[GitHub Issues](https://github.com/rightup/pyMC_Repeater/issues)** - Search existing issues +4. **System Logs**: `journalctl -u pymc-repeater -f` - View real-time logs + +--- + +**Project Maintained by**: [rightup](https://github.com/rightup) +**License**: See [LICENSE](https://github.com/rightup/pyMC_Repeater/blob/main/LICENSE) +**Version**: Compatible with pyMC Repeater v1.0.5+ diff --git a/Installation.md b/Installation.md new file mode 100644 index 0000000..a452362 --- /dev/null +++ b/Installation.md @@ -0,0 +1,263 @@ +# Installation Guide + +Complete guide to installing pyMC Repeater on your Raspberry Pi. + +--- + +## Prerequisites + +### Hardware Requirements +- **Raspberry Pi** (Zero W, 3, 4, or 5) +- **SX1262 LoRa Module** (e.g., Waveshare LoRa HAT) +- **MicroSD Card** (8GB minimum, 16GB+ recommended) +- **Power Supply** (appropriate for your Pi model) +- **Antenna** (868/915 MHz depending on region) + +### Software Requirements +- **Raspberry Pi OS** (Bookworm or newer recommended) +- **Python 3.9+** (included in recent Pi OS) +- **Internet connection** (for initial setup) + +--- + +## Quick Installation + +The easiest way to install pyMC Repeater is using the interactive management script: + +```bash +# Clone the repository +git clone https://github.com/rightup/pyMC_Repeater.git +cd pyMC_Repeater + +# Run the installer +sudo ./manage.sh install +``` + +The installer will: +1. Enable SPI interface (with reboot if needed) +2. Install system dependencies +3. Create service user and directories +4. Install Python packages +5. Configure systemd service +6. Launch interactive radio configuration + +--- + +## Manual Installation + +If you prefer manual installation or need more control: + +### 1. Enable SPI Interface + +```bash +sudo raspi-config +# Navigate to: Interface Options → SPI → Enable +``` + +Or edit `/boot/firmware/config.txt` directly: +```bash +echo "dtparam=spi=on" | sudo tee -a /boot/firmware/config.txt +sudo reboot +``` + +### 2. Install System Dependencies + +```bash +sudo apt-get update +sudo apt-get install -y libffi-dev jq pip python3-rrdtool wget +``` + +### 3. Install yq (YAML processor) + +```bash +YQ_VERSION="v4.40.5" +YQ_BINARY="yq_linux_arm64" # or yq_linux_amd64 for 64-bit x86 +sudo wget -qO /usr/local/bin/yq "https://github.com/mikefarah/yq/releases/download/${YQ_VERSION}/${YQ_BINARY}" +sudo chmod +x /usr/local/bin/yq +``` + +### 4. Create Service User + +```bash +sudo useradd --system --home /var/lib/pymc_repeater --shell /sbin/nologin repeater +sudo usermod -a -G gpio,i2c,spi,dialout repeater +``` + +### 5. Create Directories + +```bash +sudo mkdir -p /opt/pymc_repeater /etc/pymc_repeater /var/log/pymc_repeater /var/lib/pymc_repeater +``` + +### 6. Copy Files + +```bash +sudo cp -r repeater /opt/pymc_repeater/ +sudo cp pyproject.toml README.md /opt/pymc_repeater/ +sudo cp config.yaml.example /etc/pymc_repeater/config.yaml.example +sudo cp config.yaml.example /etc/pymc_repeater/config.yaml +``` + +### 7. Install Python Package + +```bash +cd /opt/pymc_repeater +sudo pip install --break-system-packages -e . +``` + +### 8. Install Systemd Service + +```bash +sudo cp pymc-repeater.service /etc/systemd/system/ +sudo systemctl daemon-reload +sudo systemctl enable pymc-repeater +``` + +### 9. Configure Permissions + +```bash +sudo chown -R repeater:repeater /opt/pymc_repeater /etc/pymc_repeater /var/log/pymc_repeater /var/lib/pymc_repeater +sudo chmod 750 /etc/pymc_repeater /var/log/pymc_repeater /var/lib/pymc_repeater +``` + +### 10. Configure Radio Settings + +Edit `/etc/pymc_repeater/config.yaml` - see [Configuration Guide](Configuration) for details. + +### 11. Start Service + +```bash +sudo systemctl start pymc-repeater +``` + +--- + +## Post-Installation + +### Verify Installation + +Check service status: +```bash +sudo systemctl status pymc-repeater +``` + +View logs: +```bash +journalctl -u pymc-repeater -f +``` + +Access web interface: +``` +http://:8000 +``` + +### Configure Radio + +Run the radio configuration helper: +```bash +cd /path/to/pyMC_Repeater +sudo ./setup-radio-config.sh /etc/pymc_repeater +``` + +Or edit `/etc/pymc_repeater/config.yaml` manually - see [Configuration Reference](Configuration). + +### Set Node Identity + +Generate a new identity: +```bash +# Identity is auto-generated on first start +# Find it in: /var/lib/pymc_repeater/identity.key +``` + +Or provide your own: +```yaml +# In config.yaml: +repeater: + identity_file: "/etc/pymc_repeater/my_identity.key" +``` + +--- + +## Upgrading + +To upgrade to the latest version: + +```bash +cd pyMC_Repeater +git pull +sudo ./manage.sh upgrade +``` + +The upgrade process preserves your configuration and data. + +--- + +## Uninstalling + +To completely remove pyMC Repeater: + +```bash +sudo ./manage.sh uninstall +``` + +This removes all files except a configuration backup in `/tmp/`. + +--- + +## Troubleshooting + +### Service won't start + +Check logs for errors: +```bash +journalctl -u pymc-repeater -n 50 +``` + +Common issues: +- SPI not enabled → Run `sudo raspi-config` +- Wrong GPIO pins → Check `sx1262` section in config +- Permission errors → Verify service user has correct groups + +### No radio detected + +Verify SPI is working: +```bash +ls -l /dev/spidev* +# Should show: /dev/spidev0.0 and /dev/spidev0.1 +``` + +Check module is loaded: +```bash +lsmod | grep spi +``` + +### Can't access web interface + +Check service is running: +```bash +sudo systemctl status pymc-repeater +``` + +Verify port 8000 is listening: +```bash +sudo netstat -tulpn | grep 8000 +``` + +Check firewall rules if using one. + +--- + +## Next Steps + +1. **[Hardware Setup](Hardware-Setup)** - Verify GPIO wiring +2. **[Configuration Guide](Configuration)** - Configure your repeater +3. **[First Boot](First-Boot)** - Test your installation +4. **[LetsMesh Integration](LetsMesh-Integration)** - Enable cloud monitoring + +--- + +## Additional Resources + +- [Troubleshooting Guide](Troubleshooting) +- [Configuration Reference](Configuration) +- [GitHub Issues](https://github.com/rightup/pyMC_Repeater/issues) diff --git a/Troubleshooting.md b/Troubleshooting.md new file mode 100644 index 0000000..a053551 --- /dev/null +++ b/Troubleshooting.md @@ -0,0 +1,505 @@ +# Troubleshooting Guide + +Common issues and solutions for pyMC Repeater. + +--- + +## Quick Diagnostics + +```bash +# 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:** +```bash +journalctl -u pymc-repeater -n 50 +``` + +**Common causes:** + +1. **SPI Not Enabled** + ```bash + 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** + ```bash + cd /opt/pymc_repeater + sudo pip install --break-system-packages -e . + ``` + +4. **Permission Issues** + ```bash + 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:** +```bash +# 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:** + ```bash + lsmod | grep spi + ls -l /dev/spidev* + ``` + +2. **Check GPIO configuration:** + ```yaml + 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:** + ```yaml + 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:** + ```yaml + radio: + tx_power: 14 # Try increasing to 20 + ``` + +4. **Verify other nodes are transmitting** + +5. **Check logs for received packets:** + ```bash + 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:** + ```yaml + radio: + tx_power: 20 # Maximum for most modules + ``` + +3. **Optimize placement:** + - Higher location + - Clear line of sight + - Away from interference sources + +4. **Monitor signal:** + ```bash + # 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:** +```bash +sudo systemctl status pymc-repeater +``` + +**Verify port 8000 listening:** +```bash +sudo netstat -tulpn | grep 8000 +``` + +**Test from Pi itself:** +```bash +curl http://localhost:8000 +``` + +**Check firewall (if enabled):** +```bash +sudo ufw status +sudo ufw allow 8000/tcp +``` + +**Find Pi's IP address:** +```bash +ip add +``` + +### LetsMesh Not Connecting + +**Symptoms:** No status updates on LetsMesh dashboard + +**Check configuration:** +```yaml +letsmesh: + enabled: true + iata_code: "NYC" # Set your location code + broker_index: 0 # 0=EU, 1=US + status_interval: 60 +``` + +**Verify internet connectivity:** +```bash +ping -c 4 mqtt-eu-v1.letsmesh.net +curl -I https://analyzer.letsmesh.sh +``` + +**Check logs for errors:** +```bash +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:** +```yaml +storage: + mqtt: + enabled: true + broker: "localhost" + port: 1883 +``` + +**Test MQTT broker:** +```bash +# Install mosquitto-clients +sudo apt-get install mosquitto-clients + +# Subscribe to test +mosquitto_sub -h localhost -t "meshcore/#" -v +``` + +**Check broker running:** +```bash +sudo systemctl status mosquitto +``` + +--- + +## Configuration Issues + +### Invalid YAML Syntax + +**Error:** `Error parsing config.yaml` + +**Test syntax:** +```bash +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:** +```bash +sudo systemctl restart pymc-repeater +``` + +**Verify config loaded:** +```bash +journalctl -u pymc-repeater -n 50 | grep -i config +``` + +### Settings Reverting After Upgrade + +**Use manage script for upgrades:** +```bash +sudo bash manage.sh upgrade +``` + +This preserves your configuration while adding new options. + +--- + +## Performance Issues + +### High CPU Usage + +**Check current usage:** +```bash +top -u repeater +``` + +**Common causes:** + +1. **DEBUG logging** + ```yaml + logging: + level: INFO # Change from DEBUG + ``` + +2. **High packet rate** - Normal for busy networks + +3. **Database operations** - Check SQLite file size + +**Monitor:** +```bash +# CPU temperature +vcgencmd measure_temp + +# Process stats +ps aux | grep repeater +``` + +### High Memory Usage + +**Check memory:** +```bash +free -h +``` + +**Solutions:** +- Reduce `repeater.cache_ttl` +- Clean up old database records +- Restart service periodically + +### Disk Space Issues + +**Check disk usage:** +```bash +df -h +du -sh /var/lib/pymc_repeater/* +``` + +**Clean up old data:** +```yaml +storage: + retention: + sqlite_cleanup_days: 7 # Reduce from 31 +``` + +**Manual cleanup:** +```bash +# 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:** +```bash +# Restore from backup +sudo cp /etc/pymc_repeater.backup.*/config.yaml /etc/pymc_repeater/ + +# Restart service +sudo systemctl restart pymc-repeater +``` + +**Manual merge:** +```bash +# Compare old and new +diff /etc/pymc_repeater.backup.*/config.yaml /etc/pymc_repeater/config.yaml.example +``` + +### Service Fails After Upgrade + +**Check Python dependencies:** +```bash +cd /opt/pymc_repeater +sudo pip install --break-system-packages -e . --force-reinstall +``` + +**Verify systemd service:** +```bash +sudo systemctl daemon-reload +sudo systemctl restart pymc-repeater +``` + +--- + +## Data/Database Issues + +### Database Corruption + +**Symptoms:** Service crashes, database errors in logs + +**Check integrity:** +```bash +sqlite3 /var/lib/pymc_repeater/repeater.db "PRAGMA integrity_check" +``` + +**Backup and repair:** +```bash +# 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:** +```bash +ls -lh /var/lib/pymc_repeater/*.rrd +``` + +**Recreate if missing:** +```bash +# Service will auto-create on next start +sudo systemctl restart pymc-repeater +``` + +--- + +## Getting More Help + +### Enable Debug Logging + +```yaml +logging: + level: DEBUG +``` + +```bash +sudo systemctl restart pymc-repeater +journalctl -u pymc-repeater -f +``` + +**⚠️ Remember to set back to INFO after debugging** + +### Collect Diagnostic Info + +```bash +# 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](https://github.com/rightup/pyMC_Repeater/issues): + +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 + +- [Configuration Reference](Configuration) +- [Hardware Setup](Hardware-Setup) +- [GitHub Issues](https://github.com/rightup/pyMC_Repeater/issues) +- [GitHub Discussions](https://github.com/rightup/pyMC_Repeater/discussions) diff --git a/config-YAML.md b/config-file.md similarity index 97% rename from config-YAML.md rename to config-file.md index b4edc87..f60d955 100644 --- a/config-YAML.md +++ b/config-file.md @@ -14,7 +14,7 @@ Reference for configuring your pyMC Repeater using `config.yaml`. - [Duty Cycle Management](#duty-cycle-management) - [Storage and Data Management](#storage-and-data-management) - [Local MQTT Publishing](#local-mqtt-publishing) -- [LetsMesh Cloud Integration](#letsmesh-cloud-integration) +- [LetsMesh Integration](#letsmesh-cloud-integration) - [Logging Configuration](#logging-configuration) - [Web Interface Settings](#web-interface-settings) @@ -27,7 +27,7 @@ Basic repeater identity and behavior settings. ### `repeater.node_name` **Type:** `string` **Default:** `"mesh-repeater-01"` -**Description:** Friendly name for your repeater node. Used in adverts, web interface, and LetsMesh cloud. +**Description:** Friendly name for your repeater node. Used in adverts, web interface, and LetsMesh. ```yaml repeater: @@ -354,14 +354,14 @@ Messages published to: --- -## LetsMesh Cloud Integration +## LetsMesh Integration -Publish data to LetsMesh cloud service for network-wide monitoring. +Publish data to LetsMesh service for network-wide monitoring. ### `letsmesh.enabled` **Type:** `boolean` **Default:** `false` -**Description:** Enable/disable LetsMesh cloud publishing. +**Description:** Enable/disable LetsMesh publishing. ```yaml letsmesh: @@ -561,28 +561,28 @@ logging: ## Configuration Tips -### Hardware Setup +### 🔧 Hardware Setup 1. Verify GPIO pin numbers match your hardware (use BCM numbering) 2. Ensure SPI is enabled: `sudo raspi-config` → Interface Options → SPI 3. Test radio connection before deploying -### Radio Tuning +### 📡 Radio Tuning 1. All nodes must use **identical** radio settings 2. Lower spreading factor = faster but shorter range 3. Higher TX power = longer range but more power draw 4. Balance bandwidth vs. range for your deployment -### Network Integration +### 🌐 Network Integration 1. Start with local MQTT disabled, enable after testing 2. Use LetsMesh for cloud monitoring and analytics 3. Filter unnecessary packet types to reduce bandwidth -### Security +### 🔒 Security 1. Keep your identity file secure (contains private key) 2. Use strong passwords for MQTT authentication 3. Consider firewall rules for web interface -### Monitoring +### 📊 Monitoring 1. Use `INFO` level for normal operation 2. Switch to `DEBUG` when troubleshooting 3. Monitor SQLite database size and clean up old data @@ -620,7 +620,7 @@ logging: - [GitHub Repository](https://github.com/rightup/pyMC_Repeater) - [MeshCore Protocol Documentation](https://github.com/rightup/pyMC_core) -- [LetsMesh Cloud Dashboard](https://analyzer.letsmesh.sh/) +- [LetsMesh Dashboard](https://analyzer.letsmesh.sh/) ---