From c8c86c6abab751aec4dfbbe6010d736cb7bc4538 Mon Sep 17 00:00:00 2001 From: Lloyd Date: Tue, 25 Nov 2025 13:15:58 +0000 Subject: [PATCH] Updated INDEX (markdown) --- INDEX.md | 1 - config-YAML.md | 627 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 627 insertions(+), 1 deletion(-) delete mode 100644 INDEX.md create mode 100644 config-YAML.md diff --git a/INDEX.md b/INDEX.md deleted file mode 100644 index 8719cc9..0000000 --- a/INDEX.md +++ /dev/null @@ -1 +0,0 @@ -Welcome to the pyMC_Repeater wiki! diff --git a/config-YAML.md b/config-YAML.md new file mode 100644 index 0000000..b4edc87 --- /dev/null +++ b/config-YAML.md @@ -0,0 +1,627 @@ +# pyMC Repeater Configuration Guide + +Reference for configuring your pyMC Repeater using `config.yaml`. + +--- + +## Table of Contents + +- [Repeater Configuration](#repeater-configuration) +- [Mesh Network Settings](#mesh-network-settings) +- [Radio Configuration](#radio-configuration) +- [Hardware Configuration (SX1262)](#hardware-configuration-sx1262) +- [Timing and Delays](#timing-and-delays) +- [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) +- [Logging Configuration](#logging-configuration) +- [Web Interface Settings](#web-interface-settings) + +--- + +## 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 cloud. + +```yaml +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. + +```yaml +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. + +```yaml +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. + +```yaml +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. + +```yaml +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). + +```yaml +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) + +```yaml +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) + +```yaml +radio: + frequency: 869618000 +``` + +### `radio.tx_power` +**Type:** `integer` (dBm) +**Default:** `14` +**Description:** Transmit power. Higher = longer range but more power consumption. + +```yaml +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. + +```yaml +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. + +```yaml +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). + +```yaml +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 + +```yaml +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. + +```yaml +sx1262: + cs_pin: 21 # Chip select + reset_pin: 18 # Reset + busy_pin: 20 # Busy status + irq_pin: 16 # Interrupt request +``` + +### Optional Pins + +```yaml +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 + +```yaml +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. + +```yaml +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. + +```yaml +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. + +```yaml +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: +```yaml +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. + +```yaml +storage: + storage_dir: "/var/lib/pymc_repeater" +``` + +### Data Retention + +```yaml +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. + +```yaml +storage: + mqtt: + enabled: true +``` + +### MQTT Broker Settings + +```yaml +storage: + mqtt: + broker: "localhost" + port: 1883 + username: null # Optional authentication + password: null +``` + +### Topic Structure + +```yaml +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 Cloud Integration + +Publish data to LetsMesh cloud service for network-wide monitoring. + +### `letsmesh.enabled` +**Type:** `boolean` +**Default:** `false` +**Description:** Enable/disable LetsMesh cloud publishing. + +```yaml +letsmesh: + enabled: true +``` + +### `letsmesh.iata_code` +**Type:** `string` +**Default:** `"Test"` +**Description:** Airport/location code for grouping nodes geographically (e.g., "SFO", "LHR", "NYC"). + +```yaml +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) + +```yaml +letsmesh: + broker_index: 0 # Use EU broker +``` + +### `letsmesh.status_interval` +**Type:** `integer` (seconds) +**Default:** `60` +**Description:** Heartbeat interval for status updates (uptime, packet counts). + +```yaml +letsmesh: + status_interval: 60 +``` + +### Packet Type Filtering + +Block specific packet types from being published to LetsMesh. + +```yaml +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. + +```yaml +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. + +```yaml +web: + cors_enabled: false +``` + +--- + +## Example Configurations + +### Minimal Configuration (Default Settings) + +```yaml +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 + +```yaml +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 + +```yaml +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 + +- [GitHub Repository](https://github.com/rightup/pyMC_Repeater) +- [MeshCore Protocol Documentation](https://github.com/rightup/pyMC_core) +- [LetsMesh Cloud Dashboard](https://analyzer.letsmesh.sh/) + +--- + +**Configuration Version:** Compatible with pyMC Repeater v1.0.5+ (or current dev branch)