meshcore-packet-capture

MeshCore Packet Capture

在操作、配置、部署或排查 meshcore-packet-capture 时使用此技能，尤其是涉及 Companion 电台、BLE/串口/TCP 捕获、MQTT 发布、LetsMesh、TOML 配置、Docker、systemd、launchd 或 NixOS 的请求。

范围边界

此项目仅从 MeshCore Companion 电台捕获数据。不要在此处处理中继器或 RoomServer 捕获；请改用 meshcoretomqtt。

操作工作流

1. 更改配置前，先确定传输方式：
   • ble：直接指定地址、设备名称或进行常规扫描。
   • serial：一个或多个串口；运行时使用第一个已配置的串口。
   • tcp：主机和端口；默认启用 SDK 自动重连。
2. 优先使用已安装的 CLI：

   meshcore-packet-capture --help
   meshcore-packet-capture --debug
   

   对于代码检出目录，请使用 python3 -m meshcore_packet_capture 或 python3 packet_capture.py。 **已验证的 CLI 边界（v2.2.0）：**解析器提供 --output、--verbose、--debug、--no-mqtt、可重复使用的 --config，以及邻居按需执行参数对 --neighbors-now / --neighbors-exit（立即运行一次零跳邻居发现与 scopes 周期；使用 --neighbors-exit 时，在周期结束后退出）。它不提供 --show-config 或 dry-run 标志。记录文档或使用其他任何标志前，请先对实际安装的二进制运行 --help；不要虚构配置预览命令。
3. 配置一个 IATA 代码和至少一个 MQTT Broker，然后再期待上传网络数据。LOC 是占位符，不适合作为实际部署标识。
4. 排查电台连接问题时，先使用 --no-mqtt。只有设备已能在本地捕获数据包后，再添加 MQTT。
5. 每次更改后验证实际状态：设备连接日志、数据包输出、Broker 连接情况，以及服务/容器状态。不要把安装成功视为捕获正常运行的证明。

**变更门槛：**如果请求仅供只读或制定计划，不要把停止、启动、编辑、删除或重启命令作为待执行操作。请将未来可能执行的变更单独说明，并将每个示例标注为未执行；在首次变更前，必须确认目标、范围和回滚方案。

配置规则

配置优先级从高到低如下：

1. 实际的 PACKETCAPTURE_* 进程环境变量。
2. TOML：先读取 /etc/meshcore-packet-capture/config.toml，再按排序读取 config.d/*.toml。
3. 工作目录/软件包目录中的旧版 .env.local，然后是 .env。

使用多次 --config PATH，仅按顺序加载指定的 TOML 文件。后面的文件会覆盖前面的文件。TOML Broker 配置块按 name 合并；启用的 Broker 会依次展开为 PACKETCAPTURE_MQTT<n>_* 配置项。请将用户自定义覆盖项保存在 config.d/99-user.toml 中。

最简 TOML 结构：

[general]
iata = "SEA"

[capture]
connection_type = "serial"
# ble_pin = "123456"   # optional six-digit PIN for BLE connections

[serial]
ports = ["/dev/ttyUSB0"]

[[broker]]
name = "home"
enabled = true
server = "mqtt.example.com"
port = 1883
transport = "tcp"
# include_decoded = true   # publish the nested "decoded" object to this broker
# neighbors = true         # publish the neighbors snapshot to this broker

[broker.auth]
method = "password"
username = "user"
password = "secret"

请阅读 references/configuration.md，了解完整选项映射、Broker 身份验证、主题模板、数据包过滤器和优先级边界情况。

可选功能块（v2.1.0+）

• 载荷解码（decode_payloads、include_decoded、decode_hashtag_channels、decode_channel_keys、decode_include_public）：添加一个包含纯文本／结构化字段的嵌套 decoded 对象。GRP_TXT 频道消息会被解密（发送者、文本），ADVERT 会被解析（名称、角色、纬度／经度），并附带易读的类型／路由标签和路径。原始字段保持不变。被动观察者无法解密直接消息（TXT_MSG）。默认关闭；在相应的 [[broker]] 块中设置 include_decoded = true，即可为该代理启用。
• 发布邻居信息（每个代理的 neighbors，以及 neighbors_interval_hours、neighbors_discover_window、neighbors_command_timeout、neighbors_scope_timeout、neighbors_scope_min_timeout、neighbors_scope_gap、neighbors_cycle_timeout、neighbors_max、neighbors_self_scopes）：将定期零跳邻居表及每个邻居的区域范围发布到 neighbors 主题。默认关闭；仅当至少一个已启用的代理设置 neighbors = true 时，才会运行该周期任务。需要 IATA（或显式配置 [broker.topics] neighbors）。间隔会限制在 12–336 小时，以匹配观察器固件。--neighbors-now / --neighbors-exit 可按需触发周期任务。
• 日志轮转（log_rotation = off|size|time、log_max_bytes、log_rotation_when、log_backup_count）：仅当通过 --output 指定输出文件时适用。

MQTT 和身份验证

• 代理按顺序处理，数量没有固定上限。若缺少 MQTT<n>_ENABLED，发现过程就会终止，因此编号不要留空档。
• 支持的传输方式为 tcp 和 websockets；如需安全传输，请显式启用 TLS。
• 密码身份验证使用 username 和 password。
• 令牌身份验证使用 Ed25519 JWT 风格的令牌。如果已连接的无线电支持设备端签名，优先使用该方式；当存在有效的 64 字节私钥时，则使用 Python 签名作为备用方式。
• 切勿将私钥放入公开的技能、命令记录、已提交的 .env 文件或共享的 Docker Compose 文件中。建议使用受保护的密钥文件或注入密钥。
• 主题占位符为 {IATA}、{IATA_lower}、{PUBLIC_KEY} 和 {TOKEN}。每个代理的主题配置会覆盖全局主题配置。除非显式配置，否则不会发布 RAW。每个代理的主题包括：status、packets、decoded、debug、raw、neighbors。启用 include_decoded 时，decoded 主题会携带嵌套的解码对象；启用 neighbors 时，neighbors 主题会携带定期邻居快照。
• 对于使用令牌身份验证的代理，每个代理的 owner 和 email 会覆盖全局的 capture.owner_public_key / capture.owner_email。
• LetsMesh Analyzer 代理需要配置 IATA。部署 LetsMesh 时，请勿默认接受 LOC。

部署默认设置

可以使用旧式混合安装：systemd 或 launchd 单元可以包装用户主目录下的代码检出，并加载 .env.local，而不使用 /opt 或 /etc TOML 文件。选择现代托管安装路径之前，请检查正在运行的命令、工作目录、服务单元以及环境变量／配置来源。

• 手动／PyPI： pipx install meshcore-packet-capture 会安装 CLI，但不会安装后台服务。
• 托管式 Linux/macOS： root 引导安装程序会创建 /opt/meshcore-packet-capture、/etc/meshcore-packet-capture、虚拟环境和系统服务。默认安装最新发布版本；使用 --tag 或 --branch 固定版本。
• 用户服务（v2.1.0+）： 对于 Linux 上的本地代码检出，./install.sh --user-service 会创建一个按用户运行的 systemd 服务，从代码检出的 .venv 启动（如果代码检出目录不是脚本所在目录，请传入 --repo-dir PATH）。配置文件位于仓库本身（.env、.env.local、config.toml、config.d/）。从同一代码检出目录运行 ./uninstall.sh --user-service 可移除服务；添加 --remove-venv 还会删除本地 .venv。使用 systemctl --user status|restart meshcore-packet-capture 和 journalctl --user -u meshcore-packet-capture -f 管理服务。
• macOS BLE： 使用按用户运行的 LaunchAgent，因为蓝牙权限属于登录用户。Serial/TCP 可以使用 LaunchDaemon。
• Docker： 使用已发布的镜像或运行 docker compose up -d；Serial 需要设备映射，而 BLE 通常需要 privileged: true，并且可能需要主机网络。Linux 是硬件访问最可靠的容器主机。
• NixOS： 使用 services.meshcore-packet-capture，并通过 sudo nixos-rebuild switch 重建。

阅读 references/deployment-and-troubleshooting.md，了解服务命令、Docker 硬件访问、迁移／更新行为以及有界诊断。

输出与验证

普通模式会输出最少的报文信息。--verbose 会附加 JSON 报文数据；--debug 会附加连接、重试、报文解析和 MQTT 诊断信息。--output PATH 会将报文数据写入文件。捕获的记录包含设备身份、时间戳、报文类型、路由、负载长度、原始十六进制数据、SNR、RSSI 和哈希值。启用 decode_payloads 后，记录还会包含嵌套的 decoded 对象，其中有便于阅读的字段（频道消息的发送者／文本、ADVERT 名称／角色／坐标、类型／路由标签）。

排查问题时，请按以下顺序收集证据：

1. 运行 meshcore-packet-capture --debug --no-mqtt，并确认 BLE、Serial 或 TCP 连接正常。
2. 确认报文记录出现在控制台或 --output 文件中。
3. 启用一个代理，并检查代理连接／重连消息。
4. 检查解析后的环境变量／配置和主题名称，但不要打印机密信息。
5. 对于托管服务，请检查服务自身的日志和状态。对于 Docker，请使用 docker compose config、docker compose ps 和 docker compose logs。

诊断期间不要删除安装目录、状态目录或配置。卸载程序会以交互方式运行并备份用户配置，但仍只会在确认后执行破坏性移除操作。

不适用场景

不要将此技能用于 MeshCore 中继器或 RoomServer 的报文捕获、通用 MQTT 管理，或在上游仓库中实施更改。对于代码更改，请使用仓库的贡献工作流，并单独验证项目测试。

参考资料

文件	加载时机
references/configuration.md	编写 TOML／环境变量配置、MQTT 主题、身份验证或报文过滤器时
references/deployment-and-troubleshooting.md	安装、升级、运行 Docker/systemd/launchd/NixOS，或调试故障服务时
references/source-index.md	检查源码覆盖范围、版本标记，或根据上游重新验证此技能时

完成条件

当所选传输方式成功连接、本地观察到数据包、（若涉及 MQTT）预期的 MQTT 主题收到数据，且相关服务/容器报告健康时，即可停止。如果硬件、凭据或代理访问不可用，请准确说明未经验证的边界，不要声称已成功。