PYNQ-Z2入门指南：SD卡烧写、Jupyter联网与外设例程

简介《PYNQ-Z2入门指导手册_v2.01》面向刚接触Xilinx Zynq平台、希望用Python快速上手嵌入式开发的初学者与教学人员重点解决不熟悉可编程逻辑设计却想调用FPGA硬件加速能力的问题。内容先介绍PYNQ框架如何把硬件功能封装成可调用的硬件库再说明Jupyter Notebook的交互式编程方式随后给出网络连接、主机名与代理配置、硬件接口连接等准备事项并安排按键控制LED、录音及音频处理、动态实时面部识别三个由浅入深的实验同时附上依元素科技与PYNQ.io社区的支持渠道形成从环境搭建到例程实践的完整路径。压缩包内仅1个PDF文件约1.68MB按简介、软硬件准备、硬件设置、Jupyter连接、例程实践分章编排目录清晰便于按步骤查阅或打印跟做。目前已有2699人学习适合作为课程配套讲义或自学入门材料。1. 板子亮灯不等于启动PYNQ-Z2 入门指导手册里最容易被跳过的一分钟第一次给 PYNQ-Z2 上电的人多半会在最初那一分钟里怀疑板子坏了电源灯亮着四个红灯一动不动网口灯也不闪显示器上什么都没有。这份《PYNQ-Z2 入门指导手册 v2.01》解决的正是这个最难熬的开局——它不碰时序约束和逻辑综合而是把开发板当成一台跑着 Jupyter 的小服务器从烧卡、跳线、拿 IP 一路带到三个能出画面的例程。适合谁写过 Python 但没摸过 FPGA 的软件工程师、要带学生做嵌入式实验的高校老师以及手上已经有一块板子却卡在“连不上”这一步的人。三个例程看着简单按键控制 LED、录音回放、摄像头人脸框但它们恰好把 GPIO、音频编解码、HDMI 帧缓冲三条链路各走了一遍复现完这三条后面接自己的传感器思路就顺了。2. 从空白 micro SD 到能打开网页烧写、跳线、灯序与两种联网接法这一章的全部目标只有一个让浏览器里出现 Jupyter 的登录页。听着简单但实际卡人的地方几乎都不在代码上而在“卡烧没烧进去”“跳线帽插没插对”“网线那头到底该接哪儿”这三件事上。2.1 镜像烧写的两条路径与设备号确认卡的要求是 8GB 起步我一般直接上 16GB Class10便宜卡在启动阶段偶发读写超时会让你误判成镜像坏了。镜像解压出来是一个完整的.img烧写是把整盘按块覆盖不是把文件拷进分区。Windows 下用 win32DiskImager 最省事Image File 选中解压出来的 imgDevice 选 SD 卡对应的盘符通常是 E 或 F点 Write弹出“会覆盖数据”确认后等进度条走完。这里唯一要盯的就是 Device 别选成移动硬盘。Linux 和 macOS 下用 dd但下命令前必须先把设备名认准写错一个字母就是系统盘报废# 先列出块设备按容量和型号认出哪一块是 SD 卡 lsblk -d -o NAME,SIZE,MODEL # 假设确认是 /dev/sdb先卸载它已挂载的分区 sudo umount /dev/sdb* 2/dev/null # 整盘写入of 写的是磁盘本身不是 /dev/sdb1 sudo dd ifpynq_z2_v2.01.img of/dev/sdb bs4M statusprogress convfsync # 确保缓冲区落盘再拔卡 sync参数上bs4M是块大小太小慢、太大在部分读卡器上会报错statusprogress给你实时进度不然 dd 一声不吭最吓人convfsync强制在结束前把数据刷到物理介质省得拔卡拔早了。提示烧完之后 Windows 可能弹窗说“需要格式化”直接点取消。那是它读不懂 Linux 分区格式化会把刚写进去的启动文件全清掉。macOS 上设备名是/dev/rdisk2这种形式r前缀走原始设备速度快不少命令结构一样。烧完插回板子之前别在电脑上做任何分区操作。2.2 跳线、接口与启动灯序判断板子活没活硬件侧要动的开关就三处插错任何一个都会表现成“上电没反应”项目设置说明Boot 跳线拨到 SD决定从 micro SD 启动不是从 JTAG 或 QSPI电源跳线USB由 micro USB 供电拨到 REG 则走外部 12V拨码开关ON整板总电源PROG UARTJ14micro USB 连电脑同时承担供电和串口通信网线路由器或电脑网口决定后面用哪个地址访问micro SD插入板底卡槽提前烧好镜像上电之后的灯序是判断生死的唯一依据手册里写得很清楚大约一分钟后两个蓝色 LED 和四个红色 LED 会同时闪动随后蓝色熄灭、四个红色常亮这时系统启动完毕。换句话说红灯常亮是“活着”只有一颗电源灯亮着就是“没进系统”。我第一次玩的时候盯着四个不亮的红灯等了五分钟最后发现是 Boot 跳线还停在默认位置这种坑后面还会细说。2.3 两种联网接法的地址差异板子的网络接法直接决定你浏览器里敲哪个地址两种方式在手册里是分开写的接路由器或交换机时板子通过 DHCP 自动拿地址主机名默认是pynq浏览器访问http://pynq:9090。这条路的好处是板子和电脑在同一网段板子本身也能出网后面装 Python 包不用折腾。直连电脑时需要先给电脑网卡配一个静态 IP板子的地址是固定的192.168.2.99访问http://192.168.2.99:9090。注意这条路下板子拿不到外网pip install和系统包更新都会失败只能跑镜像里预装的东西。接法电脑侧访问地址能否装新包路由器 / 交换机无需配置http://pynq:9090能网线直连静态 IP与 192.168.2.x 同段http://192.168.2.99:9090不能第一次访问pynq这个名字时电脑要花几秒钟做名称解析页面白屏别急着刷新等十秒再说。如果一直解析不出来直接用 IP 访问或者在串口里ifconfig看一眼实际地址。3. 进 Jupyter 之后默认凭据、Samba 挂载、hostname 与串口兜底浏览器出现登录框说明最难的一段已经过去了。这一章处理的是“进去之后怎么把文件传上去、怎么让多块板子不打架、以及页面彻底打不开时怎么救”。3.1 默认凭据与示例目录的分类用户名和密码都是xilinx两个都小写。登录进去是标准的 Jupyter 文件树Getting_Started目录里放着入门 notebook示例按三类组织common是不依赖特定 overlay 的通用例程base对应 base overlay 的外设演示logictools对应逻辑工具那条线。三个实验分别落在base/board、base/audio、base/video下面。这里有个必须提前知道的机制notebook 是会被就地修改的。你运行一个 cell、改一行代码文件内容立刻就变了没有“未保存”提示这回事。原始版本没了就只能重新下载所以第一次打开示例之前先复制一份改名这是我踩过一次之后固定下来的习惯。3.2 Samba 挂载把板子目录当网络盘用板子上跑着 Samba 服务主目录可以直接映射成网络驱动器传数据集、取录音文件都比在 Jupyter 里上传下载快。Windows 下在资源管理器地址栏敲\\pynq\xilinx直连模式敲\\192.168.2.99\xilinx弹框里用户名密码还是xilinx。Linux 下用文件管理器的smb://pynq/xilinx或smb://192.168.2.99/xilinx命令行则是smbclient。挂上之后/home/xilinx就是你的地盘notebook 里用的绝对路径都能在这边对应上。传大文件时我一般走 Samba改代码还是在 Jupyter 里改两边同时操作同一个文件会冲突别问我怎么知道的。3.3 改 hostname多块板子同网段的必修课默认主机名是pynq如果实验室或办公室里同时插了两块以上的板子这个名字就会打架——谁先应答算谁的你永远不知道自己连的是哪一块。手册里给的做法是在 Jupyter 主页开New Terminal那个终端是 root 权限# 用你希望的名字替换 NEW_HOST_NAME建议带编号 sudo /home/xilinx/scripts/hostname.sh mypynq01 # 改完必须重启才生效然后用新名字重新访问 sudo shutdown -r now脚本会改/etc/hostname和相关配置重启后访问地址就变成http://mypynq01:9090。如果你是用xilinx用户登录的sudo不能省用 root 登录则可以不带。3.4 USB 串口兜底页面打不开时的后悔药Jupyter 进不去、又不知道板子拿了什么 IP 的时候串口是唯一还能说上话的通道。做法是装一个终端工具PuTTY 或 Tera Term 都行先在 Windows 设备管理器里展开“端口”找到板子占用的 COM 口比如 COM5。PuTTY 里选 Serial填 COM 口波特率 115200数据位 8、停止位 1、无校验、无流控。点 Open 之后在窗口里敲一下回车出现xilinxpynq:~$就通了。hostname # 看当前主机名 ifconfig # 看板子实际拿到的 IP串口这条通道不依赖网络配置板子只要能启动就能用。我现在的习惯是首次上电一定先开串口窗口挂着网络那边出什么幺蛾子都能从这里看到内核打印。4. Overlay 调用模型把按键 LED、音频回放、摄像头人脸框拆到函数级三个例程看起来是三个不相干的东西实际上共用同一套调用模型先加载一个 overlay把可编程逻辑的配置灌进去然后通过 Python 对象操作板载外设。理解这一层比背下三段代码有用得多。4.1 overlay 到底是什么BaseOverlay(base.bit)这一行做了两件事把base.bit这个比特流写进可编程逻辑同时把配套的硬件信息读进来在 Python 侧生成一组对象——base.leds、base.buttons、base.audio、base.video都是这么来的。对使用者来说它就像一个硬件库导入之后按对象调方法。这也解释了为什么例程开头永远是这一行。没有加载 overlay那些外设对象根本不存在后面写什么都会报 AttributeError。加载本身要几百毫秒重复加载同一个 overlay 会重新配置逻辑能复用一个实例就别反复 new。注意overlay 文件不只是一个.bit配套的.hwh或.tcl描述文件必须放在同一目录否则加载会因为找不到寄存器映射而失败。4.2 例程一按键控制 LED 的轮询模型这个例程在base/board/board_btn_leds.ipynb。四个按键分工是按键 0 换 RGB 灯颜色按键 1 从右到左流水灯按键 2 从左到右按键 3 退出。核心逻辑可以压成这么几行from time import sleep from pynq.overlays.base import BaseOverlay base BaseOverlay(base.bit) # 加载 PL 配置生成外设对象 for led in base.leds: # 四个用户 LED 先全亮做一次自检 led.on() color 0 while base.buttons[3].read() 0: # 按键 3 是退出条件 if base.buttons[0].read() 1: # 按键 0 换色 color (color 1) % 8 # 颜色值 0-7三位二进制对应 RGB for i in (4, 5): # rgbleds[4] 和 [5] 是板载两颗 RGB 灯 base.rgbleds[i].write(color) sleep(0.3) # 轮询间隔决定按键手感逻辑上就是死循环加轮询read()返回 0 或 1没有中断回调这回事所以sleep的时长直接决定按键响应快慢设成 0.3 秒手感刚好设 0.05 秒 CPU 就空转得厉害。rgbleds的write接收 0 到 7 的整数三个比特分别对应红绿蓝的通断不是亮度值所以只会出八种纯色组合想要渐变得自己在外层做 PWM 占空比切换。4.3 例程二录音、回放与 PCM 频谱音频例程在base/audio/audio_playback.ipynb第一步不是录音是确认链路通from pynq.overlays.base import BaseOverlay base BaseOverlay(base.bit) pAudio base.audio pAudio.select_line_in() # 选线路输入作为音源 pAudio.bypass(seconds5) # 直通 5 秒输入直接送到输出先听有没有声 pAudio.record(5) # 录 5 秒到内存缓冲区 pAudio.save(recording_1.wav) # 落盘成 wav pAudio.load(/home/xilinx/jupyter_notebooks/base/audio/recording_0.wav) pAudio.play()bypass是最容易被跳过但最该先跑的一步它绕过软件路径纯粹验证硬件输入输出是否正常。如果直通都没声音后面录出来的文件也不用看了。拿到 wav 之后手册演示了两种分析频谱和时频谱。读文件那几个参数值得逐个认清import wave, numpy as np from scipy.fftpack import fft wav_path /home/xilinx/jupyter_notebooks/base/audio/recording_0.wav with wave.open(wav_path, r) as wav_file: raw_frames wav_file.readframes(-1) # 读全部帧 num_frames wav_file.getnframes() # 总帧数 num_channels wav_file.getnchannels() # 声道数 sample_rate wav_file.getframerate() # 采样率决定频率轴上限 sample_width wav_file.getsampwidth() # 每样本字节数通常是 2 或 3手册里把sample_width不足 4 字节的样本高位补齐再view(i4)是为了统一按 32 位有符号整数处理否则 24 位样本没法直接喂给 numpy。做 FFT 时取yf fft(frames[:, ch])的前一半配上np.linspace(0, sample_rate/2, len(yf))作为横轴这才是真实的频率刻度plt.specgram的Fs参数必须等于sample_rate填错了频率轴整个是错的图看着挺漂亮但一点意义没有。4.4 例程三HDMI 帧缓冲与 Haar 级联人脸框视频例程要接两样东西USB HOST 口插摄像头HDMI OUT 接显示器。开头先配输出模式from pynq.lib.video import * base BaseOverlay(base.bit) hdmi_out base.video.hdmi_out hdmi_out.configure(VideoMode(640, 480, 24), PIXEL_BGR) # 宽、高、位深 hdmi_out.start()VideoMode(640, 480, 24)是分辨率和色深PIXEL_BGR必须和 OpenCV 的通道顺序一致选错颜色会红蓝互换。主循环里newframe()取一块输出缓冲切片赋值再writeframe()推给 HDMI这个三段式是所有视频输出的固定套路。摄像头那侧用 OpenCV 的标准接口cv2.VideoCapture(0)打开第一个设备set指定分辨率。人脸检测就是把帧转灰度后丢给 Haar 级联gray cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) faces face_cascade.detectMultiScale(gray, 1.3, 5) # 缩放步长、邻域阈值 for (x, y, w, h) in faces: cv2.rectangle(frame, (x, y), (x w, y h), (255, 0, 0), 2)1.3是每次图像金字塔的缩放比例越小检测越全但越慢5是邻域阈值越大越严格、误检越少。这两个参数没有通用最优值得按你的场景调。ARM A9 双核跑 640x480 的 Haar帧率个位数是正常表现别指望流畅。5. 五个高频翻车点从红灯不闪到 writeframe 报错5.1 上电后四颗红灯不闪只有电源灯亮现象是等待超过两分钟蓝色 LED 始终不闪串口也没输出。原因基本落在三处SD 卡没插到底、Boot 跳线不在 SD 位置、镜像根本没写进去。解决顺序是先拔卡重插确认卡槽卡住再看跳线帽位置最后把卡插回电脑重新烧一次镜像烧完别格式化。5.2 浏览器打不开 pynq:9090现象是页面一直转圈或者提示找不到主机。原因是主机名解析失败或电脑和板子不在同一网段。先改成用 IP 访问直连模式下确认电脑网卡是192.168.2.x段都不行就用串口ifconfig看板子实际拿到的地址很多时候 DHCP 分配的和你想的不是一个段。5.3 直连模式下 pip install 全部失败现象是装任何包都超时。原因很明确网线直连时板子没有出网路径只有和电脑的那一条点对点链路。解决办法要么改成接路由器要么在电脑上下好 whl 文件通过 Samba 传过去用pip install ./xxx.whl本地装。这个不是配置错误是拓扑决定的上限别在这上面耗时间。5.4 notebook 改乱了回不去现象是示例代码被改得面目全非运行报错又找不到原始版本。原因是 Jupyter 保存是即时的没有版本回退。做法是打开任何示例前先复制一份副本再改或者从原始仓库重新拉一份 notebook 覆盖。我现在的习惯是每个示例目录下先建一个_orig子目录放原件。5.5 writeframe 报错或画面花屏现象是视频循环跑几帧就抛异常或者 HDMI 上出现斜纹撕裂。原因通常是帧缓冲尺寸对不上newframe()拿到的缓冲尺寸由configure时的VideoMode决定如果你按 1080p 去切片赋值而实际配的是 640x480越界立刻报错。另一类是摄像头实际输出分辨率和你set的不一致赋值时形状不匹配。解决是把摄像头读回来的frame.shape打印出来和缓冲形状对一遍再切片。6. 让 notebook 变成可复现脚本转 .py、看 ip_dict、做最小验证notebook 适合摸索不适合反复跑。我一般等一个例程调通之后第一件事是把它固化成脚本这样下次换板子、换电脑不用再一格格点运行。Jupyter 自带转换工具在板子的终端里执行# 把 notebook 转成纯 Python 脚本输出到同目录 jupyter nbconvert --to script board_btn_leds.ipynb # 无显示器场景下直接跑-u 保证日志实时输出 python3 -u board_btn_leds.py转出来的脚本会保留所有 cell 的顺序但%matplotlib inline这类魔法命令会变成注释需要手动处理。跑之前建议加一层保护把主循环包进if __name__ __main__:不然 import 这个文件的时候循环会直接启动。第二个技巧是用ip_dict看 overlay 里到底有什么。加载完BaseOverlay之后敲base.ip_dict会列出所有已注册的 IP 核和它们的寄存器地址、可访问属性。想知道某个外设对象支持哪些方法dir(base.leds[0])比翻文档快。我排查“这个外设为什么没反应”时第一步永远是确认它到底在不在ip_dict里——不在说明加载的 overlay 不对代码写得再对也没用。第三个是最小验证法。任何一个例程跑不通先退回到一行代码base.leds[0].on()。这一行能亮说明 overlay 加载、外设映射、供电全部正常问题一定在后面这一行不亮后面所有调试都是白费。音频和视频同理先用bypass或纯色帧确认通路再往里加算法。血泪经验是别在 notebook 里边改边跑超过二十分钟。改到第五个版本的时候你已经不记得哪一行是最初能跑通的了。调通即固化固化即备份这个习惯救过我很多次。从那以后我每次拿到一块新板子都是先跑通最小验证、转成脚本、再动业务代码顺序反了就要花一晚上找后悔药。希望帮到你。本文还有配套的精品资源点击获取