# ADB终端

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

**ADB** 是 **Android Debug Bridge（Android调试桥）** 的缩写，是一套用于主机电脑与设备之间通信的命令行工具。通过 **ADB**，用户可以在电脑端查看设备连接状态、进入设备 Shell、传输文件、重启设备以及执行调试命令。

在 **Quectel Pi M2 Debian** 系统中，ADB 主要用于开发阶段的本地调试和快速文件传输。电脑端通过双头 **Type-A USB** 数据线连接开发板后，即可使用 `adb devices`、`adb shell`、`adb push`、`adb pull` 等命令管理设备。

# 准备工作

1. 准备一条双头 **Type-A USB** 数据线，将一端接入 **Quectel Pi M2** 的 **USB** 接口，另一端接入主机电脑。

```{image} images/image_MKYTbvNmQoSqpoxw2aScI3gFnjg.webp
:width: 495px
:height: 340px
```

2. 在电脑端下载 [platform-tools](<https://www.quectel.com.cn/wp-content/uploads/2026/08/platform-tools.zip>) 工具，并解压到本地目录。

3. 打开 **platform-tools** 工具所在文件夹，在顶部路径框中输入 **cmd**，按回车键打开 **ADB** 终端。

```{image} images/image_MdpSbVpUfoBAYCxN1Qrc55mlnHf.webp
:width: 1293px
:height: 833px
```

```{image} images/image_NOhRbTTtZoLc71xtnoRct4Dbnmg.webp
:width: 1291px
:height: 837px
```

```{image} images/image_UeW6bA2vAorrcsxNjq3ceOM0nUb.webp
:width: 972px
:height: 505px
```

# 软件安装

电脑端需要安装或解压 **platform-tools**，其中包含 `adb` 命令。

Quectel Pi M2 Debian 系统中已集成 ADB 功能，由 `usbdevice.service` 管理，ADB 程序路径为 `/usr/bin/adbd`。通常无需额外安装软件包。

可在开发板端查看 USB 设备功能服务状态：

```bash
systemctl status usbdevice.service --no-pager -l
```

# 软件配置

ADB 功能由 `usbdevice.service` 管理，常用配置和管理方式如下：

| **配置项** | **说明** |
| --- | --- |
| 服务名称 | `usbdevice.service` |
| 管理脚本 | `/usr/bin/usbdevice` |
| ADB 程序 | `/usr/bin/adbd` |
| 连接方式 | 双头 Type-A USB 数据线连接主机电脑和开发板 |
| 典型用途 | Shell 调试、文件传输、设备状态查看 |

如需限制 ADB 使用，可停止或禁用 USB 设备功能服务。禁用后建议重启系统，使状态保持一致：

```bash
sudo systemctl stop usbdevice.service
sudo systemctl disable usbdevice.service
sudo reboot
```

如需重新开启 ADB 功能，可执行：

```bash
sudo systemctl start usbdevice.service
sudo systemctl enable usbdevice.service
sudo reboot
```

# 软件启动

启动 USB 设备功能服务：

```bash
sudo systemctl start usbdevice.service
```

设置开机自启：

```bash
sudo systemctl enable usbdevice.service
```

查看当前状态：

```bash
systemctl status usbdevice.service --no-pager -l
systemctl is-active usbdevice.service
```

重启服务：

```bash
sudo systemctl restart usbdevice.service
```

# ADB 调试

## 查看连接设备

在电脑端 **ADB** 终端中执行：

```bash
adb devices
```

若列表中出现设备条目，且状态为 `device`，表示电脑已识别开发板。

## 进入设备 Shell

在电脑端执行：

```bash
adb shell
```

进入 Shell 后，即可在开发板系统中执行常用 Linux 命令。可先执行以下命令确认当前用户：

```bash
id
whoami
```

若需退出 Shell，请输入：

```bash
exit
```

```{image} images/image_SmGhbjqCzo8bdIxh8c5cfBAynqd.webp
:width: 1113px
:height: 626px
```

## 从电脑传输文件到设备

```bash
# 用法：adb push <电脑文件路径> <设备存放路径>
adb push ./test.txt /data/local/tmp/
```

## 从设备传输文件到电脑

```bash
# 用法：adb pull <设备文件路径> <电脑存放路径>
adb pull /data/local/tmp/test.txt ./
```

其中 `./` 表示保存到当前 **ADB** 终端所在目录。

## 重启设备

```bash
adb reboot
```

# 疑难解答

| **问题现象** | **排查方法** |
| --- | --- |
| `adb devices` 无设备 | 检查 USB 线是否支持数据传输；确认线缆已接入 M2 的 USB 接口；重新插拔后再次执行 `adb devices`。 |
| 设备状态为 `offline` | 执行 `adb kill-server` 和 `adb start-server` 后重新连接。 |
| 电脑端无 `adb` 命令 | 确认已解压 platform-tools，并在该目录打开终端，或将 platform-tools 加入系统环境变量。 |
| 开发板端服务未运行 | 在开发板端执行 `systemctl status usbdevice.service --no-pager -l` 查看服务状态，并按需执行 `sudo systemctl restart usbdevice.service`。 |
| 文件传输失败 | 检查目标路径是否存在、是否有写入权限，建议先使用 `/data/local/tmp/` 目录进行测试。 |