蓝点UWB-TWR 上位机V1.0 用户手册

本文档面向现场工程师、测试人员和设备调试人员，说明如何使用 蓝点UWB-TWR 上位机V1.0 完成 UWB-TWR 基站配置、TCP/串口通信、实时定位显示、调试解析、日志保存和协议联调。

1. 软件概述

蓝点UWB-TWR 上位机V1.0 是一款基于 Python 的 Windows 桌面端 UWB-TWR 定位上位机，用于接收 UWB 标签到基站的距离数据，完成二维或三维定位解算，并在界面中实时显示基站、标签位置、测距辅助信息和调试数据。

软件下载地址：https://pan.baidu.com/s/1U7JAYJxGwWGJLVO1yse7yA?pwd=v7br 提取码：v7br。

主要功能：

  • 支持 TCP Server 通信和串口 COM 通信，二者互斥。
  • 默认 4 个 UWB 基站配置。
  • 基站 1/2/3 固定使能，不可取消。
  • 基站 4 默认使能，可按需取消。
  • 支持 3 基站二维定位、4 基站二维定位、4 基站三维定位。
  • 支持文本协议、mr 二进制距离协议、mri UWB+IMU 融合协议。
  • 支持多标签同时显示，不同标签使用不同颜色。
  • 支持主绘图区缩放、鼠标拖动画布平移、3D 视角调节。
  • 支持测距圆和基站到标签距离连线显示/隐藏。
  • 支持调试页原始数据查看、距离解析表、最近 20s 距离趋势图。
  • 支持保存新接收到的原始数据和解析后的明文距离日志。

2. 启动软件

2.1 获取发布包

正式发布包为一个 Windows 免安装可执行文件：

Landian_UWB_TWR_Host_V1.0.exe

用户电脑不需要安装额外运行环境或依赖包。

2.2 复制与启动

操作步骤：

  1. 将 Landian_UWB_TWR_Host_V1.0.exe 复制到目标 Windows 电脑。
  2. 建议放到固定目录，例如桌面或 D:\Tools\Landian_UWB_TWR_Host_V1.0.exe。
  3. 双击启动：
Landian_UWB_TWR_Host_V1.0.exe

注意：

  • 该 exe 已包含软件运行所需的界面插件、运行库和算法依赖库。
  • 首次启动会解压内部运行文件，可能比普通小工具稍慢，这是正常现象。
  • 软件启动后不会弹出命令行窗口。

窗口标题显示为：

蓝点UWB-TWR 上位机V1.0

启动后的默认状态：

  • 窗口自动显示在屏幕中间。
  • 默认进入 定位 页面。
  • 通信区域默认选中 COM Tab，方便直接进行串口调试。
  • 首次启动时 TCP 默认端口为 8888。
  • 首次启动时基站 1/2/3/4 默认勾选。
  • 显示模式默认根据基站配置自动判断，初始通常为 2D。
  • 状态栏显示连接状态、定位算法状态和显示模式。
  • 如果软件上一次正常退出时已经保存过配置，启动后会自动恢复上次的基站、通信和显示设置。

2.3 配置自动保存和加载

软件关闭时会自动保存当前常用配置，下次启动自动加载。

自动保存内容：

  • 基站数量。
  • 基站地址、使能状态和 x/y/z 坐标。
  • TCP 端口。
  • 默认 COM 号。
  • 默认串口波特率。
  • 当前通信 Tab。
  • 历史数量。
  • 绘图区缩放比例。
  • 3D 视角角度。
  • 测距辅助显示/隐藏状态。

保存时机：

  • 用户点击窗口关闭按钮并确认退出后保存。
  • 保存后再关闭 TCP/COM 服务和日志文件。

配置文件位置：

  • Windows：%APPDATA%\LandianUWB\TWRLocationTool\config.json
  • Linux：~/.config/landian_uwb_twr/config.json
  • macOS：~/Library/Application Support/LandianUWB/TWRLocationTool/config.json

如果配置文件损坏或缺失，软件会自动使用出厂默认配置启动。

3. 界面区域说明

主界面分为顶部配置区域、下方功能页和底部状态栏。

顶部区域包含：

  • 基站配置：配置 4 个基站的使能、地址和坐标。
  • 定位结果：显示实时标签定位结果。
  • 通信：选择 TCP 或 COM 通信方式。

下方功能页包含：

  • 定位：主绘图区，显示基站、标签、轨迹、测距辅助和 2D/3D 视图。
  • 调试：查看原始通信数据、解析距离信息、距离趋势图和保存日志。

底部状态栏包含：

  • 连接状态：当前 TCP/COM 是否连接。
  • 定位算法：当前使用的定位模式、RMS 和质量状态。
  • 显示模式：当前绘图为 2D 或 3D。

4. 基站配置

默认基站配置如下：

编号 地址 默认使能 x y z
基站1 0x0001 是，固定 0.00 0.00 0.00
基站2 0x0002 是，固定 1.60 0.00 0.00
基站3 0x0003 是，固定 1.60 1.60 0.00
基站4 0x0004 是，可选 0.00 1.60 0.00

使用规则：

  • 基站 1/2/3 是基础定位基站，勾选框始终勾选且不可取消。
  • 基站 4 是增强基站，未连接 TCP/COM 时可以勾选或取消。
  • 基站地址使用十六进制格式，例如 0x0001。
  • 坐标单位为米。
  • 修改地址或坐标后，绘图区会重新绘制基站位置。
  • TCP 或 COM 打开后，基站配置表会被锁定；关闭连接后恢复可编辑。

定位模式与基站配置关系：

  • 基站 4 取消使能时：有效基站数为 3，执行 3 基站二维定位。
  • 4 个基站全部使能，且 z 坐标全部相等时：执行 4 基站二维定位。
  • 4 个基站全部使能，且任意基站 z 坐标不同：执行 4 基站三维定位。

5. TCP 通信

TCP 通信采用服务端模式，上位机负责监听端口，外部设备或测试程序作为 TCP Client 连接到上位机。

操作步骤：

  1. 在 通信 区域选择 TCP。
  2. 查看 本机IP。软件会自动获取当前电脑可用 IPv4 地址。
  3. 在 端口Port 输入监听端口，默认 8888。
  4. 点击 OPEN。
  5. 打开成功后按钮变为 CLOSE，状态栏显示 TCP 已连接信息。
  6. 让 UWB 设备或 TCP Client 连接到界面显示的 IP 和端口。

注意事项：

  • 端口范围必须是 1..65535。
  • 如果端口被占用，打开会失败，需要更换端口或关闭占用程序。
  • TCP 打开后，COM 功能会禁用。
  • TCP 打开后，基站配置表会锁定。
  • 如需关闭 TCP，点击 CLOSE 并确认。
  • 如果外部设备无法连接，请检查 Windows 防火墙、网段、设备目标 IP 和端口。

6. 串口 COM 通信

COM 通信用于直接从串口读取 UWB 数据。

操作步骤：

  1. 在 通信 区域选择 COM。
  2. 点击 刷新，更新当前电脑可用串口。
  3. 在 串口 下拉框选择目标串口，例如 COM12。
  4. 在 波特率 下拉框选择设备波特率，常用为 115200。
  5. 点击 OPEN。
  6. 打开成功后按钮变为 CLOSE，状态栏显示 COM 已连接信息。

支持的波特率选项：

115200, 921600, 460800, 230400, 57600, 38400, 19200, 9600

注意事项：

  • COM 打开后，TCP 功能会禁用。
  • 点击 刷新 后，如果没有历史选择，软件会优先选择非 Bluetooth 的真实硬件串口，例如 USB、CH340、CP210、FTDI、UART 设备。
  • 当前软件串口读取采用 0.05s 超时和动态读取长度，现场日志显示会比较流畅。
  • 如果下拉框显示未发现串口，请确认设备驱动和 USB 连接。
  • 如果启动后串口功能异常，请检查 USB 转串口驱动。
  • COM 打开后，基站配置表会锁定。

7. 定位页面使用

定位 页面用于显示实时定位结果。

7.1 主绘图区

绘图区显示：

  • 基站点：蓝色圆点。
  • 基站文字：基站1、基站2、基站3、基站4 和坐标。
  • 标签点：不同标签使用不同颜色。
  • 标签轨迹：根据历史长度显示最近若干点。
  • 测距辅助：可显示基站测距圆、基站到标签距离线和距离文字。
  • 网格线：全域虚线，用于辅助判断空间位置。

基站编号规则：

  • 按启用基站地址从小到大排序。
  • 最小地址显示为 基站1，第二小显示为 基站2，依次类推。

7.2 缩放和平移

工具栏左侧为缩放控制：

  • -：缩小画布。
  • 100%：当前缩放比例。
  • 重置：恢复到 100% 并重新居中。
  • +：放大画布。
  • 鼠标滚轮：以鼠标位置为中心缩放。
  • 鼠标左键拖动画布：平移视图。

缩放时，绘图文字会保持相对稳定，不会随缩放变得过大或过小。

7.3 测距辅助显示

按钮显示为：

  • 隐藏测距：当前正在显示测距辅助，点击后隐藏。
  • 显示测距：当前已隐藏测距辅助，点击后显示。

测距辅助包含：

  • 以基站为圆心的测距圆。
  • 基站到标签的距离实线。
  • 距离数值标注。

7.4 历史长度

历史 数值用于控制每个标签保留的历史点数量。

  • 默认值为 5。
  • 可调范围为 1..100。
  • 数值越大，轨迹越长，但界面刷新压力也会增加。

7.5 2D 与 3D 显示

软件会根据基站配置自动选择显示模式：

  • 3 个有效基站：2D。
  • 4 个有效基站且 z 全相等：2D。
  • 4 个有效基站且 z 不全相等：3D。

进入 3D 后，工具栏右侧的 3D 视图控制可用：

  • 3D视图：3D 视角控制区域。
  • 视角滑块：调整 3D 投影视角，范围 15..75 度。
  • 角度值：显示当前角度，例如 35 deg。
  • 视角重置：恢复默认 35 deg。

3D 定位时标签会输出真实 x/y/z 坐标，并在图中显示高度信息。

8. 定位结果表

定位结果 表显示当前识别到的标签定位结果。

列含义：

  • 地址：标签地址。
  • x：标签 x 坐标，单位 m。
  • y：标签 y 坐标，单位 m。
  • z：标签 z 坐标，单位 m。

说明：

  • 默认显示 4 行标签结果。
  • 如果识别到更多标签，表格会自动扩展。
  • 不同标签的表格地址颜色与绘图区标签颜色一致。
  • 当前输出结果经过每标签 EKF 平滑和历史平均显示。

9. 调试页面使用

调试 页面用于现场联调和数据诊断。

调试按钮只有在 TCP 或 COM 打开后才可用。

按钮说明：

  • 开始：开始向窗口显示新收到的原始数据，并刷新解析表和最近 20s 距离趋势图。
  • 停止：停止刷新调试页可见内容，保留当前原始日志、解析表和趋势图画面；通信、定位和文件日志仍继续工作。
  • 清空：清空当前窗口显示内容。
  • 解析：打开解析面板。
  • 关闭解析：关闭解析面板。
  • 日志：开始保存新收到的数据到文件。
  • 停止日志：停止保存文件日志。

9.1 原始数据显示

原始日志会显示 TCP 或 COM 收到的数据。

  • 如果数据可识别为可打印 ASCII，则显示文本。
  • ASCII 文本按完整行显示，软件会先缓存串口分片，直到遇到 \r 或 \n 后再显示，避免一条日志被拆成多行。
  • 如果文本协议长时间没有换行，软件会在短暂空闲后补刷当前残留内容，避免看起来无响应。
  • 如果是二进制 mr/mri 数据，则按完整 packet 以 HEX ... 单行显示；即使串口底层把一帧拆成多次读取，窗口也不会把 m 和后续字节拆成多行。
  • 调试窗口最多显示最近 1000 行，超过后自动丢弃最旧的可见行，防止长时间高频日志导致界面卡死。
  • 窗口显示日志和文件日志是两套机制；点击 停止 冻结窗口显示不影响文件保存和定位显示。

9.2 文件日志

点击 日志 后，软件会在 exe 同级目录的 logs 文件夹下创建日志文件：

logs/uwb_stream_YYYYMMDD_HHMMSS.txt

日志规则：

  • 只记录点击 日志 后新收到的数据。
  • 不会把调试窗口中已经存在的内容复制到文件。
  • 原始数据以 RAW 开头。
  • 解析摘要以 PARSE 开头。
  • 距离明细以 PARSE DIST 开头。

9.3 解析面板

点击 解析 后，调试页会变为左右分割：

  • 左侧：继续显示 TCP/COM 原始数据。
  • 右侧：显示解析结果。

右侧解析结果再分为上下两部分：

  • 上方：距离表。
  • 下方：最近 20s 距离趋势图。

距离表列含义：

列 说明
标签 标签地址
帧 帧序号
基站 基站地址
距离(m) 基站到标签距离，单位 m
RSSI 信号强度字段，若协议无 RSSI 则为 0
状态 IMU 状态，运动/静止/无

距离趋势图说明：

  • 显示选中标签最近 20s 内到各基站的距离变化。
  • 每个基站一条曲线。
  • 图上方显示标签、当前基站距离、RSSI 和时间窗口。
  • 如果识别到多个标签，可通过右上角 标签 下拉框选择查看。

10. 支持的数据格式

10.1 文本协议

文本协议是 ASCII 可变长度帧，软件按 &&&: 查找帧头，按第一个 #### 判断帧结束。

完整格式：

&&&:LEN$TAG:SEQ$ANCHOR_ID:DIST_CM:RSSI[#ANCHOR_ID:DIST_CM:RSSI...]$CRC####

逐字节/字符定义：

字节/字符位置 字段 ASCII/格式 说明
0 & 0x26 帧头第 1 字节
1 & 0x26 帧头第 2 字节
2 & 0x26 帧头第 3 字节
3 : 0x3A 帧头分隔符
4..N LEN 十六进制 ASCII 长度字段。当前软件校验其为十六进制，但不使用该字段做长度强校验
N+1 $ 0x24 Header 与标签字段分隔符
后续 TAG 十六进制 ASCII 标签 ID，软件按 16 进制解析
后续 : 0x3A 标签 ID 与帧号分隔符
后续 SEQ 十六进制 ASCII 帧序号，软件按 16 进制解析
后续 $ 0x24 标签字段与基站距离字段分隔符
后续 ANCHOR_ID 十六进制 ASCII 基站地址，例如 0001 对应 0x0001
后续 : 0x3A 基站地址与距离分隔符
后续 DIST_CM 十六进制 ASCII 距离，单位 cm；软件解析后乘以 0.01 转为 m
后续 : 0x3A 距离与 RSSI 分隔符
后续 RSSI 十六进制 ASCII RSSI/信号字段；若设备无 RSSI，可填 00
后续 # 0x23 多基站距离组分隔符；最后一组后可省略
后续 $ 0x24 基站距离字段与 CRC 字段分隔符
后续 CRC 建议十六进制 ASCII CRC/校验字段。当前软件只检查后面是否存在 ####，暂不校验 CRC 值
末尾 4 字节 #### 0x23 0x23 0x23 0x23 帧结束标志

基站距离组定义：

ANCHOR_ID:DIST_CM:RSSI

多基站示例：

0001:009D:00#0002:0096:00#0003:004F:00#0004:0057:00

含义：

  • 0001:009D:00：基站 0x0001，距离 0x009D = 157cm = 1.57m，RSSI 为 0。
  • 0002:0096:00：基站 0x0002，距离 150cm = 1.50m。
  • 0003:004F:00：基站 0x0003，距离 79cm = 0.79m。
  • 0004:0057:00：基站 0x0004，距离 87cm = 0.87m。

完整帧示例：

&&&:0048$0033:0001$0001:009D:00#0002:0096:00#0003:004F:00#0004:0057:00$0000####

字段说明：

  • TAG：标签地址。
  • SEQ：帧序号。
  • ANCHOR_ID：基站地址。
  • DIST_CM：十六进制距离，单位 cm，软件内部转换为 m。
  • RSSI：信号强度字段，用于调试显示。
  • CRC：当前版本仅作为帧尾前字段保留，不参与校验。

注意：

  • 文本协议可以携带 3 个或 4 个基站距离，也可以扩展更多距离组。
  • 软件最终只使用“基站配置表中已使能且地址匹配”的基站参与定位。
  • 如果基站 4 已取消使能，即使文本协议上传了 0x0004 距离，该距离也不会参与定位。
  • 文本帧不要求 \r\n 结尾，#### 即为帧结束标志。

10.2 mr 二进制距离协议

总长度 16 字节：

字节 字段 说明
0 m 帧头 1
1 r 帧头 2
2 0x02 协议版本
3 TAG_ID 标签 ID
4 Frame_L 帧序号低字节
5 Frame_H 帧序号高字节
6-7 Dis0 基站 1 距离，cm，小端
8-9 Dis1 基站 2 距离，cm，小端
10-11 Dis2 基站 3 距离，cm，小端
12-13 Dis3 基站 4 距离；3 基站模式下可重复第 1 路
14 \r / \n 结束符 1
15 \n / \r 结束符 2

3/4 基站判断：

  • 如果 Dis3 == Dis0，判定为 3 基站帧，只使用 Dis0/Dis1/Dis2。
  • 3 基站帧中第 4 路重复距离不参与定位，也不在定位图或调试图中显示第 4 个测距圆/连线。
  • 如果 Dis3 != Dis0 且基站 4 使能，按 4 基站解析。
  • 如果基站 4 取消使能，按 3 基站解析。
  • 帧尾兼容 CR LF 和 LF CR，也就是 0D 0A 和 0A 0D 都可以解析。

10.3 mri UWB+IMU 融合协议

总长度 18 字节：

字节 字段 说明
0 m 帧头 1
1 r 帧头 2
2 i 帧头 3
3 0x02 协议版本
4 TAG_ID 标签 ID
5 Frame_L 帧序号低字节
6 Frame_H 帧序号高字节
7-14 Dis0..Dis3 4 路距离，cm，小端
15 s/m s 静止，m 运动
16 0x0A / 0x0D 结束符 1
17 0x0D / 0x0A 结束符 2

帧尾兼容 LF CR 和 CR LF。

IMU 状态规则：

  • m：运动，正常使用 UWB 距离进行定位和 EKF 更新。
  • s：静止，不使用当前 UWB 距离重新解算，保持该标签上一次 EKF 定位结果。
  • 如果静止帧到来时该标签没有历史结果，则本帧不更新位置，并提示无历史定位结果。

11. 定位算法状态说明

软件内部使用：

线性最小二乘初值 + NLLS 非线性最小二乘优化 + 每标签 EKF 平滑

状态栏常见算法状态：

  • 等待数据：尚无足够有效基站距离。
  • 3基站二维定位：基站 4 关闭或仅收到 3 个有效基站。
  • 4基站二维定位：4 个有效基站 z 坐标全部相等。
  • 4基站三维定位：4 个有效基站 z 坐标不全相等。
  • IMU静止:保持上次EKF定位结果：mri 静止状态保持上次结果。
  • IMU静止:无历史定位结果：静止状态但没有历史位置可保持。

12. 常见问题

12.1 TCP 打不开

可能原因：

  • 端口号不在 1..65535。
  • 端口已经被其他程序占用。
  • 当前已有 COM 连接打开。

处理建议：

  • 换一个端口。
  • 关闭占用端口的程序。
  • 先关闭 COM，再打开 TCP。

12.2 外部设备连不上 TCP

可能原因：

  • 设备连接的 IP 不是界面显示的本机 IP。
  • 设备和电脑不在同一网段。
  • Windows 防火墙拦截。
  • 路由器或交换机网络隔离。

处理建议：

  • 使用界面显示的 IP 和端口。
  • 检查电脑 IP、设备 IP、网关和掩码。
  • 临时允许该程序通过防火墙。
  • 先用本机 127.0.0.1 或同网段 TCP 测试工具验证端口。

12.3 找不到串口

可能原因：

  • 设备未插入。
  • 驱动未安装。
  • 串口被其他软件占用。
  • exe 文件不完整，或 USB 转串口驱动异常。

处理建议：

  • 重新插拔设备。
  • 在 Windows 设备管理器确认 COM 号。
  • 关闭其他串口工具。
  • 重新获取完整 exe 文件，并确认 USB 转串口驱动正常。

12.4 有数据但不定位

可能原因：

  • 数据格式不是支持的文本、mr 或 mri 格式。
  • 基站地址和基站配置表中的地址不匹配。
  • 有效基站距离少于 3 个。
  • 距离单位不是 cm，导致数值异常。
  • 3D 基站几何不足或坐标配置错误。

处理建议：

  • 打开 调试 -> 解析 查看是否能解析出距离表。
  • 检查基站地址是否为 0x0001..0x0004 或与设备一致。
  • 检查基站坐标单位是否为米。
  • 查看状态栏定位算法提示。

12.5 3D 没有显示

3D 显示需要同时满足：

  • 4 个基站全部使能。
  • 4 个基站的 z 坐标不全相等。

如果基站 4 未勾选，软件会进入 3 基站二维定位。

12.6 标签位置抖动

可能原因：

  • 测距噪声较大。
  • NLOS 或遮挡严重。
  • 基站坐标配置不准确。
  • 历史长度过短。

处理建议：

  • 检查现场遮挡和基站安装位置。
  • 适当增加 历史 数值。
  • 查看调试页最近 20s 距离趋势，确认是哪一路基站距离波动较大。

12.7 调试日志显示不完整或刷新太快

当前版本的调试窗口按完整文本行显示：

  • 如果设备每行以 \r\n 结束，窗口应稳定显示一行一条日志。
  • mr/mri 二进制帧尾同时兼容 0D 0A 和 0A 0D。
  • mr/mri 二进制帧按完整 HEX ... 单行显示，不会把 m 与后续字节拆成多行。
  • 如果设备输出没有换行，窗口会在短暂空闲后显示残留片段。
  • 窗口最多保留 1000 行，超过后自动清理旧行，这是防止界面卡死的保护策略。
  • 如需保存完整长时间数据，请点击 日志，文件日志会写入 logs/uwb_stream_YYYYMMDD_HHMMSS.txt。

12.8 串口有数据时拖动窗口

当前版本在窗口 resize 时会暂停主绘图区刷新，清理旧图元并重建画布，完成后自动恢复串口/TCP 数据刷新。现场使用时可以正常横向或纵向调整窗口大小，不需要先断开串口。

13. 现场使用建议

  • 首次使用前，先确认 4 个基站地址和实际设备地址一致。
  • 建议先使用 4 基站 2D 模式完成基础联调，再配置不同 z 坐标验证 3D。
  • 调试新设备时，先打开 调试 -> 解析，确认距离表稳定后再观察定位结果。
  • 需要追溯问题时，先点击 日志，再开始设备发送数据。
  • 长时间测试时，建议保存日志和 CSV 测试结果，方便复盘测距噪声和定位误差。