OP-BT/BTS 文件管理器 MAUI 版用户手册

目录

• 第一章：MAUI 版本简介
• 第二章：快速开始
• 第三章：界面详解
• 第四章：设备连接
• 第五章：文件管理
• 第六章：Python 开发支持
• 第七章：通信监视器
• 第八章：设置和配置
• 第九章：平台特定指南
• 第十章：常见问题
• 第十一章：故障排除

第一章：MAUI 版本简介

1.1 什么是 MAUI 版本

OP-BT/BTS 文件管理器 MAUI 版是基于 .NET MAUI（Multi-platform App UI）框架开发的跨平台文件管理应用。MAUI 版本继承了桌面版本的核心功能，同时提供了现代化的用户界面和更好的跨平台体验。

1.2 MAUI 版本特点

跨平台支持

MAUI 版本支持以下平台：

• Windows 10/11：完整功能支持，包括串口和蓝牙 BLE 连接
• Android：平台支持正在开发中，后续版本将逐步完善串口和蓝牙 BLE 连接（计划支持 Android 5.0+）
• iOS：平台支持正在开发中，后续版本将支持蓝牙 BLE 连接（计划支持 iOS 13.0+）
• macOS (MacCatalyst)：平台支持正在开发中，计划支持蓝牙 BLE 连接（要求 macOS 11.0+）

现代化用户界面

• 响应式设计：适配不同屏幕尺寸和分辨率
• Material Design 风格：遵循现代设计规范
• 流畅动画：提供流畅的用户交互体验
• 深色模式支持：自动适配系统主题（预留功能）

核心功能

• 双面板文件管理：类似资源管理器的双面板界面
• 多种连接方式：支持串口和蓝牙 BLE 连接
• Python 开发支持：编译和运行 Python 文件
• 通信监视器：实时简易的监控设备通信数据（MAUI 特有功能）
• 多语言支持：支持中文和英文界面切换

1.3 系统要求

Windows 平台

• 操作系统：Windows 10 版本 1903 或更高版本，Windows 11
• 处理器：Intel/AMD x64 处理器
• 内存：4GB RAM（推荐 8GB）
• 存储空间：100MB 可用磁盘空间
• .NET 运行时：.NET 9.0 运行时（通常随应用一起安装）

Android 平台

• 操作系统：Android 5.0 (API 21) 或更高版本
• 内存：2GB RAM（推荐 4GB）
• 存储空间：50MB 可用存储空间
• 权限：需要蓝牙和位置权限（Android 6.0+）

iOS 平台

• 操作系统：iOS 13.0 或更高版本
• 设备：iPhone、iPad
• 存储空间：50MB 可用存储空间
• 权限：需要蓝牙权限

macOS 平台

• 操作系统：macOS 11.0 (Big Sur) 或更高版本
• 处理器：Intel 或 Apple Silicon (M1/M2)
• 内存：4GB RAM（推荐 8GB）
• 存储空间：100MB 可用磁盘空间

第二章：快速开始

2.1 安装应用

Windows 平台

1. 从应用商店安装（暂时不可用）：

   • 打开 Microsoft Store
   • 搜索 “OP-BT/BTS 文件管理器”
   • 点击"安装"

2. 从安装包安装：

   • 下载 .msix 或 .exe 安装包
   • 双击安装包文件
   • 按照安装向导完成安装

Android 平台(暂不支持)

1. 从 Google Play 安装（如果可用）：

   • 打开 Google Play Store
   • 搜索应用并安装

2. 从 APK 安装：

   • 下载 .apk 文件
   • 启用"未知来源"安装权限
   • 打开 APK 文件进行安装

iOS 平台(暂不支持)

1. 从 App Store 安装（如果可用）：

   • 打开 App Store
   • 搜索应用并安装

2. 从 TestFlight 安装（测试版本）：

   • 使用 TestFlight 应用安装测试版本

macOS 平台(暂不支持)

1. 从 Mac App Store 安装（如果可用）
2. 从 DMG 安装：
   • 下载 .dmg 文件
   • 打开 DMG 并拖拽应用到 Applications 文件夹

2.2 首次启动

启动应用

1. Windows：从开始菜单或桌面快捷方式启动
2. Android：从应用抽屉启动
3. iOS：从主屏幕启动
4. macOS：从 Applications 文件夹或 Launchpad 启动

首次使用向导

应用首次启动时会显示主界面。建议按以下步骤操作：

1. 检查语言设置：

   • 点击右上角菜单按钮（⋮）
   • 选择"设置"
   • 确认语言设置为"中文"

2. 准备连接设备：

   • 确保 OP-BT/BTS 设备已上电
   • 根据连接方式准备相应的硬件（串口线或蓝牙）

3. 查看帮助信息：

   • 阅读本手册了解详细功能
   • 参考界面提示信息

2.3 界面概览

主界面分为四个主要区域：

1. 连接控制面板（顶部）：配置和建立设备连接
2. 本地文件面板（左侧）：浏览和管理本地文件
3. 远程设备面板（右侧）：浏览和管理设备文件
4. 底部状态栏：显示连接状态和操作进度

2.4 基本操作流程

典型使用流程

1. 启动应用
   ↓
2. 选择连接方式（串口或蓝牙 BLE）
   ↓
3. 配置连接参数
   ↓
4. 点击"连接"按钮
   ↓
5. 等待连接成功
   ↓
6. 浏览设备文件
   ↓
7. 执行文件操作（上传/下载/删除等）
   ↓
8. 完成操作后断开连接

快速连接示例

串口连接：

1. 选择"串口"连接方式
2. 选择串口（如 COM3）
3. 使用默认参数（9600, 8, None, 1）
4. 点击"连接"

蓝牙 BLE 连接：

1. 选择"蓝牙 BLE"连接方式
2. 点击"扫描"按钮
3. 等待扫描完成
4. 选择设备
5. 点击"连接"

第三章：界面详解

3.1 主界面布局

主界面采用经典的双面板布局，类似 Windows 资源管理器，但针对移动设备和触摸操作进行了优化。

界面区域说明

3.2 连接控制面板

连接控制面板位于主界面顶部，提供设备连接的所有配置选项。

串口模式界面

当选择"串口"连接方式时，显示以下控件：

• 连接方式：下拉框选择"串口"
• 串口选择：下拉框显示可用串口列表
• 波特率：下拉框选择（300-1152000）
• 数据位：下拉框选择（7 或 8）
• 校验位：下拉框选择（None/Even/Odd）
• 停止位：下拉框选择（1 或 2）

蓝牙 BLE 模式界面

当选择"蓝牙 BLE"连接方式时，显示以下控件：

• 连接方式：下拉框选择"蓝牙 BLE"
• BLE设备：下拉框显示扫描到的设备列表
• 扫描按钮：点击扫描附近的 BLE 设备

操作按钮

连接控制面板右侧包含以下按钮：

• 🔗 连接：建立与设备的连接
• ❌ 断开：断开当前连接
• 🔄 刷新：刷新连接状态或设备列表
• 🚪 退出：退出应用程序
• 📡 监控：打开通信监视器页面（MAUI 特有）
• ⋮ 菜单：打开应用菜单（设置、关于等）

3.3 本地文件面板（左侧）

本地文件面板显示计算机上的文件和文件夹。

路径选择区域

位于面板顶部，包含：

• 当前路径标签：显示"当前路径:"
• 快速目录选择器：下拉框选择常用目录（桌面、文档、下载等）
• 选择文件夹按钮：打开文件夹选择对话框
• 文件类型过滤器：下拉框选择文件类型（全部文件、文本文件、Python文件等）

路径导航栏

• ⬆️ 向上按钮：返回上级目录
• 🔄 刷新按钮：刷新当前目录
• 🔨 编译按钮：编译选中的 Python 文件
• 路径输入框：显示和编辑当前路径
• 📁 在资源管理器中打开按钮：在系统文件管理器中打开当前目录（仅 Windows）

文件列表区域

显示当前目录的文件和文件夹：

• 列表头部：显示列标题（图标、文件名、大小、修改时间）
• 文件项：
  • 📁 文件夹图标 + 文件夹名称
  • 📄 文件图标 + 文件名 + 大小 + 修改时间
• 选择功能：支持单选和多选（复选框）

状态栏

显示本地文件统计信息：

• 文件数量
• 文件夹数量
• 选中项数量

3.4 远程设备面板（右侧）

远程设备面板显示 OP-BT/BTS 设备上的文件和文件夹。

路径导航栏

• ⬆️ 向上按钮：返回上级目录
• 🔄 刷新按钮：刷新设备文件列表
• 路径输入框：显示和编辑当前设备路径（Unix 风格，如 /py）

操作按钮栏

包含以下操作按钮：

• ⏹️ 停止：中断正在进行的操作（通常隐藏）
• 🗑️ 删除：删除选中的文件/文件夹
• ⬆️ 上传：上传本地文件到设备
• ⬇️ 下载：下载设备文件到本地
• 创建目录：在设备上创建新文件夹
• 📝 重命名：重命名文件或文件夹
• ▶️ 运行：运行选中的 Python 文件
• 下载后删除复选框：下载时自动删除源文件

文件列表区域

显示设备当前目录的文件和文件夹：

• 列表头部：显示列标题（图标、名称、大小）
• 文件项：
  • 📁 文件夹：显示 <DIR> 表示目录
  • 📄 文件：显示实际文件大小
• 选择功能：支持单选和多选

状态栏

显示远程设备统计信息：

• 文件数量
• 文件夹数量
• 可用存储空间

3.5 底部状态栏

底部状态栏实时显示应用程序状态和操作进度。

状态信息显示

左侧区域：连接状态

• 🔴 未连接：设备未连接
• 🟡 连接中…：正在建立连接
• 🟢 已连接：显示连接类型和设备信息

中间区域：操作进度

• 显示当前操作描述（如"正在上传: file.txt"）
• 显示进度条和百分比

右侧区域：统计信息

• 本地文件统计
• 远程设备统计
• 选中文件统计

3.6 通信监视器页面（MAUI 特有）

待完善

3.7 设置页面

设置页面提供应用程序的各项配置选项。

设置选项

1. 🌐 语言设置：选择界面语言（中文/English）
2. ⬆️ 上传封包大小：配置上传数据块大小（10-100字节）
3. ⬇️ 下载封包大小：配置下载数据块大小（50-800字节）
4. ⏱️ 超时时间：配置命令响应超时时间（500-30000毫秒）
5. 📡 BLE特征值：配置 BLE GATT 服务和特征 UUID
6. 🔑 访问权限KEY：配置根目录访问权限
7. 📡 BLE连接超时时间：配置 BLE 连接超时时间
8. 💾 保存：保存所有配置
9. ❌ 取消：取消所有未保存的修改

详细配置说明请参考第八章：设置和配置。

第四章：设备连接

4.1 连接方式概述

MAUI 版本支持两种连接方式：

1. 串口连接：通过 USB 工装串口适配器或蓝牙虚拟串口连接OPBT/BTS 设备
2. 蓝牙 BLE 连接：通过低功耗蓝牙直接连接（无需配对）

不同平台的支持情况：

4.2 串口连接

Windows 平台串口连接

连接步骤：

1. 选择连接方式：

   • 在"连接方式"下拉框中选择"串口"

2. 选择串口：

   • 点击"串口"下拉框
   • 软件会自动检测可用串口
   • 选择与设备连接的串口（如 COM3）
   • 蓝牙虚拟串口会显示为"COMx - OP-BTS xxxxx SPP"

3. 配置参数（通常使用默认值）：

   • 波特率：9600（默认）
   • 数据位：8（默认）
   • 校验位：None（默认）
   • 停止位：1（默认）

4. 建立连接：

   • 点击"🔗 连接"按钮
   • 等待连接建立
   • 状态栏显示"🔌 串口连接成功"

参考文档：如何在 Windows 11 上配对及获取端口号

Android 平台串口连接

待完善

4.3 蓝牙 BLE 连接

Windows 平台 BLE 连接

连接步骤：

1. 选择连接方式：

   • 在"连接方式"下拉框中选择"蓝牙 BLE"

2. 扫描设备：

   • 点击"扫描"按钮
   • 等待扫描完成（约5-10秒）
   • 扫描到的 OP-BT 设备会显示在设备列表中

3. 选择设备：

   • 在"BLE设备"下拉框中选择要连接的设备
   • 设备显示格式：设备名称 - 信号强度
   • 例如：OP-BTS T2 SPP - -65dBm

4. 建立连接：

   • 点击"🔗 连接"按钮
   • 等待连接建立
   • 状态栏显示"✅ BLE连接成功"

信号强度参考：

• -50dBm：信号很强
• -65dBm：信号良好（推荐）
• -80dBm：信号较弱
• -90dBm 以下：信号很差，可能连接不稳定

Android 平台 BLE 连接

iOS 平台 BLE 连接

4.4 连接参数说明

串口参数详解

重要提示：连接双方（计算机和设备）的参数必须完全一致，否则无法正常通信。

BLE 连接参数

BLE 连接使用以下配置（可在设置中修改）：

• 服务UUID：默认 18F0
• TX特征UUID：默认 2AF1（发送数据）
• RX特征UUID：默认 2AF0（接收数据）
• 连接超时时间：默认 2000ms

4.5 连接故障排除

常见问题

Q: 串口连接失败，提示"串口被占用"？

A:

1. 关闭其他可能使用串口的程序
2. 检查设备管理器中的串口状态
3. 尝试重新插拔 USB 适配器
4. 重启计算机

Q: BLE 扫描不到设备？

A:

1. 确保是OP-BT 设备，并已开启并处于可发现状态
2. 检查计算机/手机蓝牙是否已启用
3. 确保设备在蓝牙信号范围内（1-2米内）
4. Android 6.0+ 需要授予位置权限
5. 尝试重新扫描

Q: BLE 连接失败？

A:

1. 检查信号强度，建议在 -65dBm 以上
2. 确认设备未被其他应用占用
3. 尝试重新扫描并选择设备
4. 检查 BLE 特征值配置是否正确

Q: 连接成功但无法查看文件？

A:

1. 尝试手动刷新文件列表
2. 检查设备是否正常工作
3. 确认设备固件版本兼容
4. 查看状态栏的错误信息

第五章：文件管理

5.1 文件浏览和导航

本地文件导航

快速目录选择：

点击"当前路径"下方的下拉框，可以选择常用系统目录：

• 🏠 桌面
• 📄 文档
• 📥 下载
• 🖼️ 图片
• 🎵 音乐
• 🎬 视频
• 💻 自定义…

路径输入：

• 在路径输入框中直接输入完整路径
• 按回车键跳转到指定目录
• 支持路径自动补全（部分平台）

文件列表导航：

• 双击文件夹：进入该文件夹
• 双击文件：无操作（与传统文件管理器不同）
• ⬆️ 向上按钮：返回上级目录

远程设备导航

路径导航：

• 当前路径显示：显示设备上的当前路径（如 /py）
• 路径编辑：可以直接输入设备路径进行导航
• 向上导航：点击 ⬆️ 按钮返回上级目录

路径格式：

• 使用 Unix 风格路径（如 /py/subdir）
• 根目录为 /
• Python 文件目录为 /py
• 只能访问 /py 及其子目录
• 访问被拒绝时会显示错误提示

5.2 文件选择

单选模式

• 默认模式：每次只能选择一个文件或文件夹
• 选择方式：点击文件行选中
• 视觉反馈：选中行背景高亮显示

多选模式

• 启用方式：默认支持多选，无需特殊设置
• 选择方式：
  • 点击文件行切换选中状态
  • 复选框直接勾选/取消勾选
• 批量操作：支持对多个文件进行批量上传、下载、删除等操作

选择状态显示

• 状态栏显示：已选择: X 个文件, Y 个文件夹
• 选择限制：
  • 本地面板：文件和文件夹都可以选择
  • 远程面板：文件和文件夹都可以选择

5.3 文件类型过滤

文件类型过滤器帮助快速找到特定类型的文件。

过滤器选项

过滤规则

• 文件夹始终显示：无论选择什么过滤器，文件夹都会显示
• 扩展名匹配：根据文件的扩展名进行过滤
• 大小写不敏感：扩展名匹配不区分大小写
• 实时过滤：选择过滤器后立即应用，无需刷新

5.4 文件上传

单文件上传

操作步骤：

1. 选择源文件：

   • 在左侧本地面板中选择要上传的文件
   • 支持单选或多选文件
   • 只能选择文件，不能选择文件夹

2. 确认目标位置：

   • 右侧远程面板显示当前设备目录
   • 文件将上传到设备当前显示的目录

3. 执行上传：

   • 或点击右侧面板的"⬆️ 上传"按钮

4. 上传过程：

   • 状态栏显示上传进度："⬆️ 正在上传: 文件名 (X%)"
   • 进度条显示实时进度
   • 显示传输速度和剩余时间

5. 上传完成：

   • 显示成功提示："✅ 上传完成"
   • 右侧面板自动刷新显示新上传的文件

     

批量上传

操作步骤：

1. 选择多个文件：

   • 在左侧面板中使用多选功能选择多个文件
   • 支持选择不同类型的文件

2. 批量上传：

   • 点击"上传"按钮
   • 软件会依次上传每个文件

3. 进度显示：

   • 显示总体进度：“批量上传: X 个文件”
   • 显示当前文件进度
   • 显示已完成的文件数量

4. 结果汇总：

   • 所有文件上传完成后显示汇总结果
   • 显示成功和失败的文件数量
   • 列出失败的文件及其错误原因

上传限制

• 文件类型：支持所有文件类型
• 文件大小：无理论限制，通过分块传输实现
• 同时上传：每次只能上传一个文件（设备限制）
• 覆盖处理：如果目标文件存在，会提示是否覆盖

5.5 文件下载

单文件下载

操作步骤：

1. 选择源文件：

   • 在右侧远程面板中选择要下载的文件
   • 支持单选或多选文件

2. 确认目标位置：

   • 左侧本地面板显示当前本地目录
   • 文件将下载到本地当前显示的目录

3. 执行下载：

   • 点击右侧面板的"⬇️ 下载"按钮
   • 或双击远程面板中的文件

4. 下载过程：

   • 状态栏显示下载进度："⬇️ 正在下载: 文件名 (X%)"
   • 进度条显示实时进度
   • 显示已下载大小和总大小

5. 下载完成：

   • 显示成功提示："✅ 下载完成"
   • 左侧面板自动刷新显示新下载的文件

批量下载

操作步骤：

1. 选择多个文件：

   • 在右侧面板中选择多个文件

2. 批量下载：

   • 点击"下载"按钮
   • 根据"下载后删除"选项处理每个文件

3. 进度显示：

   • 显示当前正在下载的文件
   • 显示总体进度和统计信息

4. 结果汇总：

   • 下载完成后显示详细的成功/失败统计
   • 失败文件列表包含具体错误信息

下载后删除选项

功能说明：

• 适用场景：文件迁移、设备空间清理
• 安全机制：只有下载成功后才删除源文件
• 批量支持：支持批量下载时的逐个删除

使用方法：

1. 在右侧面板底部找到"下载后删除"复选框
2. 勾选该选项
3. 执行下载操作
4. 下载成功后自动删除远程文件

注意事项：

• ⚠️ 不可逆操作：删除的文件无法恢复

5.6 文件系统操作

创建目录

操作步骤：

1. 定位目标位置：

   • 在右侧远程面板中导航到要在其中创建目录的位置

2. 打开创建对话框：

   • 点击右侧面板的"创建目录"按钮
   • 弹出目录名称输入对话框

3. 输入目录名称：

   • 输入新目录的名称
   • 名称要求：字母、数字、下划线，不能包含特殊字符

4. 确认创建：

   • 点击"确定"按钮
   • 软件验证名称有效性并发送创建命令

5. 创建结果：

   • 成功：显示"目录创建成功"
   • 失败：显示错误原因
   • 面板自动刷新显示新创建的目录

删除文件/目录

删除文件：

1. 在右侧面板中选择要删除的文件
2. 点击"🗑️ 删除"按钮
3. 弹出确认对话框
4. 点击"是"确认删除

删除目录：

1. 选择要删除的目录
2. 删除确认对话框会特别提示：“删除目录将同时删除其中的所有文件，是否继续？”
3. 目录及其所有子文件和子目录都会被删除
4. 删除操作不可逆

重命名文件/目录

操作步骤：

1. 选择目标：

   • 在右侧面板中选择要重命名的文件或目录
   • 每次只能选择一个项目

2. 打开重命名对话框：

   • 点击"📝 重命名"按钮
   • 弹出重命名输入对话框

3. 输入新名称：

   • 显示当前名称
   • 输入新的名称
   • 遵循与创建目录相同的命名规则

4. 确认重命名：

   • 点击"确定"按钮
   • 软件检查新名称的有效性和可用性

5. 重命名结果：

   • 成功：显示"重命名成功"
   • 失败：显示错误原因
   • 面板自动刷新显示新名称

第六章：Python 开发支持

6.1 Python 文件编译功能

OP-BT/BTS 文件管理器提供了一键 Python 文件编译功能，将 Python 源代码编译为字节码文件，便于在设备上运行。

编译功能特性

• 一键编译：无需手动执行命令，点击按钮即可编译
• 批量处理：支持单个或多个文件批量编译
• 进度显示：实时显示编译进度和结果统计
• 错误处理：详细的编译错误信息显示
• 自动刷新：编译完成后自动刷新文件列表

支持的文件类型

• Python 源文件：.py - 标准 Python 源代码文件

编译输出

• 字节码文件：.py.o - OpPython 编译后的字节码文件

6.2 编译工具配置

编译功能依赖外部 Python 编译工具 op-py-compile.exe。

工具要求

• 文件名：op-py-compile.exe
• 位置：应用程序目录或系统 PATH 中
• 权限：可执行权限
• 兼容性：与当前 Python 版本兼容

工具获取

1. 随软件安装：理想情况下随软件一起安装
2. 手动放置：将工具文件放到软件安装目录
3. PATH 配置：添加到系统 PATH 环境变量

命令格式

op-py-compile.exe -c "文件名"

6.3 单文件编译

操作步骤：

1. 选择源文件：

   • 在左侧本地面板中选择一个 Python 文件
   • 支持的文件扩展名：.py

2. 点击编译按钮：

   • 点击左侧面板的"🔨 编译"按钮
   • 按钮仅在选择 Python 文件时可用

3. 编译过程：

   • 状态栏显示：“编译中…”
   • 调用 op-py-compile.exe -c "完整路径"

4. 编译结果：

   • 成功：显示"编译成功"，自动刷新文件列表
   • 失败：弹出错误对话框显示详细错误信息

6.4 批量编译

操作步骤：

1. 选择多个文件：

   • 使用多选功能选择多个 Python 文件

2. 点击编译按钮：

   • 弹出批量编译选择对话框

3. 选择编译方式：

   • 编译第一个文件：只编译选择的文件中的第一个
   • 编译全部文件：依次编译所有选中的文件
   • 取消：取消编译操作

4. 批量编译过程：

   • 状态栏显示：“编译 X/Y 个文件（成功：A，失败：B）”
   • 进度条显示总体进度
   • 逐个调用编译工具

5. 结果汇总：

   • 编译完成后显示详细结果对话框
   • 包含成功和失败的文件数量
   • 失败文件列表及具体错误信息

6.5 运行 Python 文件

OP-BT/BTS 文件管理器提供了直接在设备上运行 Python 文件的功能。

功能特性

• 一键运行：选择文件后点击"运行"按钮即可
• 支持文件类型： 目前只支持编译后的.o（字节码文件）
• 状态反馈：在状态栏显示运行命令发送状态

操作步骤

1. 选择文件：

   • 在右侧远程文件列表中选择一个 .o 文件
   • 重要：文件必须位于 /py 目录下
   • 只能选择一个文件（不支持多选）

2. 点击运行按钮：

   • 点击远程操作区域的"▶️ 运行"按钮

3. 查看状态：

   • 状态栏显示："▶️ 运行 文件名 命令已发送"
   • 命令已发送给设备，设备会执行文件

文件要求

错误提示

如果操作不符合要求，状态栏会显示相应的错误信息：

• 未选择文件：“请先选择要运行的文件”
• 选择了多个文件：“一次只能运行一个文件”
• 选择了目录：“不能运行目录”
• 文件类型错误：“只能运行 Python 字节码文件 (.py.o)”
• 文件不在/py目录：“文件不在 /py 目录下”
• 路径过长：“文件路径过长（超过30个字符）”

6.6 查看编译结果

文件类型过滤器

使用"Python字节码文件"过滤器查看编译生成的文件：

1. 在文件类型下拉框中选择"Python字节码文件 (.o)"
2. 文件列表只显示 .o 格式的字节码文件
3. 确认字节码文件已生成

字节码文件管理

设备运行建议

• 优先使用：.o 格式的设备特定字节码
• 调试建议：开发时保留 .py 文件，部署时使用字节码

第七章：通信监视器

7.1 功能概述

功能完善中…

第八章：设置和配置

8.1 打开设置页面

打开方式：

1. 点击主界面右上角的菜单按钮（⋮）
2. 从弹出菜单中选择"⚙️ 设置"
3. 设置页面以模态对话框形式打开

8.2 语言设置

设置选项：

• 中文：完整的中文用户界面
• English：完整的英文用户界面

切换步骤：

1. 打开设置页面
2. 点击"语言选择"下拉框
3. 选择"中文"或"English"
4. 点击"保存"按钮
5. 软件立即应用新的语言设置

语言切换效果：

• 界面文本：所有按钮、标签、菜单项立即更新
• 对话框：弹出对话框的文本也随之更新
• 状态信息：状态栏和提示信息使用新语言

8.3 连接参数配置

上传封包大小

参数说明：

• 单位：字节
• 默认值：100 字节
• 有效范围：10-100 字节

选择建议：

• 10-30字节：高延迟网络，最高稳定性
• 31-70字节：一般网络，平衡性能
• 71-100字节：高速网络，最高效率

推荐值：50-80字节（平衡稳定性和速度）

下载封包大小

参数说明：

• 单位：字节
• 默认值：500 字节
• 有效范围：50-800 字节

选择建议：

• 50-200字节：内存受限设备，低内存占用
• 201-500字节：标准设备，平衡性能
• 501-800字节：高性能设备，最高效率

推荐值：200-500字节（大多数设备的最佳选择）

超时时间

参数说明：

• 单位：毫秒
• 默认值：2000 毫秒（2秒）
• 有效范围：500-30000 毫秒

选择建议：

• 500-1000ms：高速网络，本地串口连接
• 1001-2000ms：一般网络，标准蓝牙连接
• 2001-5000ms：慢速网络，不稳定连接

推荐值：2000ms（大多数情况适用）

8.4 BLE 特征值配置

配置 BLE 连接的 GATT 服务和特征 UUID 值。

配置项说明

服务UUID（Service UUID）：

• 参数说明：BLE GATT 服务的 UUID
• 格式：4位十六进制数（例如：18F0）
• 默认值：18F0
• 用途：用于识别 OP-BT 设备的 GATT 服务

TX特征UUID（TX Characteristic UUID）：

• 参数说明：用于发送数据到设备的特征 UUID
• 格式：4位十六进制数（例如：2AF0）
• 默认值：2AF0
• 用途：用于向设备写入数据

RX特征UUID（RX Characteristic UUID）：

• 参数说明：用于从设备接收数据的特征 UUID
• 格式：4位十六进制数（例如：2AF1）
• 默认值：2AF1
• 用途：用于接收设备发送的数据（通过通知）

UUID格式要求

• 长度：必须是4位字符
• 字符：只能包含 0-9 和 A-F（不区分大小写）
• 示例：
  • ✅ 正确：18F0、2AF0、2AF1、0001
  • ❌ 错误：18F（3位）、18F00（5位）、18G0（包含非法字符）

使用建议

• 默认值：大多数 OP-BT 设备使用默认值（18F0, 2AF0, 2AF1），无需修改
• 自定义值：仅在设备使用非标准 UUID 时才需要修改
• 留空处理：如果留空，将使用默认值

8.5 访问权限 KEY 配置

功能等完善中…

8.6 BLE 连接超时时间配置

功能说明：

• 参数说明：BLE连接时等待设备响应的最长时间
• 单位：毫秒（ms）
• 默认值：2000ms（2秒）
• 有效范围：1000-30000ms（1秒-30秒）

超时时间选择建议

使用建议

• 推荐值：2000ms（大多数情况适用）
• 快速环境：如果设备在附近且信号强，可以使用1000-1500ms
• 慢速环境：如果设备距离较远或信号弱，建议使用3000-5000ms

8.7 保存设置

保存操作：

1. 完成所有配置修改
2. 点击"💾 保存"按钮
3. 设置立即保存并生效
4. 显示"设置保存成功！“提示

取消操作：

1. 点击”❌ 取消"按钮
2. 所有未保存的修改会被丢弃
3. 返回主界面

设置生效时机：

• 立即生效：设置保存后立即应用到新的操作
• 现有连接：不影响当前已建立的连接
• 重连生效：重新连接设备时使用新参数

第九章：平台特定指南

9.1 Windows 平台

功能支持

• ✅ 串口连接：完整支持
• ✅ 蓝牙 BLE 连接：完整支持
• ✅ 通信监视器：完整支持
• ✅ 所有文件操作：完整支持

特殊注意事项

串口访问权限：

• 某些串口可能需要管理员权限才能访问
• 如果遇到权限问题，尝试以管理员身份运行应用

蓝牙权限：

• Windows 10/11 会自动管理蓝牙权限
• 首次使用 BLE 功能时会提示用户授权

文件系统访问：

• 支持访问所有本地文件系统
• 支持在资源管理器中打开目录（Windows 特有功能）

推荐配置

• 上传封包大小：50-80字节
• 下载封包大小：200-500字节
• 超时时间：2000ms
• BLE连接超时：2000ms

9.2 Android 平台

功能待完善中…

第十章：常见问题

10.1 连接问题

Q: 软件启动后无法找到串口设备？

A: 请按以下步骤检查：

1. 确认串口适配器已正确连接到计算机USB端口,是否进行蓝牙连接的配对
2. 检查设备管理器中是否有串口设备
3. 点击软件中的"刷新"按钮重新检测串口
4. 如果仍然找不到，尝试重新插拔USB适配器或更换USB端口或者重新进行蓝牙配对
5. Windows 平台：检查是否需要管理员权限

Q: 连接设备时提示"串口被占用"？

A: 此错误表示串口被其他程序占用：

1. 关闭可能使用串口的程序（如串口调试工具、其他文件管理软件）
2. 检查是否有其他终端或命令行程序在使用该串口
3. 重启计算机释放所有串口资源
4. 确认没有其他设备连接到同一个串口

Q: BLE扫描不到设备怎么办？

A: BLE设备扫描问题排查：

1. 设备状态：确保OP-BT/BTS设备已开启并处于可发现状态
2. 蓝牙适配器：检查计算机/手机蓝牙是否已启用
3. 距离问题：确保设备在蓝牙信号范围内（建议1-2米内）
4. 设备可见性：确认设备正在广播BLE信号（设备指示灯应闪烁）
5. 重新扫描：点击"扫描"按钮重新扫描，扫描过程约5-10秒
6. 平台限制：BLE功能仅在支持的平台上可用
7. Android权限：Android 6.0+ 需要授予位置权限

Q: BLE连接失败怎么办？

A: BLE连接失败排查步骤：

1. 设备选择：确认已从下拉列表中选择正确的设备
2. 信号强度：检查信号强度，建议在-65dBm以上（数值越大越好）
3. 设备占用：确认设备未被其他应用占用
4. 重新连接：尝试断开后重新扫描并连接
5. 设备支持：确认设备支持BLE模式（不是所有OP-BT设备都支持）
6. 特征值配置：检查BLE特征值配置是否正确
7. 备用方案：如果BLE连接不稳定，建议使用串口连接

Q: 连接成功但无法查看文件？

A: 连接成功但无文件显示：

1. 确认设备已正确上电并运行OP-BT/BTS固件
2. 尝试手动刷新右侧面板（点击"刷新"按钮）
3. 检查设备是否支持文件系统操作
4. 确认连接参数正确（波特率等）

10.2 文件操作问题

Q: 文件上传非常慢或经常失败？

A: 上传问题及解决方法：

1. 减少封包大小：在设置中减小上传封包大小（尝试50字节）
2. 检查连接稳定性：确认串口连接稳定，无数据线松动，蓝牙连接则拉进一些距离
3. 增加超时时间：在设置中增加超时时间（尝试3000毫秒）
4. 分批上传：避免一次性上传过多大文件
5. 检查设备空间：确认设备有足够存储空间
6. 平台特定：移动平台（Android/iOS）建议使用较小的封包大小

Q: 下载文件时出现乱码或损坏？

A: 下载文件损坏的可能原因：

1. 传输参数不匹配：确认上传和下载使用相同的数据格式
2. 文件类型问题：某些二进制文件可能需要特殊处理
3. 存储空间不足：本地磁盘空间不足导致文件截断
4. 权限问题：本地文件夹没有写入权限
5. 重新下载：删除损坏文件，重新从设备下载
6. 编码问题：文本文件可能需要检查编码设置

Q: 批量上传/下载时部分文件失败？

A: 批量操作失败的原因：

1. 文件名冲突：目标位置已有同名文件，选择覆盖或重命名
2. 权限不足：某些文件或目录没有访问权限
3. 空间不足：设备或本地存储空间不足
4. 文件锁定：文件被其他程序使用中
5. 继续处理：失败的文件不会影响其他文件的传输
6. 查看错误信息：失败文件列表包含具体错误信息

10.3 Python 编译问题

Q: 点击编译按钮无反应或显示工具未找到？

A: 编译工具问题的解决：

1. 工具位置：确认op-py-compile.exe在软件目录或系统PATH中
2. 文件完整性：检查编译工具文件是否完整且未损坏
3. 权限设置：确认编译工具具有执行权限
4. 路径问题：避免工具路径包含中文或特殊字符
5. 重新安装：重新下载或安装编译工具
6. 平台兼容性：确认编译工具与当前平台兼容

Q: 编译过程中提示语法错误？

A: Python语法错误的处理：

1. 检查代码：使用文本编辑器检查Python文件语法
2. 编码问题：确保文件使用UTF-8编码保存
3. Python版本：确认代码兼容目标Python版本
4. 导入错误：检查import语句和模块路径
5. 缩进问题：Python对缩进非常敏感，检查缩进是否正确

Q: 运行 Python 文件没有反应？

A: 运行问题的排查：

1. 文件位置：确认文件在 /py 目录下
2. 文件类型：确认文件是 .py 或 .o 文件
3. 选择数量：确认只选择了一个文件
4. 设备状态：检查设备是否正常工作
5. 查看设备输出：软件只发送命令，不显示执行结果，需要查看设备端的输出

10.4 平台特定问题

Q: Android 平台无法扫描 BLE 设备？

A: Android BLE 扫描问题：

1. 位置权限：Android 6.0+ 需要位置权限才能扫描 BLE 设备
2. 蓝牙权限：确认已授予蓝牙权限
3. 位置服务：某些设备需要启用位置服务（即使不使用GPS）
4. 应用权限：在系统设置中检查应用权限
5. 重新授权：尝试撤销权限后重新授权

Q: iOS 平台 BLE 连接不稳定？

A: iOS BLE 连接问题：

1. 应用状态：保持应用在前台运行，后台可能断开连接
2. 设备距离：确保设备在蓝牙信号范围内
3. 系统限制：iOS 对后台 BLE 连接有限制
4. 重新连接：断开后重新连接
5. 设备兼容性：确认设备与 iOS 兼容

Q: Windows 平台串口需要管理员权限？

A: Windows 串口权限问题：

1. 以管理员身份运行：右键点击应用，选择"以管理员身份运行"
2. 权限设置：检查串口设备的权限设置
3. 用户组：将用户添加到相应的用户组
4. 驱动问题：检查串口驱动是否正确安装

第十一章：故障排除

11.1 常见错误信息

连接相关错误

文件操作错误

编译相关错误

11.2 诊断步骤

基本检查

1. 硬件检查：

   • 确认串口适配器指示灯是否正常
   • 检查USB连接是否牢固
   • 验证蓝牙配对状态（如果使用蓝牙）

2. 软件检查：

   • 确认选择的串口正确
   • 验证通信参数设置
   • 检查软件版本是否最新

3. 设备检查：

   • 检查设备电源和状态指示灯
   • 确认设备固件版本
   • 验证设备正常工作

逐步隔离问题

1. 尝试不同连接方式：

   • 如果串口连接失败，尝试 BLE 连接
   • 如果 BLE 连接失败，尝试串口连接

2. 使用最小化配置：

   • 使用默认参数测试连接
   • 排除参数配置问题

3. 在不同平台上测试：

   • 如果可能，在另一台设备上测试
   • 排除平台特定问题

4. 排除第三方软件干扰：

   • 关闭可能冲突的程序
   • 检查防火墙和杀毒软件设置

11.3 获取技术支持

准备信息

如果问题无法自行解决，请准备以下信息：

1. 基本信息：

   • 软件版本号
   • 操作系统版本
   • 硬件配置（CPU、内存、存储）
   • OP-BT/BTS设备型号和固件版本

2. 问题描述：

   • 问题发生的详细步骤
   • 期望的行为和实际行为
   • 错误信息和截图
   • 问题发生的频率（总是/有时/偶尔）

3. 诊断信息：

   • 相关的日志文件
   • 系统事件日志
   • 串口参数和连接设置
   • 测试过程中的观察结果

4. 环境信息：

   • 其他相关软件和硬件
   • 网络环境（如果是网络相关问题）
   • 最近的系统变更或更新

联系方式

• 技术支持邮箱：联系技术支持团队support@zenovate.tech

附录

A. 快捷键参考

Windows 平台

Android/iOS 平台

• 主要使用触摸操作
• 支持长按显示上下文菜单（如果实现）

B. 文件路径格式

本地文件路径

• Windows：C:\Users\Username\Documents\file.txt
• Android：/storage/emulated/0/Documents/file.txt
• iOS：应用沙盒目录（用户不可直接访问）
• macOS：/Users/Username/Documents/file.txt

远程设备路径

• Unix 风格：/py/subdir/file.py
• 根目录：/
• Python 目录：/py

C. 版本历史

文档 v1.1（2026-01-31）

• 英文版用户手册全文翻译完成

v0.0.47（当前版本）

• 初始 MAUI 版本发布
• 支持 Windows、Android、iOS、macOS
• 实现双面板文件管理
• 支持串口和蓝牙 BLE 连接
• 实现通信监视器功能
• 支持 Python 文件编译和运行
• 实现多语言支持（中文/英文）

文档版本：1.1
最后更新：2026年1月31日
适用版本：OpBtFileManager.MAUI v0.0.47+

感谢您使用 OP-BT/BTS 文件管理器 MAUI 版！如有任何问题或建议，欢迎反馈。

©2007-2024 TESPRO CORPORATION. ALL RIGHTS RESERVED.

English | 中文 |