Add comprehensive guides for new module, sensor, and hardware variant development

2026-10-04 03:18:10 +10:00 · 2026-04-16 08:01:03 -05:00
parent c1bee82baf
commit 23f92c1cbd
4 changed files with 629 additions and 27 deletions
@@ -0,0 +1,138 @@
+# New Meshtastic Module
+
+Guide for developing a new Meshtastic firmware module.
+
+## Module Hierarchy
+
+Choose the appropriate base class:
+
+1. **`MeshModule`** — Raw base class. Override `wantPacket()` and `handleReceived()`. Returns `ProcessMessage::STOP` or `ProcessMessage::CONTINUE`.
+2. **`SinglePortModule`** — Handles a single `meshtastic_PortNum`. Constructor takes `(name, portNum)`. Simplified `wantPacket()` checking `decoded.portnum`. Use `allocDataPacket()` to create outgoing packets.
+3. **`ProtobufModule<T>`** — Template for protobuf-encoded modules. Constructor takes `(name, portNum, fields)`. Override `handleReceivedProtobuf()`. Use `allocDataProtobuf(payload)` to create outgoing packets.
+
+Most modules also mix in `concurrency::OSThread` for periodic background tasks.
+
+## Implementation Pattern
+
+```cpp
+// src/modules/MyModule.h
+#pragma once
+#include "ProtobufModule.h"
+#include "concurrency/OSThread.h"
+
+class MyModule : public ProtobufModule<meshtastic_MyMessage>, private concurrency::OSThread
+{
+  public:
+    MyModule();
+
+  protected:
+    // Process incoming protobuf packet. Return true to stop further processing.
+    virtual bool handleReceivedProtobuf(const meshtastic_MeshPacket &mp, meshtastic_MyMessage *msg) override;
+
+    // Generate response packet (optional)
+    virtual meshtastic_MeshPacket *allocReply() override;
+
+    // Periodic task — return next run interval in ms, or disable()
+    virtual int32_t runOnce() override;
+
+    // Modify packet in-flight before delivery (optional)
+    virtual bool alterReceivedProtobuf(meshtastic_MeshPacket &mp, meshtastic_MyMessage *msg);
+
+    // Request a UI display frame (optional)
+    virtual bool wantUIFrame();
+};
+```
+
+## Registration
+
+Register in `src/modules/Modules.cpp` inside `setupModules()`:
+
+```cpp
+#if !MESHTASTIC_EXCLUDE_MYMODULE
+    new MyModule();
+#endif
+```
+
+If other code needs to reference the module instance:
+
+```cpp
+#if !MESHTASTIC_EXCLUDE_MYMODULE
+    myModule = new MyModule();
+#endif
+```
+
+And declare the global in the header:
+
+```cpp
+extern MyModule *myModule;
+```
+
+Some modules also conditionally instantiate based on `moduleConfig`:
+
+```cpp
+#if !MESHTASTIC_EXCLUDE_MYMODULE
+    if (moduleConfig.has_my_module && moduleConfig.my_module.enabled) {
+        new MyModule();
+    }
+#endif
+```
+
+## Conditional Compilation
+
+Add a `MESHTASTIC_EXCLUDE_MYMODULE` guard. This allows the module to be excluded from constrained builds. The flag name must follow the pattern: `MESHTASTIC_EXCLUDE_` + uppercase module name.
+
+## Protobuf Messages (if needed)
+
+1. Define messages in `protobufs/meshtastic/` (e.g., `mymodule.proto`)
+2. Add a `.options` file for nanopb field size constraints
+3. Regenerate with `bin/regen-protos.sh`
+4. Generated code appears in `src/mesh/generated/meshtastic/`
+5. Assign a `meshtastic_PortNum` if the module uses a new port number
+
+## Timing and Defaults
+
+Use `Default` class helpers for configurable intervals:
+
+```cpp
+int32_t MyModule::runOnce()
+{
+    uint32_t interval = Default::getConfiguredOrDefaultMs(moduleConfig.my_module.update_interval,
+                                                          default_my_module_interval);
+    // ... do work ...
+    return interval;
+}
+```
+
+On public/default channels, enforce minimums with `Default::getConfiguredOrMinimumValue()`.
+
+## Observer Pattern
+
+Subscribe to system events:
+
+```cpp
+CallbackObserver<MyModule, const meshtastic::Status *> statusObserver =
+    CallbackObserver<MyModule, const meshtastic::Status *>(this, &MyModule::handleStatusUpdate);
+```
+
+## Testing
+
+Add test suite in `test/test_mymodule/`:
+
+```
+test/
+└── test_mymodule/
+    └── test_main.cpp
+```
+
+Run with: `pio test -e native`
+
+## Checklist
+
+- [ ] Header and implementation files in `src/modules/`
+- [ ] Inherit from appropriate base class (MeshModule / SinglePortModule / ProtobufModule)
+- [ ] Mix in OSThread if periodic work is needed
+- [ ] Register in `src/modules/Modules.cpp` with `MESHTASTIC_EXCLUDE_` guard
+- [ ] Add protobuf definitions if needed (`protobufs/meshtastic/`)
+- [ ] Use `Default::getConfiguredOrDefaultMs()` for timing
+- [ ] Respect bandwidth limits on public channels
+- [ ] Add test suite in `test/`
@@ -0,0 +1,149 @@
+# New Telemetry Sensor
+
+Guide for adding a new I2C telemetry sensor driver to Meshtastic firmware.
+
+## Overview
+
+Telemetry sensors live in `src/modules/Telemetry/Sensor/`. There are 50+ existing drivers organized by measurement type. Each sensor integrates with one of the telemetry modules:
+
+- **EnvironmentTelemetryModule** — Temperature, humidity, pressure, gas, light
+- **AirQualityTelemetryModule** — Particulate matter, VOCs
+- **PowerTelemetryModule** — Voltage, current, power monitoring
+- **HealthTelemetryModule** — Heart rate, SpO2, body temperature
+
+## Sensor Driver Pattern
+
+Each sensor has a `.h` and `.cpp` file pair following this pattern:
+
+```cpp
+// src/modules/Telemetry/Sensor/MySensor.h
+#pragma once
+#include "TelemetrySensor.h"
+#include <MySensorLibrary.h>  // Arduino/PlatformIO library
+
+class MySensor : virtual public TelemetrySensor
+{
+  private:
+    MySensorLibrary sensor;
+
+  public:
+    MySensor() : TelemetrySensor(meshtastic_TelemetrySensorType_MY_SENSOR, "MySensor") {}
+
+    // Initialize sensor hardware. Return true on success.
+    virtual void setup() override;
+
+    // Read sensor data into the telemetry protobuf. Return true on success.
+    virtual bool getMetrics(meshtastic_Telemetry *measurement) override;
+};
+```
+
+```cpp
+// src/modules/Telemetry/Sensor/MySensor.cpp
+#include "MySensor.h"
+#include "TelemetrySensor.h"
+
+void MySensor::setup()
+{
+    sensor.begin();
+    // Configure sensor parameters...
+}
+
+bool MySensor::getMetrics(meshtastic_Telemetry *measurement)
+{
+    // Read from hardware
+    float value = sensor.readValue();
+
+    // Populate the appropriate protobuf variant
+    measurement->variant.environment_metrics.temperature = value;
+    // ... other fields ...
+
+    return true;
+}
+```
+
+## I2C Address Registration
+
+Register the sensor's I2C address(es) in `src/detect/ScanI2C` so it's auto-detected at boot:
+
+1. Add a `DeviceType` enum entry in `src/detect/ScanI2C.h`
+2. Add the I2C address mapping in `src/detect/ScanI2CTwoWire.cpp`
+
+The scan runs at boot and populates a device map that telemetry modules use to decide which sensors to initialize.
+
+## Protobuf Fields
+
+If the sensor provides data not covered by existing telemetry fields:
+
+1. Add fields to the appropriate message in `protobufs/meshtastic/telemetry.proto`:
+   - `EnvironmentMetrics` — Environmental measurements
+   - `AirQualityMetrics` — Air quality data
+   - `PowerMetrics` — Power/energy data
+   - `HealthMetrics` — Health/biometric data
+2. Add a `.options` constraint if needed (field sizes for nanopb)
+3. Regenerate: `bin/regen-protos.sh`
+
+## Sensor Type Enum
+
+Add the sensor to `meshtastic_TelemetrySensorType` enum in `protobufs/meshtastic/telemetry.proto`:
+
+```protobuf
+enum TelemetrySensorType {
+    // ... existing entries ...
+    MY_SENSOR = XX;
+}
+```
+
+## Integration with Telemetry Module
+
+Wire the sensor into the appropriate telemetry module. For environment sensors, this is typically in `src/modules/Telemetry/EnvironmentTelemetry.cpp`:
+
+1. Include the sensor header
+2. Add initialization in `setupSensor()` guarded by detection results
+3. Call `getMetrics()` in the measurement collection path
+
+Example pattern from existing sensors:
+
+```cpp
+#include "Sensor/MySensor.h"
+
+MySensor mySensor;
+
+// In setup:
+if (nodeTelemetrySensorsMap[meshtastic_TelemetrySensorType_MY_SENSOR].first > 0) {
+    mySensor.setup();
+}
+
+// In measurement collection:
+if (nodeTelemetrySensorsMap[meshtastic_TelemetrySensorType_MY_SENSOR].first > 0) {
+    mySensor.getMetrics(&measurement);
+}
+```
+
+## Library Dependencies
+
+If the sensor needs an external library, add it to the `lib_deps` in the relevant base platformio.ini configs:
+
+```ini
+lib_deps =
+    ${env.lib_deps}
+    mysensorlibrary@^1.0.0
+```
+
+Or use a conditional dependency if it's platform-specific.
+
+## Unit Conversions
+
+If the sensor reports values in non-standard units, use `src/modules/Telemetry/UnitConversions.h` for conversion helpers (e.g., Celsius ↔ Fahrenheit, hPa ↔ inHg).
+
+## Checklist
+
+- [ ] Create `src/modules/Telemetry/Sensor/MySensor.h` and `.cpp`
+- [ ] Inherit from `TelemetrySensor` base class
+- [ ] Implement `setup()` and `getMetrics()` methods
+- [ ] Add `meshtastic_TelemetrySensorType` enum entry in `telemetry.proto`
+- [ ] Add I2C address to `src/detect/ScanI2C` for auto-detection
+- [ ] Add protobuf fields in `telemetry.proto` if new data types needed
+- [ ] Regenerate protos: `bin/regen-protos.sh`
+- [ ] Wire into the appropriate telemetry module (Environment/AirQuality/Power/Health)
+- [ ] Add library dependency if external library required
+- [ ] Test on hardware or native build
@@ -0,0 +1,178 @@
+# New Hardware Variant
+
+Guide for adding a new Meshtastic hardware variant to the firmware.
+
+## Directory Structure
+
+Create under `variants/<arch>/<name>/`:
+
+```
+variants/
+├── esp32/          # ESP32
+├── esp32s3/        # ESP32-S3
+├── esp32c3/        # ESP32-C3
+├── esp32c6/        # ESP32-C6
+├── nrf52840/       # nRF52840
+├── rp2040/         # RP2040/RP2350
+├── stm32/          # STM32WL
+└── native/         # Linux/Portduino
+```
+
+Each variant needs at minimum:
+
+- `variant.h` — Pin definitions and hardware capabilities
+- `platformio.ini` — Build configuration
+
+Optional files:
+
+- `pins_arduino.h` — Arduino pin mapping overrides
+- `rfswitch.h` — RF switch control for multi-band radios
+- `nicheGraphics.h` — InkHUD e-ink configuration
+
+## variant.h Template
+
+```cpp
+// Pin definitions
+#define I2C_SDA 21
+#define I2C_SCL 22
+
+// LoRa radio
+#define USE_SX1262              // Radio chip: USE_SX1262, USE_SX1268, USE_SX1280, USE_RF95, USE_LLCC68, USE_LR1110, USE_LR1120, USE_LR1121
+#define LORA_CS   18
+#define LORA_SCK  5
+#define LORA_MOSI 27
+#define LORA_MISO 19
+#define LORA_DIO1 33            // SX126x: DIO1, SX128x: DIO1, RF95: IRQ
+#define LORA_RESET 23
+#define LORA_BUSY 32            // SX126x/SX128x only
+#define SX126X_DIO2_AS_RF_SWITCH // Common for SX1262 boards
+
+// GPS
+#define HAS_GPS 1
+#define GPS_RX_PIN 34
+#define GPS_TX_PIN 12
+// #define PIN_GPS_EN 47         // Optional GPS enable pin
+// #define GPS_BAUDRATE 9600     // Override default 9600
+
+// Display
+#define HAS_SCREEN 1
+// #define USE_SSD1306            // OLED type
+// #define USE_SH1106             // Alternative OLED
+// #define USE_ST7789             // TFT type
+// #define SCREEN_WIDTH 128
+// #define SCREEN_HEIGHT 64
+
+// LEDs
+#define LED_PIN 2               // Status LED (optional)
+// #define HAS_NEOPIXEL 1        // WS2812 support
+
+// Buttons
+#define BUTTON_PIN 38
+// #define BUTTON_PIN_ALT 0      // Secondary button
+
+// Power management
+// #define HAS_AXP192 1          // AXP192 PMU (T-Beam v1.0)
+// #define HAS_AXP2101 1         // AXP2101 PMU (T-Beam v1.2+)
+// #define BATTERY_PIN 35        // ADC battery voltage pin
+// #define ADC_MULTIPLIER 2.0    // Voltage divider ratio
+
+// Optional I2C devices
+// #define HAS_RTC 1             // Real-time clock
+// #define HAS_TELEMETRY 1       // Enable telemetry sensor support
+// #define HAS_SENSOR 1          // I2C sensors present
+```
+
+## platformio.ini Template
+
+```ini
+[env:my_variant]
+extends = esp32s3_base            ; Use architecture-specific base
+board = esp32-s3-devkitc-1        ; PlatformIO board definition (or custom in boards/)
+board_level = extra               ; Build level: extra, or omit for default
+custom_meshtastic_support_level = 1  ; 1 = PR builds, 2 = merge builds only
+
+build_flags =
+    ${esp32s3_base.build_flags}
+    -D MY_VARIANT_SPECIFIC_FLAG=1
+    -I variants/esp32s3/my_variant  ; Include path for variant.h
+
+upload_speed = 921600
+```
+
+### Common Base Configs
+
+- `esp32_base` / `esp32-common.ini` — ESP32
+- `esp32s3_base` — ESP32-S3
+- `esp32c3_base` — ESP32-C3
+- `esp32c6_base` — ESP32-C6
+- `nrf52840_base` / `nrf52.ini` — nRF52840
+- `rp2040_base` — RP2040/RP2350
+
+### Support Levels
+
+- `custom_meshtastic_support_level = 1` — Built on every PR (actively supported)
+- `custom_meshtastic_support_level = 2` — Built only on merge to main branches
+- `board_level = extra` — Only built on full releases
+
+## Build Manifest Metadata
+
+`bin/platformio-custom.py` emits UI capability flags in the build manifest:
+
+- `custom_meshtastic_has_mui = true/false` — Override MUI detection
+- `custom_meshtastic_has_ink_hud = true/false` — Override InkHUD detection
+- Architecture names are normalized (e.g., `esp32s3` → `esp32-s3`)
+
+## InkHUD E-Ink Variants
+
+For e-ink display variants using the InkHUD framework, add `nicheGraphics.h`:
+
+```cpp
+// nicheGraphics.h — InkHUD configuration for this variant
+#define INKHUD                     // Enable InkHUD
+// Configure display, applets, and refresh behavior per device
+```
+
+InkHUD has its own PlatformIO config: `src/graphics/niche/InkHUD/PlatformioConfig.ini`
+
+## I2C Device Detection
+
+If the variant has I2C devices, ensure `src/detect/ScanI2C` will detect them. The auto-detection system handles 80+ device types including displays, sensors, RTCs, keyboards, PMUs, and touch controllers at boot.
+
+## Custom Board Definitions
+
+If the PlatformIO board doesn't exist, create a custom board JSON in `boards/`:
+
+```json
+{
+  "build": {
+    "arduino": { "ldscript": "esp32s3_out.ld" },
+    "core": "esp32",
+    "f_cpu": "240000000L",
+    "f_flash": "80000000L",
+    "flash_mode": "qio",
+    "mcu": "esp32s3",
+    "variant": "esp32s3"
+  },
+  "connectivity": ["wifi", "bluetooth"],
+  "frameworks": ["arduino", "espidf"],
+  "name": "My Custom Board",
+  "upload": {
+    "flash_size": "8MB",
+    "maximum_ram_size": 327680,
+    "maximum_size": 8388608
+  },
+  "url": "https://example.com",
+  "vendor": "MyVendor"
+}
+```
+
+## Checklist
+
+- [ ] Create `variants/<arch>/<name>/variant.h` with pin definitions
+- [ ] Create `variants/<arch>/<name>/platformio.ini` extending correct base
+- [ ] Set `custom_meshtastic_support_level` (1 or 2)
+- [ ] Verify radio chip define matches hardware (`USE_SX1262`, etc.)
+- [ ] Set hardware capability flags (`HAS_GPS`, `HAS_SCREEN`, etc.)
+- [ ] Add custom board JSON in `boards/` if needed
+- [ ] Test build: `pio run -e my_variant`
+- [ ] For e-ink: add `nicheGraphics.h` with InkHUD config