Ubuntu 完美安装 FT_SCServo_Debug_Qt 飞特SCS_STS舵机调试工具

一、前言

FT_SCServo_Debug_Qt 是一款基于 Qt 开发的飞特 Feetech SCS/STS 系列总线舵机专用调试上位机，专为 Linux（Ubuntu）平台设计，完美适配嵌入式开发、机器人舵机调试场景。

官方提供 AMD64 / ARM64 预编译 deb 安装包，理论上可一键安装，但在实际 Ubuntu22.04 安装过程中，会遇到 APT 沙盒权限警告、安装成功但命令找不到、deb 包安装残缺、程序本体缺失 等一系列隐性BUG。

本文结合真实踩坑经历，整理两套可用安装方案（快速源码编译+修复版deb安装），彻底解决所有安装报错，零基础可直接复刻操作。

适配环境

系统：Ubuntu 22.04（AMD64 / ARM64 通用）
开发依赖：Qt5.14 / Qt5.15
硬件适配：飞特 SCS/STS 全系列串行总线舵机
必备硬件驱动：CH340 串口驱动

已知软件限制（v1.1.0 最新版）

当前版本暂未开发以下功能，无对应操作入口：

固件升级（Upgrade）标签及功能
PWM 调节标签及相关功能

二、前置必备配置（所有安装方式必做）

舵机调试核心依赖串口通信，Ubuntu 默认普通用户无串口权限，不配置会导致软件识别不到设备、通信失败。

1. 配置串口权限

bash 复制代码

# 将当前用户加入串口拨号组
sudo usermod -aG dialout $USER
# 权限即时生效（无需注销重启）
newgrp dialout

2. 验证串口设备

插入 CH340 舵机调试板，执行以下命令，正常会输出 ttyUSB 设备：

bash 复制代码

ls /dev/ttyUSB*

三、踩坑复盘（重点！官方deb安装通病）

很多用户按照官方文档安装 deb 包后，会出现以下现象，也是本文核心解决的问题：

安装过程无报错，显示成功配置软件
终端提示：无法被用户'_apt'访问，已脱离沙盒并提权 权限警告
输入启动命令，提示 未找到命令
系统仅保留 dpkg 安装记录，无任何程序本体文件，软链接失效

故障根源

在家目录（/home/xxx）下执行 deb 安装，APT 沙盒用户 _apt 无读取权限，导致安装流程虚假完成，仅注册记录，未解压程序文件，最终软件无法启动。

四、方案一：源码编译安装（推荐！稳定无BUG）

彻底规避 deb 打包缺陷，无权限报错、无文件缺失问题，适合长期使用、二次开发，优先推荐。

步骤1：安装全套编译依赖

bash 复制代码

sudo apt update
sudo apt install -y libqt5serialport5 libqt5serialport5-dev qt5-qmake g++ cmake git

步骤2：拉取官方源码仓库

bash 复制代码

git clone https://github.com/Kotakku/FT_SCServo_Debug_Qt.git
cd FT_SCServo_Debug_Qt

步骤3：Qt 编译构建

bash 复制代码

# 生成编译配置文件
qmake .
# 多线程编译，加速编译过程
make -j$(nproc)

步骤4：启动软件（两种方式）

方式1：目录内直接启动（默认）

bash 复制代码

./FT_SCServo_Debug_Qt

方式2：配置全局命令（任意终端可启动）

bash 复制代码

# 复制程序到系统全局目录
sudo cp ./FT_SCServo_Debug_Qt /usr/local/bin/ft-scservo-debug-qt
# 全局启动
ft-scservo-debug-qt

五、方案二：修复版 deb 包一键安装（官方方案改良）

保留官方一键安装的便捷性，修复沙盒权限报错问题，适合不想编译源码的用户。

步骤1：彻底清理残缺旧安装

bash 复制代码

# 彻底卸载残留安装记录
sudo apt purge -y ft-scservo-debug-qt
# 清理无用依赖
sudo apt autoremove -y

步骤2：临时目录重新安装（规避权限BUG）

核心修复：将 deb 包放入无权限限制的 /tmp 目录安装，彻底解决沙盒访问失败问题。

bash 复制代码

# 进入临时目录
cd /tmp

# AMD64 台式机/笔记本 执行
wget https://github.com/Kotakku/FT_SCServo_Debug_Qt/releases/download/v1.1.0/ft-scservo-debug-qt_1.1.0_amd64.deb
sudo apt install ./ft-scservo-debug-qt_1.1.0_amd64.deb

# ARM64 树莓派/飞腾开发板 执行
# wget https://github.com/Kotakku/FT_SCServo_Debug_Qt/releases/download/v1.1.0/ft-scservo-debug-qt_1.1.0_arm64.deb
# sudo apt install ./ft-scservo-debug-qt_1.1.0_arm64.deb

步骤3：验证并配置全局启动

bash 复制代码

# 查看程序是否安装成功
ls /opt/ft-scservo-debug-qt/
# 创建全局软链接
sudo ln -s /opt/ft-scservo-debug-qt/ft-scservo-debug-qt /usr/local/bin/ft-scservo-debug-qt
# 启动软件
ft-scservo-debug-qt

六、Docker 自行打包deb（开发者专用）

如需自行编译生成适配本机架构的 deb 安装包，可使用官方 Docker 打包脚本，普通用户无需操作：

bash 复制代码

git clone https://github.com/Kotakku/FT_SCServo_Debug_Qt.git
cd FT_SCServo_Debug_Qt/deb
bash create_deb.bash

执行完成后，deb 安装包将生成在 deb 目录下，可按照方案二方式安装。

七、常见问题终极排查

1. 命令未找到、软链接失效

原因：deb 安装残缺，程序本体缺失。解决：卸载残留记录，改用源码编译方案。

2. 软件打开无串口

解决：重新执行串口权限配置命令，或注销用户重新登录。

3. apt 沙盒权限警告

解决：不要在 /home 家目录安装 deb，必须放入 /tmp 临时目录执行安装。

4. 编译提示 qmake 命令不存在

解决：重新执行依赖安装命令，补全 qt5-qmake 组件。