machine --- 与硬件相关的函数

machine 模块包含与特定开发板上的硬件相关的特定函数。该模块中的大多数函数允许直接、不受限制地访问和控制系统上的硬件模块（如 CPU、定时器、总线等）。

内存访问

该模块暴露了三个可下标的对象，用于原始内存访问。每个对象的行为类似于按字节地址索引的稀疏数组：value = memN[addr] 读取，memN[addr] = value 写入。无论访问宽度如何，地址始终是字节地址。

machine.mem8

可下标的 8 位内存访问器。mem8[addr] 从 addr 处的字节读取一个 0-255 范围内的 int；mem8[addr] = value 写入 value 的低 8 位。addr 必须按 1 字节对齐（任意地址）。

machine.mem16

可下标的 16 位（半字）内存访问器。mem16[addr] 读取一个 0-65535 范围内的 int；mem16[addr] = value 写入低 16 位。addr 必须按 2 字节对齐。

machine.mem32

可下标的 32 位（字）内存访问器。mem32[addr] 读取一个 0-0xFFFFFFFF 范围内的 int；mem32[addr] = value 写入低 32 位。addr 必须按 4 字节对齐。

使用示例（寄存器特定于 STM32H7 微控制器——在 OpenMV Cam H7 / H7 Plus / Pure Thermal 上，排针引脚 P0 连接到 PB15）：

import machine
from micropython import const

GPIOB = const(0x58020400)
GPIO_BSRR = const(0x18)
GPIO_IDR = const(0x10)

# set P0 (PB15) high via the GPIOB bit-set/reset register
machine.mem32[GPIOB + GPIO_BSRR] = 1 << 15

# read P0 (PB15) directly out of the GPIOB input-data register
value = (machine.mem32[GPIOB + GPIO_IDR] >> 15) & 1

复位相关函数

machine.reset() → None

以类似于按下外部 RESET 按钮的方式 硬复位 设备。

machine.soft_reset() → None

执行解释器的 软复位，删除所有 Python 对象并重置 Python 堆。

machine.reset_cause() → int

获取复位原因。有关可能的返回值，请参阅 常量。

machine.bootloader(value: int | None = None, /) → NoReturn

将摄像头复位进入其 DFU / 串行下载引导加载程序，准备好用新固件重新刷写。此调用永不返回；开发板直接重启进入引导加载程序。

value 参数为了跨移植版本兼容性而被接受，但在每个 OpenMV 支持的开发板上都会被忽略。

中断相关函数

以下函数允许控制中断。某些系统需要中断才能正常运行，因此长时间禁用它们可能会损害核心功能，例如看门狗定时器可能会意外触发。中断应仅禁用最短的时间，然后重新启用到其先前的状态。例如：：

import machine

# Disable interrupts
state = machine.disable_irq()

# Do a small amount of time-critical work here

# Enable interrupts
machine.enable_irq(state)

machine.disable_irq() → int

禁用中断请求。返回先前的 IRQ 状态，应将其视为一个不透明值。此返回值应传递给 enable_irq() 函数，以便将中断恢复到调用 disable_irq() 之前的原始状态。

machine.enable_irq(state: int) → None

重新启用中断请求。state 参数应为最近一次调用 disable_irq() 函数所返回的值。

电源相关函数

machine.freq(hz: int | None = None, /) → int | tuple[int, ...]

返回 MCU 时钟频率。

在 STM32 移植版本上（每个 OpenMV Cam M4/M7/H7/H7+/PT/N6 和 Arduino 品牌的变体）返回值是一个以 Hz 为单位的内部时钟元组。在 STM32N6（OpenMV Cam N6）上，该元组为 (CPUCLK, SYSCLK, HCLK, PCLK1, PCLK2, PCLK4, PCLK5)；在其他 STM32 摄像头上，它是 (SYSCLK, HCLK, PCLK1, PCLK2)。

在 mimxrt 移植版本（OpenMV Cam RT1062）和 alif 移植版本（OpenMV Cam AE3）上，返回值是单个整数——以 Hz 为单位的 CPU 频率。

调用 freq(hz) 来设置时钟会在每个 OpenMV 支持的开发板上引发 NotImplementedError。

machine.idle() → None

门控到 CPU 的时钟，可在任何时候（短期或长期）减少功耗。外设继续工作，并且一旦触发任何中断，或在 CPU 暂停后至多一毫秒，执行就会恢复。

建议在任何持续检查外部变化（即轮询）的紧密循环内调用此函数。这将在不显著影响性能的情况下减少功耗。若要进一步减少功耗，请参阅 lightsleep()、time.sleep() 和 time.sleep_ms() 函数。

machine.sleep() → None

备注

此函数已弃用，请改用不带参数的 lightsleep()。

machine.lightsleep(time_ms: int | None = None, /) → None

停止执行并进入低功耗状态，保留完整的 RAM 和外设。MCU 时钟被门控；当函数返回时，执行从调用 lightsleep() 的位置恢复，所有子系统仍正常运行。

如果指定了 time_ms，它是以毫秒为单位的最大睡眠持续时间。无论是否带超时，如果任何已配置的唤醒源触发（Pin IRQ、RTC 闹钟、已启用的外设中断等），执行都可能提前恢复。唤醒源必须在调用 之前 设置好。

省电效果比 deepsleep() 更适度，但唤醒是瞬时的，且不会丢失任何状态。

machine.deepsleep(time_ms: int | None = None, /) → NoReturn

停止执行并进入可用的最深低功耗状态。RAM 内容、外设状态和网络连接都可能丢失。当 MCU 唤醒时，它从主脚本的开头启动，类似于上电或硬复位；reset_cause() 随后将返回 DEEPSLEEP_RESET，以便脚本能够区分深度睡眠唤醒与其他复位原因。

如果指定了 time_ms，MCU 会安排在那么多毫秒之后唤醒（或者更早，如果另一个已配置的唤醒源先触发）。不传入任何参数则会睡眠直到外部唤醒源触发。

此调用永不返回——在主脚本的顶部以 reset_cause() 为条件处理恢复的执行。

杂项函数

machine.unique_id() → bytes

返回一个 bytes 对象，包含此开发板的唯一标识符。该值从 MCU 的硬件中读取（通常是出厂编程的设备序列号），因此它在重启之间保持稳定，并且每块开发板各不相同。

长度取决于 MCU 系列——STM32 上为 12 字节，mimxrt 和 alif 移植版本上为 8 字节。如果你的应用程序需要固定长度的 ID，请对返回值进行切片或哈希处理。

machine.time_pulse_us(pin: Pin, pulse_level: int, timeout_us: int = 1000000, /) → int

测量 pin 上单个脉冲的宽度，并以微秒为单位返回其持续时间。

pin 必须配置为数字输入。

pulse_level 是要计时的脉冲极性：1 表示高电平脉冲，0 表示低电平脉冲。

该函数分两个阶段工作。首先，如果引脚尚未处于 pulse_level，它会等待引脚转换到 pulse_level（脉冲的开始）。然后它测量引脚在转换回去之前保持在 pulse_level 的时间（脉冲的结束）。测得的时间以微秒为单位返回。

timeout_us 独立地限制 每个 阶段（因此最坏情况下的调用最长持续 2 * timeout_us）。超时时，函数返回一个负值，标识哪个阶段超时：

• -2 —— 等待前沿超时（引脚从未达到 pulse_level）。

• -1 —— 等待后沿超时（脉冲长于 timeout_us）。

machine.bitstream(pin: Pin, encoding: int, timing: tuple, data: bytes, /) → None

通过对指定的 pin 进行位拼接（bit-banging）来发送 data。encoding 参数指定如何对位进行编码，而 timing 是特定于编码的时序规范。

支持的编码有：

• 0 表示“高低”脉冲持续时间调制。这将把 0 和 1 位作为定时脉冲发送，从最高有效位开始。timing 必须是一个以纳秒为单位、格式为 (high_time_0, low_time_0, high_time_1, low_time_1) 的四元组。例如，(400, 850, 800, 450) 是 WS2812 RGB LED 在 800kHz 下的时序规范。

时序精度取决于硬件；更快的 MCU 产生更紧凑的脉冲（通常为数十纳秒）。

备注

若要控制 WS2812 / NeoPixel 灯带，请参阅 neopixel 模块以获取更高级别的 API。

常量

下面的常量由 reset_cause() 返回，用于标识 MCU 上次复位的原因。在 STM32 和 mimxrt 移植版本上可用；alif 移植版本（OpenMV Cam AE3）目前不暴露复位原因常量，其 reset_cause() 始终返回 0。

machine.PWRON_RESET: int

由芯片上电引起的复位。STM32 和 mimxrt 移植版本。

machine.WDT_RESET: int

由看门狗定时器到期引起的复位。STM32 和 mimxrt 移植版本。

machine.SOFT_RESET: int

由 soft_reset() 引起的复位（Python 解释器在没有硬件复位的情况下重启）。STM32 和 mimxrt 移植版本。

machine.HARD_RESET: int

由 NRST 引脚被置位（外部复位按钮）引起的复位。仅限 STM32 移植版本。

machine.DEEPSLEEP_RESET: int

由从深度睡眠唤醒引起的复位。仅限 STM32 移植版本。

类

• class Pin -- 控制 I/O 引脚
• class Signal -- 控制和感测外部 I/O 设备
• class LED -- 可移植的板载 LED 控制
• class ADC -- 模数转换
• class PWM -- 脉冲宽度调制
• class UART -- 双工串行通信总线
• class SPI -- 串行外设接口总线协议（控制器端）
• class SoftSPI -- 软件模拟的 SPI 总线
• class I2C —— 一种双线串行协议
• class SoftI2C —— 软件模拟的 I2C 总线
• class I2CTarget —— 一个 I2C 目标设备
• class I2S -- Inter-IC Sound 总线协议
• class CAN -- 控制器局域网（CAN）协议
• class RTC -- 实时时钟
• class Timer -- 虚拟周期/单次定时器
• class WDT -- 看门狗定时器
• class SDCard -- SD / MMC 卡驱动
• class Counter -- 脉冲计数器
• class Encoder -- 正交解码器