machine — funcții legate de hardware

Modulul machine conține funcții specifice legate de hardware-ul de pe o anumită placă. Majoritatea funcțiilor din acest modul permit obținerea accesului direct și nerestricționat la blocurile hardware ale unui sistem (cum ar fi CPU, temporizatoare, magistrale etc.), precum și controlul acestora.

Acces la memorie

Modulul expune trei obiecte indexabile folosite pentru accesul brut la memorie. Fiecare se comportă ca un tablou rar indexat după adresa de octet: value = memN[addr] citește, memN[addr] = value scrie. Adresa este întotdeauna o adresă de octet, indiferent de lățimea accesului.

machine.mem8

Accesor de memorie pe 8 biți, indexabil. mem8[addr] citește un int în intervalul 0-255 din octetul de la addr; mem8[addr] = value scrie cei mai puțin semnificativi 8 biți ai lui value. addr trebuie aliniat la 1 octet (orice adresă).

machine.mem16

Accesor de memorie pe 16 biți (semicuvânt), indexabil. mem16[addr] citește un int în intervalul 0-65535; mem16[addr] = value scrie cei mai puțin semnificativi 16 biți. addr trebuie aliniat la 2 octeți.

machine.mem32

Accesor de memorie pe 32 de biți (cuvânt), indexabil. mem32[addr] citește un int în intervalul 0-0xFFFFFFFF; mem32[addr] = value scrie cei mai puțin semnificativi 32 de biți. addr trebuie aliniat la 4 octeți.

Exemplu de utilizare (registrele sunt specifice unui microcontroler STM32H7 – pe OpenMV Cam H7 / H7 Plus / Pure Thermal pinul de pe header P0 este conectat la 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

Funcții legate de resetare

machine.reset() → None

Resetează hardware dispozitivul într-un mod similar cu apăsarea butonului extern RESET.

machine.soft_reset() → None

Efectuează o resetare software a interpretorului, ștergând toate obiectele Python și resetând heap-ul Python.

machine.reset_cause() → int

Obține cauza resetării. Vezi constante pentru valorile posibile returnate.

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

Resetează camera în bootloader-ul său de descărcare DFU / serială, gata să fie reprogramată cu firmware nou. Acest apel nu revine niciodată; placa repornește direct în bootloader.

Argumentul value este acceptat pentru compatibilitate între porturi, dar este ignorat pe fiecare placă acceptată de OpenMV.

Funcții legate de întreruperi

Următoarele funcții permit controlul întreruperilor. Unele sisteme necesită întreruperi pentru a funcționa corect, astfel încât dezactivarea lor pentru perioade lungi poate compromite funcționalitatea de bază, de exemplu temporizatoarele de supraveghere (watchdog) se pot declanșa în mod neașteptat. Întreruperile ar trebui dezactivate doar pentru o perioadă minimă de timp și apoi reactivate la starea lor anterioară. De exemplu:

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

Dezactivează cererile de întrerupere. Returnează starea IRQ anterioară, care ar trebui considerată o valoare opacă. Această valoare returnată ar trebui transmisă funcției enable_irq() pentru a restabili întreruperile la starea lor inițială, dinaintea apelării disable_irq().

machine.enable_irq(state: int) → None

Reactivează cererile de întrerupere. Parametrul state ar trebui să fie valoarea returnată de cel mai recent apel al funcției disable_irq().

Funcții legate de alimentare

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

Returnează frecvențele de ceas ale MCU-ului.

Pe porturile STM32 (fiecare OpenMV Cam M4/M7/H7/H7+/PT/N6 și variantele de marcă Arduino) valoarea returnată este un tuplu cu ceasurile interne în Hz. Pe STM32N6 (OpenMV Cam N6) tuplul este (CPUCLK, SYSCLK, HCLK, PCLK1, PCLK2, PCLK4, PCLK5); pe celelalte camere STM32 este (SYSCLK, HCLK, PCLK1, PCLK2).

Pe portul mimxrt (OpenMV Cam RT1062) și portul alif (OpenMV Cam AE3) valoarea returnată este un singur întreg – frecvența CPU în Hz.

Apelarea freq(hz) pentru a seta ceasul generează NotImplementedError pe fiecare placă acceptată de OpenMV.

machine.idle() → None

Întrerupe ceasul către CPU, util pentru a reduce consumul de energie în orice moment, pe perioade scurte sau lungi. Perifericele continuă să funcționeze, iar execuția reia imediat ce este declanșată orice întrerupere, sau cel mult la o milisecundă după ce CPU-ul a fost pus în pauză.

Se recomandă apelarea acestei funcții în interiorul oricărei bucle strânse care verifică în mod continuu o schimbare externă (adică polling). Acest lucru va reduce consumul de energie fără a afecta semnificativ performanța. Pentru a reduce și mai mult consumul de energie, vezi funcțiile lightsleep(), time.sleep() și time.sleep_ms().

machine.sleep() → None

Notă

Această funcție este depreciată, folosiți în schimb lightsleep() fără argumente.

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

Oprește execuția și intră într-o stare de consum redus, cu reținerea completă a RAM-ului și a perifericelor. Ceasul MCU-ului este întrerupt; când funcția revine, execuția se reia din punctul în care a fost apelată lightsleep(), cu fiecare subsistem încă operațional.

Dacă time_ms este specificat, acesta reprezintă durata maximă de somn în milisecunde. Cu sau fără timeout, execuția se poate relua mai devreme dacă se declanșează orice sursă de trezire configurată (un IRQ Pin, o alarmă RTC, o întrerupere de periferic activată, …). Sursele de trezire trebuie configurate înainte de apel.

Economia de energie este mai modestă decât la deepsleep(), dar trezirea este instantanee și nicio stare nu se pierde.

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

Oprește execuția și intră în cea mai profundă stare de consum redus disponibilă. Conținutul RAM-ului, starea perifericelor și conexiunile de rețea pot fi toate pierdute. Când MCU-ul se trezește, pornește de la începutul scriptului principal, similar unei porniri sau resetări hardware; reset_cause() va returna apoi DEEPSLEEP_RESET, astfel încât scriptul să poată distinge o trezire din deepsleep de alte cauze de resetare.

Dacă time_ms este specificat, MCU-ul programează o trezire după atâtea milisecunde (sau mai devreme, dacă se declanșează mai întâi o altă sursă de trezire configurată). Nu transmiteți nimic pentru a dormi până când se declanșează o sursă de trezire externă.

Acest apel nu revine niciodată – gestionați execuția reluată în partea de sus a scriptului principal, condiționat de reset_cause().

Funcții diverse

machine.unique_id() → bytes

Returnează un obiect bytes ce conține un identificator unic pentru această placă. Valoarea este citită din hardware-ul MCU-ului (de obicei numărul de serie al dispozitivului programat din fabrică), deci este stabilă între reporniri și diferă de la o placă la alta.

Lungimea depinde de familia MCU-ului – 12 octeți pe STM32, 8 octeți pe porturile mimxrt și alif. Dacă aplicația dvs. are nevoie de un ID de lungime fixă, secționați sau aplicați hash valorii returnate.

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

Măsoară lățimea unui singur impuls pe pin și returnează durata acestuia în microsecunde.

pin trebuie configurat ca intrare digitală.

pulse_level este polaritatea impulsului care urmează să fie cronometrat: 1 pentru un impuls la nivel ridicat, 0 pentru un impuls la nivel coborât.

Funcția lucrează în două faze. Mai întâi, dacă pinul nu se află deja la pulse_level, așteaptă ca pinul să treacă la pulse_level (începutul impulsului). Apoi măsoară timpul cât pinul rămâne la pulse_level înainte de a reveni (sfârșitul impulsului). Timpul măsurat este returnat în microsecunde.

timeout_us limitează fiecare fază independent (astfel încât un apel în cel mai rău caz durează până la 2 * timeout_us). La timeout, funcția returnează o valoare negativă care identifică ce fază a expirat:

• -2 – a expirat în așteptarea muchiei ascendente (pinul nu a atins niciodată pulse_level).

• -1 – a expirat în așteptarea muchiei descendente (impulsul a fost mai lung decât timeout_us).

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

Transmite data prin bit-banging pe pin-ul specificat. Argumentul encoding specifică modul în care sunt codificați biții, iar timing este o specificație de temporizare specifică codificării.

Codificările acceptate sunt:

• 0 pentru modulația duratei impulsului „high low”. Aceasta va transmite biții 0 și 1 ca impulsuri cronometrate, începând cu cel mai semnificativ bit. timing trebuie să fie un tuplu cu patru elemente de nanosecunde în formatul (high_time_0, low_time_0, high_time_1, low_time_1). De exemplu, (400, 850, 800, 450) este specificația de temporizare pentru LED-urile RGB WS2812 la 800kHz.

Acuratețea temporizării depinde de hardware; MCU-urile mai rapide produc impulsuri mai precise (de obicei zeci de nanosecunde).

Notă

Pentru controlul benzilor WS2812 / NeoPixel, vezi modulul neopixel pentru un API de nivel superior.

Constante

Constantele de mai jos sunt returnate de reset_cause() și identifică motivul ultimei resetări a MCU-ului. Disponibile pe porturile STM32 și mimxrt; portul alif (OpenMV Cam AE3) nu expune în prezent constante pentru cauza resetării, iar reset_cause() al său returnează întotdeauna 0.

machine.PWRON_RESET: int

Resetare cauzată de aplicarea alimentării la cip. Porturile STM32 și mimxrt.

machine.WDT_RESET: int

Resetare cauzată de expirarea temporizatorului de supraveghere (watchdog). Porturile STM32 și mimxrt.

machine.SOFT_RESET: int

Resetare cauzată de soft_reset() (interpretorul Python a repornit fără o resetare hardware). Porturile STM32 și mimxrt.

machine.HARD_RESET: int

Resetare cauzată de asertarea pinului NRST (buton extern de resetare). Doar porturile STM32.

machine.DEEPSLEEP_RESET: int

Resetare cauzată de trezirea din deep-sleep. Doar porturile STM32.

Clase

• clasa Pin – controlul pinilor de I/O
• class Signal – controlează și detectează dispozitive I/O externe
• clasa LED – control portabil al LED-ului de pe placă
• clasa ADC – conversie analog-digitală
• clasa PWM – modulație în lățimea impulsului
• clasa UART – magistrală de comunicație serială duplex
• class SPI – un protocol de magistrală Serial Peripheral Interface (partea de controler)
• class SoftSPI – magistrală SPI emulată software
• clasa I2C – un protocol serial cu două fire
• clasa SoftI2C – magistrală I2C emulată software
• clasa I2CTarget – un dispozitiv țintă I2C
• clasa I2S – protocolul magistralei de sunet Inter-IC
• clasa CAN – protocolul Controller Area Network
• clasa RTC – ceas în timp real
• class Timer – temporizator virtual periodic / cu o singură declanșare
• clasa WDT – temporizator de supraveghere (watchdog)
• class SDCard – driver pentru carduri SD / MMC
• clasa Counter – numărător de impulsuri
• clasa Encoder – decodor în cuadratură