# PyOCD 的基本使用

## 1. 基本命令

- erase：擦除 Flash；
- load：烧写 Flash，带擦除和校验；
- gdbserver：启动 GDB Server 服务器；
- list：列出已连接的调试器；
- rtt：控制 SEGGER RTT 兼容接口。

## 2. pack 管理

PyOCD 可以使用 .pack 文件（CMSIS-Packs），许多芯片尤其是国产芯片，只提供 .pack 文件来支持开发和调试。

PyOCD 通过 --pack 指定 .pack 文件。

## 3. 指定芯片型号

使用 --target 参数指定烧录芯片型号：

```bash
pyocd erase --chip --target stm32f103rc
```

如果需要指定国产芯片，则需要结合 --pack 参数，例如：

```bash
pyocd erase --chip --target n32l406cb --pack <"/Path/To/Nationstech.N32L40x_DFP.0.9.0.pack">
```

## 4. 擦除芯片

使用 erase 命令擦除芯片，需要指定擦除方法，如：--chip、--sector、--mass。

```bash
# 擦除整个芯片
pyocd erase --chip --target <Target Chip Name> --pack <"/Path/to/PackFile.pack">
```

## 5. 烧写芯片

使用 load 命令烧写新，需要指定烧写的起始地址和要烧写的程序。load 命令会自动擦除 Flash 并校验，可以指定擦除和校验方法。

```bash
pyocd.exe load --trust-crc --base-address <Program Start Address> <"/Path/To/Program.hex"> --target <Target Chip Name> --frequency {Examples: "1000", "2.5khz", "10m"} --erase {auto,chip,sector} --pack <"/Path/to/PackFile.pack">
```

## 6. GDB Server 调试

使用 gdbserver 命令启动 gdbserver 服务，然后可以使用 gdb 客户端进行连接调试。

```bash
pyocd gdbserver --port 50000 --telnet-port 50001 --target <Target Chip Name> --pack <"/Path/to/PackFile.pack">
```

## 7. RTT 控制

项目中如果兼容 RTT 接口，则可以通过 PyOCD 查看 RTT 输出。集成 RTT 的方法为，将 [RTT 接口](./RTT.zip) 文件解压后添加到项目中，代码中增加：

```c
#include "SEGGER_RTT.h"

SEGGER_RTT_ConfigUpBuffer(0, "RTTUP0", NULL, 0,
                              SEGGER_RTT_MODE_NO_BLOCK_SKIP);
SEGGER_RTT_ConfigDownBuffer(0, "RTTDOWN", NULL, 0,
                                SEGGER_RTT_MODE_NO_BLOCK_SKIP);
SEGGER_RTT_SetTerminal(0);
```

进行配置，使用：

```c
SEGGER_RTT_printf(0, "Hello\r\n");
```

进行打印。

该方法不但支持 JTAG，还支持 CMSIS-DAP/DAPLink 等调试器。

```bash
pyocd.exe rtt --target <Target Chip Name> --pack <"/Path/to/PackFile.pack">
```

其他参数：

- --help
- --address
- --size
- --up-channel-id
- --down-channel-id
- --log-file

PyOCD v0.35.1 及 v0.36.0 的 RTT 存在一个 Bug 导致使用 RTT 是出现 “C Control block not found [__main__]” 错误。回退到 v0.34.3 则该问题消失，参见 [Control block not found when using rtt with pyocd 0.35.0 #1553](https://github.com/pyocd/pyOCD/issues/1553)

遇到该问题可以使用 [Reset the offset in finding control block #1654](https://github.com/pyocd/pyOCD/pull/1654/commits/94debabb9f8b4415fa1f5ede409e77b6f60f6375) 或 [Fix RTT Control Block Search #1669](https://github.com/pyocd/pyOCD/pull/1669/commits/4c9acbcefb58de87d6e164e1868cd1cee2c16f31) 方法临时修正。但目前这两种修复方法都不支持指定 --address 和 --size 参数，因此，即便使用了这两个 pack，但在使用 RTT 时指定了这两个参数，依然会报“C Control block not found [__main__]” 错误。

## 8. 常见问题

## 8.1. 找不到 libusb 库

PyOCD 配合 ST-Link、CMSIS-DAPv2 使用时，需要 libusb 库支持，若没有按照或正确配置，将提示：

```bash
STLink, CMSIS-DAPv2 and PicoProbe probes are not supported because no libusb library was found.
```

此时需按如下方式安装配置：

```bash
pip intall libusb
```

Windows 下安装完毕后将在 \<Python 安装目录>/Lib/site-packages/libusb/_platform/_windows 的子文件夹下找到对应的 libusb-1.0.dll 文件，将其拷贝到 \<Python 安装目录> 或 \<Python 安装目录>/Scripts 下（只要被系统 PATH 包含即可）即可在系统命令行中正常使用。

## 9. 外部参考资料

1. [PyOCD Command reference](https://pyocd.io/docs/command_reference.html)