玩转 pyocd

2023-11-30 13:16:04

（一） pyocd

（1）什么是pyocd

? pyocd 是 arm 开发的一个 python 包（python package)，该软件包可以使用多种USB调试器对 arm cortex-M 微控制器进行调试、编程（烧录程序）。该软件包还是跨平台的，支持Linux、Mac、Windows。

也就是说，可以通过 pyocd 使用一些调试器来调试、擦除、烧录基于 arm cortex-M（M0/M3/M4/M7/M23/M33）内核的单片机。目前支持 Daplink、ST-Link、jlink。

目前从 pyocd github 上看到的，pyocd 内部（默认）支持70多个常用的单片机，但是通过使用 CMSIS-Packs 几乎支持所有基于 comtex-m 内核的单片机。

? 这里不关注 pyocd 调试功能，只关注把 pyocd 用作上位机来操作 MCU 的功能，可以通过两种方式使用 pyocd:

pyocd 提供了命令行工具，使用这工具可以用来调试、烧录、擦除 MCU
pyocd 提供了python API，可是使用这些API来实现控制 MCU（读取MCU寄存器、暂停、运行、复位MCU等）

（2）安装

? pyocd 支持的系统： windows、linux、Mac

由于 pyocd 是基于 python，所以需要先安装 python，pyocd 支持的 python 版本为：Python 3.6.0 or later.

安装方法有：

下载 pyocd 的源码安装

从 GitHub 获取源码：

git clone https://github.com/mbedmicro/pyOCD.git

进入pyOCD目录，使用如下命令安装：

python setup.py install

通过pip安装

pip install -U pyocd

python3 -mpip install --pre -U git+https://github.com/pyocd/pyOCD.git@develop

参考：https://pypi.org/project/pyocd/

（3） Libusb

daplink V1 使用的是 HID 协议，只要安装pyocd是可以用的，如果使用 daplink V2、ST-Link、j-link 的话，需要安装 libusb，pyocd 里面的文档给出了安装方法。

我的做法是把 libusb.dll 复制到 python 安装目录：

（二）如何使用pyocd命令行工具

首先打开命令行，windows 中可以是命令提示符或者 powershell，如下：

如果安装了 git，也可以使用 git bash，如下：

pyocd 的使用方法是在命令行中输入：

pyocd + 子命令 + 参数

在命令行中输入 pyocd 或者 pyocd -h 回车，如下图，就会输出 pyocd 的使用方法及 pyocd 的子命令：

根据上面说明，看下我安装的版本：

从上图中可以看到 0.30.2 版本有 9 个子命令，但其中 commander 跟 cmd、gdbserver 跟 gdb 是相同功能的。所以，总的来说有 9 个功能不同的子命令。分别是：

commander跟cmd：可交互的终端，
erase：擦除命令
flash：烧录命令
reset：复位设备
gdbserver跟gdb：用于gdb调试的
json：以json格式输出信息
list：可以列出dap-link、目标IC、特定板子的信息
pack：用于管理CMSIS-Pack
server

如果想知道上述命令的用法可以使用 pyocd + 上述中的一个命令 + -h/--help，如下：

这些命令各有什么用呢？什么情况下要用什么命令？这些命令怎么配合使用？

比如，使用 j-link 给 MCU 下载固件，一般会使用上位机 j-flash 通过 jlink 下载，首先上位机 j-flash 能找到 j-link，然后需要选择所下载的 MCU，然后选择所要下载的固件，这 3 步都设置好后，就可以下载程序了，

根据这些，依次介绍 pyocd 的命令：

list or json：查看能够使用的调试器、支持的 MCU
pack：管理支持的 MCU
flash & erase : 对 MCU 进行编程、擦除

（1）pyocd list 命令

从 pyocd 帮助信息来看：

list List information about probes, targets, or boards.

可以知道 list 命令使用来查看调试器、目标芯片、板子的信息，

pyocd list / pyocd list -p

列出连接到电脑上的 dap link 或者 ST link，当没接如任何pyocd所支持的设备时，如下：

接入了一个 daplink 跟 jlink 后如下：

(1.1) pyocd list -t/--target

列出所支持的IC，可以是内置的，也可以是通过安装pack获得支持的，

上面图片展示了列出了 pyocd 内置的一部分 MCU。

我的电脑中已近安装了 GD32F350 的pack，上图中，GD32F350 系列后面就显示了 pack

(1.2) pyocd list -b/--board

列出所支持的板子，如下：

（2）pyocd json 命令

json Output information as JSON.

以 json 格式输出信息，输出什么信息呢？看下 json 命令帮助：

从上图可以看到 pyocd json 一共可以输出4中信息：probes、targets、boards、features。分别看下这4中会输出什么。

（2.1）pyocd list -p

当电脑没有接入任何 pyocd 支持的设备时：

可以看到输出了所安装的 pyocd 版本信息，接了一块ST的开发板后，如下：

可以看到，输出的除了 pyocd 版本信息外，还有所接板子的信息：板子上调试器的ID、板的名字等。

再试一下，接一块没有连接目标 MCU 的 Daplink，输出的信息如下：

（2.2） pyocd json -t

从帮助信息来看，是输出所有已知的 target，先试下pyocd json -t命令，如下：

输出一大堆数据，除了有pyocd 版本信息外，就是一些MCU的信息，有MCU的厂商、型号，还有该信息是内置的还是来自pack。

试下能不能输出指定 MCU 的信息：

从上述结果来看，好像是不行。

pyocd list 跟 pyocd json 功能应该是差不多的，都是输出一些信息，如接入了电脑的调试器信息，系统所支持的单片机等，只不过输出方式不同，pyocd list 是直接输出相关信息，pyocd json 是以 json 格式输出相关信息。

（3）pyocd pack 命令

pyocd 通过两种方法支持 MCU，一个是内置的（builtin)，这个数量有限，还有一个是通过 pack 来支持，需要用pyocd 操作什么 MCU，安装对应的 pack , 类似 keil5 ，新安装的 Keil5 不支持任何单片机，如果要使用新安装的keil 支持某类型号单片机，需要安装对应的软件包。

pyocd 提供了一个内置的子命令来对pack进行管理，安装、查找、删除等，来看下 pyocd pack 命令的帮助信息：

送上图来看，有5个功能选项：

-c：清楚保存在电脑上的pack信息
-u：更新pack索引
-s：显示已安装的pack
-f：查找某个IC对应的pack
-i：安装指定的pack

pyocd 使用的 pack 有个默认的存放路劲，我电脑上为：

C:\Users\Administrator\AppData\Local\cmsis-pack-manager\cmsis-pack-manager

pyocd pack 命令就是对该目录的文件进行管理。

（3.1）pyocd pack -U

使用方法为：

pyocd pack -u
或者
pyocd pack --update

第一次使用该命令的时候，会在pyocd存放pack文件的默认路劲下下载不同厂商不同系列 MCU 的 pack 的描述文件（pdsc文件）和 index.json、aliases.json 文件。执行过一次之后，会从网络上更新相应的文件。下图是一个执行pyocd pack -u的结果，有出现错误。

下图是执行了pyocd pack -u 后，pack 所在文件夹多了很多文件：

（3.2）pyocd pack -f

使用方法为：

pyocd pack -f partnumber

该命令会显示出对应型号 MCU 的 pack 的信息，如下图，显示了 stm32f042 所对应 pack 的信息

（3.3）pyocd pack -i

使用方法为：

pyocd pack -i partnumber

该命令安装指定型号MCU的pack，如下图：

不过，由于网络的问题，一般很难下载完成，跟keil下载pack一样，非常慢，经常下载失败，可以手动下载所需的pack，然后放到对应目录。

（3.4）pyocd pack -s

使用方法为：

pyocd pack -s

列出所安装的pack，如果还未安装任何pack，该命令执行结果为：

安装有pack后，执行结果为：

（4）pyocd flash 命令

测试硬件是 Daplink+STM32F042F4 最小系统，Daplink 我自己用 STM32F042F4做的，如下：

STM32F042F42 的测试程序是用 Cube MX 创建工程，由于板子上没有其他外设，但是 Daplink 有 USB 转 TTL，实现了个 STM32F042 Uart 输出的测试程序，主要程序如下：

  /* Infinite loop */
  /* USER CODE BEGIN WHILE */
  while (1)
  {
    /* USER CODE END WHILE */

    /* USER CODE BEGIN 3 */
		printf("STM32F042:%d\r\n",i);
		i++;
		HAL_Delay(1000);
  }
  /* USER CODE END 3 */

正常跑起来是这样：

第一次测试，首先执行 pyocd list查看是否成功识别到设备，确认能够找到 daplink 后。

pyocd flash -h 输出的帮助信息看不出来 pyocd flash 应该怎么用:

非常多选项，这里只关注烧录的功能，通过查阅 pyocd 的文档，了解到可以使用如下命令来给MCU烧录程序：

pyocd flash -t mcu_partnumber  firmware

我的 MCU 是 stm32f042f4，测试固件是 pyocd_test.hex，尝试使用命令：

pyocd flash --t stm32f042f4 ./pyocd_test.hex来烧录程序，结果如下：

结果显示不支持 stm32f042f4，使用 list 查看下目前环境下支不支持 042：

下载 stm32f042 的 pack：

可以找到 STM32F042 了，重新试下烧录：

从这结果看是烧录成功了，看了下板子，也成功跑起来了：

（5）pyocd erase 命令

pyocd 帮助信息中对该指令的描述是：

erase Erase entire device flash or specified sectors.

也就是说可以使用该指令对设备进行全擦或者指定扇区，pyocd earse帮助信息如下：

我尝试使用了如下命令：

(5.1) 整片擦除：-c/--chip

看了下板子已经没有输出了，

(5.2) 擦除扇区：-s/--sector

该命令需要加一个扇区地址，如果没加的话，会不成功，如下是没加地址的：

对于目标芯片，如果添加的地址不对，也会操作不成功：

添加正确的地址结果如下：

（5）使用 pyocd 操作 STM32F051

试下安装 STM32051 的 pack，看下能不能通过安装 STM32f051 的 pack 来使 pyocd 支持 STM32f051，首先查看已安装的 pack，查询结果如下，

PS D:\project\USB\Daplink\my_dap\doc> pyocd pack -s
  Vendor   Pack   Version
---------------------------

从上述结果来看，尚未安装任何 pack，然后尝试下载 stm32f051 pack：

PS D:\project\USB\Daplink\my_dap\doc> pyocd pack -i STM32F051C8Tx
Downloading packs (press Control-C to cancel):
    Keil::STM32F0xx_DFP::2.0.0

等了很久，执行完上述命令后，尝试烧录，结果如下：

PS D:\project> pyocd flash -t stm32f051r8 .\stm32051_test.hex
0001009:CRITICAL:__main__:Failed to open CMSIS-Pack ‘C:\Users\dell\AppData\Local\cmsis-pack-manager\cmsis-pack-manager\Keil\STM32F0xx_DFP\2.0.0.pack‘: File is not a zip file
Traceback (most recent call last):
  File "C:\Users\dell\AppData\Local\Programs\Python\Python37-32\lib\site-packages\pyocd-0.23.1.dev12-py3.7.egg\pyocd\target\pack\cmsis_pack.py", line 88, in __init__
    self._pack_file = zipfile.ZipFile(file_or_path, ‘r‘)
  File "C:\Users\dell\AppData\Local\Programs\Python\Python37-32\lib\zipfile.py", line 1200, in __init__
    self._RealGetContents()
  File "C:\Users\dell\AppData\Local\Programs\Python\Python37-32\lib\zipfile.py", line 1267, in _RealGetContents
    raise BadZipFile("File is not a zip file")
zipfile.BadZipFile: File is not a zip file

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "C:\Users\dell\AppData\Local\Programs\Python\Python37-32\lib\site-packages\pyocd-0.23.1.dev12-py3.7.egg\pyocd\__main__.py", line 343, in run
    self._COMMANDS[self._args.cmd](self)
  File "C:\Users\dell\AppData\Local\Programs\Python\Python37-32\lib\site-packages\pyocd-0.23.1.dev12-py3.7.egg\pyocd\__main__.py", line 470, in do_flash
    options=convert_session_options(self._args.options))
  File "C:\Users\dell\AppData\Local\Programs\Python\Python37-32\lib\site-packages\pyocd-0.23.1.dev12-py3.7.egg\pyocd\core\helpers.py", line 241, in session_with_chosen_probe
    return Session(probe, auto_open=auto_open, options=options, **kwargs)
  File "C:\Users\dell\AppData\Local\Programs\Python\Python37-32\lib\site-packages\pyocd-0.23.1.dev12-py3.7.egg\pyocd\core\session.py", line 175, in __init__
    or Board(self, self.options.get(‘target_override‘))
  File "C:\Users\dell\AppData\Local\Programs\Python\Python37-32\lib\site-packages\pyocd-0.23.1.dev12-py3.7.egg\pyocd\board\board.py", line 48, in __init__
    pack_target.ManagedPacks.populate_target(target)
  File "C:\Users\dell\AppData\Local\Programs\Python\Python37-32\lib\site-packages\pyocd-0.23.1.dev12-py3.7.egg\pyocd\target\pack\pack_target.py", line 84, in populate_target
    targets = ManagedPacks.get_installed_targets()
  File "C:\Users\dell\AppData\Local\Programs\Python\Python37-32\lib\site-packages\pyocd-0.23.1.dev12-py3.7.egg\pyocd\target\pack\pack_target.py", line 71, in get_installed_targets
    pack = CmsisPack(pack_path)
  File "C:\Users\dell\AppData\Local\Programs\Python\Python37-32\lib\site-packages\pyocd-0.23.1.dev12-py3.7.egg\pyocd\target\pack\cmsis_pack.py", line 91, in __init__
    file_or_path, err)), err)
  File "<string>", line 3, in raise_from
pyocd.target.pack.cmsis_pack.MalformedCmsisPackError: Failed to open CMSIS-Pack ‘C:\Users\dell\AppData\Local\cmsis-pack-manager\cmsis-pack-manager\Keil\STM32F0xx_DFP\2.0.0.pack‘: File is not a zip file

还是不能成功下载，从上述信息来看应该是解析stm32f0的pack失败，到目录C:\Users\dell\AppData\Local\cmsis-pack-manager\cmsis-pack-manager\Keil\STM32F0xx_DFP\看了下,有文件2.0.0.pack，20多兆。

手动从https://www.keil.com/dd2/Pack/#/eula-container下载了Keil.STM32F0xx_DFP.2.0.0.pack，有60多兆，对比下，问题是使用pyocd pack -i安装的stm32f051的pack有问题。把自己下载的Keil.STM32F0xx_DFP.2.0.0.pack重命名为2.0.0.pack,放到目录C:\Users\dell\AppData\Local\cmsis-pack-manager\cmsis-pack-manager\Keil\STM32F0xx_DFP\，然后重新烧录：

PS D:\project\USB\Daplink\my_dap\doc> pyocd flash -t stm32f051r8 .\stm32051_test.hex
[====================] 100%
0001733:INFO:loader:Erased 3072 bytes (3 sectors), programmed 3072 bytes (3 pages), skipped 0 bytes (0 pages) at 7.12 kB/s

板子运行起来了，下载成功。

还做了实验，还是使用STM32F051板子，跑一个很简单的程序，控制一个LED闪烁，试了下指定芯片跟不指定芯片有什么区别，效果怎样，如下：

从上面结果来看，如果没指定芯片，虽然说从结果来看，是执行了擦除操作，可是板子还在运行，LED还在闪烁，指定了芯片后，执行完任务后，LED不再闪烁了。

（三）使用 pyocd python api

这里尝试下使用pyocd python api来操作单片机。

环境是：

PC： windows10
python

硬件

调试器：一块跑Daplink V1的STM32F042最小系统

目标板：一个STM32F042最小系统

如下：

首先导入库：

from pyocd.probe.aggregator import DebugProbeAggregator
from pyocd.board.board import Board
from pyocd.core.helpers import ConnectHelper
from pyocd.core.target import Target
import logging
from pyocd.core.memory_map import MemoryType
from pyocd.core.coresight_target import CoreSightTarget
from pyocd.coresight.cortex_m import CortexM

按照 pyocd 的文档，首先是创建一个 Session ，如下：

session = ConnectHelper.session_with_chosen_probe(None, None)
session.open()

然后可以获取到当前 session 中的 board，如下：

board = session.board
print("Board MSG:")
print("Board‘s name:%s" % board.name)
print("Board‘s description:%s" % board.description)
print("Board‘s target_type:%s" % board.target_type)
print("Board‘s unique_id:%s" % board.unique_id)
print("Board‘s test_binary:%s" % board.test_binary)
print("Unique ID: %s" % board.unique_id)

上述程序执行结果如下：

从上述信息来看，是可以成功是别到我的调试器，但是没有正确显示目标芯片，除了我要输出的信息外，还有一段内容，说的是当前目标类芯片类型型是 cortex_m，选这类型可以进行调试但不能烧录，可以通过 --target 或者 target_override 选项来指定目标芯片。

修改代码如下，通过 target_override 指定了我的目标芯片：

session = ConnectHelper.session_with_chosen_probe(target_override="stm32f042f4")
session.open()
board = session.board
print("Board MSG:")
print("Board‘s name:%s" % board.name)
print("Board‘s description:%s" % board.description)
print("Board‘s target_type:%s" % board.target_type)
print("Board‘s unique_id:%s" % board.unique_id)
print("Board‘s test_binary:%s" % board.test_binary)
print("Unique ID: %s" % board.unique_id)

运行结果为：

这回显示了我的目标芯片。

成功了获取到了调试器的信息，现在来试下获取当前环境下目标芯片的信息，代码如下：

target = board.target
print("Part number:%s" % target.part_number)
memory_map = target.get_memory_map()
ram_region = memory_map.get_default_region_of_type(MemoryType.RAM)
rom_region = memory_map.get_boot_memory()
print("menory map:")
print(memory_map)
print("ram_region:")
print(ram_region)
print("rom_region:")
print(rom_region)

运行结果为：

从上述结果来看，是可以成功获取到目标芯片的 part number、Flash 跟 RAM 信息。

通过查看 pyocd 的源码，target 实例有个 irq_table 属性，看下这个属性会输出什么信息：

print("Irq:")
print(target.irq_table)

输出如下：

试下读取单片机一些寄存器：

print("pc reg: 0x%X" % target.read_core_register(‘pc‘))
print("CPUID:0x%x" % target.read32(CortexM.CPUID))
print("device id:0x%x" % target.read32(0x40015800))
print("flash size:%x KB" % target.read32(0x1FFFF7CC))

运行结果如下：

第一个读取 PC 寄存器的值

这个读出来的值究竟对不对，没去查看，不过从这个值的大小来看（在0x8000000到?8004000之前?），应该是对的。
第二个，读取CPUID的值

RM0091 Reference manual (stm32f0x2 参考手册) 中关于CPU ID 部分如下：

stm32f042是arm M0 ,根据上述内容，该芯片的CPU ID为：

? ARM V0 ARMv6-M M0 Revision

? 0x41 0 c c20 0

也就是0x140cc200，跟读取到的结果对的上，

第三个读取设备ID

RM0091 Reference manual (stm32f0x2 参考手册) 中也有设备 ID 的内容，如下：

从文档来看，读取出来的值也是对的，

第四个，读取Flash大小

目标 IC 是 STM32F042F4，Flash 实际大小是 16K，读出来的也是 16K

完整代码为：

from pyocd.probe.aggregator import DebugProbeAggregator
from pyocd.board.board import Board
from pyocd.core.helpers import ConnectHelper
from pyocd.core.target import Target
import logging
from pyocd.core.memory_map import MemoryType
from pyocd.core.coresight_target import CoreSightTarget
from pyocd.coresight.cortex_m import CortexM
session = ConnectHelper.session_with_chosen_probe(target_override="stm32f042f4")
session.open()
board = session.board
print("Board MSG:")
print("Board‘s name:%s" % board.name)
print("Board‘s description:%s" % board.description)
print("Board‘s target_type:%s" % board.target_type)
print("Board‘s unique_id:%s" % board.unique_id)
print("Board‘s test_binary:%s" % board.test_binary)
print("Unique ID: %s" % board.unique_id)
target = board.target
print("Part number:%s" % target.part_number)
memory_map = target.get_memory_map()
ram_region = memory_map.get_default_region_of_type(MemoryType.RAM)
rom_region = memory_map.get_boot_memory()
print("menory map:")
print(memory_map)
print("ram_region:")
print(ram_region)
print("rom_region:")
print(rom_region)

print("Irq:")
print(target.irq_table)

print("pc reg: 0x%X" % target.read_core_register(‘pc‘))
print("CPUID:0x%x" % target.read32(CortexM.CPUID))
print("device id:0x%x" % target.read32(0x40015800))
print("flash size:%d KB" % (target.read32(0x1FFFF7CC) & 0x0000ffff))

对于这段代码，我试着在创建 session 的时候，把指定目标芯片的型号跟实际使用的芯片型号设置成不一样，

第一次看到跑的结果的时候，有点懵逼，不过想了下，合理。

参考：

api_examples：pyOCD\docs\api_examples.md，即pyocd源码目录下docs/api_examples.md

architecture：pyOCD\pyOCD-0.25.0\docs\architecture.md

（四）可以用 pyocd 用来做什么

还是只关注 pyocd 烧录的功能，在这个点上面，可以怎么使用 pyocd 呢？

对于 pyocd 命令，当然是直接用来烧录了，pyocd 是跨平台的，不管使用的是 ST-Link、J-link、Daplink，由于一般情况下使用的都是固定的几种 MCU，把 pyocd 命令做成脚本文件，如 windows 的 bat、Linux Shell 脚本，很方面使用。

对于使用 pyocd python api，可以使用 python 做个烧录的上位机，对于使用 ST-Link 烧录 ST MCU、J-link 有个j-flash 来说好像是多次一举，不过对于一些使用场景，如对于不是做单片机开发的，如硬件工程师、做上位机开发的纯软件工程师、或者其他不懂这方面的人来说，使用 j-flash 设置选项比较多可能一时用不起来，如果使用 pyocd python api 做个上位机一键烧录，就可以解决这问题。

还有对于使用 daplink 的人来说，把 daplink 用于调试是非常方便的，不用担心什么时候被识别为盗版的导致用不了而耽误工作，由于 daplink 没有对应的上位机，要使用 daplink 烧录的话就不方便了，pyocd python api 做个上位机就可以解决这问题，如下是我用 pyocd + PyQT 做的一个上位机给一个软件工程师用，只能烧录 STM32F103C8，直接把软件给过去就可以用起来，不用教这软件的使用方法，这还可以做的跟简单，一键烧录。

还有一些场景，如，如果机器给到了客户，要更新固件的话，直接把固件给客户，怕客户拿到了固件，另外找个便宜点的供应商做个硬件，不再跟你买了，岂不亏大了，如果自己做个烧录上位机，对给过去的固件做些加密什么的，客户就无法用其他烧录软件烧录这固件了，还可以加个数量限制，就不怕客户直接用这个来生成烧录了，或者直接把固件放到一个服务器里，只给个烧录上位机就可以烧录，原理上这也是可以实现的。

玩转 pyocd

码农公寓

（一） pyocd

（1） 什么是pyocd

（2） 安装

（3） Libusb

（二）如何使用pyocd命令行工具

（1）pyocd list 命令

(1.1) pyocd list -t/--target

(1.2) pyocd list -b/--board

（2）pyocd json 命令

（2.1）pyocd list -p

（2.2） pyocd json -t

（3）pyocd pack 命令

（3.1）pyocd pack -U

（3.2）pyocd pack -f

（3.3）pyocd pack -i

（3.4）pyocd pack -s

（4）pyocd flash 命令

（5）pyocd erase 命令

(5.1) 整片擦除：-c/--chip

(5.2) 擦除扇区：-s/--sector

（5）使用 pyocd 操作 STM32F051

（三）使用 pyocd python api

（四）可以用 pyocd 用来做什么

相关文章

（1）什么是pyocd

（2）安装