machine --- 與硬體相關的函式

machine 模組包含與特定開發板硬體相關的特定函式。此模組中的大多數函式可讓你直接且不受限制地存取與控制系統上的硬體區塊（如 CPU、計時器、匯流排等）。

記憶體存取

此模組公開三個可下標（subscriptable）的物件，用於原始記憶體存取。每個物件的行為都類似以位元組位址索引的稀疏陣列：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) 是 800kHz WS2812 RGB LED 的時序規格。

時序準確度取決於硬體；較快的 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 -- 控制器區域網路（Controller Area Network）通訊協定
• class RTC -- 即時時鐘
• class Timer -- 虛擬週期性 / 單次計時器
• class WDT -- 看門狗計時器
• class SDCard -- SD / MMC 卡驅動程式
• class Counter -- 脈衝計數器
• class Encoder -- 正交解碼器