Plugin Submission Process Inquiry

[marcogagliardi]

🚀 How to Build & Submit a New Plugin to AutoSense

Welcome to the Autosense community! 🎉
Because the core AutoSense firmware repository is currently private, community contributors cannot submit direct pull requests to the main codebase. However, thanks to AutoSense’s modular self-registering plugin architecture, developing a new sensor or module plugin is completely decoupled from the rest of the firmware!
We have set up the public AutoSense Community Repository where you will find boilerplate templates, reference interfaces, and working examples.
Here is a complete step-by-step guide on how to build, package, and submit your plugin for evaluation and deployment into the official AutoSense release.

🛠️ How the Submission Process Works

[Community Developer] │ ▼

Grab Template & Example from AutoSense Community Repo
Write Plugin (PXXX.h & PXXX.cpp) + declare lib dependencies
Open a "Plugin Submission" Issue / PR in AutoSense Community │

▼ [AutoSense Team] │
Review code & verify PlatformIO build (ESP32 / ESP8266)
Hardware validation & assign official Plugin ID (if needed)
Merged into Private Core -> Deployed in next Firmware Release! 🚀

📦 What’s Available in the Community Repo

In the AutoSense Community Repository, you will find:

• 🚀 PlatformIO Test Harness: A runnable sandbox (platformio.ini & src/main.cpp) allowing you to compile, flash, and test your plugin on a real ESP32 or ESP8266 without needing access to the private core firmware!
• 📁 TEMPLATE/: Contains PXXX.h and PXXX.cpp with the self-registration boilerplate.
• 📁 examples/: Two fully working reference plugins:
  • P002_DHT: Single-pin digital GPIO sensor with dropdown selection (DHT11 vs DHT22).
  • P010_BME688: I2C multi-variable sensor (Temp, Humidity, Pressure, Gas) with multi-line OLED rendering.
• 📁 include/: Public stub headers (PluginInterface.h, PluginRegistry.h, display_helpers.h) providing API contracts, autocomplete, and mock dispatchers.

---

📝 Step-by-Step Development Guide

1. Reserve / Choose a Plugin Identifier

Plugins follow the naming convention PXXX (e.g., P012). In your draft, use your proposed name/code (e.g., P012 for SCD30). We will confirm or assign the official number during review.

2. Implement the Core Plugin Methods

Every AutoSense plugin implements the Plugin interface:

• init(): Hardware initialization (I2C/SPI begin, pin configuration, sensor startup).
• read(): Sensor reading loop (called every user_settings.frequency ms). Updates internal state, OLED display, MQTT topics, and Web UI metrics.
• registerSettings() & registerSettingsExtra(): Exposes plugin toggles (module_PXXX) and configurable parameters (GPIO pins, I2C address, thresholds).
• isEnabled(): Checks if pluginSettings["module_PXXX"] == 1.
• createHTMLTile() & createHTMLSettingsForm(): Generates the dashboard card and configuration form for the local web UI.
• Self-Registration Hook:

  __attribute__((constructor)) void registerPXXXFactory() {
      PluginRegistry::getInstance().registerFactory("PXXX", []() -> Plugin* {
          return new PXXX();
      });
  }

  (This allows your plugin to automatically register at boot time without modifying any core firmware files!)

3. Test on Real Hardware (With the Community Test Harness)

You don't have to code blindly! You can test on your physical ESP board:

1. Clone the Autosense-Community repo and open it in VS Code with PlatformIO.
2. Copy your plugin files into the src/ folder.
3. Add your sensor library to platformio.ini under lib_deps.
4. Click PlatformIO: Upload & Monitor.
5. The Test Harness boots, calls your init(), and runs your read() loop every 2 seconds, printing live sensor data, mock MQTT payloads, and OLED lines to the Serial Monitor!

4. Display Integration (OLED Guidelines)

If your sensor displays readings on the OLED screen, follow our standard coordinate offsets:

64px OLED (3 lines available):

• Line 1: Y = 16
• Line 2: Y = 32
• Line 3: Y = 50

32px OLED (2 lines available):

• Line 1: Y = 14

---

📬 How to Submit Your Plugin

Once your code is ready:

1. Head over to the AutoSense Community Discussions (or submit a PR).
2. Use the submission template below:

📋 Submission Template (Copy & Paste)

**Plugin Name:** (e.g., SCD30 CO2 Sensor)
**Proposed Module Code:** (e.g., P012)
**Sensor Description:** (Brief overview of the sensor and metrics measured)
**Hardware Interface:** (e.g., I2C 0x61, SPI, or Analog GPIO)
**Required PlatformIO Dependencies:**
```ini
lib_deps =
    sparkfun/SparkFun SCD30 Arduino Library @ ^1.0.20

Settings & Defaults:

• module_P012: 0 (disabled by default)
• p012_i2c_addr: 0x61

Attached Files / PR Link:

• P012.h
• P012.cpp

Testing Notes / Evidence:
(Paste serial monitor logs, screenshots of the Web UI tile, or photos of the sensor in action)

---

## 🔍 Evaluation & Deployment
Once submitted:

1. **Automated / Local Build Verification:** We build your plugin with PlatformIO against both ESP8266 and ESP32 targets.
2. **Code Review:** We verify memory footprint, error handling (e.g., sensor disconnected during boot), and settings persistence.
3. **Merge & Release:** Your plugin will be merged into the private master repo and will appear in the next official AutoSense firmware release binary with full attribution to you!

Questions or ideas for new modules? Drop a reply below! 👇