From 3fab0c5ea1ccae48eacba9e40b74cecfc3ba5452 Mon Sep 17 00:00:00 2001 From: Lloyd Date: Fri, 30 Jan 2026 14:06:34 +0000 Subject: [PATCH] Add new guides and update links in documentation - Introduced Identity Management, Development, First Boot, Network Planning, Performance Tuning, Transport Keys, and Web Dashboard guides. - Updated links in Home.md and other documentation to reflect new structure and ensure consistency. - Marked several sections as "coming soon" to indicate future content. --- API-Reference.md | 19 ++ Development.md | 19 ++ First-Boot.md | 19 ++ Home.md | 40 ++-- Identity-Management.md | 459 +++++++++++++++++++++++++++++++++++++++++ Network-Planning.md | 18 ++ Performance-Tuning.md | 18 ++ Transport-Keys.md | 17 ++ Web-Dashboard.md | 18 ++ config-file.md | 3 + 10 files changed, 610 insertions(+), 20 deletions(-) create mode 100644 API-Reference.md create mode 100644 Development.md create mode 100644 First-Boot.md create mode 100644 Identity-Management.md create mode 100644 Network-Planning.md create mode 100644 Performance-Tuning.md create mode 100644 Transport-Keys.md create mode 100644 Web-Dashboard.md diff --git a/API-Reference.md b/API-Reference.md new file mode 100644 index 0000000..c8737da --- /dev/null +++ b/API-Reference.md @@ -0,0 +1,19 @@ +# API Reference + +> **📝 TODO:** This page is on the todo list and will be created soon. + +--- + +## Coming Soon + +This guide will cover: +- HTTP API endpoints +- RESTful API documentation +- Authentication methods +- Request/response formats +- WebSocket connections +- API rate limiting +- Example API calls +- Integration examples + +For now, see the `web_server` section in [config-file.md](config-file.md). diff --git a/Development.md b/Development.md new file mode 100644 index 0000000..493b40b --- /dev/null +++ b/Development.md @@ -0,0 +1,19 @@ +# Development Guide + +> **📝 TODO:** This page is on the todo list and will be created soon. + +--- + +## Coming Soon + +This guide will cover: +- Development environment setup +- Project structure and architecture +- Contributing guidelines +- Code style and standards +- Testing procedures +- Debugging techniques +- Building custom features +- Pull request process + +For now, visit the [GitHub repository](https://github.com/rightup/pyMC_Repeater). diff --git a/First-Boot.md b/First-Boot.md new file mode 100644 index 0000000..8239ba4 --- /dev/null +++ b/First-Boot.md @@ -0,0 +1,19 @@ +# First Boot Guide + +> **📝 TODO:** This page is on the todo list and will be created soon. + +--- + +## Coming Soon + +This guide will cover: +- Verifying your installation works +- Checking radio initialization +- Sending your first advertisement +- Accessing the web interface +- Monitoring initial packet activity +- Common first-boot issues + +For now, see: +- [Installation Guide](Installation.md) +- [Troubleshooting Guide](Troubleshooting.md) diff --git a/Home.md b/Home.md index d0adf86..48822bb 100644 --- a/Home.md +++ b/Home.md @@ -10,36 +10,36 @@ 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 +3. **[Configuration Guide](config-file)** - Configure your repeater settings +4. **[First Boot](First-Boot)** - Verify everything works *(coming soon)* --- ## Documentation ### Setup & Configuration -- **[Configuration Reference](Configuration)** - Complete `config.yaml` documentation +- **[Configuration Reference](config-file)** - 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 +- [Radio Settings](config-file#radio-configuration) - LoRa parameter tuning guide +- [Network Planning](Network-Planning) - Deployment best practices *(coming soon)* ### 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 +- [Web Dashboard](Web-Dashboard) - Using the built-in web interface *(coming soon)* +- [LetsMesh Integration](config-file#letsmesh-integration) - Cloud monitoring setup +- [MQTT Publishing](config-file#local-mqtt-publishing) - Local MQTT broker integration +- [Transport Keys](Transport-Keys) - Advanced flood control *(coming soon)* ### Operation -- [Monitoring & Logs](Monitoring) - System health and diagnostics +- [Monitoring & Logs](Troubleshooting#quick-diagnostics) - System health and diagnostics - [Troubleshooting](Troubleshooting) - Common issues and solutions -- [Performance Tuning](Performance-Tuning) - Optimization tips -- [Upgrading](Upgrading) - Update to latest version +- [Performance Tuning](Performance-Tuning) - Optimization tips *(coming soon)* +- [Upgrading](Installation#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 +- [Duty Cycle Management](config-file#duty-cycle-management) - Regulatory compliance +- [Database Management](config-file#storage-and-data-management) - SQLite and RRD data +- [API Reference](API-Reference) - HTTP API endpoints *(coming soon)* +- [Development](Development) - Contributing to the project *(coming soon)* --- @@ -51,7 +51,7 @@ pyMC Repeater supports various LoRa hardware: - **Waveshare LoRa HAT** (SX1262) - **Custom SX1262 boards** via GPIO configuration -See [Hardware Compatibility](Hardware-Compatibility) for full list. +See [Hardware Compatibility](Hardware-Setup#hardware-compatibility-list) for full list. --- @@ -66,7 +66,7 @@ See [Hardware Compatibility](Hardware-Compatibility) for full list. ## Key Resources ### Essential Guides -- **[Configuration Reference](Configuration)** - Complete config.yaml guide +- **[Configuration Reference](config-file)** - Complete config.yaml guide - [Installation](Installation) - Step-by-step setup - [Troubleshooting](Troubleshooting) - Fix common issues @@ -93,11 +93,11 @@ See [Changelog](Changelog) for full release history. | Topic | Description | |-------|-------------| -| [Configuration](Configuration) | Complete config.yaml reference | +| [Configuration](config-file) | 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 | +| [API Reference](API-Reference) | HTTP API documentation *(coming soon)* | | [LetsMesh Setup](LetsMesh-Integration) | Cloud monitoring | --- diff --git a/Identity-Management.md b/Identity-Management.md new file mode 100644 index 0000000..c4e9dd2 --- /dev/null +++ b/Identity-Management.md @@ -0,0 +1,459 @@ +# Identity Management Guide + +Guide for managing cryptographic identities in pyMC Repeater. + +--- + +## Table of Contents + +- [Understanding Identity](#understanding-identity) +- [Automatic Identity Generation](#automatic-identity-generation) +- [Creating Your Own Identity](#creating-your-own-identity) +- [Identity Configuration Methods](#identity-configuration-methods) +- [Verifying Your Identity](#verifying-your-identity) +- [Identity Security Best Practices](#identity-security-best-practices) +- [Troubleshooting Identity Issues](#troubleshooting-identity-issues) + +--- + +## Understanding Identity + +Each repeater has a unique cryptographic identity consisting of a private key and derived public key. The identity determines your repeater's node address and enables packet signing. + +### Key Components + +- **Private Key:** 64-byte (128 hex characters) Ed25519 key used for signing packets +- **Public Key:** Derived from the private key using Ed25519 scalar multiplication +- **Node Address:** The first byte of the public key (0x00-0xFF) + +### Why Identity Matters + +- **Unique Identification:** Each node has a unique address on the mesh network +- **Packet Signing:** Enables cryptographic verification of packet authenticity +- **Network Trust:** Allows other nodes to verify messages came from your repeater +- **Persistent Identity:** Maintains the same address across restarts + +--- + +## Automatic Identity Generation + +If no identity is configured, the repeater automatically generates a new identity on first startup. + +### Configuration + +```yaml +repeater: + identity_file: null # Auto-generate +``` + +### Behavior + +1. On first startup, generates a random 64-byte Ed25519 private key +2. Derives the public key and node address +3. Stores the identity in the storage directory +4. Reuses the same identity on subsequent runs + +### When to Use + +- Quick testing and development +- Non-production deployments +- When you don't need a specific node address + +--- + +## Creating Your Own Identity + +There are two main approaches to creating a custom identity: + +### Option 1: Generate a New Random Key + +Create a fresh identity file with a cryptographically secure random key. + +**Steps:** + +```bash +# Generate a random 64-byte key +python3 -c "import secrets; print(secrets.token_hex(64))" > /etc/pymc_repeater/identity.key + +# Secure the file permissions +sudo chmod 600 /etc/pymc_repeater/identity.key +sudo chown root:root /etc/pymc_repeater/identity.key +``` + +**Configure in config.yaml:** + +```yaml +repeater: + identity_file: "/etc/pymc_repeater/identity.key" +``` + +**Advantages:** +- Full control over key storage location +- Good for new deployments + +### Option 2: Import from MeshCore Firmware + +If you have a MeshCore firmware device and want your repeater to use that identity (node address), use the `convert_firmware_key.sh` script. + +#### Prerequisites + +1. Extract the 64-byte private key from your MeshCore firmware device +2. Have sudo access to modify configuration files +3. Python 3 with `yaml` and `nacl` packages installed + +#### Script Usage + +```bash +cd /path/to/pyMC_Repeater +sudo ./convert_firmware_key.sh <64-byte-hex-key> [config-path] +``` + +**Parameters:** +- `<64-byte-hex-key>` - The 128 hex character private key from firmware (required) +- `[config-path]` - Path to config.yaml (optional, defaults to `/etc/pymc_repeater/config.yaml`) + +#### Complete Example + +```bash +# Navigate to pyMC_Repeater directory +cd ~/pyMC_Repeater + +# Run the conversion script with your firmware key +sudo ./convert_firmware_key.sh \ + 987BDA619630197351F2B3040FD19B2EE0DEE357DD69BBEEE295786FA78A4D5F298B0BF1B7DE73CBC23257CDB2C562F5033DF58C232916432948B0F6BA4448F2 \ + /etc/pymc_repeater/config.yaml +``` + +#### What the Script Does + +1. **Validates** the key format (must be exactly 128 hex characters) +2. **Derives** the public key using Ed25519 scalar multiplication +3. **Calculates** the node address (first byte of public key) +4. **Creates** a timestamped backup of your current config.yaml +5. **Imports** the key into `mesh.identity_key` field +6. **Offers** to restart the repeater service automatically + +#### Expected Output + +``` +=== MeshCore Firmware Key Import === + +Input (64-byte firmware key): + 987BDA619630197351F2B3040FD19B2E... + +Derived public key: a1b2c3d4e5f6... +Node address: 0xa1 + +Created backup: /etc/pymc_repeater/config.yaml.backup.1234567890 +✓ Successfully updated /etc/pymc_repeater/config.yaml + +Restart pymc-repeater service now? (yes/no): +``` + +#### Important Considerations + +⚠️ **Only one device with the same identity should be active at a time** +- Running multiple devices with the same key simultaneously can cause network confusion +- Other nodes may see conflicting messages from the same address +- Use shared identity only for migration or testing scenarios + +--- + +## Identity Configuration Methods + +There are two ways to configure your repeater's identity: + +### Method 1: Using `identity_file` (Recommended) + +Store the private key in a separate file. + +**Configuration:** + +```yaml +repeater: + identity_file: "/etc/pymc_repeater/identity.key" +``` + +**File Format:** + +The identity file should contain exactly 128 hex characters (64 bytes) representing the private key: + +``` +987BDA619630197351F2B3040FD19B2EE0DEE357DD69BBEEE295786FA78A4D5F298B0BF1B7DE73CBC23257CDB2C562F5033DF58C232916432948B0F6BA4448F2 +``` + +**Advantages:** +- ✅ Clean separation of config and secrets +- ✅ Easier to manage file permissions independently +- ✅ Can be symlinked or mounted from secure storage +- ✅ Simple text format for easy backup and verification +- ✅ No need to modify config.yaml when rotating keys + +**Best for:** +- Production deployments +- Security-conscious setups +- Manual key management + +### Method 2: Using `mesh.identity_key` + +Store the key directly in config.yaml as a binary field. + +**Configuration:** + +```yaml +mesh: + identity_key: !!binary | + mHvdaZYwGXNR8rMED9GbLuDe41fdaaYwGXNR8rMED9G... +``` + +**Notes:** +- This is a YAML binary field (base64-encoded) +- The `convert_firmware_key.sh` script uses this method +- The encoding is handled automatically by the script + + +### Priority Order + +If both methods are configured, the repeater uses this priority: + +1. `repeater.identity_file` (if set and file exists) +2. `mesh.identity_key` (if set in config) +3. Auto-generated identity (if neither is set) + +--- + +## Verifying Your Identity + +After configuring an identity, verify it loaded correctly. + +### Check Service Logs + +```bash +# View recent logs with identity information +sudo journalctl -u pymc-repeater -n 100 | grep -i 'identity\|hash\|address' + +# Follow logs in real-time +sudo journalctl -u pymc-repeater -f | grep -i 'identity\|hash\|address' +``` + +### Expected Output + +``` +INFO - Loading identity from file: /etc/pymc_repeater/identity.key +INFO - Identity loaded successfully +INFO - Node address: 0xa1 +INFO - Public key hash: a1b2c3d4e5f6... +``` + +### Verify Identity File + +```bash +# Check if file exists and has correct permissions +sudo ls -la /etc/pymc_repeater/identity.key + +# Verify key format (should be exactly 128 hex characters) +cat /etc/pymc_repeater/identity.key | wc -c +# Should output: 128 (or 129 if newline is present) + +# Check the key is valid hexadecimal +cat /etc/pymc_repeater/identity.key | grep -E '^[0-9a-fA-F]{128}$' +# Should output the key if valid +``` + +### Verify via Web Interface + +If the web interface is running: + +1. Open `http://:8080` in your browser +2. Check the "Node Info" or "Status" section +3. Verify the node address matches your expectations + +--- + +## Identity Security Best Practices + +### 1. Protect Your Private Key + +The private key is the most sensitive component - anyone with access can impersonate your node. + +```bash +# Set restrictive permissions (owner read-only) +sudo chmod 600 /etc/pymc_repeater/identity.key + +# Ensure root ownership +sudo chown root:root /etc/pymc_repeater/identity.key + +# Verify permissions +ls -la /etc/pymc_repeater/identity.key +# Should show: -rw------- 1 root root +``` + +### 2. Backup Your Identity + +```bash +# Create a secure backup +sudo cp /etc/pymc_repeater/identity.key ~/identity-backup-$(date +%Y%m%d).key + +# Store offline securely +# - USB drive in safe location +# - Encrypted backup service +# - Password manager with secure notes +``` + +### 3. Never Share Your Private Key + +- ❌ Don't share via email, chat, or cloud storage +- ❌ Don't commit to version control (git, etc.) +- ❌ Don't post in public forums or documentation +- ✅ Public keys and addresses are safe to share + +### 4. Use Unique Identities per Repeater + +Unless intentionally sharing identity with a firmware device: + +- Each repeater should have its own unique identity +- Prevents address conflicts on the network +- Easier to track and identify individual nodes +- Improves network security and accountability + +### 5. Rotate Keys When Compromised + +If you suspect a key has been compromised: + +```bash +# Generate a new identity immediately +python3 -c "import secrets; print(secrets.token_hex(64))" | sudo tee /etc/pymc_repeater/identity.key + +# Restart the repeater +sudo systemctl restart pymc-repeater + +# Update documentation with new node address +``` + +### 6. Secure Config Files + +```bash +# Protect config.yaml if using mesh.identity_key +sudo chmod 600 /etc/pymc_repeater/config.yaml +sudo chown root:root /etc/pymc_repeater/config.yaml +``` + +--- + +## Troubleshooting Identity Issues + +### Repeater Won't Start / Identity Errors + +**Check if identity file exists and is readable:** + +```bash +sudo ls -la /etc/pymc_repeater/identity.key +``` + +**Verify key format (should be 128 hex characters):** + +```bash +cat /etc/pymc_repeater/identity.key | wc -c +# Should output: 128 (or 129 if newline present) + +# Remove trailing newline if present +sudo truncate -s 128 /etc/pymc_repeater/identity.key +``` + +**Check logs for specific error:** + +```bash +sudo journalctl -u pymc-repeater -n 50 | grep -i identity +``` + +**Common errors:** + +- `Identity file not found` - Check path in config.yaml matches actual file location +- `Invalid key format` - Ensure file contains exactly 128 hex characters +- `Permission denied` - Check file permissions and ownership + +### Converting Firmware Key Fails + +**Ensure key is exactly 128 hex characters (no spaces/newlines):** + +```bash +echo -n "YOUR_KEY_HERE" | wc -c +# Should output: 128 +``` + +**Verify Python dependencies are installed:** + +```bash +python3 -c "import yaml, nacl; print('Dependencies OK')" +``` + +**If dependencies are missing:** + +```bash +pip3 install pyyaml pynacl +# or +sudo apt install python3-yaml python3-nacl +``` + +**Check config path is correct:** + +```bash +sudo ls -la /etc/pymc_repeater/config.yaml +``` + +**Run script with explicit path:** + +```bash +sudo ./convert_firmware_key.sh YOUR_KEY /etc/pymc_repeater/config.yaml +``` + +### Node Address Doesn't Match Firmware + +If you imported a firmware key but the address is different: + +**Verify key was imported correctly:** + +```bash +# Check if mesh.identity_key exists in config +grep -A 5 "mesh:" /etc/pymc_repeater/config.yaml | grep identity_key +``` + +**Recalculate address from key:** + +```python +# Create a test script: check_address.py +from nacl.bindings import crypto_scalarmult_ed25519_base_noclamp + +key_hex = "YOUR_64_BYTE_KEY_HERE" +key_bytes = bytes.fromhex(key_hex) +scalar = key_bytes[:32] +pubkey = crypto_scalarmult_ed25519_base_noclamp(scalar) +address = pubkey[0] +print(f"Node address should be: 0x{address:02x}") +``` + +Run it: + +```bash +python3 check_address.py +``` + +**Ensure firmware key format is correct:** +- Must be full 64-byte key (128 hex chars) +- Not just the 32-byte scalar portion +- Format: [32-byte scalar][32-byte nonce] + +--- + +## Additional Resources + +- [pyMC_Repeater GitHub](https://github.com/rightup/pyMC_Repeater) +- [MeshCore Firmware](https://github.com/rightup/MeshCore) +- [Configuration Guide](config-file.md) +- [Installation Guide](Installation.md) +- [Troubleshooting Guide](Troubleshooting.md) + +--- + +**Last Updated:** January 2026 +**Compatible with:** pyMC Repeater v1.0.5+ diff --git a/Network-Planning.md b/Network-Planning.md new file mode 100644 index 0000000..bb52c53 --- /dev/null +++ b/Network-Planning.md @@ -0,0 +1,18 @@ +# Network Planning Guide + +> **📝 TODO:** This page is on the todo list and will be created soon. + +--- + +## Coming Soon + +This guide will cover: +- Mesh network topology design +- Repeater placement strategies +- Coverage area estimation +- Multi-hop network planning +- Interference mitigation +- Urban vs rural deployment considerations +- Network capacity planning + +For now, see [Hardware Setup](Hardware-Setup.md) and [config-file.md](config-file.md). diff --git a/Performance-Tuning.md b/Performance-Tuning.md new file mode 100644 index 0000000..230ab65 --- /dev/null +++ b/Performance-Tuning.md @@ -0,0 +1,18 @@ +# Performance Tuning Guide + +> **📝 TODO:** This page is on the todo list and will be created soon. + +--- + +## Coming Soon + +This guide will cover: +- Optimization strategies for high-traffic networks +- CPU and memory usage optimization +- Radio parameter tuning for performance +- Database performance considerations +- Reducing latency +- Power consumption optimization +- Benchmarking and testing methods + +For now, see [config-file.md](config-file.md) for configuration options. diff --git a/Transport-Keys.md b/Transport-Keys.md new file mode 100644 index 0000000..39ae498 --- /dev/null +++ b/Transport-Keys.md @@ -0,0 +1,17 @@ +# Transport Keys Guide + +> **📝 TODO:** This page is on the todo list and will be created soon. + +--- + +## Coming Soon + +This guide will cover: +- Understanding transport key filtering +- Advanced flood control mechanisms +- Configuring known transport keys +- Network segmentation strategies +- Key rotation and management +- Performance impact considerations + +For now, see the `transport_keys` section in [config-file.md](config-file.md). diff --git a/Web-Dashboard.md b/Web-Dashboard.md new file mode 100644 index 0000000..0a2e5b0 --- /dev/null +++ b/Web-Dashboard.md @@ -0,0 +1,18 @@ +# Web Dashboard Guide + +> **📝 TODO:** This page is on the todo list and will be created soon. + +--- + +## Coming Soon + +This guide will cover: +- Accessing the web interface +- Dashboard overview and features +- Real-time packet monitoring +- Network statistics and graphs +- Manual advertisement sending +- Configuration management via web UI +- Security and authentication + +For now, see the `web_server` section in [config-file.md](config-file.md). diff --git a/config-file.md b/config-file.md index f60d955..8c5cbc8 100644 --- a/config-file.md +++ b/config-file.md @@ -7,6 +7,7 @@ Reference for configuring your pyMC Repeater using `config.yaml`. ## Table of Contents - [Repeater Configuration](#repeater-configuration) +- [Identity Management](Identity-Management.md) ⭐ - [Mesh Network Settings](#mesh-network-settings) - [Radio Configuration](#radio-configuration) - [Hardware Configuration (SX1262)](#hardware-configuration-sx1262) @@ -56,6 +57,8 @@ repeater: identity_file: "/etc/pymc_repeater/identity.key" ``` +**For information about identity management, key generation, and importing firmware keys, see the [Identity Management Guide](Identity-Management.md).** + ### `repeater.cache_ttl` **Type:** `integer` (seconds) **Default:** `60`