iarv/meshing-around
1
0
Fork 1
mirror of https://github.com/SpudGunMan/meshing-around.git synced 2026-03-28 17:32:36 +01:00
Code Issues Packages Projects Releases Wiki Activity

dox

Browse Source
This commit is contained in:
SpudGunMan
2025-10-26 11:06:48 -07:00
parent ca896c0f35
commit c679cee66c
2 changed files with 78 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
modules/README.md
View File

@@ -11,16 +11,16 @@ This document provides an overview of all modules available in the Mesh-Bot proj
- [BBS (Bulletin Board System)](#bbs-bulletin-board-system)
- [Checklist](#checklist)
- [Location & Weather](#location--weather)
- [Map Command](#-map-command)
- [Map Command](#map-command)
- [EAS & Emergency Alerts](#eas--emergency-alerts)
- [File Monitoring & News](#file-monitoring--news)
- [Radio Monitoring](#radio-monitoring)
- [Voice Commands (VOX)](#voice-commands-vox)
- [Ollama LLM/AI](#ollama-llmai)
- [Wikipedia Search](#wikipedia-search)
- [Mesh Bot Scheduler User Guide](#-mesh-bot-scheduler-user-guide)
- [Other Utilities](#other-utilities)
- [DX Spotter Module](#dx-spotter-module)
- [Mesh Bot Scheduler User Guide](#mesh-bot-scheduler-user-guide)
- [Other Utilities](#other-utilities)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)
- [Messaging Settings](#messaging-settings)
@@ -317,12 +317,12 @@ W1XYZ @7.030 MHz CW SOTA W7W/WE-001 by:K7MHI CN88
`No DX spots found.`
## Configuration
No additional configuration is required. The module is enabled if present in your `modules/` directory.
```ini
[radioMon]
dxspotter_enabled = True
```
---
**Written for Meshtastic mesh-bot by K7MHI Kelly Keeton 2025**
## 📅 Mesh Bot Scheduler User Guide
@@ -363,7 +363,6 @@ To send a daily message at 09:00:
- All scheduled jobs run asynchronously as long as the bot is running.
- For troubleshooting, check the logs for scheduler activity and errors.
### Basic Scheduler Options
You can schedule messages or actions using the following options in your configuration:
@@ -408,7 +407,7 @@ You can schedule messages or actions using the following options in your configu
- Schedules the bot to send a weather update at the specified time of day, daily.
- **Example:**
- Option: `weather`
- Interval: `08:00`
- Time: `08:00`
- → Sends a weather update daily at 8:00a.
---
@@ -425,16 +424,6 @@ You can use any of these options to schedule messages on specific days:
---
### Configuration Fields
- **schedulerValue**: The schedule type (e.g., `day`, `joke`, `weather`, `mon`, etc.)
- **schedulerTime**: The time to run (e.g., `08:00`). Leave blank for interval-based schedules.
- **schedulerInterval**: The interval (e.g., `2` for every 2 hours/days/minutes).
- **schedulerChannel**: The channel number to send to.
- **schedulerInterface**: The device/interface number.
---
## Other Utilities
- `motd` — Message of the day
@@ -595,9 +584,6 @@ If you continue to have issues, review the logs for error messages and consult t
---
### Configuration Guide
The following is documentation for the config.ini file
@@ -897,41 +883,5 @@ qrz_hello_string = "send CMD or DM me for more info." # will be sent to all hear
training = True # Training mode will not send the hello message to new nodes, use this to build up database
```
### Scheduler
In the config.ini enable the module
```ini
[scheduler]
enabled = False # enable or disable the scheduler module
interface = 1 # channel to send the message to
channel = 2
message = "MeshBot says Hello! DM for more info."
value = # value can be min,hour,day,mon,tue,wed,thu,fri,sat,sun.
# value can also be joke (everyXmin) or weather (hour) for special scheduled messages
# custom for module/scheduler.py custom schedule examples
interval = # interval to use when time is not set (e.g. every 2 days)
time = # time of day in 24:00 hour format when value is 'day' and interval is not set
```
The basic brodcast message can be setup in condig.ini. For advanced, See the [modules/scheduler.py](modules/scheduler.py) to edit the schedule. See [schedule documentation](https://schedule.readthedocs.io/en/stable/) for more. Recomend to backup changes so they dont get lost.
```python
#Send WX every Morning at 08:00 using handle_wxc function to channel 2 on device 1
schedule.every().day.at("08:00").do(lambda: send_message(handle_wxc(0, 1, 'wx'), 2, 0, 1))
#Send a Net Starting Now Message Every Wednesday at 19:00 using send_message function to channel 2 on device 1
schedule.every().wednesday.at("19:00").do(lambda: send_message("Net Starting Now", 2, 0, 1))
```
#### 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
```python
# Send bbslink looking for peers every other day at 10:00 using send_message function to channel 8 on device 1
schedule.every(2).days.at("10:00").do(lambda: send_message("bbslink MeshBot looking for peers", 8, 0, 1))
```
```ini
bbslink_enabled = True
bbslink_whitelist = # list of whitelisted nodes numbers ex: 2813308004,4258675309 empty list allows all
```
Happy meshing!

113
modules/bbstools.md
View File

@@ -8,50 +8,55 @@ This document covers the Bulliten Board System or BBS componment of the meshing-
## Table of Contents
1. [BBS Core Functions](#1-bbs-core-functions)
- [Direct Messages (DMs)](#11-direct-messages-dms)
- [Central Message Store](#11-central-message-store)
- [Direct Messages (DMs)](#12-direct-mail-dm-messages)
- [Message Storage](#message-storage)
- [BBS Commands](#bbs-commands)
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)
5. [Example: Full Sync Workflow](#31-example-full-sync-workflow)
6. [Troubleshooting](#4-troubleshooting)
7. [API Reference: BBS Sync](#5-api-reference-bbs-sync)
8. [Best Practices](#6-best-practices)
## 1. **BBS Core Functions**
## 1.1 Central Message Store
## 1.1 **Direct Messages (DMs)**
- **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]`
### **How DMs Work**
- Direct Messages (DMs) are private messages sent from one node to another.
- DMs are stored separately from public posts in `data/bbsdm.pkl`.
- Each DM entry in the pickle, typically includes: `[id, toNode, message, fromNode, timestamp, threadID, replytoID]`.
### Posting to Public
### **DM Delivery**
- When a DM is posted using `bbs_post_dm(toNode, message, fromNode)`, it is added to the recipient's DM database.
- DMs can be delivered in two ways:
1. **File-Based Sync:**
- The `bbsdm.pkl` file is copied between nodes using SCP, rsync, or other file transfer methods.
- After syncing, the recipient node can check for new DMs using `bbs_check_dm(toNode)`.
2. **Over-the-Air (OTA) Sync:**
- DMs can be exchanged between nodes using the same OTA sync mechanism as other posts.
- The bot will receive (onRX) or detect any packet and deliver the DM/mail to the recipient.
- DMs are only visible to the intended recipient node and are not listed in the public message list.
### **DM Commands**
| Command | Description |
|-----------------|---------------------------------------------|
| `bbs_post_dm` | Send a direct message to another node |
| `bbs_check_dm` | Check for new DMs for your node |
| `bbs_delete_dm` | Delete a DM after reading |
To post a public message:
```sh
bbspost $Subject #Message
```
---
## 1.2 Direct Mail (DM) Messages
### **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]`.
- **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]`
### 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 |
|--------------|-----------------------------------------------|
@@ -64,7 +69,7 @@ The .. database is
| `bbslink` | Link messages between BBS systems |
---
Enable in `[bbs]` section of `config.ini`.
## 1. **BBS Database Sync: File-Based (Out-of-Band)**
@@ -116,18 +121,34 @@ Enable in `[bbs]` section of `config.ini`.
- 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**
#### 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_bbslink, send_message, schedulerChannel, schedulerInterface)
```
---
## 3.1. **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`.
@@ -138,7 +159,7 @@ see more at [Module Readme](README.md#scheduler)
---
## 6. **Troubleshooting**
## 4. **Troubleshooting**
- **Messages not syncing?**
- Check `bbs_link_enabled` and whitelist settings.
@@ -149,7 +170,7 @@ see more at [Module Readme](README.md#scheduler)
- Verify file permissions and paths.
- Ensure the bot reloads the database after file copy.
## 7. **API Reference: BBS Sync**
## 5. **API Reference: BBS Sync**
### **Key Functions in Python**
| Function | Purpose | Usage Example |
@@ -185,5 +206,11 @@ Future Use
- Receiving node uses `bbs_receive_compressed()`.
---
### 6. **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.
---