class SDCard – driver per schede SD / MMC

La classe SDCard gestisce lo slot per schede SD / MMC presente sulle camere OpenMV che ne dispongono. Il driver implementa l’interfaccia vfs.AbstractBlockDev, quindi può essere passato direttamente a vfs.mount()

import machine
import vfs

sd = machine.SDCard()
vfs.mount(sd, "/sd")

Nota

Il firmware OpenMV monta automaticamente la scheda SD all’avvio, perciò la maggior parte degli script non costruisce mai direttamente un oggetto SDCard – si limita a leggere e scrivere attraverso il percorso montato automaticamente. Costruiscine uno manualmente solo quando hai bisogno di un punto di montaggio non predefinito o dell’accesso grezzo a livello di blocco tramite readblocks() / writeblocks() / ioctl().

Sulle OpenMV Cam M7 / H7 / H7 Plus / Pure Thermal / N6 lo slot è gestito dal controller SDMMC integrato nell’STM32 in modalità SD a 4 bit. Sulla OpenMV Cam RT1062 lo slot è gestito dal controller USDHC dell’i.MX RT, anch’esso in modalità SD a 4 bit. Su nessuna scheda OpenMV attuale sono necessari argomenti di pin-mux – il driver conosce il cablaggio della scheda.

Non disponibile sulla OpenMV Cam AE3 (porta alif).

Costruttori

class machine.SDCard(id: int = 1) → SDCard

Restituisce il singleton SDCard per lo slot SD identificato da id. id è accettato per compatibilità tra le varie porte, ma le porte supportate da OpenMV espongono un solo slot; passa 1 oppure ometti l’argomento.

Su STM32 il costruttore non accetta alcun argomento; su mimxrt l’argomento id è accettato ma solo 1 è valido.

Metodi

present() → bool

Restituisce True se attualmente è rilevata una scheda nello slot, altrimenti False.

Sulle schede che cablano un segnale di rilevamento scheda (card-detect) il metodo riflette tale segnale in tempo reale, quindi può essere interrogato dopo la costruzione dell’oggetto SDCard per reagire all’inserimento / rimozione a caldo. Sulle schede prive di un segnale di card-detect il valore viene memorizzato (latched) al momento della costruzione – riporta il risultato della sonda CMD0 iniziale eseguita dal driver alla creazione dell’oggetto, e una scheda inserita a caldo successivamente non sarà visibile finché l’oggetto non viene ricostruito (oppure non viene chiamato init() su mimxrt).

info() → tuple[int, int, int]

Restituisce una tupla di 3 elementi che descrive la scheda attualmente inserita:

  • [0] num_blocks – capacità totale in blocchi da 512 byte. Moltiplica per 512 per ottenere la capacità grezza in byte.

  • [1] block_size – sempre 512 per le schede SD. Incluso così i chiamanti possono calcolare num_blocks * block_size in modo portabile.

  • [2] card_type – il tipo di scheda riportato dal bus SD durante l’handshake di inizializzazione CMD8 / OCR. I valori tipici sono 0 (SDSC – capacità standard), 0x40 (SDHC / SDXC – capacità alta / estesa) e 0x80 (MMC).

Utile per verificare che la scheda sia stata riconosciuta, oppure per mostrare le cifre dello spazio libero rispetto alla capacità totale.

power(state: bool, /) → None

Accende o spegne la linea di alimentazione dello slot per schede. Il firmware STM32 espone il metodo, ma nessuna OpenMV Cam attuale controlla l’alimentazione della SD, quindi la chiamata è di fatto una no-op. Mantenuto per compatibilità con il codice scritto originariamente per le schede di riferimento STM32 dell’upstream MicroPython. Solo porta STM32.

read(block_num: int, /) → bytes

Legge un singolo blocco da 512 byte dalla scheda e lo restituisce come un nuovo oggetto bytes appena allocato.

Questa è la lettura legacy a blocco singolo fornita dalla porta STM32. Il nuovo codice dovrebbe usare invece readblocks() – quel metodo funziona su ogni porta OpenMV, può leggere un numero qualsiasi di blocchi contigui in un unico trasferimento ed evita l’allocazione a ogni chiamata scrivendo in un buffer fornito dal chiamante. Solo porta STM32.

write(block_num: int, data: bytes, /) → None

Scrive un singolo blocco da 512 byte sulla scheda. data deve essere lungo esattamente 512 byte.

Questa è la scrittura legacy a blocco singolo fornita dalla porta STM32; il nuovo codice dovrebbe usare invece writeblocks(), che funziona su ogni porta OpenMV e può scrivere un numero qualsiasi di blocchi contigui per chiamata. Solo porta STM32.

readblocks(block_num: int, buf: bytearray) → None
readblocks(block_num: int, buf: bytearray, offset: int) → None

Legge dati grezzi allineati ai blocchi dalla scheda in buf. Punto di ingresso standard del dispositivo a blocchi vfs.AbstractBlockDev usato dal livello del filesystem.

Forma semplice (readblocks(block_num, buf)): legge blocchi interi a partire dall’indice di blocco block_num. len(buf) deve essere un multiplo della dimensione del blocco SD (512 byte).

Forma estesa (readblocks(block_num, buf, offset)): legge len(buf) byte – non necessariamente un numero intero di blocchi – a partire dal byte offset all’interno del blocco block_num. Usata da littlefs e da altri filesystem indirizzabili a byte.

writeblocks(block_num: int, buf: bytes | bytearray) → None
writeblocks(block_num: int, buf: bytes | bytearray, offset: int) → None

Scrive dati grezzi allineati ai blocchi da buf sulla scheda. Punto di ingresso standard del dispositivo a blocchi vfs.AbstractBlockDev usato dal livello del filesystem.

Forma semplice (writeblocks(block_num, buf)): scrive blocchi interi a partire dall’indice di blocco block_num. len(buf) deve essere un multiplo della dimensione del blocco SD (512 byte). Ogni blocco interessato viene sovrascritto per intero.

Forma estesa (writeblocks(block_num, buf, offset)): scrive len(buf) byte – non necessariamente un numero intero di blocchi – a partire dal byte offset all’interno del blocco block_num. Usata da littlefs e da altri filesystem indirizzabili a byte.

ioctl(cmd: int, arg: int) → int | None

Punto di ingresso di controllo standard di vfs.AbstractBlockDev. Chiamato dal livello del filesystem al momento del montaggio/smontaggio e a ogni sincronizzazione. I valori cmd riconosciuti sono:

  • 1 – inizializza. Restituisce 0 in caso di successo.

  • 2 – deinizializza. Restituisce 0 in caso di successo.

  • 3 – sincronizza eventuali scritture in sospeso. Restituisce 0 (il driver SDMMC scrive in modo sincrono, non c’è nulla da scaricare).

  • 4 – restituisce il numero di blocchi sul dispositivo.

  • 5 – restituisce la dimensione di un singolo blocco (sempre 512).

  • 6 – cancella un blocco (no-op su SD, mantenuto per il contratto di vfs.AbstractBlockDev).

  • 7 – restituisce se il dispositivo supporta la cancellazione dei blocchi (0 su SD).

Normalmente i chiamanti diretti non usano questo metodo – il driver del filesystem invia automaticamente tutti i codici standard una volta che la SDCard è montata.

init(*args, **kwargs) → None

Reinizializza l’interfaccia SD da zero. Accetta gli stessi argomenti del costruttore. Utile per rilevare nuovamente una scheda inserita a caldo sulle schede prive di un segnale di card-detect, dato che altrimenti present() viene memorizzato (latched) al momento della costruzione. Solo porta mimxrt.

deinit() → None

Deinizializza l’interfaccia SD, rilasciando il controller SDMMC/USDHC e i pin IO che aveva occupato. L’oggetto SDCard diventa inutilizzabile finché non viene richiamato init(). Usalo prima di riprogrammare la scheda da un’altra interfaccia, oppure per togliere l’alimentazione allo slot in un’applicazione alimentata a batteria. Solo porta mimxrt.