diff --git a/README.md b/README.md index 950d111..3ee77e1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # LoBBS - Meshtastic BBS on the Firmware -LoBBS is a full bulletin board system that runs entirely inside the Meshtastic firmware. Once the module is built into your node you can create user accounts, exchange private mail, broadcast news posts, and remotely administer the device without any sidecar services or host computer. +**A Meshtastic firmware plugin providing a full bulletin board system** + +LoBBS is a Meshtastic plugin that runs a complete bulletin board system entirely inside the Meshtastic firmware. Once installed and built into your node, you can create user accounts, exchange private mail, broadcast news posts, and remotely administer the device without any sidecar services or host computer. ## Features @@ -10,54 +12,36 @@ LoBBS is a full bulletin board system that runs entirely inside the Meshtastic f - Session-aware command parser with **contextual help** - Backed by [LoDB](https://github.com/MeshEnvy/lodb) for on-device storage so the entire BBS persists across reboots -## Prerequisites - -- A working Meshtastic firmware checkout with a build environment configured for your target board -- Python environment compatible with PlatformIO (used for the existing Meshtastic build pipeline) -- Git access to clone the LoBBS and LoDB submodules - ## Installation -**Step 1: Vendor LoBBS and LoDB** +LoBBS is a Meshtastic plugin that is automatically discovered and integrated by the Meshtastic Plugin Manager (MPM). To install LoBBS: -LoBBS ships as a firmware module and depends on LoDB for its embedded database layer. Add both submodules to your firmware tree and pull their contents: +1. **Clone LoBBS into the plugins directory:** ```bash -git submodule add git@github.com/MeshEnvy/lobbs.git src/modules/LoBBSModule -git submodule add git@github.com/MeshEnvy/lodb.git src/lodb -git submodule update --init --recursive +cd /path/to/meshtastic/firmware +git clone https://github.com/MeshEnvy/lobbs.git src/plugins/lobbs ``` -**Step 2: Wire LoDB code generation into PlatformIO** +2. **Install LoDB dependency:** -The protobuf definitions in `lobbs.proto` must be regenerated whenever they change. Append the following helper to `bin/platformio-custom.py` so PlatformIO can discover the generator provided by LoDB: +LoBBS requires LoDB as a dependency. Install it as a plugin as well: -```python -# Ensure LoDB helper utilities are available when LoDB is vendored as a submodule -lodb_helper_path = join(env["PROJECT_DIR"], "src", "lodb") if env else None -if lodb_helper_path and lodb_helper_path not in sys.path: - sys.path.append(lodb_helper_path) - -try: - from gen_proto import register_protobufs # type: ignore - register_protobufs( - env, - "$BUILD_DIR/src/modules/LoBBSModule/LoBBSModule.cpp.o", - "$PROJECT_DIR/src/modules/LoBBSModule/lobbs.proto", - ) -except Exception: - print("Warning: gen_proto utilities not found; protobufs will not auto-regenerate") +```bash +git clone https://github.com/MeshEnvy/lodb.git src/plugins/lodb ``` -**Step 3: Build and flash** +3. **Build and flash:** -Use the standard Meshtastic PlatformIO targets to compile and upload. The example below targets an `esp32` environment; adjust the environment name to match your board: +The Meshtastic Plugin Manager automatically discovers both plugins, generates protobuf files, and integrates them into the build. Simply build and flash as usual: ```bash pio run -e esp32 -t upload ``` -After flashing, reboot the node. LoBBS registers automatically through `Modules.cpp`, so no additional firmware configuration is required. +After flashing, reboot the node. LoBBS registers automatically, so no additional firmware configuration is required. + +**Note:** For detailed information about Meshtastic plugin development, see the [Plugin Development Guide](/path/to/meshtastic/src/plugins/README.md). ## Using LoBBS @@ -75,9 +59,9 @@ All user, mail, and news data is persisted via LoDB in the device filesystem. Cl ## Troubleshooting -- Ensure the LoDB generator is reachable; if protobufs fail to regenerate you will see the warning printed during the PlatformIO build. - Verify your node clock is roughly correct. Timestamps in mail and news rely on the RTC and GPS time sources provided by the firmware. - Confirm that your node stays logged in (no `/bye` issued) if you expect to receive `@mentions`. Unauthenticated nodes receive only the login help banner. +- If protobuf generation fails, ensure both LoBBS and LoDB plugins are properly installed in `src/plugins/` and that the Meshtastic Plugin Manager can discover them. ## License