pyb — funzioni relative alla scheda

Avvertimento

Il modulo pyb è deprecato. Per il nuovo codice usa il modulo cross-port machine – offre le stesse funzionalità su ogni OpenMV Cam indipendentemente dalla famiglia di MCU, mentre pyb esiste solo sulle schede basate su STM32. pyb è mantenuto per compatibilità con gli script più vecchi, non verranno aggiunte nuove funzionalità e potrebbe essere rimosso in una versione futura.

Il modulo pyb contiene funzioni specifiche per STM32 relative alla scheda.

Funzioni relative al tempo

pyb.delay(ms: int) → None

Attende per il numero di millisecondi indicato.

pyb.udelay(us: int) → None

Attende per il numero di microsecondi indicato.

pyb.millis() → int

Restituisce il numero di millisecondi trascorsi dall’ultimo reset della scheda.

Il risultato è sempre uno smallint di MicroPython (numero con segno a 31 bit), quindi dopo 2^30 millisecondi (circa 12,4 giorni) inizierà a restituire numeri negativi.

Nota che se viene invocato pyb.stop() il contatore hardware che supporta questa funzione si fermerà per la durata dello stato di «sleep». Questo influirà sul risultato di pyb.elapsed_millis().

pyb.micros() → int

Restituisce il numero di microsecondi trascorsi dall’ultimo reset della scheda.

Il risultato è sempre uno smallint di MicroPython (numero con segno a 31 bit), quindi dopo 2^30 microsecondi (circa 17,8 minuti) inizierà a restituire numeri negativi.

Nota che se viene invocato pyb.stop() il contatore hardware che supporta questa funzione si fermerà per la durata dello stato di «sleep». Questo influirà sul risultato di pyb.elapsed_micros().

pyb.elapsed_millis(start: int) → int

Restituisce il numero di millisecondi trascorsi da start.

Questa funzione gestisce il wrap del contatore e restituisce sempre un numero positivo. Questo significa che può essere usata per misurare periodi fino a circa 12,4 giorni.

Esempio:

start = pyb.millis()
while pyb.elapsed_millis(start) < 1000:
    # Perform some operation

pyb.elapsed_micros(start: int) → int

Restituisce il numero di microsecondi trascorsi da start.

Questa funzione gestisce il wrap del contatore e restituisce sempre un numero positivo. Questo significa che può essere usata per misurare periodi fino a circa 17,8 minuti.

Esempio:

start = pyb.micros()
while pyb.elapsed_micros(start) < 1000:
    # Perform some operation
    pass

Funzioni relative al reset

pyb.hard_reset() → None

Reimposta l’OpenMV Cam in modo simile alla pressione del pulsante RESET esterno.

pyb.bootloader() → None

Effettua il reset nel bootloader USB DFU integrato di OpenMV, pronto per un aggiornamento del firmware. Questo è il modo consigliato per invocare DFU dal codice in esecuzione – non è necessario asserire alcun pin BOOT durante il reset.

Non disponibile sull’OpenMV Cam N6 (il livello di compatibilità legacy pyb è disabilitato su quella scheda); usa invece machine.bootloader().

pyb.fault_debug(value: bool) → None

Abilita o disabilita il debug degli hard-fault. Un hard-fault si verifica quando c’è un errore fatale nel sistema sottostante, come un accesso non valido alla memoria.

Se l’argomento value è False allora la scheda eseguirà automaticamente il reset in caso di hard fault.

Se value è True allora, quando la scheda subisce un hard fault, stamperà i registri e la stack trace, e poi farà lampeggiare i LED all’infinito.

Il valore predefinito è disabilitato, ovvero il reset automatico.

Funzioni relative agli interrupt

pyb.disable_irq() → bool

Disabilita le richieste di interrupt. Restituisce lo stato precedente delle IRQ: False/True rispettivamente per IRQ disabilitate/abilitate. Questo valore di ritorno può essere passato a enable_irq per ripristinare le IRQ al loro stato originale.

pyb.enable_irq(state: bool = True) → None

Abilita le richieste di interrupt. Se state è True (il valore predefinito) allora le IRQ sono abilitate. Se state è False allora le IRQ sono disabilitate. L’uso più comune di questa funzione è passarle il valore restituito da disable_irq per uscire da una sezione critica.

pyb.freq(sysclk: int | None = None, hclk: int | None = None, pclk1: int | None = None, pclk2: int | None = None) → Tuple[int, int, int, int] | None

Se chiamata senza argomenti, restituisce una tupla di frequenze di clock (sysclk, hclk, pclk1, pclk2) in hertz:

Campo	Significato
sysclk	Frequenza della CPU
hclk	Frequenza del bus AHB, della memoria core e del DMA
pclk1	Frequenza del bus APB1
pclk2	Frequenza del bus APB2

Se chiamata con qualsiasi argomento, la funzione imposta la frequenza della CPU (e le frequenze dei bus se vengono forniti argomenti aggiuntivi). Le frequenze sono in hertz; viene selezionata la frequenza supportata più alta non superiore al valore indicato. L’insieme delle frequenze sysclk valide e i valori massimi di hclk / pclk1 / pclk2 dipendono dall’MCU – fai riferimento al relativo manuale di riferimento STM32 dell’OpenMV Cam in uso. Le frequenze dei bus sono derivate da sysclk tramite prescaler che il driver sceglie per corrispondere al meglio ai valori richiesti.

Avvertimento

Cambiare la frequenza mentre l’USB è abilitato può rendere l’USB inaffidabile. Modificala da boot.py, prima che la periferica USB venga avviata, e non selezionare un valore di sysclk troppo basso per i requisiti di clock USB dell’MCU.

Funzioni relative all’alimentazione

pyb.wfi() → None

Attende un interrupt interno o esterno.

Questo esegue un’istruzione wfi che riduce il consumo energetico dell’MCU finché non si verifica un interrupt qualsiasi (interno o esterno), momento in cui l’esecuzione continua. Nota che l’interrupt del system-tick si verifica una volta ogni millisecondo (1000Hz), quindi questa funzione si bloccherà per al massimo 1ms.

pyb.stop() → None

Mette l’OpenMV Cam nello stato a basso consumo stop di STM32. L’esecuzione continua da questo punto al risveglio. Il risveglio richiede un interrupt esterno o un evento del real-time clock; vedi pyb.RTC.wakeup() per configurarne uno. L’assorbimento di corrente effettivamente ottenibile dipende dalla scheda e da quali periferiche restano alimentate dal clock.

pyb.standby() → None

Mette l’OpenMV Cam nello stato di deep-sleep standby di STM32. Questo è il livello di spegnimento a consumo più basso; il dispositivo esce tramite un hard reset al risveglio, quindi l’esecuzione non riprende dal punto in cui era. Il risveglio richiede un evento del real-time clock; vedi pyb.RTC.wakeup() per configurarne uno. L’assorbimento di corrente effettivamente ottenibile dipende dalla scheda.

Funzioni varie

pyb.have_cdc() → bool

Restituisce True se l’USB è connesso come dispositivo seriale, False altrimenti.

Nota

Questa funzione è deprecata. Usa invece pyb.USB_VCP().isconnected().

pyb.hid(data: Tuple[int, int, int, int]) → None

Prende una tupla di 4 elementi (o una lista) e la invia all’host USB (il PC) per segnalare un evento di movimento del mouse HID.

Nota

Questa funzione è deprecata. Usa invece pyb.USB_HID.send().

pyb.info(dump_alloc_table: bool | None = None) → None

Stampa molte informazioni sulla scheda.

pyb.main(filename: str) → None

Imposta il nome del file dello script principale da eseguire dopo che boot.py ha terminato. Se questa funzione non viene chiamata, verrà eseguito il file predefinito main.py.

Ha senso chiamare questa funzione solo dall’interno di boot.py.

pyb.mount(device: Any, mountpoint: str, *, readonly: bool = False, mkfs: bool = False) → None

Nota

Questa funzione è deprecata. Usa invece vfs.mount() / vfs.umount() e un dispositivo a blocchi derivato da vfs.AbstractBlockDev.

Monta un dispositivo a blocchi sotto mountpoint. device deve implementare il protocollo legacy dei dispositivi a blocchi di pyb (anch’esso deprecato – vedi vfs.AbstractBlockDev per l’interfaccia moderna):

Metodo	Scopo
readblocks(self, blocknum, buf)	Copia buf byte dal dispositivo a partire dal blocco blocknum. La lunghezza di buf è un multiplo di 512.
writeblocks(self, blocknum, buf) (opzionale)	Scrive buf sul dispositivo a partire dal blocco blocknum. Se omesso, il dispositivo viene montato in sola lettura.
count(self)	Restituisce il numero di blocchi da 512 byte presenti sul dispositivo.
sync(self) (opzionale)	Scarica eventuali scritture in cache.

mountpoint è il percorso nella radice del filesystem in cui montare il dispositivo; deve iniziare con una barra. readonly forza un montaggio in sola lettura. mkfs crea un nuovo filesystem se non ne è presente alcuno.

pyb.repl_uart(uart: UART | None = None) → UART | None

Ottiene o imposta l’oggetto UART su cui viene replicato il REPL.

pyb.rng() → int

Restituisce un numero casuale generato dall’hardware a 30 bit.

pyb.sync() → None

Sincronizza tutti i filesystem.

pyb.unique_id() → bytes

Restituisce una stringa di 12 byte (96 bit), che è l’ID univoco dell’MCU.

pyb.usb_mode(modestr: str | None = None, port: int = -1, vid: int = 0xf055, pid: int = -1, msc: Tuple = (), hid: Tuple = pyb.hid_mouse, high_speed: bool = False) → str | None

Se chiamata senza argomenti, restituisce la modalità USB corrente come stringa.

Se chiamata con modestr fornito, tenta di configurare la modalità USB. Sono riconosciuti i seguenti valori di modestr:

modestr	Configura
None	Disabilita l’USB.
'VCP'	Solo VCP (Virtual COM Port).
'MSC'	Solo MSC (USB mass storage class).
'VCP+MSC'	VCP e MSC.
'VCP+HID'	VCP e HID (human interface device).
'VCP+MSC+HID'	VCP, MSC e HID insieme. Non supportato su ogni OpenMV Cam.

Per compatibilità con il passato, 'CDC' viene interpretato come 'VCP' (e analogamente per 'CDC+MSC' e 'CDC+HID').

Il parametro port deve essere un intero (0, 1, …) e seleziona quale porta USB usare se la scheda supporta più porte. Un valore di -1 usa la porta predefinita o selezionata automaticamente.

I parametri vid e pid permettono di specificare il VID (vendor id) e il PID (product id). Un valore di pid pari a -1 selezionerà un PID in base al valore di modestr.

Se si abilita la modalità MSC, il parametro msc può essere usato per specificare una lista di LUN SCSI da esporre sull’interfaccia di mass storage. Per esempio msc=(pyb.Flash(), pyb.SDCard()).

Se si abilita la modalità HID, è possibile specificare anche i dettagli HID passando il parametro keyword hid. Prende una tupla di (subclass, protocol, max packet length, polling interval, report descriptor). Per impostazione predefinita imposterà valori appropriati per un mouse USB. Esiste anche una costante pyb.hid_keyboard, che è una tupla appropriata per una tastiera USB.

Il parametro high_speed, quando impostato a True, abilita la modalità USB HS se supportata dall’hardware.

Costanti

Entrambe le costanti seguenti sono tuple di 5 elementi già pronte nella forma

(subclass, protocol, max_packet_size, polling_interval_ms, report_descriptor)

adatte a essere passate come argomento hid di usb_mode() per far apparire l’OpenMV Cam all’host come dispositivo USB HID. subclass = 1 significa «boot interface» e protocol seleziona la classe del dispositivo boot (1 = tastiera, 2 = mouse). Il quinto elemento è un oggetto bytes che contiene il report descriptor HID usato quando l’host enumera il dispositivo.

pyb.hid_mouse: tuple

Report descriptor HID predefinito per un boot mouse a 3 pulsanti con movimento relativo X/Y. La tupla è (1, 2, 4, 8, <mouse report descriptor>): boot subclass, protocollo mouse, report di input di 4 byte (maschera dei pulsanti + X + Y + rotellina), interrogati ogni 8 ms. Il report descriptor integrato è quello usato da pyb.USB_HID().send((buttons, dx, dy, wheel)).

pyb.hid_keyboard: tuple

Report descriptor HID predefinito per una boot keyboard USB. La tupla è (1, 1, 8, 8, <keyboard report descriptor>): boot subclass, protocollo tastiera, report di input di 8 byte (byte dei modificatori, un byte riservato, sei codici di tasto concorrenti), interrogati ogni 8 ms. Il report descriptor integrato corrisponde al layout standard della boot-keyboard HID a 8 byte, quindi il report inviato tramite USB_HID.send() deve essere un bytes della forma (modifiers, 0, key1, key2, key3, key4, key5, key6).

Classi

• class ADC – conversione analogico-digitale
• class ADCAll – accesso a tutti i canali ADC
• class CAN – bus di comunicazione controller area network
• classe DAC – conversione digitale-analogica
• classe ExtInt – configura i pin di I/O per generare interrupt su eventi esterni
• classe Flash – accesso alla memoria flash integrata
• classe I2C – un protocollo seriale a due fili
• classe LED – LED integrato
• class Pin – controllo dei pin di I/O
• class PinAF – funzioni alternative dei pin
• class RTC – orologio in tempo reale
• class Servo – driver per servo hobby a 3 fili
• class SPI – un protocollo seriale pilotato da un controller
• class Timer – controllo dei timer interni
• class TimerChannel – configurazione di un canale per un timer
• class UART – bus di comunicazione seriale duplex
• class USB_HID – USB Human Interface Device (HID)
• class USB_VCP – porta di comunicazione virtuale USB