Meshtastic 技能

通过 USB 控制 Meshtastic 节点，实现离网 LoRa 网状通信。

前提条件

• Meshtastic 兼容硬件（RAK4631、T-Beam、Heltec、LilyGo 等）
• 通过 USB 连接至主机
• Python 3.9+，并已安装 meshtastic 和 paho-mqtt 包
• 完整安装指南请参阅 references/SETUP.md

配置

使用您的节点信息、MQTT 设置及告警目标编辑 CONFIG.md 文件。

架构

┌─────────────────────────────────────────────────────────────┐
│                    MQTT Bridge                               │
├─────────────────────────────────────────────────────────────┤
│  接收：mqtt.meshtastic.org（全局 JSON 流量）                 │
│  发布：可选地图代理（protobuf 格式）                        │
│  套接字：localhost:7331（支持命令：send、status、toggle）    │
├─────────────────────────────────────────────────────────────┤
│  文件：                                                    │
│  • /tmp/mesh_messages.txt —— 接收消息日志                  │
│  • /tmp/mesh_nodes.json   —— 缓存的节点位置                 │
└─────────────────────────────────────────────────────────────┘

┌─────────────┐     USB      ┌─────────────┐
│  LoRa 节点  │◄────────────►│ Bridge.py   │
│  （无线电）  │              │  - 串口     │
└─────────────┘              │  - 套接字   │
                             │  - MQTT     │
                             └──────┬──────┘
                                    │
           ┌────────────────────────┼────────────────────────┐
           │                        │                        │
           ▼                        ▼                        ▼
    localhost:7331           /tmp/mesh_*            MQTT Broker
    （发送命令）             （消息日志）             （网状流量）

快速参考

发送消息

# 通过套接字（推荐方式 —— 桥接服务运行时即可使用）
echo '{"cmd":"send","text":"Hello mesh!"}' | nc -w 2 127.0.0.1 7331

# 向特定节点发送直连消息
echo '{"cmd":"send","text":"Hey!","to":"!abcd1234"}' | nc -w 2 127.0.0.1 7331

# 查询状态
echo '{"cmd":"status"}' | nc -w 2 127.0.0.1 7331

# 列出射频节点（通过无线电侦测到的节点）
echo '{"cmd":"nodes"}' | nc -w 2 127.0.0.1 7331

地图可见性（如已配置）

# 切换地图发布开关
echo '{"cmd":"map"}' | nc -w 2 127.0.0.1 7331

# 显式启用/禁用
echo '{"cmd":"map","enable":true}' | nc -w 2 127.0.0.1 7331
echo '{"cmd":"map","enable":false}' | nc -w 2 127.0.0.1 7331

# 强制立即上报位置
echo '{"cmd":"map_now"}' | nc -w 2 127.0.0.1 7331

读取消息

# 最近 20 条消息
tail -20 /tmp/mesh_messages.txt

# 过滤常见噪声（如测试消息、问候语等）
tail -50 /tmp/mesh_messages.txt | grep -v -E "(Hello!|hey|mqtt-test)"

消息日志格式

TIMESTAMP|CHANNEL|SENDER|DISTANCE|TEXT
2026-02-02T12:43:59|LongFast|!433bf114|1572km|Moin moin!

桥接服务

# 查看服务状态
sudo systemctl status meshtastic-bridge

# 重启服务
sudo systemctl restart meshtastic-bridge

# 实时查看日志
sudo journalctl -u meshtastic-bridge -f

# 停止服务（需直接使用 CLI 时执行）
sudo systemctl stop meshtastic-bridge

监控与告警

选项 1：Cron 任务（推荐）

cron.add({
  name: "mesh-monitor",
  schedule: { kind: "every", everyMs: 300000 },  // 每 5 分钟
  sessionTarget: "isolated",
  payload: {
    kind: "agentTurn",
    message: "检查 /tmp/mesh_messages.txt 中的新消息。过滤噪声（测试消息、'Hello!'、'hey'）。对其中有趣的消息发出告警，并在非英文时提供翻译。",
    timeoutSeconds: 60,
    deliver: true,
    channel: "telegram"  // 或您配置的其他通道
  }
})

选项 2：摘要汇总

cron.add({
  name: "mesh-digest",
  schedule: { kind: "cron", expr: "0 8,14,20 * * *", tz: "Europe/Madrid" },
  sessionTarget: "isolated",
  payload: {
    kind: "agentTurn",
    message: "读取 /tmp/mesh_messages.txt。生成过去 6 小时内有趣消息的摘要。对非英文消息进行翻译，并根据距离推测来源国家。发布汇总报告。",
    timeoutSeconds: 120,
    deliver: true,
    channel: "telegram"
  }
})

选项 3：派生式监控代理

sessions_spawn({
  task: "每 30 秒监控一次 /tmp/mesh_messages.txt。发现有趣消息（非噪声）即告警。运行时长为 1 小时。",
  label: "mesh-monitor",
  runTimeoutSeconds: 3600
})

距离参考

用于国家推测的近似距离（请根据您的实际地理位置调整）：

隐私说明

• 地图上报可采用模糊定位（精度约 ±2km）
• 位置发布功能可完全关闭
• 本地射频消息会被记录，但默认不对外共享
• 切勿在消息中广播精确地理位置

支持的硬件

硬件专属配置请参阅 references/SETUP.md。

地区频率

文件结构

~/.openclaw/skills/meshtastic/
├── SKILL.md           # 本文件
├── CONFIG.md          # 您的配置文件
├── scripts/
│   └── mesh.py        # CLI 封装脚本
└── references/
    └── SETUP.md       # 安装指南

故障排查

“资源暂时不可用”

• 同一时间仅允许一个进程访问串口
• 执行直接 CLI 操作前，请先停止桥接服务：sudo systemctl stop meshtastic-bridge

无消息显示

• 确认 MQTT 订阅主题与您所在地区匹配
• 验证防火墙是否允许出站端口 1883
• 检查日志：journalctl -u meshtastic-bridge

无法发送消息

• 确保桥接服务正在运行（即套接字服务器已启动）
• 核对配置中指定的串口路径是否正确
• 尝试执行：echo '{"cmd":"status"}' | nc -w 2 127.0.0.1 7331

考虑改用 BLE 替代 USB？

• 不建议。在 Linux 系统上，USB 连接要可靠得多。
• Linux 上的 BLE（基于 BlueZ / bleak）存在通知异常、配对不稳定及随机断连等问题。
• 详细分析请参阅 references/SETUP.md。

延伸阅读

• Meshtastic 官方文档
• MQTT 集成说明
• 硬件选型指南