Skip to content

Hardware Setup

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

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:

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:

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:

sx1262:
  is_waveshare: true
  use_dio3_tcxo: false

Custom Pin Configuration

If using different GPIO pins:

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

ls -l /dev/spidev*

Should show:

/dev/spidev0.0
/dev/spidev0.1

Verify GPIO Access

# As repeater user
sudo -u repeater gpio readall

Test Service Start

sudo systemctl start pymc-repeater
sudo systemctl status pymc-repeater

Check logs for radio initialization:

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:

sx1262:
  txen_pin: 13  # Enable when transmitting
  rxen_pin: 19  # Enable when receiving

LED Indicators

Add status LEDs:

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:

sx1262:
  use_dio3_tcxo: true

Next Steps

  1. Configuration Guide - Configure radio parameters
  2. First Boot - Test your hardware
  3. Troubleshooting - Fix common issues

Additional Resources

Clone this wiki locally