mirror of
https://github.com/pyMC-dev/pyMC_Repeater.git
synced 2026-07-06 18:01:34 +02:00
Add documentation for pyMC Repeater setup and configuration
Lloyd
Vendored
BIN
Binary file not shown.
+339
@@ -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)
|
||||
+118
-1
@@ -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+
|
||||
|
||||
+263
@@ -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://<raspberry-pi-ip>: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)
|
||||
+505
@@ -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)
|
||||
+11
-11
@@ -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/)
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user