Plan MeshCore Python application with serial interface

README.md

@@ -1,2 +1,136 @@
-# meshcore-sidekick
-MeshCore Companion Node Data Harvesting and Messaging Bridge
+# MeshCore Sidekick
+
+MeshCore companion application for event collection, persistence, and REST API access.
+
+## Features
+
+- Subscribe to all MeshCore events via Serial/BLE connection
+- Persist events in SQLite database with configurable retention
+- REST API for querying collected data and sending commands
+- Mock MeshCore implementation for development without hardware
+- Prometheus metrics for monitoring
+- OpenAPI/Swagger documentation
+- Docker deployment ready
+
+## Quick Start
+
+### Development (Mock Mode)
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Run with mock MeshCore
+python -m meshcore_sidekick --use-mock --log-level DEBUG
+```
+
+### Production (Real Hardware)
+
+```bash
+# Run with real MeshCore device
+python -m meshcore_sidekick \
+    --serial-port /dev/ttyUSB0 \
+    --serial-baud 115200 \
+    --db-path /data/meshcore.db \
+    --retention-days 90
+```
+
+### Docker
+
+```bash
+# Development with mock
+docker-compose up --build
+
+# Production with real hardware
+docker-compose -f docker-compose.prod.yml up -d
+```
+
+## Configuration
+
+Configuration priority: **CLI Arguments > Environment Variables > Defaults**
+
+### CLI Arguments
+
+```bash
+python -m meshcore_sidekick --help
+```
+
+### Environment Variables
+
+```bash
+MESHCORE_SERIAL_PORT=/dev/ttyUSB0
+MESHCORE_USE_MOCK=true
+MESHCORE_DB_PATH=/data/meshcore.db
+MESHCORE_RETENTION_DAYS=30
+MESHCORE_API_PORT=8000
+MESHCORE_LOG_LEVEL=INFO
+```
+
+See full configuration options in documentation.
+
+## Querying the Database
+
+View captured data with the query tool:
+
+```bash
+# Full report (all tables and statistics)
+python -m meshcore_sidekick.query
+
+# Summary statistics only
+python -m meshcore_sidekick.query --summary
+
+# Recent messages (last 20)
+python -m meshcore_sidekick.query --messages 20
+
+# Discovered nodes
+python -m meshcore_sidekick.query --nodes 10
+
+# Recent advertisements
+python -m meshcore_sidekick.query --advertisements 10
+
+# Telemetry data
+python -m meshcore_sidekick.query --telemetry 5
+
+# Trace paths
+python -m meshcore_sidekick.query --traces 5
+
+# Activity in last 6 hours
+python -m meshcore_sidekick.query --activity 6
+
+# Custom database location
+python -m meshcore_sidekick.query --db-path /data/meshcore.db
+```
+
+## API Documentation
+
+Once running, access interactive API docs at:
+- Swagger UI: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc
+- OpenAPI Schema: http://localhost:8000/openapi.json
+
+## Prometheus Metrics
+
+Metrics available at: http://localhost:8000/metrics
+
+## Development
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Run tests
+pytest
+
+# Format code
+black src/ tests/
+
+# Lint
+ruff check src/ tests/
+
+# Type check
+mypy src/
+```
+
+## License
+
+See LICENSE file.

pyproject.toml

@@ -0,0 +1,49 @@
+[tool.poetry]
+name = "meshcore-sidekick"
+version = "1.0.0"
+description = "MeshCore companion application for event collection and REST API"
+authors = ["Your Name <you@example.com>"]
+readme = "README.md"
+packages = [{include = "meshcore_sidekick", from = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.11"
+meshcore = "^2.2.1"
+fastapi = "^0.115.0"
+uvicorn = {extras = ["standard"], version = "^0.31.0"}
+sqlalchemy = "^2.0.0"
+alembic = "^1.13.0"
+pydantic = "^2.9.0"
+prometheus-client = "^0.21.0"
+prometheus-fastapi-instrumentator = "^7.0.0"
+python-multipart = "^0.0.12"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.0"
+pytest-asyncio = "^0.24.0"
+pytest-cov = "^6.0.0"
+black = "^24.10.0"
+ruff = "^0.7.0"
+mypy = "^1.13.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 100
+target-version = ['py312']
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

requirements.txt

@@ -0,0 +1,9 @@
+meshcore>=2.2.1
+fastapi>=0.115.0
+uvicorn[standard]>=0.31.0
+sqlalchemy>=2.0.0
+alembic>=1.13.0
+pydantic>=2.9.0
+prometheus-client>=0.21.0
+prometheus-fastapi-instrumentator>=7.0.0
+python-multipart>=0.0.12

src/meshcore_sidekick/__init__.py

@@ -0,0 +1,3 @@
+"""MeshCore Sidekick - Event collector and REST API for MeshCore devices."""
+
+__version__ = "1.0.0"