From 2111bb46ae5187c9e29206d3fc24929e8ab76b19 Mon Sep 17 00:00:00 2001 From: SpudGunMan Date: Thu, 23 Oct 2025 10:27:28 -0700 Subject: [PATCH] bbs doc --- modules/README.md | 2 + modules/bbstools.md | 160 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 162 insertions(+) create mode 100644 modules/bbstools.md diff --git a/modules/README.md b/modules/README.md index 8a1d1e6..2721cf7 100644 --- a/modules/README.md +++ b/modules/README.md @@ -92,6 +92,8 @@ Enable/disable games in `[games]` section of `config.ini`. Enable in `[bbs]` section of `config.ini`. +more at [meshBBS: How-To & API Documentation](bbstools.md) + --- ## Checklist diff --git a/modules/bbstools.md b/modules/bbstools.md new file mode 100644 index 0000000..b67aff3 --- /dev/null +++ b/modules/bbstools.md @@ -0,0 +1,160 @@ + +--- + +# 📡 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) +2. [BBS Database Sync: File-Based (Out-of-Band)](#1-bbs-database-sync-file-based-out-of-band) +3. [BBS Over-the-Air (OTA) Sync: Linking](#2-bbs-over-the-air-ota-sync-linking) +4. [Scheduling BBS Sync](#3-scheduling-bbs-sync) +5. [Best Practices](#4-best-practices) +6. [Example: Full Sync Workflow](#5-example-full-sync-workflow) +7. [Troubleshooting](#6-troubleshooting) +8. [API Reference: BBS Sync](#7-api-reference-bbs-sync) + +## 1. **BBS Core Functions** + +### **Message Storage** +The .. database is +- Messages are stored in `data/bbsdb.pkl` (public posts) and `data/bbsdm.pkl` (direct messages). +- Format: Each message is a list, e.g. `[id, subject, body, fromNode, timestamp, threadID, replytoID]`. + + +| 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 | + +--- +Enable in `[bbs]` section of `config.ini`. + +## 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. +- **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. **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). +--- + +## 3. **Scheduling BBS 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) +--- + +## 4. **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. + +--- + +## 5. **Example: 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. + +--- + +## 6. **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. + +## 7. **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()`. + +--- + +--- \ No newline at end of file