v4.5.6

v4.5.6 是机器学习方面的重大版本。TensorFlow 的 tf C 模块被一个全新的、与引擎无关的 ml 包取代，该包以 TensorFlow Lite Micro（TFLM）为后端；图像到张量的转换迁移到了 image.to_ndarray()，双核板卡则迁移到了 Open-AMP。本版本包含若干破坏性变更——升级 ML 脚本前请先阅读下文。

重点摘要

  • 全新 ml 包——旧的 tf 模块被重写为一个与引擎无关的 ml 包（ml.Model、ml.preprocessing、ml.utils、ml.apps）；tf 仍作为别名保留。

  • TFLM 后端——过时的 libtf 被基于上游的 TensorFlow Lite Micro 取代：推理速度提升约 20%，库体积更小。

  • Open-AMP 双核——GIGA 和 Portenta H7 现在使用 Open-AMP/RPMsg 进行 M7/M4 核间通信（旧的 CM4 机制已移除）。

  • 板载蓝牙——Nicla Vision、Portenta H7 和 GIGA 上启用了 CYW43 蓝牙固件。

  • MicroPython 1.23.0、ulab 6.5.2（支持 4 维 ndarray）。

  • 破坏性变更： ML API 发生了实质性变化，且 Haar 级联在大多数板卡上默认禁用——参见破坏性变更部分。

新特性

  • ml 包——带有 predict()（roi、callback、多输入列表）的 ml.Model，每张量的 shape/dtype/scale/zero-point 属性，ml.preprocessing.Normalization，ml.utils（NMS），以及 ml.apps（一个纯 Python 的 MicroSpeech 关键词检测器，带 listen() 和非阻塞的 timeout=-1 流式处理，外加 draw_predictions()）。

  • 内置模型系统——models/index.txt 中列出的模型会按板卡有条件地嵌入（所有 ML 板卡嵌入 FOMO，带麦克风的板卡嵌入音频模型）。

  • image.to_ndarray(dtype, buffer=...)——将图像转换为 ulab ndarray（可选择原地转换）。

  • 从原始数组构造 Image()——新增的 shape=、strides=、scale= 关键字参数可从原始像素列表构建灰度/RGB565 图像。

  • 抗锯齿的 draw_circle()。

  • ssl 模块已冻结进 GIGA、Nicla Vision、Portenta H7、Nano RP2040 Connect、OpenMV 4/4P/PRO/PT、RT1060 和 Pico 的固件中。

  • 音频——audio.init() 新增 samples= 关键字（每通道的 PDM 采样数）；gain_db 现在对 DFSDM 麦克风（如 Nicla Vision）生效。

  • 调试协议——新的 GET_STATE 命令在单个数据包中返回运行/文本/JPEG 标志、帧几何信息和文本，减少了主机往返次数。

  • 用于核间通信的 Open-AMP vuart 示例。

其他变更与改进

  • MicroPython 更新至 1.23.0；ulab 更新至 6.5.2，支持 4 维 ndarray。

  • 更快的推理——ML 后端会在多次调用之间保持持久的状态/内存（约快 20%，支持 LSTM 类模型）。

  • get_similarity() 已在 draw_image 后端上重新实现（支持更广泛的格式/操作）。

  • morph() 和 mean() 滤波器系列改为使用关键字参数解析；mask= 现在接受可变图像。

  • 内存布局重构——DMA 区域按 2 的幂对齐，GC 块可重排，支持多个堆；在低 RAM 板卡上减少了早期堆碎片；RT1060 获得额外的 GC 堆。

  • WiFi（CYW43）现在会在软复位时反初始化；SPI-TV 显示器只从缓存刷新帧缓冲区域，使更新更平滑。

错误修复

摄像头与传感器：

  • 修复了 STM32 和 i.MX RT 上帧缓冲/传感器路径中意外的 CPU 缓存失效问题，该问题可能损坏图像数据。

  • 修复了 i.MX RT 板卡上 MLX90640/MLX90641 热成像 I2C 读取问题（大数据传输现在会分块进行）。

机器学习：

  • 修复了 ml.Model 的 load_to_fb 处理、输入 bytearray 大小计算、ndarray 的 ndim 检查，以及 Normalization 的图像格式/形状校验。

图像 / 系统：

  • 补充了缺失的 image.BLACK_BACKGROUND 绘制提示常量，以及图像/张量缓冲区长度的合理性检查。

  • 修复了 FIR 和音频的 GC 根指针问题，该问题可能导致回收器释放正在使用的缓冲区。

  • Servo Shield 示例现在使用 SoftI2C，使其能在 OpenMV RT 板卡上工作。

硬件与板卡支持

  • Arduino GIGA——支持 HM01B0 / HM0360 传感器；Open-AMP 双核。

  • 蓝牙——Nicla Vision、Portenta H7 和 GIGA 上的 CYW43 BT 固件。

  • Portenta H7——Open-AMP M7/M4 RPMsg。

  • OpenMV RT1060——额外的 GC 堆块（更多 Python 内存）。

破坏性 API 变更

v4.5.5 与 v4.5.6 之间用户可见的 API 变更。范围：modules/ 中的 Python C 模块和 scripts/libraries/ 中的 Python 库。

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

  • major（重大）——大多数使用它的脚本都需要修改。

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

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

  • tooling（工具链）——影响双核/板卡机制，而非 Python API。

变更按影响顺序分组。如果你只想移植代码，可直接跳到末尾的 迁移清单。每个提交哈希都链接到 GitHub 上对应的 diff。

tf 模块被 ml 包取代 (major)

TensorFlow 的 tf C 模块被重写为与引擎无关的 ml 包（tf 作为向后兼容的别名保留，但新代码应使用 ml）。模块级函数 tf.load、tf.load_builtin_model 以及 detect()/segment()/分类方法均已移除——请构造一个 ml.Model 并调用 predict()。ml.Model(path) 现在只返回模型（不再是 (labels, model) 元组）；标签现为 model.labels 属性。predict() 现在返回 ulab ndarray（而非浮点元组），支持多输入模型（传入一个列表），NMS 移至 ml.utils；输入归一化移至 ml.preprocessing.Normalization。旧的 ml.py 现在是 ml.apps。

提交： c7228cbb4、6c212409c、3e37f46db、9a186f4e2、70b89f474、3f8491cb0、4506682c2、8b38f3837

image.unpack() 已移除——请使用 to_ndarray() (major)

存在时间很短的 image.unpack() 已被移除；请改用 image.to_ndarray(dtype, buffer=...) 将图像转换为张量，并使用 ml.preprocessing.Normalization 而非旧的内置图像缩放路径来应用 scale/mean/stdev 归一化。

提交： 9848eed12、de0d46fa6

Image() 的原始数组 scale 参数 (minor)

从原始像素数组构造 Image 时，scale 参数现在接受 (min, max) 范围，而不再是 (scale, add)。

提交： 7b79fb4c7

Haar 级联在大多数板卡上默认禁用 (behavior)

为释放闪存空间，Haar 级联人脸检测（find_features() / image.HaarCascade()）现在在 Arduino GIGA、Nicla Vision、Portenta H7、OpenMV 3、OpenMV 4 / 4 Plus / PRO 和 OpenMV Pure Thermal 上默认禁用。在这些板卡上使用 Haar 级联的脚本必须重新编译固件并启用该功能。

提交： 6ce27c910

脚本中断与张量缩放 (behavior)

USB 调试器现在通过 MicroPython 的 VM-abort 特性来中断正在运行的脚本，而不再强制跳转 PendSV（更干净，但中断点有所不同）。SCALE_S128_127 输入缩放被修正为将 0–255 映射到 −128–127 而不再带有错误的增益——依赖旧（不正确）缩放的模型将产生不同的结果。

提交： e758a0f95、a4d97c572

CM4 协处理器被 Open-AMP 取代 (tooling)

GIGA / Nicla Vision / Portenta H7 上已弃用的 CM4 协处理器固件机制已被移除，并由 Open-AMP/RPMsg 取代。双核代码必须迁移到 Open-AMP 模型（已提供 vuart 示例）。

提交： 3cc57fea4、93f2d4c41

迁移清单

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

  1. 将 ML 代码移植到 ml：构造 ml.Model(path)，调用 predict()，读取 model.labels，预期输出为 ndarray，并将归一化移至 ml.preprocessing.Normalization、将 NMS 移至 ml.utils（ml 包变更）。

  2. 将 image.unpack() 替换为 image.to_ndarray()（unpack 移除）。

  3. 将任何 Image() 原始数组的 scale 参数更新为 (min, max) 范围（Image scale 变更）。

  4. 如果你在受影响的板卡上使用 Haar 级联，请重新编译并启用该功能（Haar 级联变更）。

  5. 重新验证依赖于 SCALE_S128_127 的模型（缩放变更）。

  6. 将双核代码迁移到 Open-AMP（CM4 变更）。