# 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