adam/LoRa-Mesh-Analyzer
1
0
Fork 0
mirror of https://github.com/eddieoz/LoRa-Mesh-Analyzer.git synced 2026-08-07 09:12:56 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: Restructure and expand project documentation, add contribution guidelines and license, and update reporting dependencies.

Browse Source
This commit is contained in:
eddieoz
2025-11-28 21:35:17 +02:00
parent ded1de6b2f
commit 6366baae8d
12 changed files with 370 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+68
View File
@@ -0,0 +1,68 @@
# Architecture Overview
The LoRa Mesh Analyzer is structured as a modular Python application. This document outlines the key components and their responsibilities.
## Directory Structure
```
LoRa-Mesh-Analyzer/
├── mesh_analyzer/ # Core package
│ ├── monitor.py # Main application loop and orchestration
│ ├── analyzer.py # Passive health check logic
│ ├── active_tests.py # Active testing logic (Traceroute, etc.)
│ ├── reporter.py # Report generation (Markdown/HTML)
│ ├── route_analyzer.py# Route analysis and topology mapping
│ ├── config_validator.py # Configuration validation
│ └── utils.py # Shared utility functions
├── scripts/ # Standalone scripts and tools
│ ├── report_generate.py # Tool to regenerate reports from JSON
│ └── ...
├── reports/ # Generated reports and data
├── tests/ # Unit tests
├── config.yaml # User configuration
└── main.py # Entry point
```
## Core Components
### `monitor.py`
The central coordinator. It:
1. Initializes the Meshtastic interface.
2. Loads configuration.
3. Runs the main loop:
- Collects node data.
- Triggers auto-discovery or priority node selection.
- Orchestrates active tests.
- Invokes the analyzer and reporter.
### `analyzer.py`
Responsible for passive analysis of the mesh. It checks for:
- **Congestion**: High Channel Utilization.
- **Spam**: High Airtime usage.
- **Placement**: Routers without GPS, redundant routers.
- **Configuration**: Deprecated roles, bad hop limits.
### `active_tests.py`
Handles active network probing. It:
- Sends traceroute requests.
- Parses responses.
- Manages timeouts and rate limiting.
### `reporter.py`
Generates human-readable reports. It:
- Takes analysis results and test data.
- Formats them into Markdown or HTML.
- Saves raw data to JSON for persistence.
### `route_analyzer.py`
Analyzes the topology based on traceroute data. It:
- Identifies common relays (backbone nodes).
- Detects bottlenecks (single points of failure).
- Calculates link quality metrics.
## Data Flow
1. **Collection**: `monitor.py` collects raw node data from the Meshtastic interface.
2. **Testing**: `active_tests.py` probes specific nodes and adds results to the dataset.
3. **Analysis**: `analyzer.py` and `route_analyzer.py` process the raw data and test results to identify issues and patterns.
4. **Reporting**: `reporter.py` formats the findings into a report and saves the state to JSON.
docs/configuration.md
+90
View File
@@ -0,0 +1,90 @@
# Configuration Guide
The `config.yaml` file controls the behavior of the Meshtastic Network Monitor. This guide explains each configuration option.
## Core Settings
### `log_level`
- **Description**: Sets the verbosity of the logging output.
- **Values**: `debug`, `info`, `warn`, `error`.
- **Default**: `info`.
## Auto-Discovery Settings
These settings control how the monitor automatically finds nodes to test when `priority_nodes` is empty.
### `analysis_mode`
- **Description**: Determines the strategy for selecting target nodes.
- **Values**:
- `distance`: Selects a mix of nearest and furthest nodes.
- `router_clusters`: Selects nodes that are within a certain radius of identified routers.
- **Default**: `distance`.
### `cluster_radius`
- **Description**: The radius (in meters) around a router to search for nodes when `analysis_mode` is set to `router_clusters`.
- **Default**: `2000`.
### `auto_discovery_roles`
- **Description**: A list of node roles to prioritize for testing. The monitor will look for nodes with these roles in the specified order.
- **Values**: `ROUTER`, `ROUTER_LATE`, `REPEATER`, `CLIENT`, `CLIENT_MUTE`, `TRACKER`, etc.
### `auto_discovery_limit`
- **Description**: The maximum number of nodes to select for active testing in each cycle.
- **Default**: `5`.
## Reporting Settings
### `report_cycles`
- **Description**: The number of full testing cycles to complete before generating a report.
- **Default**: `1`.
### `report_output_formats`
- **Description**: The formats in which to generate the report.
- **Values**: `markdown`, `html`.
- **Default**: `['markdown']`.
## Active Testing Settings
### `traceroute_timeout`
- **Description**: The time (in seconds) to wait for a traceroute response before giving up.
- **Default**: `90`.
### `active_test_interval`
- **Description**: The minimum time (in seconds) to wait between sending test packets to different nodes. This prevents flooding the network.
- **Default**: `30`.
### `hop_limit`
- **Description**: The maximum number of hops for traceroute packets.
- **Default**: `7`.
### `priority_nodes`
- **Description**: A list of specific Node IDs to test. If this list is populated, auto-discovery is disabled, and only these nodes are tested.
- **Format**: `"!<NodeID>"` (e.g., `"!12345678"`).
## Manual Geolocation Overrides
### `manual_positions`
- **Description**: Allows you to manually specify the latitude and longitude for nodes that do not report their position (e.g., fixed routers without GPS).
- **Format**:
```yaml
manual_positions:
"!nodeid":
lat: 59.12345
lon: 24.12345
```
## Analysis Thresholds
These thresholds determine when the monitor flags a node or network condition as an issue.
### `thresholds`
- **`channel_utilization`**: The percentage of channel utilization above which a node is flagged for congestion (Default: `25.0`).
- **`air_util_tx`**: The percentage of transmit airtime above which a node is flagged for spamming (Default: `7.0`).
- **`router_density_threshold`**: The minimum distance (in meters) between routers. Routers closer than this are flagged as redundant (Default: `2000`).
- **`active_threshold_seconds`**: Nodes seen within this time window are considered "active" (Default: `7200` i.e., 2 hours).
## Network Size Settings
### `max_nodes_for_long_fast`
- **Description**: The recommended maximum number of nodes for the `LONG_FAST` preset. If the network size exceeds this, a warning is generated.
- **Default**: `60`.
docs/report_generation.md
+38
View File
@@ -0,0 +1,38 @@
# Report Generation Tool
The `report_generate.py` script allows you to regenerate Markdown reports from existing JSON data files. This is useful for:
- Re-applying analysis logic after updating the code or configuration.
- Generating reports in different formats (e.g., if you forgot to enable HTML).
- Debugging report generation issues without re-running long tests.
## Usage
```bash
python3 scripts/report_generate.py <json_file_path> [--output <output_path>]
```
### Arguments
- `json_file_path`: Path to the JSON data file (e.g., `reports/report-20251128-145548.json`).
- `--output`, `-o`: (Optional) Custom output path for the Markdown report. If not specified, the report is generated in the `reports/` directory with a new timestamp.
## Examples
**Regenerate a report from a JSON file:**
```bash
python3 scripts/report_generate.py reports/report-20251128-145548.json
```
**Regenerate a report and save it to a specific file:**
```bash
python3 scripts/report_generate.py reports/report-20251128-145548.json --output my_custom_report.md
```
## How it Works
1. **Loads Data**: Reads the raw node data, test results, and session metadata from the JSON file.
2. **Applies Configuration**: Uses the configuration embedded in the JSON file, but applies any manual positions from the *current* `config.yaml` to ensure up-to-date geolocation.
3. **Re-runs Analysis**: Re-initializes the `NetworkHealthAnalyzer` and re-runs the analysis on the loaded data. This means any improvements to the analysis logic in the code will be reflected in the new report.
4. **Generates Report**: Uses the `NetworkReporter` to generate the Markdown report, incorporating the new analysis results.
docs/usage.md
+70
View File
@@ -0,0 +1,70 @@
# Usage Guide
This guide covers how to run the Meshtastic Network Monitor in various modes.
## Prerequisites
Ensure you have installed the dependencies:
```bash
pip install -r requirements.txt
```
## Basic Execution
### USB / Serial Connection
If your Meshtastic device is connected via USB:
```bash
python3 main.py
```
The monitor will automatically detect the serial port.
### TCP / Network Connection
If your Meshtastic device is on the network (e.g., WiFi):
```bash
python3 main.py --tcp <IP_ADDRESS>
```
Example:
```bash
python3 main.py --tcp 192.168.1.10
```
## Command Line Options
| Option | Description |
| :--- | :--- |
| `--tcp <IP>` | Connect to a device via TCP/IP instead of Serial. |
| `--ignore-no-position` | Suppress warnings about routers without a valid GPS position. Useful for portable routers. |
| `--help` | Show the help message and exit. |
## Running in the Background
To run the monitor continuously, you might want to use `nohup` or a systemd service.
**Using nohup:**
```bash
nohup python3 main.py > monitor.log 2>&1 &
```
## Interpreting Output
The monitor outputs logs to the console (and `monitor.log` if redirected).
### Common Log Messages
- **`INFO - Connected to radio...`**: Successful connection to the Meshtastic device.
- **`INFO - Starting analysis cycle...`**: The monitor is beginning a new round of checks.
- **`WARNING - Congestion: Node X reports ChUtil Y%`**: The specified node is experiencing high channel utilization.
- **`INFO - Sending traceroute to...`**: The monitor is actively testing a node.
## Reports
Reports are generated in the `reports/` directory.
- **Format**: `report-YYYYMMDD-HHMMSS.md` (and `.html` if enabled).
- **Data**: `report-YYYYMMDD-HHMMSS.json` contains the raw data.
See [Report Generation](report_generation.md) for details on how to regenerate reports.