classe SDCard – driver de cartão SD / MMC

A classe SDCard controla o slot de cartão SD / MMC nas câmeras OpenMV que possuem um. O driver implementa a interface vfs.AbstractBlockDev para que possa ser passado diretamente para vfs.mount()

import machine
import vfs

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

Nota

O firmware da OpenMV monta automaticamente o cartão SD na inicialização, então a maioria dos scripts nunca constrói um SDCard diretamente – eles apenas leem e escrevem através do caminho montado automaticamente. Construa um manualmente apenas quando você precisar de um ponto de montagem não padrão ou de acesso bruto em nível de bloco através de readblocks() / writeblocks() / ioctl().

Na OpenMV Cam M7 / H7 / H7 Plus / Pure Thermal / N6 o slot é controlado pelo controlador SDMMC integrado do STM32 em modo SD de 4 bits. Na OpenMV Cam RT1062 o slot é controlado pelo controlador USDHC do i.MX RT, também em modo SD de 4 bits. Nenhum argumento de pin-mux é necessário em qualquer placa OpenMV atual – o driver conhece o cabeamento da placa.

Não exposto na OpenMV Cam AE3 (porta alif).

Construtores

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

Retorna o singleton SDCard para o slot SD identificado por id. id é aceito por compatibilidade entre portas, mas as portas suportadas pela OpenMV expõem apenas um slot; passe 1 ou omita-o.

No STM32 o construtor não aceita nenhum argumento; no mimxrt o argumento id é aceito, mas apenas 1 é válido.

Métodos

present() → bool

Retorna True se um cartão estiver atualmente detectado no slot, False caso contrário.

Em placas que conectam um sinal de detecção de cartão, o método reflete esse sinal em tempo real, de modo que pode ser consultado periodicamente após o objeto SDCard ter sido construído para reagir à inserção / remoção a quente. Em placas sem sinal de detecção de cartão, o valor é fixado no momento da construção – ele relata o resultado da sondagem CMD0 inicial que o driver realizou quando o objeto foi criado, e um cartão inserido a quente posteriormente não será visível até que o objeto seja reconstruído (ou que init() seja chamado no mimxrt).

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

Retorna uma tupla de 3 elementos descrevendo o cartão atualmente inserido:

  • [0] num_blocks – capacidade total em blocos de 512 bytes. Multiplique por 512 para obter a capacidade bruta em bytes.

  • [1] block_size – sempre 512 para cartões SD. Incluído para que os chamadores possam fazer num_blocks * block_size de forma portável.

  • [2] card_type – o tipo de cartão relatado pelo barramento SD durante o handshake de inicialização CMD8 / OCR. Valores típicos são 0 (SDSC – capacidade padrão), 0x40 (SDHC / SDXC – capacidade alta / estendida) e 0x80 (MMC).

Útil para verificar se o cartão foi reconhecido, ou para exibir números de espaço livre em relação à capacidade total.

power(state: bool, /) → None

Liga ou desliga o trilho de alimentação do slot de cartão. O firmware do STM32 expõe o método, mas nenhuma OpenMV Cam atual controla a alimentação do SD, então a chamada é efetivamente um no-op. Mantido por compatibilidade com código originalmente escrito para as placas de referência STM32 do MicroPython upstream. Apenas na porta STM32.

read(block_num: int, /) → bytes

Lê um único bloco de 512 bytes do cartão e o retorna como um objeto bytes recém-alocado.

Esta é a leitura de bloco único legada fornecida pela porta STM32. Código novo deve usar readblocks() em seu lugar – esse método funciona em todas as portas OpenMV, pode ler qualquer número de blocos contíguos em uma única transferência e evita a alocação por chamada escrevendo em um buffer fornecido pelo chamador. Apenas na porta STM32.

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

Escreve um único bloco de 512 bytes no cartão. data deve ter exatamente 512 bytes de comprimento.

Esta é a escrita de bloco único legada fornecida pela porta STM32; código novo deve usar writeblocks() em seu lugar, que funciona em todas as portas OpenMV e pode escrever qualquer número de blocos contíguos por chamada. Apenas na porta STM32.

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

Lê dados brutos alinhados a blocos do cartão para buf. Ponto de entrada padrão de dispositivo de bloco vfs.AbstractBlockDev usado pela camada de sistema de arquivos.

Forma simples (readblocks(block_num, buf)): lê blocos inteiros começando no índice de bloco block_num. len(buf) deve ser um múltiplo do tamanho de bloco SD (512 bytes).

Forma estendida (readblocks(block_num, buf, offset)): lê len(buf) bytes – não necessariamente um número inteiro de blocos – começando no byte offset dentro do bloco block_num. Usada pelo littlefs e outros sistemas de arquivos endereçáveis por byte.

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

Escreve dados brutos alinhados a blocos de buf no cartão. Ponto de entrada padrão de dispositivo de bloco vfs.AbstractBlockDev usado pela camada de sistema de arquivos.

Forma simples (writeblocks(block_num, buf)): escreve blocos inteiros começando no índice de bloco block_num. len(buf) deve ser um múltiplo do tamanho de bloco SD (512 bytes). Cada bloco afetado é totalmente sobrescrito.

Forma estendida (writeblocks(block_num, buf, offset)): escreve len(buf) bytes – não necessariamente um número inteiro de blocos – começando no byte offset dentro do bloco block_num. Usada pelo littlefs e outros sistemas de arquivos endereçáveis por byte.

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

Ponto de entrada de controle padrão vfs.AbstractBlockDev. Chamado pela camada de sistema de arquivos no momento de montagem/desmontagem e em cada sincronização. Os valores de cmd reconhecidos são:

  • 1 – inicializar. Retorna 0 em caso de sucesso.

  • 2 – desinicializar. Retorna 0 em caso de sucesso.

  • 3 – sincronizar quaisquer escritas pendentes. Retorna 0 (o driver SDMMC escreve de forma síncrona, nada a descarregar).

  • 4 – retornar o número de blocos no dispositivo.

  • 5 – retornar o tamanho de um único bloco (sempre 512).

  • 6 – apagar um bloco (no-op no SD, mantido para o contrato vfs.AbstractBlockDev).

  • 7 – retornar se o dispositivo suporta apagamento de bloco (0 no SD).

Chamadores diretos normalmente não usam este método – o driver de sistema de arquivos despacha todos os códigos padrão automaticamente assim que o SDCard é montado.

init(*args, **kwargs) → None

Reinicializa a interface SD do zero. Aceita os mesmos argumentos que o construtor. Útil para re-detectar um cartão inserido a quente em placas sem sinal de detecção de cartão, já que present() é, de outro modo, fixado no momento da construção. Apenas na porta mimxrt.

deinit() → None

Desinicializa a interface SD, liberando o controlador SDMMC/USDHC e os pinos de IO que ele reservou. O objeto SDCard torna-se inutilizável até que init() seja chamado novamente. Use-o antes de regravar o cartão a partir de outra interface, ou para cortar a alimentação do slot em uma aplicação alimentada por bateria. Apenas na porta mimxrt.