终极指南：如何快速掌握PyFTDI库——用Python轻松控制FTDI设备的完整教程 🚀
项目地址: https://gitcode.com/gh_mirrors/py/pyftdi PyFTDI是一个纯Python编写的FTDI设备驱动库，支持通过Python轻松控制FT232H、FT4232H、FT2232H等系列USB转串口芯片，实现UART、SPI、I2C、GPIO等多种接口通信，是嵌入式开发、硬件调试和协议转换的高效工具。
📋 为什么选择PyFTDI？核心优势一览
PyFTDI凭借纯Python实现和跨平台特性，成为连接FTDI硬件与软件的理想桥梁。以下是它的四大核心优势：
✅ 多接口同时运行，功能强大
- 全接口支持：UART（最高6Mbps）、SPI主模式、I2C主模式、JTAG和GPIO可同时工作
- 灵活GPIO访问：SPI/I2C未使用的引脚可作为通用GPIO读写，实现硬件扩展
- 多设备并发：同一Python进程可同时控制多个FTDI适配器，满足复杂系统需求
💻 跨平台兼容，开箱即用
- 全系统支持：完美运行于Linux、macOS和Windows（需特殊配置）
- 纯Python实现：无需编译原生代码，通过PyUSB调用libusb实现硬件通信
- 轻量化设计：仅依赖pyusb（≥1.0.0）和pyserial（≥3.0），安装便捷
🛠️ 丰富工具链，开发提效
- 设备检测工具：
ftdi_urls.py自动列出所有连接的FTDI设备及访问URL - I2C扫描工具：
i2cscan.py快速发现总线上的I2C从设备 - 串口终端：
pyterm.py支持FTDI虚拟串口通信测试 - EEPROM配置：
ftconf.py轻松管理FTDI设备EEPROM参数
📚 详尽文档，新手友好
- 模块化API设计：清晰的类结构（如
Ftdi、SpiController、I2cController）降低学习成本 - 丰富示例代码：覆盖从基础连接到高级协议通信的完整场景
- 活跃社区支持：完善的错误处理指南和常见问题解答
🔧 零基础安装指南：3步快速上手
📦 1. 安装系统依赖
PyFTDI依赖libusb库实现USB通信，需根据操作系统提前安装：
Debian/Ubuntu Linux
sudo apt-get install libusb-1.0
Homebrew macOS
brew install libusb
Windows系统
推荐使用Zadig工具安装libusb-win32驱动：
- 打开Zadig → 选项 → 列出所有设备
- 选择FTDI复合设备（如"Dual RS232-HS"，不要选择带Interface的子设备）
- 驱动选择
libusb-win32→ 点击"Replace Driver"
👥 2. 配置设备访问权限（Linux特有）
创建udev规则文件允许用户空间访问FTDI设备：
sudo nano /etc/udev/rules.d/11-ftdi.rules
添加以下内容（覆盖主流FTDI设备PID）：
# FT232H/FT2232H/FT4232H等常见设备
SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6001", GROUP="plugdev", MODE="0664"
SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6010", GROUP="plugdev", MODE="0664"
SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6014", GROUP="plugdev", MODE="0664"
刷新规则并添加用户到plugdev组：
sudo udevadm control --reload-rules
sudo udevadm trigger
sudo adduser $USER plugdev # 需注销重新登录生效
🐍 3. 安装PyFTDI库
通过pip一键安装（支持Python 3.6+）：
pip install pyftdi
验证安装是否成功：
from pyftdi.ftdi import Ftdi
Ftdi.show_devices() # 列出所有检测到的FTDI设备
成功输出示例：
Available interfaces:
ftdi://ftdi:232h:FT1PWZ0Q/1 (C232HD-DDHSP-0)
ftdi://ftdi:2232/1 (Dual RS232-HS)
🔌 核心功能实战：4大接口应用教程
📡 UART串口通信：即插即用的串行通信
PyFTDI提供pyserial兼容API，可无缝替换传统串口库：
from pyftdi.serialext import serial_for_url
# 打开FTDI虚拟串口（URL格式：ftdi://<vendor>:<product>/<interface>）
ser = serial_for_url('ftdi://ftdi:232h/1', baudrate=115200)
if not ser.is_open:
ser.open()
# 发送数据
ser.write(b'Hello FTDI!')
# 接收数据（超时1秒）
data = ser.read(100)
print(f'Received: {data.decode()}')
模块路径：UART功能实现位于
pyftdi/serialext/protocol_ftdi.py，通过重载pyserial协议实现FTDI设备支持。
🔄 SPI主模式：高速同步通信示例
以下代码演示如何通过FT232H实现SPI通信（支持Mode 0/2）：
from pyftdi.spi import SpiController
# 初始化SPI控制器（使用第一个FTDI接口）
spi = SpiController()
spi.configure('ftdi://ftdi:232h/1')
# 打开SPI从设备（CS=D3引脚，时钟10MHz）
slave = spi.get_port(cs=0, freq=10E6, mode=0)
# 全双工通信：发送0xAA同时接收数据
tx_data = bytes([0xAA])
rx_data = slave.exchange(tx_data, duplex=True)
print(f'SPI received: {rx_data.hex()}')
接线指南：SPI接口使用FTDI的MPSSE引脚（SCK=D0, MOSI=D1, MISO=D2, CS=D3），未使用引脚可配置为GPIO。
图：PyFTDI SPI通信典型接线方式，展示FT232H与SPI从设备的连接关系（SCK/MOSI/MISO/CS信号线对应关系）
📤 I2C主模式：多设备总线通信
通过I2C控制器扫描总线上的设备并读取数据：
from pyftdi.i2c import I2cController
# 初始化I2C控制器
i2c = I2cController()
i2c.configure('ftdi://ftdi:232h/1')
# 扫描I2C总线设备
devices = i2c.scan()
print(f'Detected I2C devices: {[hex(addr) for addr in devices]}')
# 读取从设备（地址0x50）数据
slave = i2c.get_port(0x50)
data = slave.read(16) # 读取16字节
注意事项：I2C模式仅支持7位地址，时钟频率最高支持400kHz，需确保总线上的上拉电阻（通常4.7kΩ）连接正确。
图：PyFTDI I2C通信推荐接线图，显示SDA/SCL信号线的上拉电阻配置及设备连接方式
🔀 GPIO控制：灵活的数字输入输出
利用未被SPI/I2C占用的引脚实现GPIO功能：
from pyftdi.gpio import GpioController
# 初始化GPIO控制器（使用8个低字节引脚）
gpio = GpioController()
gpio.configure('ftdi://ftdi:232h/1', direction=0x0F) # 低4位输出，高4位输入
# 设置输出引脚（D0=1, D1=0, D2=1, D3=0）
gpio.write(0x05)
# 读取输入引脚（D4-D7）
input_data = gpio.read() >> 4
print(f'GPIO input: {input_data:04b}')
引脚分配：FT232H提供16个GPIO引脚（D0-D15），具体功能需参考设备数据手册，MPSSE模式下部分引脚被固定为特定功能。
🛠️ 实用工具与高级技巧
🔍 设备检测与URL格式
PyFTDI使用URL标识设备，格式灵活支持多种寻址方式：
- 按序列号：
ftdi://ftdi:232h:FT1PWZ0Q/1（精确匹配） - 按产品型号：
ftdi://ftdi:2232/2（第二个接口） - 自定义VID/PID：需提前调用
Ftdi.add_custom_product(vid, pid)注册
📝 EEPROM配置工具：ftconf.py
通过命令行工具修改FTDI设备参数（如厂商名称、产品描述）：
# 读取EEPROM内容
ftconf.py -d ftdi://ftdi:232h/1 read eeprom_backup.bin
# 修改产品描述
ftconf.py -d ftdi://ftdi:232h/1 write --product "My Custom FTDI Device"
警告：错误的EEPROM配置可能导致设备无法识别，操作前建议备份原始数据。
🐞 常见问题解决指南
❶ "Error: No backend available"
原因：系统缺少libusb库或路径未配置
解决：
- Linux：
sudo apt install libusb-1.0-0 - macOS：
brew install libusb - Windows：确保Zadig安装了libusb-win32驱动
❷ "Access denied (insufficient permissions)"
原因：Linux用户无设备访问权限
解决：
sudo udevadm control --reload-rules
sudo udevadm trigger
newgrp plugdev # 无需注销生效
❸ "PyUSB 1.2.0 not supported"
原因：PyUSB 1.2.0破坏兼容性
解决：降级PyUSB版本
pip install "pyusb<1.2.0"
🎯 总结：PyFTDI助你打通硬件与软件的最后一公里
PyFTDI凭借纯Python实现、丰富接口支持和跨平台特性，为开发者提供了便捷的FTDI设备控制方案。无论是嵌入式系统调试、传感器数据采集还是自定义硬件开发，它都能显著降低开发门槛，提升工作效率。
通过本文介绍的安装配置、核心功能和实用技巧，你已经具备使用PyFTDI开发实际项目的能力。立即访问项目仓库获取完整代码和文档，开启你的硬件编程之旅吧！
官方文档：完整API说明和高级用法请参考
pyftdi/doc/目录下的rst文档，包含接口时序图、性能优化和虚拟设备测试等高级内容。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
