classe SDCard – controlador de cartão SD / MMC¶

A classe SDCard controla a ranhura de cartão SD / MMC nas câmaras OpenMV que a possuem. O controlador implementa a interface vfs.AbstractBlockDev, pelo que pode ser passado diretamente a vfs.mount()

import machine
import vfs

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

Nota

O firmware OpenMV monta automaticamente o cartão SD no arranque, pelo que a maioria dos scripts nunca cria um SDCard diretamente – limitam-se a ler e escrever através do caminho de montagem automática. Crie um manualmente apenas quando precisar de um ponto de montagem diferente do predefinido ou de acesso direto a blocos através de readblocks() / writeblocks() / ioctl().

Na OpenMV Cam M7 / H7 / H7 Plus / Pure Thermal / N6, a ranhura é controlada pelo controlador SDMMC integrado do STM32 em modo SD de 4 bits. Na OpenMV Cam RT1062, a ranhura é controlada pelo controlador USDHC do i.MX RT, também em modo SD de 4 bits. Nenhuma placa OpenMV atual requer argumentos de mux de pinos – o controlador já conhece a ligação da placa.

Não disponível na OpenMV Cam AE3 (porto alif).

Construtores¶

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

Devolve o singleton SDCard para a ranhura SD identificada por id. O argumento id é aceite por compatibilidade entre portos, mas os portos suportados pela OpenMV expõem apenas uma ranhura; passe 1 ou omita-o.

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

Métodos¶

present() → bool¶

Devolve True se um cartão estiver atualmente detetado na ranhura, False caso contrário.

Nas placas que ligam um sinal de deteção de cartão, o método reflete esse sinal em tempo real, pelo que pode ser consultado após a criação do objeto SDCard para reagir a inserção / remoção a quente. Nas placas sem sinal de deteção de cartão, o valor fica fixo no momento da criação – reporta o resultado da sondagem CMD0 inicial efetuada pelo controlador quando o objeto foi criado, e um cartão inserido a quente depois disso não será visível até o objeto ser recriado (ou até ser chamado init() no mimxrt).

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

Devolve um tuplo de 3 elementos que descreve 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 calcular num_blocks * block_size de forma portável.

[2] card_type – o tipo de cartão reportado pelo barramento SD durante o protocolo de inicialização CMD8 / OCR. Os valores típicos são 0 (SDSC – capacidade padrão), 0x40 (SDHC / SDXC – alta / capacidade expandida) e 0x80 (MMC).

Útil para verificar que o cartão foi reconhecido, ou para apresentar valores de espaço livre relativamente à capacidade total.

power(state: bool, /) → None¶: Liga ou desliga o circuito de alimentação da ranhura do cartão. O firmware STM32 expõe o método, mas nenhuma OpenMV Cam atual controla a alimentação do cartão SD, pelo que a chamada é efetivamente uma operação vazia. Mantido por compatibilidade com código originalmente escrito para as placas de referência STM32 do MicroPython. Apenas no porto STM32.

read(block_num: int, /) → bytes¶

Lê um único bloco de 512 bytes do cartão e devolve-o como um novo objeto bytes.

Trata-se da leitura legada de bloco único fornecida pelo porto STM32. O novo código deve usar readblocks() – esse método funciona em todos os portos OpenMV, pode ler qualquer número de blocos contíguos numa única transferência e evita a alocação por chamada ao escrever num buffer fornecido pelo chamador. Apenas no porto STM32.

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

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

Trata-se da escrita legada de bloco único fornecida pelo porto STM32; o novo código deve usar writeblocks(), que funciona em todos os portos OpenMV e pode escrever qualquer número de blocos contíguos por chamada. Apenas no porto STM32.

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

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

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

Forma simples (readblocks(block_num, buf)): lê blocos completos a partir do índice de bloco block_num. len(buf) deve ser um múltiplo do tamanho do bloco SD (512 bytes).

Forma estendida (readblocks(block_num, buf, offset)): lê len(buf) bytes – não necessariamente um número inteiro de blocos – a partir do byte offset dentro do bloco block_num. Utilizado pelo littlefs e outros sistemas de ficheiros 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 por bloco de buf no cartão. Ponto de entrada padrão de dispositivo de blocos vfs.AbstractBlockDev utilizado pela camada de sistema de ficheiros.

Forma simples (writeblocks(block_num, buf)): escreve blocos completos a partir do índice de bloco block_num. len(buf) deve ser um múltiplo do tamanho do bloco SD (512 bytes). Cada bloco afetado é substituído na totalidade.

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

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

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

1 – inicializar. Devolve 0 em caso de sucesso.

2 – desinicializar. Devolve 0 em caso de sucesso.

3 – sincronizar escritas pendentes. Devolve 0 (o controlador SDMMC escreve de forma síncrona, nada a descarregar).

4 – devolver o número de blocos no dispositivo.

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

6 – apagar um bloco (operação vazia em SD, mantido para cumprir o contrato vfs.AbstractBlockDev).

7 – devolver se o dispositivo suporta apagamento de blocos (0 em SD).

Os chamadores diretos normalmente não utilizam este método – o controlador do sistema de ficheiros despacha todos os códigos padrão automaticamente após a montagem do SDCard.

init(*args, **kwargs) → None¶: Reinicializa a interface SD de raiz. Aceita os mesmos argumentos que o construtor. Útil para redetetar um cartão inserido a quente em placas sem sinal de deteção de cartão, uma vez que present() fica de outra forma fixo no momento da criação. Apenas no porto mimxrt.

deinit() → None¶: Desinicializa a interface SD, libertando o controlador SDMMC/USDHC e os pinos de IO que este reclamou. O objeto SDCard fica inutilizável até que init() seja chamado novamente. Use-o antes de reprogramar o cartão a partir de outra interface, ou para cortar a alimentação da ranhura numa aplicação a bateria. Apenas no porto mimxrt.