名称： meshtastic
描述： 通过 Meshtastic LoRa 网状网络收发消息。可用于离线通信、查看网络状态、读取近期消息或通过 LoRa 无线电发送文本。

Meshtastic 技能

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

前提条件

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

配置

在 CONFIG.md 中编辑你的节点详情、MQTT 设置和警报目的地。

架构

┌─────────────────────────────────────────────────────────────┐
│                    MQTT 桥接器                               │
├─────────────────────────────────────────────────────────────┤
│  接收: mqtt.meshtastic.org (全局 JSON 流量)                  │
│  发布: 可选的地图代理 (protobuf)                             │
│  套接字: localhost:7331 (命令: 发送、状态、切换)              │
├─────────────────────────────────────────────────────────────┤
│  文件:                                                       │
│  • /tmp/mesh_messages.txt - 接收到的消息日志                 │
│  • /tmp/mesh_nodes.json   - 缓存的节点位置                   │
└─────────────────────────────────────────────────────────────┘

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

快速参考

发送消息

# 通过套接字发送（推荐 - 桥接器运行时可用）
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)"

消息日志格式

时间戳|频道|发送者|距离|文本
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.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
})

距离参考

用于猜测国家/地区的大致距离（根据你的位置调整）：

隐私说明

• 地图报告可使用模糊定位（约 2 公里精度）
• 位置发布功能可完全关闭
• 本地无线电消息默认仅记录，不对外共享
• 切勿在消息中广播精确位置

支持的硬件

硬件特定设置请参阅 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 集成
• 硬件选项