kosmo-connect/firmware/README.md

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 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