machine — funzioni relative all’hardware

Il modulo machine contiene funzioni specifiche relative all’hardware di una particolare scheda. La maggior parte delle funzioni in questo modulo consente di ottenere accesso e controllo diretti e senza restrizioni dei blocchi hardware di un sistema (come CPU, timer, bus, ecc.).

Accesso alla memoria

Il modulo espone tre oggetti indicizzabili usati per l’accesso grezzo alla memoria. Ciascuno si comporta come un array sparso indicizzato per indirizzo di byte: value = memN[addr] legge, memN[addr] = value scrive. L’indirizzo è sempre un indirizzo di byte, indipendentemente dalla larghezza dell’accesso.

machine.mem8

Accessore di memoria indicizzabile a 8 bit. mem8[addr] legge un int nell’intervallo 0-255 dal byte all’indirizzo addr; mem8[addr] = value scrive gli 8 bit bassi di value. addr deve essere allineato a 1 byte (qualsiasi indirizzo).

machine.mem16

Accessore di memoria indicizzabile a 16 bit (halfword). mem16[addr] legge un int nell’intervallo 0-65535; mem16[addr] = value scrive i 16 bit bassi. addr deve essere allineato a 2 byte.

machine.mem32

Accessore di memoria indicizzabile a 32 bit (word). mem32[addr] legge un int nell’intervallo 0-0xFFFFFFFF; mem32[addr] = value scrive i 32 bit bassi. addr deve essere allineato a 4 byte.

Esempio di utilizzo (i registri sono specifici di un microcontrollore STM32H7 – sulla OpenMV Cam H7 / H7 Plus / Pure Thermal il pin dell’header P0 è collegato a 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

Funzioni relative al reset

machine.reset() → None

Esegue un hard reset del dispositivo in modo simile alla pressione del pulsante RESET esterno.

machine.soft_reset() → None

Esegue un soft reset dell’interprete, eliminando tutti gli oggetti Python e ripristinando l’heap di Python.

machine.reset_cause() → int

Ottiene la causa del reset. Vedere costanti per i possibili valori di ritorno.

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

Riavvia la camera nel suo bootloader DFU / serial-download, pronta per essere ri-flashata con un nuovo firmware. Questa chiamata non ritorna mai; la scheda si riavvia direttamente nel bootloader.

L’argomento value è accettato per compatibilità tra le porte ma viene ignorato su tutte le schede supportate da OpenMV.

Funzioni relative agli interrupt

Le seguenti funzioni consentono il controllo sugli interrupt. Alcuni sistemi richiedono interrupt per funzionare correttamente, quindi disabilitarli per lunghi periodi può compromettere le funzionalità di base; ad esempio i watchdog timer potrebbero scattare in modo inaspettato. Gli interrupt dovrebbero essere disabilitati solo per il tempo minimo necessario e poi riabilitati al loro stato precedente. Ad esempio:

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

Disabilita le richieste di interrupt. Restituisce lo stato IRQ precedente, che deve essere considerato un valore opaco. Questo valore di ritorno deve essere passato alla funzione enable_irq() per ripristinare gli interrupt al loro stato originale, prima che disable_irq() venisse chiamata.

machine.enable_irq(state: int) → None

Riabilita le richieste di interrupt. Il parametro state dovrebbe essere il valore restituito dalla chiamata più recente alla funzione disable_irq().

Funzioni relative all’alimentazione

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

Restituisce le frequenze di clock dell’MCU.

Sulle porte STM32 (ogni OpenMV Cam M4/M7/H7/H7+/PT/N6 e le varianti a marchio Arduino) il valore di ritorno è una tupla dei clock interni in Hz. Sullo STM32N6 (OpenMV Cam N6) la tupla è (CPUCLK, SYSCLK, HCLK, PCLK1, PCLK2, PCLK4, PCLK5); sulle altre camere STM32 è (SYSCLK, HCLK, PCLK1, PCLK2).

Sulla porta mimxrt (OpenMV Cam RT1062) e sulla porta alif (OpenMV Cam AE3) il valore di ritorno è un singolo intero – la frequenza della CPU in Hz.

Chiamare freq(hz) per impostare il clock solleva NotImplementedError su tutte le schede supportate da OpenMV.

machine.idle() → None

Interrompe il clock verso la CPU, utile per ridurre il consumo energetico in qualsiasi momento durante periodi brevi o lunghi. Le periferiche continuano a funzionare e l’esecuzione riprende non appena viene attivato un interrupt qualsiasi, o al massimo un millisecondo dopo che la CPU è stata messa in pausa.

Si consiglia di chiamare questa funzione all’interno di qualsiasi ciclo stretto che controlla continuamente una variazione esterna (cioè il polling). Questo ridurrà il consumo energetico senza impattare in modo significativo sulle prestazioni. Per ridurre ulteriormente il consumo energetico vedere le funzioni lightsleep(), time.sleep() e time.sleep_ms().

machine.sleep() → None

Nota

Questa funzione è deprecata, usare invece lightsleep() senza argomenti.

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

Interrompe l’esecuzione ed entra in uno stato a basso consumo con piena ritenzione di RAM e periferiche. Il clock dell’MCU viene interrotto; quando la funzione ritorna, l’esecuzione riprende dal punto in cui è stata chiamata lightsleep() con ogni sottosistema ancora operativo.

Se time_ms è specificato è la durata massima del sonno in millisecondi. Con o senza un timeout, l’esecuzione può riprendere in anticipo se scatta una qualsiasi sorgente di risveglio configurata (un IRQ di Pin, un allarme di RTC, un interrupt di periferica abilitato, …). Le sorgenti di risveglio devono essere impostate prima della chiamata.

Il risparmio energetico è più modesto rispetto a deepsleep() ma il risveglio è istantaneo e nessuno stato viene perso.

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

Interrompe l’esecuzione ed entra nello stato a basso consumo più profondo disponibile. Il contenuto della RAM, lo stato delle periferiche e le connessioni di rete potrebbero andare tutti persi. Quando l’MCU si risveglia, avvia il boot dall’inizio dello script principale, in modo simile a un’accensione o a un hard reset; reset_cause() restituirà quindi DEEPSLEEP_RESET in modo che lo script possa distinguere un risveglio da deepsleep da altre cause di reset.

Se time_ms è specificato l’MCU pianifica un risveglio dopo quel numero di millisecondi (o prima, se scatta prima un’altra sorgente di risveglio configurata). Non passare nulla per dormire fino a quando una sorgente di risveglio esterna non si attiva.

Questa chiamata non ritorna mai – gestire l’esecuzione ripresa all’inizio dello script principale, condizionandola a reset_cause().

Funzioni varie

machine.unique_id() → bytes

Restituisce un oggetto bytes contenente un identificatore univoco per questa scheda. Il valore viene letto dall’hardware dell’MCU (tipicamente il numero di serie del dispositivo programmato in fabbrica), quindi è stabile tra i riavvii e differisce da una scheda all’altra.

La lunghezza dipende dalla famiglia dell’MCU – 12 byte su STM32, 8 byte sulle porte mimxrt e alif. Se la tua applicazione necessita di un ID a lunghezza fissa, esegui lo slice o l’hash del valore restituito.

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

Misura la larghezza di un singolo impulso su pin e restituisce la sua durata in microsecondi.

pin deve essere configurato come input digitale.

pulse_level è la polarità dell’impulso da misurare: 1 per un impulso alto, 0 per un impulso basso.

La funzione lavora in due fasi. Prima, se il pin non è già a pulse_level, attende che il pin transiti a pulse_level (l’inizio dell’impulso). Poi misura il tempo in cui il pin rimane a pulse_level prima di tornare indietro (la fine dell’impulso). Il tempo misurato viene restituito in microsecondi.

timeout_us limita ciascuna fase in modo indipendente (quindi una chiamata nel caso peggiore dura fino a 2 * timeout_us). In caso di timeout la funzione restituisce un valore negativo che identifica quale fase è andata in timeout:

• -2 – timeout in attesa del fronte di salita (il pin non ha mai raggiunto pulse_level).

• -1 – timeout in attesa del fronte di discesa (l’impulso è stato più lungo di timeout_us).

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

Trasmette data tramite bit-banging sul pin specificato. L’argomento encoding specifica come vengono codificati i bit, e timing è una specifica di temporizzazione dipendente dalla codifica.

Le codifiche supportate sono:

• 0 per la modulazione della durata dell’impulso «high low». Questo trasmetterà i bit 0 e 1 come impulsi temporizzati, partendo dal bit più significativo. Il timing deve essere una quadrupla di nanosecondi nel formato (high_time_0, low_time_0, high_time_1, low_time_1). Ad esempio, (400, 850, 800, 450) è la specifica di temporizzazione per i LED RGB WS2812 a 800kHz.

L’accuratezza della temporizzazione dipende dall’hardware; gli MCU più veloci producono impulsi più precisi (tipicamente decine di nanosecondi).

Nota

Per il controllo delle strisce WS2812 / NeoPixel, vedere il modulo neopixel per un’API di livello superiore.

Costanti

Le costanti seguenti vengono restituite da reset_cause() e identificano il motivo per cui l’MCU si è resettato l’ultima volta. Disponibili sulle porte STM32 e mimxrt; la porta alif (OpenMV Cam AE3) attualmente non espone le costanti di causa del reset e il suo reset_cause() restituisce sempre 0.

machine.PWRON_RESET: int

Reset causato dall’applicazione dell’alimentazione al chip. Porte STM32 e mimxrt.

machine.WDT_RESET: int

Reset causato dalla scadenza del watchdog timer. Porte STM32 e mimxrt.

machine.SOFT_RESET: int

Reset causato da soft_reset() (l’interprete Python è stato riavviato senza un reset hardware). Porte STM32 e mimxrt.

machine.HARD_RESET: int

Reset causato dall’asserzione del pin NRST (pulsante di reset esterno). Solo porte STM32.

machine.DEEPSLEEP_RESET: int

Reset causato dal risveglio dal deep-sleep. Solo porte STM32.

Classi

• class Pin – controllo dei pin di I/O
• class Signal – controlla e rileva dispositivi di I/O esterni
• classe LED – controllo portabile dei LED on-board
• class ADC – conversione analogico-digitale
• classe PWM – modulazione di larghezza di impulso
• classe UART – bus di comunicazione seriale duplex
• class SPI – protocollo bus Serial Peripheral Interface (lato controller)
• class SoftSPI – bus SPI emulato via software
• class I2C – un protocollo seriale a due fili
• class SoftI2C – bus I2C emulato via software
• class I2CTarget – un dispositivo target I2C
• classe I2S – protocollo del bus Inter-IC Sound
• classe CAN – protocollo Controller Area Network
• class RTC – orologio in tempo reale
• class Timer – timer virtuale periodico / one-shot
• classe WDT – watchdog timer
• class SDCard – driver per schede SD / MMC
• class Counter – contatore di impulsi
• class Encoder – decodificatore in quadratura