--- # 📡 meshBBS: How-To & API Documentation This document covers the Bulliten Board System or BBS componment of the meshing-around project. ## Table of Contents 1. [BBS Core Functions](#1-bbs-core-functions) - [Central Message Store](#11-central-message-store) - [Direct Mail (DM) Messages](#12-direct-mail-dm-messages) - [BBS Commands](#bbs-commands) 2. [Synchronization bot2bot: Full Sync Workflow](#2-synchronization-bot2bot--full-sync-workflow) - [BBS Database Sync: File-Based (Out-of-Band)](#21-bbs-database-sync-file-based-out-of-band) - [BBS Over-the-Air (OTA) Sync: Linking](#22-bbs-over-the-air-ota-sync-linking) - [Scheduling BBS Auto Sync](#23-scheduling-bbs-auto-sync) 3. [Troubleshooting](#4-troubleshooting) 4. [API Reference: BBS Sync](#5-api-reference-bbs-sync) 5. [Best Practices](#5-best-practices) ## 1. **BBS Core Functions** The mesh-bot provides a basic message mail system for Meshtastic ## 1.1 Central Message Store - **Shared public message space** for all nodes. - Classic BBS list with a simple, one-level message tree. - Messages are stored in `data/bbsdb.pkl`. - Each entry typically includes: `[id, subject, body, fromNode, timestamp, threadID, replytoID]` ### Posting to Public To post a public message: ```sh bbspost $Subject #Message ``` --- ## 1.2 Direct Mail (DM) Messages - **DMs are private messages** sent from one node to another. - Stored separately from public posts in `data/bbsdm.pkl`. - Each DM entry typically includes: `[id, toNode, message, fromNode, timestamp, threadID, replytoID]` - You can inject DMs directly for automation using the `script/injectDM.py` tool. ### DM Delivery - To post a DM, use: ```sh bbspost @USER #Message ``` - When a DM is posted, it is added to the DM database. - When the bot detects the recipient node on the network, it delivers the DM and then removes it from local storage. --- ### BBS Commands | Command | Description | |--------------|-----------------------------------------------| | `bbshelp` | Show BBS help | | `bbslist` | List messages | | `bbsread` | Read a message by ID | | `bbspost` | Post a message or DM | | `bbsdelete` | Delete a message | | `bbsinfo` | BBS stats (sysop) | | `bbslink` | Link messages between BBS systems | --- ## 2. **Synchronization bot2bot : Full Sync Workflow** 1. **Set up a dedicated sync channel** (e.g., channel bot-admin). 2. **Configure both nodes** with `bbs_link_enabled = True` and add each other to `bbs_link_whitelist`. 3. **Schedule sync** every hour: - Node A sends `bbslink 0` to Node B on channel 99. - Node B responds with messages and `bbsack`. 4. **Optionally, use SSH/scp** to copy `bbsdb.pkl` for full out-of-band backup. ## 2.1. **BBS Database Sync: File-Based (Out-of-Band)** ### **Manual/Automated File Sync (e.g., SSH/SCP)** - **Purpose:** Sync BBS data between nodes by copying `bbsdb.pkl` and `bbsdm.pkl` files. ```ini [bbs] # The "api" needs enabled which enables file polling bbsAPI_enabled = True ``` - **How-To:** 1. **Locate Files:** - `data/bbsdb.pkl` (public posts) - `data/bbsdm.pkl` (direct messages) 2. **Copy Files:** Use `scp` or `rsync` to copy files between nodes: ```sh scp user@remote:/path/to/meshing-around/data/bbsdb.pkl ./data/bbsdb.pkl scp user@remote:/path/to/meshing-around/data/bbsdm.pkl ./data/bbsdm.pkl ``` 3. **Reload Database:** After copying, when the "API" is enabled the watchdog will look for changes and injest. - **Automating with Cron/Scheduler:** - Set up a cron job or use the bot’s scheduler to periodically pull/push files. --- ## 2.2. **BBS Over-the-Air (OTA) Sync: Linking** ### **How OTA Sync Works** - Nodes can exchange BBS messages using special commands over the mesh network. - Uses `bbslink` and `bbsack` commands for message exchange. - Future supports compression for bandwidth efficiency. ### **Enabling BBS Linking** - Set `bbs_link_enabled = True` in your config. - Optionally, set `bbs_link_whitelist` to restrict which nodes can sync. ### **Manual Sync Command** - To troubleshoot request sync from another node, send: ``` bbslink $ # ``` - The receiving node will respond with `bbsack `. ### **Out-of-Band Channel** - For high-reliability sync, configure a dedicated channel (not used for chat). --- ## 2.3. **Scheduling BBS Auto Sync** ### **Using the Bot’s Scheduler** - You can schedule periodic sync requests to a peer node. - Example: Every hour, send a `bbslink` request to a peer. see more at [Module Readme](README.md#scheduler) --- #### BBS Link The scheduler also handles the BBS Link Broadcast message, this would be an example of a mesh-admin channel on 8 being used to pass BBS post traffic between two bots as the initiator, one direction pull. The message just needs to have bbslink ```ini [bbs] bbslink_enabled = True bbslink_whitelist = # list of whitelisted nodes numbers ex: 2813308004,4258675309 empty list allows all [scheduler] enabled = True interface = 1 channel = 2 value = link interval = 12 # 12 hours ``` ```python # Custom Schedule Example if using custom for [scheduler] # Send bbslink looking for peers every 2 days at 10 AM schedule.every(2).days.at("10:00").do(send_message("bbslink MeshBot looking for peers", schedulerChannel, 0, schedulerInterface)) ``` --- --- ## 4. **Troubleshooting** - **Messages not syncing?** - Check `bbs_link_enabled` and whitelist settings. - Ensure both nodes are on the same sync channel. - Check logs for errors. - **File sync issues?** - Verify file permissions and paths. - Ensure the bot reloads the database after file copy. - **Custom file problems?** - remove the custom_scheduler.py and replace it with [etc/custom_scheduler.py](etc/custom_scheduler.py) The bbs link command should include `bbslink` `.do(send_message("bbslink MeshBot looking for peers", schedulerChannel, 0, schedulerInterface))` ```ini [bbs] # The "api" needs enabled which enables file polling and use of `script/injectDM.py` bbsAPI_enabled = True ``` ## 5. **API Reference: BBS Sync** ### **Key Functions in Python** | Function | Purpose | Usage Example | |-------------------------|-------------------------------------------|----------------------------------------------------| | `bbs_post_message()` | Post a new public message | `bbs_post_message(subject, body, fromNode)` | | `bbs_read_message()` | Read a message by ID | `bbs_read_message(messageID)` | | `bbs_delete_message()` | Delete a message (admin/owner only) | `bbs_delete_message(messageID, fromNode)` | | `bbs_list_messages()` | List all message subjects | `bbs_list_messages()` | | `bbs_post_dm()` | Post a direct message | `bbs_post_dm(toNode, message, fromNode)` | | `bbs_check_dm()` | Check for DMs for a node | `bbs_check_dm(toNode)` | | `bbs_delete_dm()` | Delete a DM after reading | `bbs_delete_dm(toNode, message)` | | `get_bbs_stats()` | Get stats on BBS and DMs | `get_bbs_stats()` | | Function | Purpose | |---------------------------|-------------------------------------------| | `bbs_sync_posts()` | Handles incoming/outgoing sync requests | | `bbs_receive_compressed()`| Handles compressed sync data | | `compress_data()` | Compresses data for OTA transfer | | `decompress_data()` | Decompresses received data | ### **Handle Incoming Sync** - The bot automatically processes incoming `bbslink` and `bbsack` commands via `bbs_sync_posts()`. ### **Compressed Sync** Future Use - If `useSynchCompression` is enabled, use: ```python compressed = compress_data(msg) send_raw_bytes(peerNode, compressed) ``` - Receiving node uses `bbs_receive_compressed()`. --- ### 5. **Best Practices** - **Backup:** Regularly back up `bbsdb.pkl` and `bbsdm.pkl`. - **Security:** Use SSH keys for file transfer; restrict OTA sync to trusted nodes. - **Reliability:** Use a dedicated channel for BBS sync to avoid chat congestion. - **Automation:** Use the scheduler for regular syncs, both file-based and OTA. ---