Tomas Kracmar
0a4fb7b55e
Includes: - Backend services: ingestion (:8001), weather API (:8002), gateway (:8003), billing (:8004) with BTCPay integration - Shared asyncpg pool, TimescaleDB hypertable, Redis, Mosquitto MQTT - React frontend: Dashboard (MapLibre) and Messaging (chat UI) - Bridge daemon for Pi + Meshtastic (Serial/TCP T-Deck support) - Production Docker Compose, Nginx reverse proxy, ops scripts - DEPLOY.md with step-by-step deployment guide
96 lines
3.5 KiB
Markdown
96 lines
3.5 KiB
Markdown
# Firmware
|
|
|
|
This directory contains all embedded software for KosmoConnect edge devices.
|
|
|
|
## Structure
|
|
|
|
```
|
|
firmware/
|
|
├── enviro-node/ # Firmware for solar-powered monitoring stations
|
|
│ ├── src/ # Main application source
|
|
│ ├── lib/ # Internal libraries
|
|
│ ├── meshtastic-patch/ # Patches or modules for Meshtastic firmware
|
|
│ └── tests/ # Unit tests (native/emu)
|
|
├── infrastructure-node/ # Software for bridge devices
|
|
│ ├── bridge-daemon/ # Python daemon running on bridge host
|
|
│ └── firmware/ # Any custom bridge device firmware
|
|
└── shared-libs/ # Libraries shared across both nodes
|
|
├── packet-format/ # Binary serialization for enviro packets
|
|
└── power-manager/ # Common power management utilities
|
|
```
|
|
|
|
## Enviro-Node Firmware
|
|
|
|
### Strategy
|
|
|
|
There are two architectural approaches:
|
|
|
|
#### A. Meshtastic Fork with Custom Module
|
|
Fork the official Meshtastic firmware and add a `kosmo_enviro` module that:
|
|
- Runs on the secondary CPU core or as a low-priority thread
|
|
- Interfaces with I2C/SPI sensors
|
|
- Manages the local data buffer
|
|
- Formats and injects data packets into the mesh router
|
|
|
|
**Pros**: Tight integration, single binary, leverages mature mesh stack
|
|
**Cons**: Build complexity, upstream sync overhead, limited to supported chipsets
|
|
|
|
#### B. Companion MCU Architecture
|
|
Use a dedicated sensor MCU (e.g., ESP32-S3 or STM32L4) that talks to a Meshtastic module (e.g., RAK4631 or T-Beam) via UART.
|
|
|
|
**Pros**: Complete isolation of concerns, easier sensor debugging, can use any MCU
|
|
**Cons**: More hardware, more power draw, inter-board communication complexity
|
|
|
|
**Decision**: Start with **Approach A** (Meshtastic fork with custom module) on ESP32-S3. This keeps the kit BOM simple and the software stack unified.
|
|
|
|
### Key Modules
|
|
|
|
1. **Sensor Manager**
|
|
- Abstracts BME680, SPS30, anemometer
|
|
- Handles sensor warmup, error recovery, calibration
|
|
|
|
2. **Data Logger**
|
|
- Ring buffer in SPIFFS / LittleFS on flash
|
|
- CRC-protected records
|
|
- Wear leveling
|
|
|
|
3. **Mesh Injector**
|
|
- Formats `kosmo_enviro_packet_t` into a Meshtastic `Data` payload
|
|
- Schedules transmissions during low-congestion windows
|
|
- Respects duty cycle limits
|
|
|
|
4. **Power Manager**
|
|
- Deep sleep orchestration
|
|
- Dynamic interval scaling based on battery voltage
|
|
- Solar charging state monitoring
|
|
|
|
5. **Config Manager**
|
|
- Persistent settings (intervals, sensor enable flags, channel keys)
|
|
- Remote config via Meshtastic admin messages
|
|
|
|
## Infrastructure Node Software
|
|
|
|
### Bridge Daemon
|
|
A Python daemon (`infrastructure-node/bridge-daemon/`) that runs on a Linux host (Raspberry Pi, etc.) connected to a Meshtastic device via USB/serial.
|
|
|
|
**Responsibilities**:
|
|
- Connect to Meshtastic device via `meshtastic` Python API
|
|
- Listen for environmental data packets and publish to cloud MQTT
|
|
- Subscribe to cloud MQTT topics and inject messages into the mesh
|
|
- Monitor device health and report bridge status
|
|
- Support multiple backhaul transports (WiFi, Ethernet, LTE)
|
|
|
|
See [`infrastructure-node/bridge-daemon/README.md`](./infrastructure-node/bridge-daemon/README.md) for full setup instructions and RPi installation guide.
|
|
|
|
### Runtime
|
|
- Python 3.10+
|
|
- `meshtastic` library
|
|
- `paho-mqtt`
|
|
- `systemd` service file for auto-start
|
|
|
|
## Build System
|
|
|
|
- **Enviro-Node**: PlatformIO with custom board definition
|
|
- **Bridge Daemon**: Poetry or `pip` with `requirements.txt`
|
|
- **CI**: GitHub Actions for firmware builds, flash size checks, and unit tests
|