PYNQ开发板启动实验：从镜像烧写到Jupyter连接全流程指南

1. 项目概述：从Zynq到PYNQ，让FPGA开发更“Pythonic”

如果你接触过Xilinx的Zynq系列SoC，肯定对那种既要写C代码驱动PS（处理系统），又要写HDL代码设计PL（可编程逻辑）的“分裂感”记忆犹新。传统的开发流程像是一场在硬件和软件之间不断切换的“接力赛”，调试起来更是让人头大。几年前，当我第一次听说PYNQ这个项目时，感觉就像在硬件的世界里发现了一片绿洲。它本质上是一个基于Ubuntu Linux的开源框架，核心目标就一个：让开发者能用Python来调用、控制和交互Zynq/UltraScale+ MPSoC上的可编程硬件（PL）。

简单来说，PYNQ把FPGA硬件模块（我们称之为Overlay，覆盖层）包装成了Python的类和方法。你想让PL部分的硬件加速器跑起来？不用再写繁琐的驱动和底层C代码了，直接import pynq，然后像调用一个Python库函数一样去操作硬件。这极大地降低了软硬件协同开发的门槛，尤其适合算法加速、图像处理、通信原型验证以及高校教学等场景。这次我们要做的“Pynq开发板启动实验”，就是踏入PYNQ世界的第一步。它不仅仅是给板子通个电，更是要搭建起一个完整的、可交互的Python硬件开发环境。无论你是嵌入式软件工程师想尝试硬件加速，还是算法工程师希望验证FPGA加速的可行性，亦或是学生初次接触异构计算，这个实验都是必经的“上电仪式”。整个过程会涉及镜像烧写、网络配置、Jupyter Notebook连接等关键环节，我会把每一步的原理和踩过的坑都详细道来。

2. 核心设计思路：为什么是Jupyter + Overlay？

在深入实操之前，有必要先拆解一下PYNQ框架的核心设计哲学。它没有选择传统的命令行交互或者独立的GUI应用作为主界面，而是构建在Jupyter Notebook之上。这个选择非常精妙。Jupyter是一个基于Web的交互式计算环境，天生支持Python代码分段执行、实时可视化（如图表、图片）和富文本说明（Markdown）。这完美契合了硬件探索式开发的需求：你可以写一段代码配置硬件，立刻看到结果（比如一幅处理后的图像），然后在下一个Cell里记录实验现象和分析。整个开发过程就像在写一本交互式的实验报告，可复现性极强。

框架的另一个核心是Overlay（覆盖层）的概念。你可以把它理解为一个硬件功能的“容器”或“驱动包”。一个Overlay文件（通常是.bit或.bit.bin文件）包含了PL部分的完整硬件设计（逻辑电路），以及与之配套的Python API（.py文件）。这个API封装了所有访问和控制该硬件模块的细节，比如寄存器读写、DMA数据传输、中断处理等。当你通过Overlay(“xxx.bit”)加载一个Overlay时，PYNQ框架会自动完成硬件比特流的配置，并将对应的Python类实例化。之后，你操作的就是这个Python对象，完全不用关心底层硬件是如何被配置的。这种抽象层次，是PYNQ生产力提升的关键。

那么，要让这套体系跑起来，我们的开发板（以常见的Pynq-Z2为例）上需要运行一个什么样的系统呢？答案是一个定制的Linux操作系统镜像。这个镜像基于Ubuntu，但预装了所有PYNQ所需的软件栈：Python 3、Jupyter Notebook服务器、Pynq Python库、各种常用Overlay，以及FPGA管理工具。我们的启动实验，目标就是把这个镜像正确地部署到开发板的SD卡上，并让板子成功启动，最终通过电脑的浏览器访问到板子上的Jupyter服务。

3. 实验前的准备工作：工具与镜像选择

工欲善其事，必先利其器。开始烧录之前，我们需要准备好以下几样东西：

1. 硬件：

   • Pynq-Z2开发板（或其他官方支持的板卡，如Ultra96）。
   • Micro SD卡（建议Class 10或以上，容量不小于8GB）。这是板子的“硬盘”。
   • SD卡读卡器。
   • 网线一根，用于连接开发板和路由器（或电脑）。
   • 12V电源适配器（通常板子自带）。

2. 软件：

   • SD卡格式化工具：推荐使用SD Association官方的 SD Memory Card Formatter 。相比操作系统自带的格式化工具，它能更彻底地处理SD卡，避免残留分区导致启动失败。
   • 镜像烧录工具：在Windows下， Etcher 或 Win32 Disk Imager 是简单可靠的选择。在macOS或Linux下，dd命令是经典工具，但使用需格外小心。
   • PYNQ镜像文件：这是核心。务必前往PYNQ官方GitHub的 Release页面 下载。选择与你开发板型号完全对应的最新稳定版镜像（例如pynq_z2_v2.7.img）。下载错误版本的镜像是新手最常见的“翻车”点。

3. 网络环境：

   • 一个可供开发板有线连接的路由器（能分配IP地址）。这是最推荐的方式。
   • 如果没有路由器，也可以使用电脑的网络共享（如Windows的“Internet连接共享”），但配置稍复杂。

注意：镜像版本与板卡型号的严格对应。PYNQ镜像为不同板卡的硬件（如DDR型号、外设接口、时钟频率）做了特定配置。将Z2的镜像烧给Ultra96板，百分之百无法启动，甚至可能有风险。下载时务必双击确认文件名。

4. 实操步骤一：SD卡烧录与细节剖析

拿到SD卡后，第一步不是直接烧录。我建议先用SD Card Formatter进行全卡格式化。这里有个细节：在格式化工具的选项里，选择“OVERWRITE FORMAT”（覆盖格式化），而不是“QUICK FORMAT”（快速格式化）。快速格式化只是清除了文件索引，而覆盖格式化会真正擦写整个卡，能清除一些顽固的旧分区表信息，这对于确保启动loader能正确识别SD卡结构至关重要。很多“板子卡在启动阶段”的玄学问题，都是因为SD卡里有历史遗留的分区导致的。

格式化完成后，打开Etcher。它的界面非常直观，就三步：“Select image”选择你下载的.img文件，“Select drive”选择你的SD卡盘符，“Flash!”开始烧录。Etcher会自动校验烧录内容，这个过程需要几分钟，取决于SD卡速度和镜像大小。

如果你习惯使用命令行（比如在Linux下），那么dd命令是标准操作。但这也是一个“危险”的命令，一旦写错目标磁盘（of=参数），可能会清空你的系统硬盘。务必反复确认磁盘标识符。

# 示例：在Linux下，首先用 `lsblk` 命令确认SD卡设备名（例如是 /dev/sdb） # 确保该设备没有其他挂载分区（如有，用 `umount /dev/sdb1` 卸载） sudo dd if=./pynq_z2_v2.7.img of=/dev/sdb bs=1M status=progress sudo sync

实操心得：dd命令的“坑”。of=后面跟的应该是整个磁盘设备（如/dev/sdb），而不是某个分区（如/dev/sdb1）。bs=1M设置块大小，可以提升大文件拷贝速度。status=progress是较新版本dd才支持的进度显示功能。最后执行sync是为了确保所有缓存数据都真正写入SD卡，再安全拔出。

烧录完成后，你会发现Windows可能弹窗提示需要格式化SD卡。千万不要点格式化！这是因为PYNQ镜像包含多个分区（如FAT32格式的boot分区和ext4格式的rootfs分区），Windows只能识别第一个FAT32分区，并且无法识别ext4分区，所以它误以为卡坏了。直接关掉提示窗口，安全弹出SD卡即可。

5. 实操步骤二：硬件连接与上电启动

将烧录好的SD卡插入Pynq-Z2板的卡槽（注意方向）。接着，用网线连接开发板的以太网口和你的路由器LAN口。最后，连接12V电源适配器并上电。

此时，你应该观察板上的指示灯：

• 电源指示灯（PWR）：常亮，表示供电正常。
• Done灯（LD13）：这是一个非常关键的指示灯。它代表FPGA的配置状态。上电后，它会先闪烁，表示PL正在从SD卡的比特流文件中加载配置。加载成功后，此灯会常亮。如果Done灯常亮，说明最低层的硬件配置已经成功，系统启动有了良好基础。
• 用户灯（LD0-LD3）：在标准镜像中，系统启动过程中这些灯可能会有流水灯效果，启动完成后可能常亮或呈现某种模式，具体取决于镜像设计。

上电后，你需要给开发板一点时间来完成首次启动。首次启动会进行一些文件系统扩展和初始化设置，可能需要2-5分钟。期间，开发板的串口（如果你连接了）会输出大量内核启动信息。对于没有串口调试习惯的用户，最直观的判断方式是看网口的指示灯。当系统启动完成，网络服务（如DHCP客户端）开始工作时，网口的绿色链路灯会常亮，黄色数据灯会闪烁。

6. 实操步骤三：网络发现与Jupyter连接

PYNQ板启动后，会通过DHCP自动从路由器获取一个IP地址。我们的电脑需要和它在同一个局域网内，才能访问其上的Jupyter服务。

方法一：通过路由器管理界面查找（推荐）这是最省事的方法。登录你家路由器的管理后台（通常是192.168.1.1或192.168.0.1），在“连接设备”或“DHCP客户端列表”里，寻找一个主机名包含“pynq”或“xilinx”的设备，记下其IP地址。例如，你可能会看到pynq-xxxx（后面是MAC地址后几位）这样的设备名。

方法二：使用网络扫描工具如果无法访问路由器，可以使用arp -a命令（Windows/Linux/macOS通用）查看本地ARP缓存表，在一堆IP中寻找可疑的地址。或者使用专业的IP扫描工具，如Advanced IP Scanner（Windows）或nmap（命令行），扫描你所在网段（如192.168.1.0/24）。

方法三：使用mDNS域名访问（最优雅）PYNQ镜像通常支持mDNS（Bonjour/Avahi）服务。这意味着你可以直接使用主机名.local来访问板子。在浏览器或终端中，直接尝试访问http://pynq.local:9090。如果你的电脑支持mDNS（macOS和现代Linux默认支持，Windows10/11需要安装“Bonjour打印服务”或使用第三方软件），这将是最直接的方式。

假设我们找到了板子的IP是192.168.1.100。那么，在你的电脑浏览器中，输入：http://192.168.1.100:9090。默认的Jupyter端口是9090。

首次访问，你会看到Jupyter的登录页面。PYNQ的默认用户名和密码都是xilinx。输入后，你就进入了PYNQ的Jupyter Notebook主页！在这里，你会看到一些预置的示例Notebook（.ipynb文件）和目录。恭喜，至此，“启动实验”的核心目标已经达成。

7. 核心环节解析：首次登录后的关键配置

成功登录Jupyter Lab（新版本镜像默认是Jupyter Lab界面，比经典Notebook更强大）后，先别急着跑例子。有几个重要的配置和检查项，能让你后续的开发更顺畅。

7.1 修改默认密码出于安全考虑，第一件事就是修改默认密码。在Jupyter Lab的左侧文件浏览器中，右键点击空白处，选择“New” -> “Terminal”，打开一个终端。在终端中，输入passwd命令，然后按照提示，先输入当前密码xilinx，再设置两遍你的新密码。

xilinx@pynq:~$ passwd Changing password for xilinx. (current) UNIX password: xilinx （输入时不显示） Enter new UNIX password: （输入你的新密码） Retype new UNIX password: （再次输入）

7.2 熟悉Overlay目录结构在Jupyter的文件浏览器中，进入/home/xilinx/jupyter_notebooks目录。这里存放着官方示例。更重要的是，进入/home/xilinx/pynq/overlays目录，这里存放着预编译好的各种Overlay比特流文件（.bit）及其Python驱动。例如，base目录下就是最基础的Overlay，包含了AXI GPIO、DMA等常用IP。了解这些资源的存放位置，是你后续加载自定义Overlay的基础。

7.3 运行一个“Hello World”测试让我们运行一个最简单的测试，验证环境完全正常。新建一个Python 3 Notebook（点击左侧的“+”图标，选择Notebook下的Python 3）。 在第一个Cell中输入以下代码：

from pynq import Overlay import pynq.lib # 加载基础Overlay base = Overlay("/home/xilinx/pynq/overlays/base/base.bit") print("Overlay loaded successfully!") print(f"Overlay name: {base.name}") print(f"Available IPs: {list(base.ip_dict.keys())}")

运行这个Cell（Shift+Enter）。如果一切正常，你会看到成功加载的信息，并打印出该Overlay中包含的IP核列表。这个操作触发了FPGA PL部分的动态重配置，是PYNQ最核心的操作之一。

8. 常见问题与排查技巧实录

即使按照步骤操作，也可能会遇到问题。下面是我在实践中总结的几个典型问题及排查思路。

8.1 问题：浏览器无法连接192.168.1.100:9090

• 排查思路1：确认IP地址。板子真的获取到这个IP了吗？再次登录路由器后台确认，或者尝试pynq.local:9090。如果路由器列表里根本没有板子，说明板子可能没启动成功或网络未连接。
• 排查思路2：检查物理连接。网线是否插紧？路由器对应LAN口的指示灯是否亮起？尝试更换网线或路由器端口。
• 排查思路3：检查防火墙。你的电脑防火墙是否阻止了对9090端口的访问？可以暂时关闭防火墙试试。
• 排查思路4：使用串口终端诊断（终极手段）。如果以上都不行，就需要串口了。将USB转UART调试器连接到Pynq-Z2的J14接口（UART0），波特率设置为115200。上电后，在串口终端（如Putty、MobaXterm、screen）里观察启动日志。如果卡在某个阶段（如“Waiting for root device /dev/mmcblk0p2”），可能是SD卡烧录问题。如果根本无输出，可能是板子未正常上电或镜像完全不对。

8.2 问题：Done灯不亮，或闪烁后熄灭

• 可能原因1：镜像与板卡不匹配。这是最可能的原因。请百分之百确认你下载的镜像文件名包含你的板卡型号（如pynq_z2）。
• 可能原因2：SD卡烧录不完整或损坏。重新用Etcher烧录一遍，并确保勾选“校验”选项。尝试换一张质量更好的SD卡（Class 10, A1）。
• 可能原因3：电源问题。确保使用原装或足额的12V/3A电源。电源不足可能导致FPGA配置过程中断电。

8.3 问题：可以ping通IP，但无法访问9090端口

• 可能原因：Jupyter服务未启动。通过串口登录（用户名xilinx，密码xilinx），手动启动Jupyter服务。

  # 在板子的串口终端中执行 sudo systemctl restart jupyter sudo systemctl status jupyter # 查看服务状态

  检查是否有错误信息。也可以查看日志：sudo journalctl -u jupyter -f。

8.4 问题：导入pynq库时报错“No module named ‘pynq’”

• 可能原因：在错误的Python环境中操作。PYNQ的库安装在板子系统的特定Python环境中。请确保你是在Jupyter Notebook的Cell中，或者通过SSH登录到板子后，直接运行python3命令。不要在你自己电脑的Python环境里安装pynq库，那是没用的（除非你做远程开发，那是另一套配置）。

8.5 问题：加载Overlay时报错“Bitstream not found”或“Bitstream download failed”

• 排查思路1：文件路径错误。检查.bit文件的路径是否正确。在Jupyter中，可以使用!ls -la /home/xilinx/pynq/overlays/base这样的命令（前面加!表示执行shell命令）来查看文件。
• 排查思路2：Overlay文件损坏。重新从可靠来源获取Overlay文件。
• 排查思路3：硬件兼容性问题。某些自定义Overlay可能依赖特定的PL时钟或资源，与当前镜像的预设不匹配。确保Overlay是为当前版本的PYNQ和你的板卡设计的。

为了方便查阅，我将常见问题、现象和解决思路汇总成下表：

9. 进阶技巧：优化开发体验

基础环境搭好后，还有几个小技巧能极大提升你的开发效率。

9.1 启用SSH免密登录频繁通过Jupyter上传下载文件或使用终端，不如直接SSH方便。首先在板子上启用密码登录（默认已启用）。然后，在你自己的电脑上生成SSH密钥对（如果还没有的话）：

# 在你的电脑上执行 ssh-keygen -t rsa -b 4096 # 一直按回车使用默认值

将公钥（~/.ssh/id_rsa.pub文件内容）追加到板子的~/.ssh/authorized_keys文件中。你可以通过Jupyter Notebook新建一个文本文件来完成粘贴，或者用一条命令（在板子终端执行）：

# 在板子终端，假设你电脑IP是192.168.1.50 ssh-keyscan 192.168.1.50 >> ~/.ssh/known_hosts # 可选，避免首次连接提示 # 然后手动将你电脑id_rsa.pub的内容，添加到板子的 ~/.ssh/authorized_keys 文件末尾。

之后，你就可以在电脑终端用ssh xilinx@192.168.1.100直接登录，无需密码。

9.2 使用VS Code进行远程开发这是更专业的做法。在电脑上安装VS Code和“Remote - SSH”扩展。配置SSH连接到板子（xilinx@192.168.1.100）。之后，你就可以在VS Code里直接浏览、编辑板子上的文件，使用集成终端，享受代码提示、语法高亮等所有IDE功能，体验远优于纯网页版的Jupyter Notebook。

9.3 管理Python环境与包板子上的系统Python环境是共用的。为了避免污染系统环境，建议为你的项目创建独立的Python虚拟环境（venv）。

# 在板子终端或Jupyter的Terminal中 python3 -m venv /home/xilinx/my_project_env source /home/xilinx/my_project_env/bin/activate pip install some_package_you_need

在Jupyter Notebook中，你可以通过安装ipykernel来让这个虚拟环境成为Notebook的一个可选的Kernel。

pip install ipykernel python -m ipykernel install --user --name=my_project_env --display-name="Python (my_project)"

重启Jupyter服务后，新建Notebook时就可以选择“Python (my_project)”这个内核了。

启动实验本身并不复杂，但它构建了通往PYNQ所有高级特性的桥梁。当你熟悉了这个环境，下一步就可以开始探索如何使用预置的Overlay（如图像处理、音频编解码），进而学习如何用Vivado设计自己的硬件模块，并打包成Overlay供Python调用。那时，你才能真正体会到软硬件协同设计的魅力所在——用Python的敏捷性，驾驭FPGA的并行威力。