Skip to content

Add developer example module#10452

Draft
yeraylois wants to merge 1 commit into
meshtastic:developfrom
yeraylois:feature/add-example-module
Draft

Add developer example module#10452
yeraylois wants to merge 1 commit into
meshtastic:developfrom
yeraylois:feature/add-example-module

Conversation

@yeraylois
Copy link
Copy Markdown

@yeraylois yeraylois commented May 11, 2026

Summary

Adds a disabled-by-default ExampleModule as a heavily-commented reference implementation for developers learning how to create firmware modules.

This follows up on Discussion #10422:
#10422

What changed

  • Adds src/modules/ExampleModule.h
  • Adds src/modules/ExampleModule.cpp
  • Registers the module in Modules.cpp
  • Adds MESHTASTIC_EXCLUDE_EXAMPLE so the module is disabled by default
  • Uses PRIVATE_APP portnum (no protobuf changes needed)

What does NOT change

  • No generated protobuf files included
  • No submodule bumps

Rationale

The current ReplyModule is useful but very small. It only demonstrates allocReply() and does not show the full lifecycle of a Meshtastic module.

ExampleModule is intentionally didactic and demonstrates:

  • Lightweight construction
  • setup() initialization
  • SinglePortModule port filtering
  • handleReceived() packet handling
  • allocReply() response generation
  • Avoiding multi-hop broadcast reply storms
  • A simple module-local state variable

Runtime impact

None by default.

The module is excluded from normal builds with:

-DMESHTASTIC_EXCLUDE_EXAMPLE=1

Developers can enable it locally by removing or undefining that flag.

Testing

  • Local prep completed for the example module and docs follow-up

@CLAassistant
Copy link
Copy Markdown

CLAassistant commented May 11, 2026

CLA assistant check
All committers have signed the CLA.

@CLAassistant
Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

@github-actions github-actions Bot added the enhancement New feature or request label May 11, 2026
@yeraylois yeraylois force-pushed the feature/add-example-module branch from b951c10 to a8a2455 Compare May 11, 2026 11:31
@yeraylois
Copy link
Copy Markdown
Author

Force-pushed to clean up commit history.

What changed in the force push:

  • Removed ~48 auto-generated .pb.* files that were accidentally included due to a nanopb version mismatch (0.4.9 vs 0.4.9.1)
  • Removed the submodule bump to a local commit
  • The commit now only contains the actual code changes:
    • ExampleModule.h / ExampleModule.cpp
    • Modules.cpp registration
    • configuration.h + platformio.ini exclusion flag
    • Minimal portnums.pb.h change with EXAMPLE_APP = 14

No functional changes, just a cleaner diff for review.

@caveman99
Copy link
Copy Markdown
Member

Minimal portnums.pb.h change with EXAMPLE_APP = 14

Please do not include ANY generated files in PR's - these will generate merge conflicts of the nasty kind once the protobuf PR is merged. What about putting this example on PRIVATE_APP portnum?

@yeraylois
Copy link
Copy Markdown
Author

Makes sense. I'll switch the example module to PRIVATE_APP, remove the generated portnums.pb.h change entirely so this PR contains no generated files, and close the protobuf PR since it won't be needed anymore.

- Add ExampleModule.h and ExampleModule.cpp with full lifecycle comments
- Register module in Modules.cpp behind MESHTASTIC_EXCLUDE_EXAMPLE flag
- Add flag to configuration.h and platformio.ini (disabled by default)
- Use PRIVATE_APP portnum to avoid generated protobuf file changes

Relates to Discussion meshtastic#10422
@yeraylois yeraylois force-pushed the feature/add-example-module branch from a8a2455 to 6aa5fe0 Compare May 13, 2026 10:12
@yeraylois
Copy link
Copy Markdown
Author

yeraylois commented May 13, 2026

Changes in this push:

  • Switched ExampleModule from EXAMPLE_APP to PRIVATE_APP
  • Removed the generated portnums.pb.h change entirely
  • Closed the protobuf PR since it's no longer needed
  • Updated PR description to remove the protobuf dependency

This PR now contain no generated files and avoid the merge-conflict risk you pointed out.

@yeraylois
Copy link
Copy Markdown
Author

yeraylois commented May 14, 2026

@caveman99 Updated this yesterday based on your feedback. Let me know if this looks like the right direction now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants