meshmap 0.1.0__tar.gz

meshmap-0.1.0/.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run:*)",
+      "Bash(python -m py_compile:*)",
+      "Bash(python3 -m py_compile:*)",
+      "Bash(python3:*)",
+      "Bash(grep:*)",
+      "Bash(find:*)",
+      "Bash(uv pip install:*)",
+      "Bash(/Users/ajo/work/meshmap/tests/test_crypto.py:*)",
+      "Bash(python -m pytest:*)",
+      "Bash(make test:*)"
+    ]
+  }
+}

meshmap-0.1.0/.github/workflows/README.md

@@ -0,0 +1,152 @@
+# GitHub Actions Workflows
+
+This directory contains CI/CD workflows for meshmap.
+
+## Workflows
+
+### 🧪 [tests.yml](tests.yml)
+**Complete test suite** - Runs on every push and PR
+
+- **Triggers**: Push to main/develop, all PRs, manual dispatch
+- **What it does**:
+  - **Always runs the full test suite** (all 16+ tests)
+  - Tests on Python 3.12 and 3.13
+  - Tests on Ubuntu and macOS
+  - Runs linting (ruff)
+  - Runs type checking (mypy)
+  - Generates coverage reports
+  - Uploads to Codecov (optional)
+
+**Jobs**:
+- `test` - Linux tests with full coverage
+- `test-macos` - macOS compatibility tests (full suite)
+- `check-formatting` - Code style checks
+
+**Philosophy**: Always run everything. No shortcuts, no quick checks. Every commit gets the full treatment.
+
+## Status Badges
+
+Add these badges to your README.md:
+
+```markdown
+![Tests](https://github.com/YOUR_USERNAME/meshmap/actions/workflows/tests.yml/badge.svg)
+![Python Version](https://img.shields.io/badge/python-3.12%2B-blue)
+![Coverage](https://img.shields.io/codecov/c/github/YOUR_USERNAME/meshmap)
+```
+
+## Running Workflows Locally
+
+### Act (GitHub Actions locally)
+```bash
+# Install act
+brew install act  # macOS
+# or download from: https://github.com/nektos/act
+
+# Run full test suite
+act -j test
+
+# Run macOS tests
+act -j test-macos
+```
+
+### Manual test run (same as CI)
+```bash
+# Exactly what CI runs:
+uv pip install -e ".[dev]"
+uv run pytest tests/ -v --cov=meshmap --cov-report=term
+uv run ruff check meshmap/ tests/
+uv run mypy meshmap/
+```
+
+## Configuration
+
+### Python Versions
+Currently testing on:
+- Python 3.12 (primary)
+- Python 3.13 (compatibility)
+
+To add more versions, edit `matrix.python-version` in [tests.yml](tests.yml).
+
+### Operating Systems
+Currently testing on:
+- Ubuntu Latest (primary)
+- macOS Latest (compatibility)
+
+To add Windows, add `windows-latest` to `matrix.os`.
+
+### Coverage Reporting
+
+Coverage is uploaded to Codecov automatically if you:
+1. Create account at https://codecov.io
+2. Connect your GitHub repo
+3. Add `CODECOV_TOKEN` to GitHub secrets (optional)
+
+Disable by removing the "Upload coverage" step.
+
+## Troubleshooting
+
+### "uv command not found"
+The `astral-sh/setup-uv@v5` action installs uv. If it fails:
+1. Check you're using the latest action version
+2. Try with `uv` installed via pip as fallback
+
+### Tests fail on Python 3.13
+Check if dependencies are compatible:
+```bash
+uv pip install -e ".[dev]" --python 3.13
+```
+
+### macOS tests fail
+Some dependencies might have macOS-specific issues. Check:
+- PyNaCl compilation (needs libsodium)
+- Cryptography library (needs OpenSSL)
+
+Add to workflow if needed:
+```yaml
+- name: Install system dependencies (macOS)
+  run: brew install libsodium
+```
+
+## Optimization Tips
+
+### Cache Dependencies
+Currently enabled via:
+```yaml
+- uses: astral-sh/setup-uv@v5
+  with:
+    enable-cache: true
+```
+
+### Parallel Jobs
+Tests run in parallel by default:
+- Multiple Python versions run concurrently
+- Linux and macOS jobs run concurrently
+
+### Skip CI
+Add to commit message to skip CI:
+```
+git commit -m "docs: update README [skip ci]"
+```
+
+## Security
+
+### Secrets
+If tests need secrets (e.g., API keys):
+1. Add to GitHub repository secrets
+2. Reference in workflow:
+   ```yaml
+   env:
+     SECRET_KEY: ${{ secrets.SECRET_KEY }}
+   ```
+
+### Dependabot
+Enable Dependabot to keep actions updated:
+```yaml
+# .github/dependabot.yml
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+```

meshmap-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,118 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.12", "3.13"]
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+        cache-dependency-glob: "pyproject.toml"
+
+    - name: Install dependencies
+      run: |
+        uv pip install --system -e ".[dev]"
+
+    - name: Run linting (ruff)
+      run: |
+        uv run ruff check meshmap/ tests/
+      continue-on-error: true
+
+    - name: Run type checking (mypy)
+      run: |
+        uv run mypy meshmap/
+      continue-on-error: true
+
+    - name: Run all tests with coverage
+      run: |
+        # Always run the full test suite
+        uv run pytest tests/ -v --cov=meshmap --cov-report=xml --cov-report=term
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        file: ./coverage.xml
+        flags: unittests
+        name: codecov-umbrella
+        fail_ci_if_error: false
+      continue-on-error: true
+
+    - name: Generate coverage badge
+      if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest'
+      run: |
+        echo "Coverage report generated"
+        uv run coverage report
+
+  test-macos:
+    name: Test on macOS (Python 3.12)
+    runs-on: macos-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+
+    - name: Install dependencies
+      run: |
+        uv pip install --system -e ".[dev]"
+
+    - name: Run all tests
+      run: |
+        # Full test suite on macOS
+        uv run pytest tests/ -v --cov=meshmap --cov-report=term
+
+  check-formatting:
+    name: Check code formatting
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+
+    - name: Install ruff
+      run: |
+        uv pip install --system ruff
+
+    - name: Check formatting
+      run: |
+        uv run ruff format --check meshmap/ tests/

meshmap-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+
+# Testing & coverage
+.coverage
+.pytest_cache/
+
+# Virtual environments
+.venv/
+
+# Keys / secrets
+my_real_key.txt
+mykey
+myotherkey
+
+# Local reference repos
+ref/
+
+# uv
+uv.lock

meshmap-0.1.0/CLAUDE.md

@@ -0,0 +1,31 @@
+# meshmap
+
+## Project Overview
+meshmap is a Python tool for scanning and mapping meshcore networks. It builds a network graph by:
+- Discovering nearby nodes
+- Accessing guest pages of repeaters to find adjacent nodes
+- Collecting map coordinates for each node
+
+## Tech Stack
+- Python 3.12+
+- uv for package management and tooling
+
+## Development Setup
+- Use `uv` for dependency management
+- Run commands via the Makefile for consistency
+- Follow PEP 8 style guidelines
+
+## Project Structure
+```
+meshmap/
+├── meshmap/          # Main package directory
+├── tests/            # Test files
+├── pyproject.toml    # Project configuration
+└── Makefile          # Development commands
+```
+
+## Key Considerations
+- Network scanning should be done responsibly
+- Handle connection errors gracefully
+- Consider rate limiting when accessing guest pages
+- Store graph data efficiently

meshmap-0.1.0/Makefile

@@ -0,0 +1,45 @@
+.PHONY: help install dev test lint format clean run
+
+help: ## Show this help message
+	@echo 'Usage: make [target]'
+	@echo ''
+	@echo 'Available targets:'
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install production dependencies
+	uv pip install -e .
+
+dev: ## Install development dependencies
+	uv pip install -e ".[dev]"
+
+test: ## Run tests with coverage
+	uv run pytest
+
+lint: ## Run linting checks
+	uv run ruff check
+	uv run mypy meshmap
+
+lint-fix: ## Run linting fixes
+	uv run ruff check --fix .
+
+format: ## Format code with ruff
+	uv run ruff format .
+
+clean: ## Clean up generated files
+	rm -rf build/
+	rm -rf dist/
+	rm -rf *.egg-info
+	rm -rf .pytest_cache/
+	rm -rf .coverage
+	rm -rf htmlcov/
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name '*.pyc' -delete
+
+run: ## Run meshmap
+	uv run meshmap
+
+sync: ## Sync dependencies
+	uv pip sync
+
+lock: ## Update lock file
+	uv pip compile pyproject.toml -o requirements.txt

meshmap-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: meshmap
+Version: 0.1.0
+Summary: A tool to scan and map meshcore network graphs
+Requires-Python: >=3.12
+Requires-Dist: click>=8.0.0
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: meshcore
+Requires-Dist: pynacl>=1.5.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rich>=13.0.0
+Description-Content-Type: text/markdown
+
+# meshmap
+
+A tool for scanning and mapping [meshcore](https://github.com/ripplebiz/MeshCore) radio networks. It discovers nearby nodes, logs in to each reachable repeater to enumerate its neighbours, and builds a graph of the network — including GPS coordinates where available.
+
+## Install
+
+Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
+
+```sh
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Clone and install
+git clone https://github.com/mangelajo/meshmap
+cd meshmap
+uv sync
+```
+
+The `meshmap` command is then available via `uv run meshmap`.
+
+## Usage
+
+All commands require `-p` to specify the serial port of your connected device.
+
+```
+meshmap -p PORT [OPTIONS] COMMAND
+```
+
+**Global options** (apply to all commands):
+
+| Flag | Description |
+|------|-------------|
+| `-p, --serial-port` | Serial port (e.g. `/dev/ttyUSB0`, `COM3`) |
+| `--sniff` | Print decoded RF packets in real time |
+| `--sniff-key PATH` | Private key file for decryption (repeatable) |
+| `-d, --debug` | Low-level meshcore debug output |
+
+## Commands
+
+### `explore` — map the network graph
+
+The main command. Discovers 0-hop repeaters, then recursively logs in to each one to fetch its neighbour list, building a full network graph. Saves to a JSON file after each node so it can be paused and resumed.
+
+```sh
+# First scan
+uv run meshmap -p /dev/ttyUSB0 explore
+
+# Resume a previous scan, open live visualisation in browser
+uv run meshmap -p /dev/ttyUSB0 explore --resume --serve
+
+# Re-visit already-explored nodes to refresh SNR data
+uv run meshmap -p /dev/ttyUSB0 explore --resume --refresh
+
+# Retry nodes that failed on the last run
+uv run meshmap -p /dev/ttyUSB0 explore --resume --retry
+
+# Limit exploration to 3 hops, save to a custom file
+uv run meshmap -p /dev/ttyUSB0 explore --depth 3 -o my-network.json
+
+# Full run with live packet sniffing and web visualisation
+uv run meshmap -p /dev/ttyUSB0 --sniff --sniff-key mykey.txt explore --serve --resume
+```
+
+The web visualisation (`--serve`) is available at `http://localhost:8080` and auto-refreshes every 3 seconds while the scan runs.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-o, --output` | `meshmap-graph.json` | Output file |
+| `--resume` | off | Load existing graph, skip already-visited nodes |
+| `--refresh` | off | Re-queue already-visited nodes (oldest first) |
+| `--retry` | off | Re-queue nodes whose last visit failed |
+| `--serve` | off | Start web visualisation server |
+| `--port` | `8080` | Web server port |
+| `--depth` | `5` | Max BFS hop depth |
+| `-w, --wait-time` | `10.0` | Seconds to wait for 0-hop discovery responses |
+
+### `discover-repeaters` — list nearby repeaters
+
+```sh
+uv run meshmap -p /dev/ttyUSB0 discover-repeaters
+```
+
+### `get-neighbours` — inspect a single repeater
+
+Log in to one repeater and print its neighbour list.
+
+```sh
+uv run meshmap -p /dev/ttyUSB0 get-neighbours
+```
+
+### `sniff` — decode RF packets
+
+Listen and decode raw RF traffic for a given duration.
+
+```sh
+uv run meshmap -p /dev/ttyUSB0 sniff 30
+uv run meshmap -p /dev/ttyUSB0 sniff 60 --key mykey.txt
+```
+
+### `contacts` — list known contacts
+
+```sh
+uv run meshmap -p /dev/ttyUSB0 contacts
+```
+
+### `scan` — quick 0-hop node scan
+
+```sh
+uv run meshmap -p /dev/ttyUSB0 scan
+```
+
+## Graph file format
+
+The graph is saved as JSON and can be loaded by external tools:
+
+```json
+{
+  "version": 1,
+  "last_updated": "2026-02-17T12:00:00+00:00",
+  "nodes": {
+    "<pubkey>": {
+      "public_key": "...", "name": "My Repeater",
+      "node_type": "repeater", "lat": 40.4, "lon": -3.7,
+      "depth": 1, "last_visited": "...", "visit_failed": false
+    }
+  },
+  "edges": [
+    { "node_a": "...", "node_b": "...", "snr_a_hears_b": 12.5, "snr_b_hears_a": 9.0, "last_seen": "..." }
+  ]
+}
+```

meshmap-0.1.0/README.md

@@ -0,0 +1,131 @@
+# meshmap
+
+A tool for scanning and mapping [meshcore](https://github.com/ripplebiz/MeshCore) radio networks. It discovers nearby nodes, logs in to each reachable repeater to enumerate its neighbours, and builds a graph of the network — including GPS coordinates where available.
+
+## Install
+
+Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
+
+```sh
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Clone and install
+git clone https://github.com/mangelajo/meshmap
+cd meshmap
+uv sync
+```
+
+The `meshmap` command is then available via `uv run meshmap`.
+
+## Usage
+
+All commands require `-p` to specify the serial port of your connected device.
+
+```
+meshmap -p PORT [OPTIONS] COMMAND
+```
+
+**Global options** (apply to all commands):
+
+| Flag | Description |
+|------|-------------|
+| `-p, --serial-port` | Serial port (e.g. `/dev/ttyUSB0`, `COM3`) |
+| `--sniff` | Print decoded RF packets in real time |
+| `--sniff-key PATH` | Private key file for decryption (repeatable) |
+| `-d, --debug` | Low-level meshcore debug output |
+
+## Commands
+
+### `explore` — map the network graph
+
+The main command. Discovers 0-hop repeaters, then recursively logs in to each one to fetch its neighbour list, building a full network graph. Saves to a JSON file after each node so it can be paused and resumed.
+
+```sh
+# First scan
+uv run meshmap -p /dev/ttyUSB0 explore
+
+# Resume a previous scan, open live visualisation in browser
+uv run meshmap -p /dev/ttyUSB0 explore --resume --serve
+
+# Re-visit already-explored nodes to refresh SNR data
+uv run meshmap -p /dev/ttyUSB0 explore --resume --refresh
+
+# Retry nodes that failed on the last run
+uv run meshmap -p /dev/ttyUSB0 explore --resume --retry
+
+# Limit exploration to 3 hops, save to a custom file
+uv run meshmap -p /dev/ttyUSB0 explore --depth 3 -o my-network.json
+
+# Full run with live packet sniffing and web visualisation
+uv run meshmap -p /dev/ttyUSB0 --sniff --sniff-key mykey.txt explore --serve --resume
+```
+
+The web visualisation (`--serve`) is available at `http://localhost:8080` and auto-refreshes every 3 seconds while the scan runs.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-o, --output` | `meshmap-graph.json` | Output file |
+| `--resume` | off | Load existing graph, skip already-visited nodes |
+| `--refresh` | off | Re-queue already-visited nodes (oldest first) |
+| `--retry` | off | Re-queue nodes whose last visit failed |
+| `--serve` | off | Start web visualisation server |
+| `--port` | `8080` | Web server port |
+| `--depth` | `5` | Max BFS hop depth |
+| `-w, --wait-time` | `10.0` | Seconds to wait for 0-hop discovery responses |
+
+### `discover-repeaters` — list nearby repeaters
+
+```sh
+uv run meshmap -p /dev/ttyUSB0 discover-repeaters
+```
+
+### `get-neighbours` — inspect a single repeater
+
+Log in to one repeater and print its neighbour list.
+
+```sh
+uv run meshmap -p /dev/ttyUSB0 get-neighbours
+```
+
+### `sniff` — decode RF packets
+
+Listen and decode raw RF traffic for a given duration.
+
+```sh
+uv run meshmap -p /dev/ttyUSB0 sniff 30
+uv run meshmap -p /dev/ttyUSB0 sniff 60 --key mykey.txt
+```
+
+### `contacts` — list known contacts
+
+```sh
+uv run meshmap -p /dev/ttyUSB0 contacts
+```
+
+### `scan` — quick 0-hop node scan
+
+```sh
+uv run meshmap -p /dev/ttyUSB0 scan
+```
+
+## Graph file format
+
+The graph is saved as JSON and can be loaded by external tools:
+
+```json
+{
+  "version": 1,
+  "last_updated": "2026-02-17T12:00:00+00:00",
+  "nodes": {
+    "<pubkey>": {
+      "public_key": "...", "name": "My Repeater",
+      "node_type": "repeater", "lat": 40.4, "lon": -3.7,
+      "depth": 1, "last_visited": "...", "visit_failed": false
+    }
+  },
+  "edges": [
+    { "node_a": "...", "node_b": "...", "snr_a_hears_b": 12.5, "snr_b_hears_a": 9.0, "last_seen": "..." }
+  ]
+}
+```

meshmap-0.1.0/meshmap/__init__.py

@@ -0,0 +1,15 @@
+"""meshmap - A tool to scan and map meshcore network graphs."""
+
+from meshmap import crypto, decoder, models
+from meshmap.scanner import MeshScanner
+from meshmap.sniffer import PacketSniffer
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MeshScanner",
+    "PacketSniffer",
+    "models",
+    "decoder",
+    "crypto",
+]