iarv/meshing-around

Fork 1

mirror of https://github.com/SpudGunMan/meshing-around.git synced 2026-03-28 17:32:36 +01:00

Files

SpudGunMan cefbe93178 Update bbstools.md

2025-10-26 12:13:24 -07:00

8.6 KiB

Raw Permalink Blame History

📡 meshBBS: How-To & API Documentation

This document covers the Bulliten Board System or BBS componment of the meshing-around project.

BBS Core Functions
Synchronization bot2bot: Full Sync Workflow
Troubleshooting
API Reference: BBS Sync
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:

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:
```
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

Set up a dedicated sync channel (e.g., channel bot-admin).
Configure both nodes with bbs_link_enabled = True and add each other to bbs_link_whitelist.
Schedule sync every hour:
- Node A sends bbslink 0 to Node B on channel 99.
- Node B responds with messages and bbsack.
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.

[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:
```
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 <messageID> $<subject> #<body>
```
The receiving node will respond with bbsack <messageID>.

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

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

[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

# 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

The bbs link command should include bbslink .do(send_message("bbslink MeshBot looking for peers", schedulerChannel, 0, schedulerInterface))

[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:

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.

8.6 KiB Raw Permalink Blame History Unescape Escape