Improving the developer experience for creating custom modules

[yeraylois]

Hi Meshtastic team and community,

I've been exploring how to create a custom module for Meshtastic firmware, and I noticed that the current onboarding path for new module developers is quite steep and not well documented.

Current situation

The closest thing we have to an "example module" is ReplyModule (src/modules/ReplyModule.h and .cpp). While functional, it is very minimal (20 lines) and only demonstrates allocReply(). It does not show:

• How setup() is used for initialization
• How handleReceived() processes incoming packets
• What wantPacket() does (though SinglePortModule abstracts this)
• How to register a new module in Modules.cpp
• How module lifecycle works (boot → setup → packet filtering → handling → response)
• What the available flags do (isPromiscuous, loopbackOk, encryptedOk)
• How PortNum selection works

Additionally, the official documentation at meshtastic.org/docs/development/firmware/ covers building, OLED, port numbers, stacktraces, and NRF52, but there is no guide for creating a module.

This gap makes it hard for new contributors to extend Meshtastic without reading large portions of the core code first.

Proposal

I would like to improve this by:

1. In the firmware repo: Creating an improved example module (or enhancing ReplyModule) that is heavily commented and demonstrates the key lifecycle methods (setup(), handleReceived(), allocReply()) in a clear, minimal way.
2. In the documentation repo (meshtastic/meshtastic): Adding a step-by-step guide covering:
   • Module architecture overview (MeshModule vs SinglePortModule)
   • Choosing a PortNum
   • Creating .h / .cpp files
   • Registering the module in Modules.cpp
   • Optional: build flags (MESHTASTIC_EXCLUDE_*)
   • Build and test workflow

Questions for the maintainers / community

• Would you prefer a new ExampleModule alongside ReplyModule, or should we expand ReplyModule with more inline documentation?
• Is there any opposition to adding a new "Creating a Module" page under the Firmware docs section?
• Should the example include state (e.g., a simple counter) to demonstrate persistence, or keep it purely event-driven to remain minimal?
• Are there any recent architectural changes to the module system that should be reflected in such a guide?

I'm happy to do the legwork and submit the PRs once we agree on the scope and approach. Looking forward to your feedback!