v3.3.0

v3.3.0 是一个重大版本。它通过全新的 sensor.ioctl() 接口和调色板添加了完整的 FLIR Lepton 热成像摄像头 支持，新增了 tv SPI 视频输出模块、全局快门触发模式、一大批新的 image 绘图/分析方法（gamma_corr()、draw_ellipse()、draw_edges() 以及众多色块属性），还有新的 ToF / 电机 / 线性代数库。cpufreq API 经过重构，sensor.set_framesize() 现在会抛出异常——请阅读下方的重大变更。

亮点

  • FLIR Lepton —— 通过全新的 sensor.ioctl() 接口、调色板和 image.to_rainbow() 提供完整的热成像摄像头支持。

  • tv 模块 —— SPI 电视 / 复合视频输出。

  • 全局快门触发模式 —— 通过 sensor.ioctl() 实现 MT9V034 触发式采集。

  • 成像 —— gamma_corr()、draw_ellipse()、draw_edges()、draw_image() alpha 混合，以及众多新的色块属性。

  • 新增库 —— VL53L1X ToF 测距、TB6612 电机驱动、micro-linalg。

  • 重大变更： cpufreq API 经过重构，sensor.set_framesize() 现在失败时会抛出异常，sensor.alloc_extra_fb() 不再支持 Bayer/JPEG，并且 image.replace() 的位置参数发生了移位——参见重大变更。

新功能

  • FLIR Lepton —— 添加了用于传感器专用控制的 sensor.ioctl()，以及一整套 Lepton ioctl（辐射测温、刷新率/分辨率、运行命令、设置/获取属性、以 °C 为单位的 FPA/AUX 温度、测量模式/范围、宽度/高度），添加了带 sensor.PALETTE_RAINBOW / PALETTE_IRONBOW 的 sensor.set_color_palette() / sensor.get_color_palette()、image.to_rainbow() 以及 Lepton 示例脚本（27-Lepton）。

  • 触发模式 —— 为 MT9V034 全局快门触发式采集添加了 IOCTL_SET_TRIGGERED_MODE / IOCTL_GET_TRIGGERED_MODE，并附带高帧率和触发模式示例。

  • tv 模块 —— 添加了 SPI 电视 / 复合视频输出绑定。

  • 成像 —— 添加了 image.gamma_corr()、image.draw_ellipse()、image.draw_edges()、draw_image() alpha 混合，clear() 上的 mask= 关键字，重新加入了 mask_rectangle() / mask_circle() / mask_ellipse()，draw_string() / draw_text() 上的旋转 / hmirror / vflip 关键字，replace() 上的 transpose 关键字（以及 assign / set 别名），copy() 的 x_scale / y_scale 以及 crop() / scale()，从尺寸构造的 Image() 构造函数，sensor.BINARY 像素格式，导出的色彩空间转换函数，以及众多新的色块属性（corners、perimeter、roundness、elongation、extent、compactness、solidity、convexity、enclosing_circle、enclosed_ellipse 和旋转）。

  • 库 —— 添加了 vl53l1x ToF 测距传感器驱动、tb6612 电机驱动（含直流电机和步进电机 Motor-Shield 示例），以及一个 micro-linalg 库（ulinalg / umatrix）。

  • 将 FatFS 升级到 FF13C（支持 exFAT）。

其他变更和改进

  • 改进了默认 JPEG 质量（采用 low–high 的中间值而非硬编码值）；原地图像操作不再需要将图像重复作为第一个参数；draw_string() 接受非整数的缩放值。

错误修复

摄像头和传感器：

  • 修复了 Lepton 3.5 启动挂起（超时 + 恢复）和复位可靠性问题，MT9V034 在 set_pixformat() 之前调用 set_framesize() 的问题（调用顺序不再重要），STM32H7 上的 MT9V034 WVGA，MT9V034 自动曝光范围和影子寄存器更新，以及 H7 ADC 错误。

成像：

  • 修复了 find_apriltags() 中的无效内存访问，将缩放后的图像复制到主帧缓冲区时的 copy()，to_grayscale() / to_rgb565() 帧缓冲区分配，关键点对象的 len()，JPEG MCU 边界处理，binary() 阈值列表解析，以及 draw_keypoints() 接受关键点元组的问题。

系统：

  • 修复了 image / fir / lcd / tv / nn 方法中 fb_alloc 的 mark/free 不平衡泄漏，使 py_assert 在捕获异常时释放帧缓冲区内存（#417），清除 UART 溢出（ORE）标志使溢出不再卡住 UART 读取，修复了 RTC IRQ 处理程序，并修复了 Windows 上的 cascade_convert.py 工具。

硬件和板卡支持

  • FLIR Lepton 热成像摄像头。

  • TV shield —— SPI 电视 / 复合视频输出。

  • 全局快门（MT9V034） 触发模式。

重大 API 变更

v3.2.0 与 v3.3.0 之间面向用户的 API 变更。范围：modules/ 中的 Python C 模块和 scripts/libraries/ 中的 Python 库。

每项变更都标注了其影响：

  • major —— 影响大多数使用该功能的脚本；你需要移植代码。

  • minor —— 范围较窄的 API；仅影响用到它的脚本。

  • behavior —— API 相同但结果不同；请重新检查已调优的脚本。

变更按影响程度依此顺序分组。如果你只是想移植代码，请跳到末尾的 迁移清单。每个提交哈希都链接到其在 GitHub 上的差异。

cpufreq API 重构 (major)

cpufreq 模块为支持 H7 进行了重构。cpufreq.CPUFREQ_120MHZ / 144 / 168 / 192 / 216MHZ 常量和 cpufreq.get_frequency() 被移除。cpufreq.set_frequency() 现在接受一个普通的 MHz 整数（例如 cpufreq.set_frequency(120)），并新增了 cpufreq.get_current_frequencies() / cpufreq.get_supported_frequencies()。

提交： 6babf84a1

image.replace() 位置参数移位 (minor)

image.replace() 新增了一个 transpose 参数，使位置参数 mask 从第 4 位移到了第 5 位。以位置方式传入 mask 的代码（例如 img.replace(src, hmirror, vflip, mask)）必须改用关键字形式 img.replace(src, mask=mask)。

提交： dbe7bf059

sensor.alloc_extra_fb() 不再接受 Bayer/JPEG (minor)

sensor.alloc_extra_fb() 不再接受 sensor.BAYER 或 sensor.JPEG（现在它还支持 sensor.BINARY）。以 Bayer 或 JPEG 格式分配额外帧缓冲区的代码必须改用 GRAYSCALE / RGB565（或以其他方式分配缓冲区）。

提交： f9e6b3fe0

sensor.set_framesize() 失败时抛出异常 (behavior)

sensor.set_framesize() 现在在 framesize 不受支持时抛出 ValueError 而不再返回 False。检查 False 返回值的代码必须改为捕获 ValueError 异常。

提交： b0442633e

迁移清单

要干净地移植到 v3.3.0，通常需要做的工作是：

  1. 将 cpufreq 代码移植为使用整数 MHz 的 set_frequency() 以及 get_current_frequencies() / get_supported_frequencies()（cpufreq 重构）。

  2. 以关键字方式向 image.replace() 传入 mask（replace 变更）。

  3. 将额外帧缓冲区分配为 GRAYSCALE / RGB565 而非 Bayer/JPEG（alloc_extra_fb 变更）。

  4. 在 sensor.set_framesize() 周围捕获 ValueError 而非检查 False（set_framesize 变更）。

所有其他脚本无需改动即可运行。