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. 实验前的准备工作工具与镜像选择工欲善其事必先利其器。开始烧录之前我们需要准备好以下几样东西硬件Pynq-Z2开发板或其他官方支持的板卡如Ultra96。Micro SD卡建议Class 10或以上容量不小于8GB。这是板子的“硬盘”。SD卡读卡器。网线一根用于连接开发板和路由器或电脑。12V电源适配器通常板子自带。软件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。下载错误版本的镜像是新手最常见的“翻车”点。网络环境一个可供开发板有线连接的路由器能分配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 bs1M statusprogress sudo sync实操心得dd命令的“坑”。of后面跟的应该是整个磁盘设备如/dev/sdb而不是某个分区如/dev/sdb1。bs1M设置块大小可以提升大文件拷贝速度。statusprogress是较新版本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 ScannerWindows或nmap命令行扫描你所在网段如192.168.1.0/24。方法三使用mDNS域名访问最优雅PYNQ镜像通常支持mDNSBonjour/Avahi服务。这意味着你可以直接使用主机名.local来访问板子。在浏览器或终端中直接尝试访问http://pynq.local:9090。如果你的电脑支持mDNSmacOS和现代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再设置两遍你的新密码。xilinxpynq:~$ 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(fOverlay name: {base.name}) print(fAvailable IPs: {list(base.ip_dict.keys())})运行这个CellShiftEnter。如果一切正常你会看到成功加载的信息并打印出该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。可能原因2SD卡烧录不完整或损坏。重新用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命令来查看文件。排查思路2Overlay文件损坏。重新从可靠来源获取Overlay文件。排查思路3硬件兼容性问题。某些自定义Overlay可能依赖特定的PL时钟或资源与当前镜像的预设不匹配。确保Overlay是为当前版本的PYNQ和你的板卡设计的。为了方便查阅我将常见问题、现象和解决思路汇总成下表问题现象可能原因排查与解决步骤浏览器无法访问板子IP:90901. IP地址错误2. 网络未连通3. 防火墙阻止4. Jupyter服务未运行1. 路由器确认IP或试pynq.local2. 检查网线、路由器指示灯3. 暂时关闭电脑防火墙4. 串口登录重启jupyter服务Done灯不亮或异常1. 镜像板卡型号不匹配2. SD卡烧录失败3. 电源供电不足1. 核对并下载正确镜像2. 换卡、换工具重新烧录3. 使用原装12V/3A电源可ping通但端口不通Jupyter进程崩溃或未启动串口登录执行sudo systemctl restart jupyterPython导入pynq失败在主机环境而非板子环境运行确保代码在板子的Jupyter Notebook或SSH终端中执行加载Overlay失败1. 文件路径错误2. 比特流文件损坏3. 硬件设计不兼容1. 检查文件路径是否存在2. 重新获取比特流文件3. 确认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 xilinx192.168.1.100直接登录无需密码。9.2 使用VS Code进行远程开发这是更专业的做法。在电脑上安装VS Code和“Remote - SSH”扩展。配置SSH连接到板子xilinx192.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 --namemy_project_env --display-namePython (my_project)重启Jupyter服务后新建Notebook时就可以选择“Python (my_project)”这个内核了。启动实验本身并不复杂但它构建了通往PYNQ所有高级特性的桥梁。当你熟悉了这个环境下一步就可以开始探索如何使用预置的Overlay如图像处理、音频编解码进而学习如何用Vivado设计自己的硬件模块并打包成Overlay供Python调用。那时你才能真正体会到软硬件协同设计的魅力所在——用Python的敏捷性驾驭FPGA的并行威力。
PYNQ开发板启动实验：从镜像烧写到Jupyter连接全流程指南
发布时间：2026/5/22 19:00:43
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. 实验前的准备工作工具与镜像选择工欲善其事必先利其器。开始烧录之前我们需要准备好以下几样东西硬件Pynq-Z2开发板或其他官方支持的板卡如Ultra96。Micro SD卡建议Class 10或以上容量不小于8GB。这是板子的“硬盘”。SD卡读卡器。网线一根用于连接开发板和路由器或电脑。12V电源适配器通常板子自带。软件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。下载错误版本的镜像是新手最常见的“翻车”点。网络环境一个可供开发板有线连接的路由器能分配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 bs1M statusprogress sudo sync实操心得dd命令的“坑”。of后面跟的应该是整个磁盘设备如/dev/sdb而不是某个分区如/dev/sdb1。bs1M设置块大小可以提升大文件拷贝速度。statusprogress是较新版本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 ScannerWindows或nmap命令行扫描你所在网段如192.168.1.0/24。方法三使用mDNS域名访问最优雅PYNQ镜像通常支持mDNSBonjour/Avahi服务。这意味着你可以直接使用主机名.local来访问板子。在浏览器或终端中直接尝试访问http://pynq.local:9090。如果你的电脑支持mDNSmacOS和现代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再设置两遍你的新密码。xilinxpynq:~$ 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(fOverlay name: {base.name}) print(fAvailable IPs: {list(base.ip_dict.keys())})运行这个CellShiftEnter。如果一切正常你会看到成功加载的信息并打印出该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。可能原因2SD卡烧录不完整或损坏。重新用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命令来查看文件。排查思路2Overlay文件损坏。重新从可靠来源获取Overlay文件。排查思路3硬件兼容性问题。某些自定义Overlay可能依赖特定的PL时钟或资源与当前镜像的预设不匹配。确保Overlay是为当前版本的PYNQ和你的板卡设计的。为了方便查阅我将常见问题、现象和解决思路汇总成下表问题现象可能原因排查与解决步骤浏览器无法访问板子IP:90901. IP地址错误2. 网络未连通3. 防火墙阻止4. Jupyter服务未运行1. 路由器确认IP或试pynq.local2. 检查网线、路由器指示灯3. 暂时关闭电脑防火墙4. 串口登录重启jupyter服务Done灯不亮或异常1. 镜像板卡型号不匹配2. SD卡烧录失败3. 电源供电不足1. 核对并下载正确镜像2. 换卡、换工具重新烧录3. 使用原装12V/3A电源可ping通但端口不通Jupyter进程崩溃或未启动串口登录执行sudo systemctl restart jupyterPython导入pynq失败在主机环境而非板子环境运行确保代码在板子的Jupyter Notebook或SSH终端中执行加载Overlay失败1. 文件路径错误2. 比特流文件损坏3. 硬件设计不兼容1. 检查文件路径是否存在2. 重新获取比特流文件3. 确认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 xilinx192.168.1.100直接登录无需密码。9.2 使用VS Code进行远程开发这是更专业的做法。在电脑上安装VS Code和“Remote - SSH”扩展。配置SSH连接到板子xilinx192.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 --namemy_project_env --display-namePython (my_project)重启Jupyter服务后新建Notebook时就可以选择“Python (my_project)”这个内核了。启动实验本身并不复杂但它构建了通往PYNQ所有高级特性的桥梁。当你熟悉了这个环境下一步就可以开始探索如何使用预置的Overlay如图像处理、音频编解码进而学习如何用Vivado设计自己的硬件模块并打包成Overlay供Python调用。那时你才能真正体会到软硬件协同设计的魅力所在——用Python的敏捷性驾驭FPGA的并行威力。
相关文章
百考通“无痕降重”如何做到“以假乱真”？
你是否也这样？ ——论文重复率高，不得不降重； ——但改完交上去，导师皱眉：“这段话不像你写的风格”“语言太‘工整’，缺乏思考过程”； ——甚至被直接问：“是不是用了什么工具&…
2026年Betaflight飞控固件：无人机爱好者的终极免费解决方案 ✈️
2026年Betaflight飞控固件：无人机爱好者的终极免费解决方案 ✈️ 【免费下载链接】betaflight Open Source Flight Controller Firmware 项目地址: https://gitcode.com/gh_mirrors/be/betaflight 想要让你的无人机飞行更稳定、响应更灵敏吗？Beta…
CLIPDraw手绘生成：用文本控制矢量线条的AI绘画新范式
1. 项目概述：当文字真的能“画”出你心里的那幅画“Text-to-Drawing Synthesis With Artistic Control”——这个标题乍看像一句学术论文的副标题，但拆开来看，它直指一个正在快速落地的创作现实：用一句话描述，就能生成…
深度解析UE4SS脚本系统：从Lua脚本到SDK生成器的完整技术指南
深度解析UE4SS脚本系统：从Lua脚本到SDK生成器的完整技术指南 【免费下载链接】RE-UE4SS Injectable LUA scripting system, SDK generator, live property editor and other dumping utilities for UE4/5 games 项目地址: https://gitcode.com/gh_mirrors/re/RE-U…
数字人交互新认知：从文本对话框到 3D 具身面试官
很多人对数字交互的认知，还停留在卡顿的对话上。不少人尝试搭建 AI 面试官项目，依托云端大模型实现基础问答，但高延迟、动作模板化，始终导致体验割裂感。 直到我发现了魔珐星云。 过往接触的传统云端数字人，大多存在…
Gemini模型输出可追溯性缺失=CCPA重大违规？——基于NIST AI RMF 1.1的5层证据留存架构（限内部技术白皮书节选）
更多请点击： https://kaifayun.com 第一章：Gemini模型输出可追溯性缺失的CCPA合规风险本质 加州消费者隐私法案（CCPA）明确要求企业对其收集、使用、共享或披露的消费者个人信息具备完整的溯源能力。当企业将Gemini等生成式AI模型…
5步彻底解决FanControl配置崩溃：从诊断到修复的完整指南
5步彻底解决FanControl配置崩溃：从诊断到修复的完整指南 【免费下载链接】FanControl.Releases This is the release repository for Fan Control, a highly customizable fan controlling software for Windows. 项目地址: https://gitcode.com/GitHub_Trending/…
NotebookLM时间线功能深度解锁：5个被90%用户忽略的高阶技巧，今天必须掌握
更多请点击： https://codechina.net 第一章：NotebookLM时间线功能概览与核心价值 NotebookLM 的时间线（Timeline）功能是其区别于传统笔记工具的关键创新，它以可视化、可交互的方式呈现文档内容的演进脉络与语义关联。…
终极指南：在Linux系统上免费安装运行SOLIDWORKS的完整方法
终极指南：在Linux系统上免费安装运行SOLIDWORKS的完整方法 【免费下载链接】SOLIDWORKS-for-Linux This is a project, where I give you a way to use SOLIDWORKS on Linux! 项目地址: https://gitcode.com/gh_mirrors/so/SOLIDWORKS-for-Linux 想在Linux系…
单日大涨4.52%！华泰柏瑞中韩半导体ETF（513310.SH）上演“高热度”行情，溢价率风险引关注
5月21日，华泰柏瑞中韩半导体ETF（513310.SH）延续强势表现，当日收盘价报5.625元，涨幅达4.52%，盘中交投异常活跃，换手率109.80%，量比为1.32，市场资金交易热情高涨。然而&…
11. 架构：前端工程化与状态管理实战
写在前面： 如果说后端 MVT 引擎是 GIS 系统的“心脏”，那么前端就是它的“大脑”和“面孔”。在现代 WebGIS 开发中，如何优雅地管理复杂的图层状态、如何处理海量瓦片的渲染逻辑，是决定项目成败的关键。 今天，我们将深入 light-mvt-server 的前端核心，看看如何利用 Vite …
淘金币自动化脚本终极指南：10分钟搞定淘宝日常任务，每天为你节省20分钟
淘金币自动化脚本终极指南：10分钟搞定淘宝日常任务，每天为你节省20分钟 【免费下载链接】taojinbi 淘宝淘金币自动执行脚本，包含蚂蚁森林收取能量，芭芭农场全任务，解放你的双手 项目地址: https://gitcode.com/gh_mi…
【实用小程序】超轻量级文件上传下载中心 (File Download Server)
站内源码及jar包下载 一、项目概述 文件下载中心一个基于 Java 内置 HTTP 服务器（com.sun.net.httpserver）构建的轻量级文件管理服务。它零第三方依赖，单 JAR 包即可运行，适合在内网环境或临时场景中快速搭建文件共享站点。 你的团队需要临时共享一批日志文件或交付物，…
py每日spider案例之某website之xin东方选课搜索接口(难度一般 扣取代码即可)
加密位置: 逆向接口参数: 逆向接口: const g = globalThis; g.window = g; g.self = g; g.location = {<
终极轻量级Android文本编辑器Markor：多格式笔记应用完全指南
终极轻量级Android文本编辑器Markor：多格式笔记应用完全指南 【免费下载链接】markor Text editor - Notes & ToDo (for Android) - Markdown, todo.txt, plaintext, math, .. 项目地址: https://gitcode.com/gh_mirrors/ma/markor 在移动设备上寻找一款…
MPC-BE：基于DirectShow架构的专业级开源媒体播放解决方案
MPC-BE：基于DirectShow架构的专业级开源媒体播放解决方案 【免费下载链接】MPC-BE MPC-BE – универсальный проигрыватель аудио и видеофайлов для операционной системы Windows. 项目地址:…
如何快速计算3D模型体积和重量：STL-Volume-Model-Calculator终极指南
如何快速计算3D模型体积和重量：STL-Volume-Model-Calculator终极指南 【免费下载链接】STL-Volume-Model-Calculator STL Volume Model Calculator Python 项目地址: https://gitcode.com/gh_mirrors/st/STL-Volume-Model-Calculator 你是否曾经为3D打印项目…
通过Taotoken CLI工具一键配置团队开发环境与模型密钥
通过Taotoken CLI工具一键配置团队开发环境与模型密钥 1. CLI工具安装与基本使用 Taotoken提供的CLI工具可通过npm全局安装或直接使用npx运行。对于需要频繁使用CLI的团队，推荐全局安装： npm install -g taotoken/taotoken对于临时使用或项目级配置&a…