4.1 Reticulum, LXMF and RNode Bridge (中文)

Trail Mate 中的 Reticulum

语言： English version: 4.1 Reticulum, LXMF and RNode Bridge

Trail Mate 已经可以作为一台独立的 Reticulum 终端使用。Reticulum 在这里服务去中心化身份、匿名控制、离网通信和 TAK 态势；它是一条网络路径，不会改写产品的位置授权边界。设备自己保存身份、联系人和路径，收发 LXMF，并接入 Contacts、Chat、Network、Team 和通话，无需依赖手机或云。

这页说明当前产品到底能做什么、怎样配置，以及哪些能力是有意限制的。

一句话理解

在 Settings > Network > Protocol 中选择 Reticulum，设备会启动自己的 Reticulum/LXMF 运行时。

• Reticulum 是设备当前运行的网络协议。
• LXMF 是 Reticulum 上的消息格式和投递机制，负责私聊、群组消息以及一部分 Trail Mate 数据。
• LoRa、Wi-Fi TCP Client 和 Auto 是 Reticulum 可以使用的网络接口。它们是同一个运行时的不同传输路径，不是不同聊天协议。
• RNode/KISS 是供外部 Reticulum 主机使用的 USB 调制解调器能力，不是设置页里与 Reticulum 并列的普通协议选项。

旧版本中保存过的 LXMF 或 RNode 协议值会兼容加载并归一化为 Reticulum。因此旧名称仍可能出现在源码或历史记录里，但新文档和界面统一使用 Reticulum。

设备端已经具备的能力

身份与发现

首次启用 Reticulum 后，Trail Mate 会建立并保存本地身份。Settings > Network 会显示：

• Identity Hash：本地 Reticulum 身份哈希。
• LXMF Address：本机的 LXMF delivery destination。别人要直接给这台设备发消息时，应分享这个地址。

两者都是 16 字节哈希，显示为 32 个十六进制字符。小屏幕上的换行只是排版，不属于地址。

设备可以发送和验证 announce、请求路径、处理 path response，并把有效的节点信息加入 Nearby 和 Network 页面。开启 Anonymous Peer 后，设备仍保留自己的身份并可主动通信，但不会发送本地 delivery/propagation announce，也不会响应普通路径发现，因此其他节点更难从网络中自动发现它。

私聊、联系人和群组

Reticulum 模式直接接入 Trail Mate 的 Contacts 与 Chat：

• Nearby 显示从 announce 和路径流量中发现的节点。
• Contacts 显示已经保存的联系人。
• Groups 显示本地配置的 LXMF shared destinations。
• Ignored 显示从普通列表隐藏的节点。

联系人优先显示对方 announce 中的 LXMF display name；没有 display name 时再使用本地备注或短哈希。也可以在 Contacts 中按 a，输入 32 位 LXMF Address 或 lxmf@... 地址手动添加联系人。

群组不是从网络上自动发现的。群组成员必须预先知道同一个 shared destination。Trail Mate 出厂不内置任何 Reticulum 群组；群组由设备界面创建，数据保存在 SD 卡的 /trailmate/reticulum/groups.tsv。

联系人如何持久化

当前固件不再使用旧文档中的 /trailmate/reticulum/lxmf_addresses.tsv。Reticulum 联系人与其他协议 peer 一起保存在统一目录：

/mesh/peers.bin

peers.bin 是固件管理的二进制数据库，不是用户配置文件。文件包含格式 magic、版本、record count、CRC 和定长 peer records，最大文件预算为 768 KiB。每条 Reticulum peer 可包含：

• LXMF delivery destination hash；
• Reticulum identity hash；
• encryption/signing public key；
• 可选 ratchet public key 及时间；
• display name、来源和 first/last seen；
• favorite、ignored、trusted 用户标志。

Reticulum 当前最多持久化 1024 条 peer，Contacts 最近列表最多投影 100 条；超出持久化容量时会淘汰该协议中最旧的记录。写入使用 /mesh/peers.tmp 后替换 /mesh/peers.bin，不要在设备运行时修改、覆盖或删除临时文件。

在设备上添加联系人

1. 选择 Reticulum，打开 Contacts。
2. 按 a 或使用 Add 操作。
3. 输入纯 32 位十六进制 LXMF destination hash，或 lxmf@... 形式。输入中的空格、冒号、连字符和下划线会被忽略。
4. 如果这个 destination 已经通过有效 announce/path response 获得 identity hash、encryption public key 和 signing public key，设备会把它标记为 favorite/contact，并同步写入 /mesh/peers.bin。
5. 如果设备只知道 destination hash，系统只能先建立本地联系人投影，保存状态会显示 Address pending。等真实 LXMF delivery announce 或 path response 补齐可验证身份与公钥后，才会形成完整、可持久的 peer record。

在 Nearby 中选择一个已经发现的 Reticulum peer，再执行 Add Contact，是最可靠的保存方式，因为该记录通常已经包含完整身份和公钥。

能否在电脑上编辑 SD 文件添加联系人

当前版本没有受支持的 Reticulum 联系人 TSV/JSON 导入文件，因此不能通过文本编辑器修改 SD 卡来添加联系人，也不要手工修改 /mesh/peers.bin。旧的 lxmf_addresses.tsv 格式已经不是当前 ESP 运行时的事实来源；创建这个文件不会按预期导入联系人。

如果需要离线批量配置，应先在设备上通过 announce/path 发现并收藏联系人，或等待项目提供单独的、带字段校验和原子导入流程的联系人 import 文件。直接生成或修改 peers.bin 会绕过 CRC、版本、身份一致性和公钥完整性检查，可能导致整个 peer directory 无法加载。

Contacts、Chat 和 Network 操作手册

快捷键只在当前页面生效。同一个按键在不同页面可能有不同含义；例如 S 在 Contacts 中是搜索，在具体会话中则是撰写消息。没有实体键盘的设备可以用触摸、旋钮、方向键和屏幕按钮完成同样的操作。

Contacts 联系人页

操作	按键或入口	结果
搜索	S 或 /	按联系人名称筛选当前列表
手动添加 LXMF 地址	A	打开地址输入框；仅在 Reticulum 模式提供
显示/隐藏分类栏	F	切换 Contacts、Nearby、Groups、Ignored 分类栏
打开所选项目	Enter	打开联系人操作菜单，或进入所选分类
查看帮助	H	显示当前页快捷键
返回/关闭	Back	关闭弹窗或返回上一页

用方向键或旋钮移动焦点。选中联系人后按 Enter，菜单会按当前状态提供 Chat、Ping、Call、Info、Add/Edit/Delete、Ignore/Unignore 等操作；不是每个联系人都会显示全部项目。

添加联系人有两条路径：

1. 推荐： 打开 Nearby，选中一个已经通过 announce/path 发现的 peer，按 Enter，再选择 Add。这种记录通常已有可验证身份和公钥，可以可靠持久化。
2. 手动： 在 Contacts 按 A，输入 32 位 destination hash 或 lxmf@... 地址并确认。如果尚未发现该地址的身份和公钥，联系人会暂时显示 Address pending；设备会继续等待可信的 announce/path 数据。

要删除、忽略或恢复联系人，选中项目后按 Enter，使用 Delete、Ignore 或 Unignore。Ignored 分类可以找回已经隐藏的 peer。

Chat 会话列表和会话页

在 Chat 的会话列表中：

操作	按键	结果
搜索会话	S 或 /	搜索联系人/会话名称，不搜索消息正文
打开操作菜单	Enter 或 Space	显示所选会话的操作
打开聊天	C	进入所选会话
查看资料	I	打开所选 peer 信息
Ping	P	对支持该操作的 Reticulum peer 发起 ping
删除	D	删除所选会话；按界面提示确认
显示/隐藏分类栏	F	切换会话筛选栏

进入具体会话后：

操作	按键	结果
撰写或回复	S	打开消息编辑器；这里的 S 不再是搜索
浏览消息	Up / Down 或旋钮	滚动消息
分页	Prev / Next	加载更旧/更新的消息
跳到边界	Home / End	跳到顶部/底部
地图	M	显示或隐藏会话位置地图
地图图层	L	切换地图图层
帮助	H	显示当前页快捷键
返回	Back 或 Esc	返回会话列表

Groups 群组

打开 Contacts 的 Groups 分类，选择列表中的 Add。输入群组名称和所有成员共同使用的 32 位 shared destination 后保存。群组不会通过 announce 自动发现；所有成员必须预先配置完全相同的 shared destination。群组配置保存在 /trailmate/reticulum/groups.tsv。

Network 节点和页面浏览

操作	按键	结果
搜索 announce	S 或 /	匹配 display name、destination、identity、aspect 和 address data
刷新	R	刷新 Network 内容
节点列表	A 或 C	打开 Nodes 列表
收藏页	F	打开 Favourites
沉浸浏览	I	显示/隐藏沉浸式页面浏览器
打开或锁定页面	Enter	打开链接；在页面视口中锁定滚动焦点
解锁或返回	Back	先解除页面滚动锁定，再返回上一层
帮助	H	显示当前页快捷键

页面滚动锁定后，用旋钮或 Up/Down 滚动，Prev/Next 翻页。节点目录和浏览器并排显示时，Right 从目录进入浏览器，Left 返回目录。

发起和接听 Reticulum 通话

在 Contacts 或 Chat 中选中支持通话的 peer，按 Enter 打开操作菜单并选择 Call。如果路径尚未建立，界面会先请求路径；看到 Path requested 时等待路径建立后再试。来电时使用屏幕上的 Answer 或 Decline，通话中使用挂断按钮结束。菜单中没有 Call 通常表示当前 peer、接口或硬件条件不满足。

LXMF 投递

当前运行时不是单包文本演示。它包含设备端实际通信需要的 Reticulum/LXMF 子集，包括：

• announce 验证、缓存和重放；
• 路径请求、path response 和多跳 HEADER_2 转发；
• packet proof 与 reverse-path proof relay；
• 本地 link session、link request relay 和 link identify；
• 直接 LXMF 投递与 shared-destination 群组消息；
• resource advertise、request、hashmap、part 和 proof 流程；
• propagation offer、同步和消息接收；
• 收发结果与本地消息、联系人和持久化存储的衔接。

对普通使用者来说，不需要手动选择“直接包”“link”或“resource”。运行时会根据路径、负载和对端信息完成当前支持范围内的投递。

Team 数据

Trail Mate 的位置、实时轨迹等 Team 数据可以封装在 Reticulum/LXMF appdata 中传输。它们使用 Trail Mate 的 Team 密钥和业务格式；另一台配置了相同 Team 密钥的 Trail Mate 可以理解这些数据，普通 LXMF 客户端通常只能把它们视为应用数据。

Reticulum Groups 与 Trail Mate Team 不是同一个概念：Groups 是 shared-destination 文本会话，Team 是 Trail Mate 自己的加密协作域。当前 Team 位置数据不会伪装成发送到某个 Reticulum Group。

音频呼叫

具备麦克风、扬声器和受支持音频 codec 的 Pager 类设备，可以通过 Reticulum 建立音频呼叫。Settings > Network 中的 Call Protocol 可选择当前支持的 Sideband 或 MeshChat 兼容线格式。

呼叫只走已连接的 Wi-Fi Reticulum 接口，不会把实时音频放到 LoRa 上。通话期间，系统会优先保障 link、呼叫控制、Codec2 和音频设备，暂停或延后 MQTT、BLE 更新、GPS 采集、下载、OTA、公共发现、周期 announce、LoRa 轮询和非紧急 SD 写入。来电可以唤醒设备并显示接听/拒接界面。

Reticulum 网络配置来自 SD 卡

Reticulum 接口和 LXMF propagation client 的权威配置文件是：

/trailmate/reticulum/config.json

它位于 SD 卡根目录下的 trailmate/reticulum/config.json。不要在 Settings 中寻找完整的 Reticulum 接口配置；Settings 中仍可见的旧 bearer/gateway 字段只用于“SD 配置和缓存都不存在”时构造出厂默认值，不是正常配置来源。

设备启动后会等待 SD 卡可用，然后读取这个文件。有效配置会立刻成为当前配置，并以 last-known-good 副本缓存到 NVS。下次启动时：

1. 先用出厂/旧设置字段构造临时默认值；
2. 如果 NVS 中有合法的 last-known-good，则先使用缓存；
3. SD 卡就绪后读取 config.json，合法时替换当前配置并刷新 NVS 缓存；
4. SD 卡或文件暂时不存在时继续使用缓存；
5. SD 文件存在但格式错误时不会用错误内容替换当前有效配置，状态会显示 Invalid Reticulum config 和具体原因。

SD 卡每 5 秒探测一次，首次成功检查后不会不停重读。显式 reload 可以重新读取文件；如果音频呼叫正在占用实时资源，reload 会延后到通话结束。最稳妥的操作方式仍是关机、取卡编辑、插卡后重新开机。

可直接使用的完整示例

config.json 是 UTF-8 JSON，不能写注释或尾随逗号：

{
  "schema": "trail-mate.reticulum",
  "version": 1,
  "interfaces": [
    {
      "id": "integrated-lora",
      "type": "IntegratedLoRaInterface",
      "enabled": true
    },
    {
      "id": "local-wifi",
      "type": "AutoInterface",
      "enabled": true,
      "group_id": "reticulum",
      "discovery_scope": "link",
      "discovery_port": 29716,
      "data_port": 42671
    },
    {
      "id": "primary-tcp",
      "type": "TCPClientInterface",
      "enabled": true,
      "target_host": "reticulum.example.net",
      "target_port": 4242
    },
    {
      "id": "backup-tcp",
      "type": "TCPClientInterface",
      "enabled": false,
      "target_host": "backup.example.net",
      "target_port": 4242
    }
  ],
  "lxmf": {
    "propagation": {
      "enabled": true,
      "service_enabled": false,
      "delivery_method": "auto",
      "propagation_node": "auto",
      "sync_on_start": true,
      "sync_interval_seconds": 900,
      "max_messages_per_sync": 32
    }
  }
}

把示例域名替换为真实 Reticulum TCP server；如果不需要某个接口，可以删除对应对象或把 enabled 设为 false，但至少必须有一个接口启用。

文件与解析限制

• 文件最大 2048 字节；空文件不合法。
• JSON 最大嵌套 5 层，最多 128 个结构 token。
• 单个 JSON 字符串最多 128 字节。
• schema 必须严格为 trail-mate.reticulum，version 必须为数字 1。
• interfaces 必须是数组，包含 1 到 6 个条目，并且至少一个条目启用。
• 每个 id 必填、全文件唯一，最长 23 字符。
• 类型名区分大小写，只接受 IntegratedLoRaInterface、AutoInterface、TCPClientInterface。

三种接口

IntegratedLoRaInterface 使用设备集成的 RNode-compatible raw LoRa radio，最多一个。频率、BW、SF、CR 和 TX power 仍来自设备的 Reticulum LoRa radio 配置；同一 LoRa 网络上的设备必须使用一致且符合法规的参数。

AutoInterface 用于局域网 IPv6 link-scope 自动发现和逐 peer UDP 通信，最多一个：

• group_id 默认 reticulum，不能为空，最长 31 字符；
• discovery_scope 当前只接受 link；
• discovery_port 默认 29716，有效范围 1–65534；
• data_port 默认 42671，有效范围 1–65535。

TCPClientInterface 主动连接 Reticulum TCP server/gateway，默认端口 4242，最多三个：

• target_host 必填，最长 63 字符；
• target_port 有效范围 1–65535；
• 使用 Reticulum TCPInterface HDLC framing，不是 MQTT 或 HTTP。

T-Display-P4 通过 C6 companion 只提供一个 TCP transport，因此只使用第一个启用的 TCP Client，也不通过 companion 提供 IPv6 AutoInterface。

未知目的地和 announce 可以从多个已就绪接口发出；已经学到的路径、link、proof、resource、call 和 Nomad 请求会绑定到实际入口或已知路径接口，避免把会话流量随意复制到所有载体。

LXMF propagation 配置

• enabled：是否启用 propagation client；默认 true。
• service_enabled：是否让本设备宣布并接受 propagation service 流量；默认 false。普通客户端不需要开启。
• delivery_method：只接受 direct、propagated、auto。
• propagation_node：写 auto，或写一个正好 32 位十六进制 propagation destination hash。
• sync_on_start：启动后是否同步。
• sync_interval_seconds：60–86400 秒。
• max_messages_per_sync：1–64。

auto 投递优先使用已有 direct link，其次尝试有可用 ratchet 的 opportunistic delivery，再选择发现到的 propagation node；没有可用 propagation node 时建立 direct link。选择自动 propagation node 时，运行时优先使用活跃、新鲜且 hop 数较低的节点。

service_enabled: true 会让电池设备承担 propagation service 角色并接收额外流量，除非明确知道为什么需要，否则保持 false。

常见配置错误

• 路径写成了 /reticulum/config.json，而不是 /trailmate/reticulum/config.json；
• Windows 隐藏扩展名后实际文件名是 config.json.txt；
• schema、version 或 interface type 拼写不完全一致；
• JSON 带注释、尾随逗号或超过 2 KB；
• interface id 重复，或所有接口都是 disabled；
• 配置了多个 Integrated LoRa/AutoInterface，或超过三个 TCP Client；
• AutoInterface 使用了非 link scope；
• propagation node 不是 auto，也不是 32 位十六进制哈希。

Wi-Fi 公共网络的背景流量可能很高。Trail Mate 会优先保留直接/群组聊天、当前 link、proof、path response 和 Team 数据，并对公共 announce、日志与非紧急 SD 写入采样或延后。因此 Network 页面是有界设备视图，不是整个公共网络的实时镜像。

Network 页面和 Nomad/Micron

选择 Reticulum 后，主菜单会出现 Network 页面。它提供：

• 当前 Reticulum 状态；
• SD 卡中最近的 announce 目录，界面最多显示最新 100 条；
• 按 display name、destination hash、identity hash 或 aspect 搜索；
• 一个为小屏设备设计的 Nomad/Micron 页面浏览器。

地址格式为 <destination>:/page/index.mu。页面先从 /trailmate/reticulum/pages/<destination>/... 的 SD 缓存读取；没有缓存时，ESP 运行时可以尝试建立 link 并发起有时限的页面请求，成功响应会先写入缓存再显示。请求条件不满足、超时或失败时，页面会明确显示失败状态。

这不是完整的 NomadNet 浏览器。当前目标是可靠显示小型静态 Micron 页面：支持常用标题、颜色、文本格式、分隔线、有限表格、链接和本地锚点；表单控件只展示、不提交。脚本、图片、附件、文件资源、动态 partial、复杂桌面表格和无限大页面不在设备边界内。

主要资源上限为：

• 页面正文最多读取 4096 字节；
• 每页最多 32 个可点击链接和 32 个本地锚点；
• 最多 180 个渲染行、520 个页面对象；
• 表格每行最多 6 个单元格。

超过限制或遇到不支持的 Micron 结构时，界面会显示截断或不支持提示，而不是悄悄给出错误内容。

SD 卡保存了什么

Reticulum 目录以 SD 卡为事实来源：

/trailmate/reticulum/announces.tsv
/trailmate/reticulum/groups.tsv
/trailmate/reticulum/pages/
/mesh/peers.bin

• announces.tsv 保存已经验证的 announce 目录。
• /mesh/peers.bin 是统一 peer directory，保存 Reticulum 联系人、发现记录、身份公钥和用户标志；它是二进制运行时文件，不能手工编辑。
• groups.tsv 是用户配置的 shared destinations。
• pages/ 是 Nomad/Micron 页面缓存。

目录更新使用有界读取和临时文件替换。公共发现带来的非紧急写入会尽量等到息屏维护窗口，避免与 UI、地图和其他 SD 访问争抢总线。没有 SD 卡时，发现缓存、持久地址簿、群组和页面缓存都不能按完整产品模型工作；系统也不会偷偷加载内置群组。

RNode/KISS 到底是什么

仓库仍包含 USB CDC RNode/KISS service。启用相应 HostLink 外部主机运行时时，电脑或其他主机可以把设备的 LoRa radio 当作 RNode-compatible modem 使用，由主机上的 Reticulum 实例负责身份、路径、LXMF 和上层应用。

必须注意：

• 当前设置页的协议列表只有 Meshtastic、MeshCore 和 Reticulum，没有单独的 RNode Bridge 选项；
• 旧配置值 RNode 只是兼容入口，加载后会归一化到 Reticulum；
• USB RNode/KISS service 属于外部主机/HostLink 运行场景，不代表日常 Reticulum 模式会把设备端协议栈交给电脑；
• Trail Mate 自有的 HostLink 数据协议与 RNode/KISS 也不是同一条协议。

因此，普通用户应选择 Reticulum 使用设备端能力。只有明确使用支持 RNode 的外部 Reticulum 主机和对应固件/HostLink 入口时，才需要关心 USB KISS。

兼容范围怎么表述才准确

准确的说法是：Trail Mate 已经实现了适合当前设备资源和产品交互的 Reticulum/LXMF 闭环，并通过固定向量、运行时状态契约和产品测试守住这部分行为。

不准确的说法是：Trail Mate 等同于 Python RNS、完整 NomadNet、公共路由器或 propagation server，或者自动支持每个桌面客户端的全部扩展。当前 conformance fixture 证明的是 Trail Mate 已支持子集的稳定性，不是对整个上游协议面的完整认证。

第一次使用建议

1. 在两台设备上选择 Reticulum。
2. 在 SD 卡的 /trailmate/reticulum/config.json 中只启用 IntegratedLoRaInterface，先完成最小 LoRa 验证，并确认频率、BW、SF、CR 和 TX Power 一致。
3. 关闭 Anonymous Peer，等待双方出现在 Contacts > Nearby 或 Network。
4. 打开对方信息，确认 LXMF Address，再发送一条短文本。
5. 需要跨 IP 网络时，再配置 Wi-Fi TCP Client；不要在 LoRa 基础通信尚未确认时同时排查所有接口。
6. 需要群聊时，在所有参与设备上配置相同的 shared destination。
7. 需要通话时，确认设备具备音频硬件、Wi-Fi gateway 已连接且对端身份/路径已知。

常见问题的判断顺序

消息发不出去时，依次检查：

1. 当前 Protocol 是否为 Reticulum；
2. /trailmate/reticulum/config.json 是否成功加载，以及是否至少有一个 enabled 且已经就绪的接口；
3. LoRa 参数是否一致，或 TCP Client 是否已连接；
4. 对端 LXMF Address、身份公钥和路径是否已知；
5. Anonymous Peer 是否让双方无法通过 announce 自动发现；
6. 群组双方是否配置了同一个 shared destination；
7. SD 卡是否可用，目录文件是否能正常加载；
8. Network 页面显示的是缓存缺失、正在请求、可重试失败还是最终失败。

相关页面：3.5 Configuration Guide (中文)、4. Protocols & Data (中文)、13. FAQ (中文)、14. Troubleshooting (中文)、15. Logging and Debugging (中文)。