Skip to content

config file

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

pyMC Repeater Configuration Guide

Reference for configuring your pyMC Repeater using config.yaml.

Table of Contents

Repeater Configuration

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.

repeater:
  node_name: "my-home-repeater"

repeater.latitude / repeater.longitude

Type: float
Default: 0.0
Range: Latitude: -90 to 90, Longitude: -180 to 180
Description: Geographic coordinates for your repeater. Optional but recommended for sending adverts with location and rendering maps within the Web UI.

repeater:
  latitude: 51.5074
  longitude: -0.1278

repeater.identity_file

Type: string or null
Default: null
Description: Path to a file containing the private key (64 hex characters). If null, a new identity is generated on first run.

repeater:
  identity_file: "/etc/pymc_repeater/identity.key"

repeater.cache_ttl

Type: integer (seconds)
Default: 60
Description: How long duplicate packets are remembered to prevent re-forwarding the same packet.

repeater:
  cache_ttl: 60

repeater.use_score_for_tx

Type: boolean
Default: false
Description: Enable quality-based packet filtering and adaptive transmission delays based on packet SNR and size.

repeater:
  use_score_for_tx: false

repeater.score_threshold

Type: float
Default: 0.3
Description: Reserved for future features. Currently has no effect on packet processing.

repeater.send_advert_interval_hours

Type: integer (hours)
Default: 10
Range: 0 (disabled) to 24+
Description: Automatic advertisement broadcast interval. Set to 0 to disable (manual only via web interface).

repeater:
  send_advert_interval_hours: 10  # Advertise every 10 hours

Mesh Network Settings

mesh.global_flood_allow

Type: boolean
Default: true
Description: Global flood policy. Controls whether the repeater forwards flood packets by default.

  • true: Allow all flood packets
  • false: Deny all flood packets (unless allowed by specific transport key)
mesh:
  global_flood_allow: true

Radio Configuration

LoRa radio parameters. Critical: Without this section the system will not start. Equally, if incorrect, the system will fail to start.

radio.frequency

Type: integer (Hz)
Default: 869618000 (869.618 MHz - EU)
Description: Radio frequency in Hz. Common frequencies:

  • EU: 869618000 (869.618 MHz)
  • US: 915000000 (915 MHz)
  • AU: 923000000 (923 MHz)
radio:
  frequency: 869618000

radio.tx_power

Type: integer (dBm)
Default: 14
Description: Transmit power. Higher = longer range but more power consumption.

radio:
  tx_power: 14

radio.bandwidth

Type: integer (Hz)
Default: 62500 (62.5 kHz)
Options: 7800, 10400, 15600, 20800, 31250, 41700, 62500, 125000, 250000, 500000
Description: LoRa bandwidth. Lower = longer range, higher = faster data rate.

radio:
  bandwidth: 62500

radio.spreading_factor

Type: integer
Default: 8
Range: 7 to 12
Description: LoRa spreading factor. Higher = longer range but slower data rate.

radio:
  spreading_factor: 8

radio.coding_rate

Type: integer
Default: 8
Range: 5 to 8
Description: Forward error correction coding rate (4/5, 4/6, 4/7, or 4/8).

radio:
  coding_rate: 8

radio.preamble_length

Type: integer (symbols)
Default: 17
Description: LoRa preamble length.

radio.sync_word

Type: integer
Default: 13380
Description: LoRa network ID. Devices with different sync words cannot communicate.

radio.crc_enabled

Type: boolean
Default: true
Description: Enable CRC checking for packet integrity.

Hardware Configuration (SX1262)

GPIO pin configuration for SX1262 LoRa module.

SPI Configuration

sx1262:
  bus_id: 0     # SPI bus (usually 0)
  cs_id: 0      # Chip select (usually 0)

GPIO Pins (BCM Numbering)

Important: Use BCM pin numbering, not physical pin numbers.

sx1262:
  cs_pin: 21      # Chip select
  reset_pin: 18   # Reset
  busy_pin: 20    # Busy status
  irq_pin: 16     # Interrupt request

Optional Pins

sx1262:
  txen_pin: -1    # TX enable (-1 to disable)
  rxen_pin: -1    # RX enable (-1 to disable)
  txled_pin: -1   # TX LED indicator (-1 to disable)
  rxled_pin: -1   # RX LED indicator (-1 to disable)

Hardware Flags

sx1262:
  use_dio3_tcxo: false      # Enable DIO3 TCXO power supply
  is_waveshare: false       # Waveshare hardware compatibility mode

Timing and Delays

Transmission delay configuration for different routing modes.

delays.tx_delay_factor

Type: float
Default: 1.0
Description: Multiplier for flood mode transmission delays. Higher values = more delay before forwarding.

delays:
  tx_delay_factor: 1.0

delays.direct_tx_delay_factor

Type: float
Default: 0.5
Description: Multiplier for direct mode transmission delays. Lower = faster forwarding for direct packets.

delays:
  direct_tx_delay_factor: 0.5

Duty Cycle Management

Control radio airtime to comply with regulations (e.g., EU 1% duty cycle).

duty_cycle.enforcement_enabled

Type: boolean
Default: false
Description: Enable/disable duty cycle enforcement.

duty_cycle:
  enforcement_enabled: false

duty_cycle.max_airtime_per_minute

Type: integer (milliseconds)
Default: 3600
Description: Maximum transmission time per minute. Default of 3600ms = 6% duty cycle.

For EU 1% duty cycle:

duty_cycle:
  enforcement_enabled: true
  max_airtime_per_minute: 600  # 1% of 60000ms

Storage and Data Management

storage.storage_dir

Type: string (path)
Default: "/var/lib/pymc_repeater"
Description: Directory for SQLite database and RRD files.

storage:
  storage_dir: "/var/lib/pymc_repeater"

Data Retention

storage:
  retention:
    sqlite_cleanup_days: 31  # Delete SQLite records older than 31 days

RRD Archives (automatic):

  • 1 minute resolution for 1 week
  • 5 minute resolution for 1 month
  • 1 hour resolution for 1 year

Local MQTT Publishing

Publish packet data to a local MQTT broker (e.g., Mosquitto, Home Assistant).

storage.mqtt.enabled

Type: boolean
Default: false
Description: Enable/disable local MQTT publishing.

storage:
  mqtt:
    enabled: true

MQTT Broker Settings

storage:
  mqtt:
    broker: "localhost"
    port: 1883
    username: null  # Optional authentication
    password: null

Topic Structure

storage:
  mqtt:
    base_topic: "meshcore/repeater"

Messages published to:

  • {base_topic}/{node_name}/packet - Packet data
  • {base_topic}/{node_name}/advert - Advertisement messages

Example: meshcore/repeater/my-home-repeater/packet

LetsMesh Integration

Publish data to LetsMesh service for network-wide monitoring.

letsmesh.enabled

Type: boolean
Default: false
Description: Enable/disable LetsMesh publishing.

letsmesh:
  enabled: true

letsmesh.iata_code

Type: string
Default: "Test"
Description: Airport/location code for grouping nodes geographically (e.g., "SFO", "LHR", "NYC").

letsmesh:
  iata_code: "NYC"

letsmesh.broker_index

Type: integer
Default: 0
Options:

  • 0 - Europe (mqtt-eu-v1.letsmesh.net)
  • 1 - US West (mqtt-us-v1.letsmesh.net)
letsmesh:
  broker_index: 0  # Use EU broker

letsmesh.status_interval

Type: integer (seconds)
Default: 60
Description: Heartbeat interval for status updates (uptime, packet counts).

letsmesh:
  status_interval: 60

Packet Type Filtering

Block specific packet types from being published to LetsMesh.

letsmesh:
  disallowed_packet_types:
    - TRACE      # Don't publish trace packets
    - ACK        # Don't publish acknowledgments

Available packet types:

  • REQ - Requests
  • RESPONSE - Responses
  • TXT_MSG - Text messages
  • ACK - Acknowledgments
  • ADVERT - Advertisements
  • GRP_TXT - Group text messages
  • GRP_DATA - Group data
  • ANON_REQ - Anonymous requests
  • PATH - Path packets
  • TRACE - Trace packets
  • RAW_CUSTOM - Custom raw packets

Logging Configuration

logging.level

Type: string
Default: "INFO"
Options: DEBUG, INFO, WARNING, ERROR
Description: Logging verbosity level.

logging:
  level: INFO

logging.format

Type: string
Default: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
Description: Log message format (Python logging format).

Web Interface Settings

web.cors_enabled

Type: boolean
Default: false
Description: Enable CORS headers for web API. Required if accessing web interface from different domain.

web:
  cors_enabled: false

Example Configurations

Minimal Configuration (Default Settings)

repeater:
  node_name: "my-repeater"
  latitude: 51.5074
  longitude: -0.1278

mesh:
  global_flood_allow: true

radio:
  frequency: 869618000
  tx_power: 14
  bandwidth: 62500
  spreading_factor: 8
  coding_rate: 8

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

Production Configuration with LetsMesh

repeater:
  node_name: "rooftop-repeater-01"
  latitude: 40.7128
  longitude: -74.0060
  send_advert_interval_hours: 10

mesh:
  global_flood_allow: true

radio:
  frequency: 915000000  # US frequency
  tx_power: 20
  bandwidth: 62500
  spreading_factor: 8
  coding_rate: 8

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

duty_cycle:
  enforcement_enabled: false

letsmesh:
  enabled: true
  iata_code: "NYC"
  broker_index: 1  # US broker
  status_interval: 60
  disallowed_packet_types:
    - TRACE
    - ACK

logging:
  level: INFO

Home Assistant Integration

repeater:
  node_name: "home-mesh-repeater"

radio:
  frequency: 869618000
  tx_power: 14

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

storage:
  mqtt:
    enabled: true
    broker: "192.168.1.100"  # Home Assistant IP
    port: 1883
    username: "mqtt_user"
    password: "mqtt_password"
    base_topic: "meshcore/repeater"

logging:
  level: INFO

Configuration Tips

🔧 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

  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

  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

  1. Keep your identity file secure (contains private key)
  2. Use strong passwords for MQTT authentication
  3. Consider firewall rules for web interface

📊 Monitoring

  1. Use INFO level for normal operation
  2. Switch to DEBUG when troubleshooting
  3. Monitor SQLite database size and clean up old data
  4. Check duty cycle compliance in regulated regions

Troubleshooting

Repeater won't start

  • Check GPIO pin configuration
  • Verify SPI is enabled
  • Check logs: journalctl -u pymc-repeater -f

No packets received

  • Verify radio settings match network
  • Check frequency is correct for region
  • Ensure antenna is properly connected

LetsMesh not connecting

  • Verify internet connectivity
  • Check broker_index (0=EU, 1=US)
  • Ensure iata_code is set
  • Look for JWT token errors in logs
  • Check if you can access https://analyzer.letsmesh.sh from the same network as the Pi

High CPU usage

  • Reduce logging.level from DEBUG to INFO
  • Check for excessive packet traffic
  • Monitor duty cycle enforcement

Additional Resources

Configuration Version: Compatible with pyMC Repeater v1.0.5+ (or current dev branch)

Clone this wiki locally