蓝点UWB-TWR 上位机V1.0 下载链接与用户手册

蓝点无限

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

1. 软件概述

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



主要功能：

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

2. 启动软件

2.1 获取发布包

正式发布包为一个 Windows 免安装可执行文件：软件下载地址：https://pan.baidu.com/s/1U7JAYJxGwWGJLVO1yse7yA?pwd=v7br 提取码：v7br。

1. 
   
2. Landian_UWB_TWR_Host_V1.0.exe
   

复制代码

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

2.2 复制与启动

操作步骤：

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

1. 
   
2. Landian_UWB_TWR_Host_V1.0.exe
   

复制代码

注意：

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

窗口标题显示为：

1. 
   
2. 蓝点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 连接到上位机。

操作步骤：

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

注意事项：

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

6. 串口 COM 通信

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

操作步骤：

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

支持的波特率选项：

1. 
   
2. 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 打开后才可用。

按钮说明：

• 开始：开始向窗口显示新收到的原始数据。
• 停止：停止向窗口继续追加原始数据。
• 清空：清空当前窗口显示内容。
• 解析：打开解析面板。
• 关闭解析：关闭解析面板。
• 日志：开始保存新收到的数据到文件。
• 停止日志：停止保存文件日志。
  

9.1 原始数据显示

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

• 如果数据可识别为可打印 ASCII，则显示文本。
• ASCII 文本按完整行显示，软件会先缓存串口分片，直到遇到 \r 或 \n 后再显示，避免一条日志被拆成多行。
• 如果文本协议长时间没有换行，软件会在短暂空闲后补刷当前残留内容，避免看起来无响应。
• 如果是二进制数据，则以 HEX 形式显示。
• 调试窗口最多显示最近 1000 行，超过后自动丢弃最旧的可见行，防止长时间高频日志导致界面卡死。
• 窗口显示日志和文件日志是两套机制；关闭窗口显示不影响文件保存。
  

9.2 文件日志

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

1. 
   
2. 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 可变长度帧，软件按 &&&: 查找帧头，按第一个 #### 判断帧结束。

完整格式：

1. 
   
2. &&&: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	帧结束标志

基站距离组定义：

1. 
   
2. ANCHOR_ID:DIST_CM:RSSI
   

复制代码

多基站示例：

1. 
   
2. 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。
  

完整帧示例：

1. 
   
2. &&&: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	结束符
15	\n	换行

3/4 基站判断：

• 如果 Dis3 == Dis0，判定为 3 基站帧，只使用 Dis0/Dis1/Dis2。
• 3 基站帧中第 4 路重复距离不参与定位，也不在定位图或调试图中显示第 4 个测距圆/连线。
• 如果 Dis3 != Dis0 且基站 4 使能，按 4 基站解析。
• 如果基站 4 取消使能，按 3 基站解析。
  

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	LF
17	0x0D	CR

IMU 状态规则：

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

11. 定位算法状态说明

软件内部使用：

1. 
   
2. 线性最小二乘初值 + 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 结束，窗口应稳定显示一行一条日志。
• 如果设备输出没有换行，窗口会在短暂空闲后显示残留片段。
• 窗口最多保留 1000 行，超过后自动清理旧行，这是防止界面卡死的保护策略。
• 如需保存完整长时间数据，请点击 日志，文件日志会写入 logs/uwb_stream_YYYYMMDD_HHMMSS.txt。
  

13. 现场使用建议

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