Skip to content

Installation

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

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:

# 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

sudo raspi-config
# Navigate to: Interface Options → SPI → Enable

Or edit /boot/firmware/config.txt directly:

echo "dtparam=spi=on" | sudo tee -a /boot/firmware/config.txt
sudo reboot

2. Install System Dependencies

sudo apt-get update
sudo apt-get install -y libffi-dev jq pip python3-rrdtool wget

3. Install yq (YAML processor)

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

sudo useradd --system --home /var/lib/pymc_repeater --shell /sbin/nologin repeater
sudo usermod -a -G gpio,i2c,spi,dialout repeater

5. Create Directories

sudo mkdir -p /opt/pymc_repeater /etc/pymc_repeater /var/log/pymc_repeater /var/lib/pymc_repeater

6. Copy Files

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

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

8. Install Systemd Service

sudo cp pymc-repeater.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable pymc-repeater

9. Configure Permissions

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 for details.

11. Start Service

sudo systemctl start pymc-repeater

Post-Installation

Verify Installation

Check service status:

sudo systemctl status pymc-repeater

View logs:

journalctl -u pymc-repeater -f

Access web interface:

http://<raspberry-pi-ip>:8000

Configure Radio

Run the radio configuration helper:

cd /path/to/pyMC_Repeater
sudo ./setup-radio-config.sh /etc/pymc_repeater

Or edit /etc/pymc_repeater/config.yaml manually - see Configuration Reference.

Set Node Identity

Generate a new identity:

# Identity is auto-generated on first start
# Find it in: /var/lib/pymc_repeater/identity.key

Or provide your own:

# In config.yaml:
repeater:
  identity_file: "/etc/pymc_repeater/my_identity.key"

Upgrading

To upgrade to the latest version:

cd pyMC_Repeater
git pull
sudo ./manage.sh upgrade

The upgrade process preserves your configuration and data.

Uninstalling

To completely remove pyMC Repeater:

sudo ./manage.sh uninstall

This removes all files except a configuration backup in /tmp/.

Troubleshooting

Service won't start

Check logs for errors:

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:

ls -l /dev/spidev*
# Should show: /dev/spidev0.0 and /dev/spidev0.1

Check module is loaded:

lsmod | grep spi

Can't access web interface

Check service is running:

sudo systemctl status pymc-repeater

Verify port 8000 is listening:

sudo netstat -tulpn | grep 8000

Check firewall rules if using one.

Next Steps

  1. Hardware Setup - Verify GPIO wiring
  2. Configuration Guide - Configure your repeater
  3. First Boot - Test your installation
  4. LetsMesh Integration - Enable cloud monitoring

Additional Resources

Clone this wiki locally