machine — funções relacionadas ao hardware

O módulo machine contém funções específicas relacionadas ao hardware de uma placa em particular. A maioria das funções deste módulo permite obter acesso e controle diretos e irrestritos a blocos de hardware de um sistema (como CPU, timers, barramentos, etc.).

Acesso à memória

O módulo expõe três objetos indexáveis usados para acesso bruto à memória. Cada um se comporta como um array esparso indexado por endereço de byte: value = memN[addr] lê, memN[addr] = value escreve. O endereço é sempre um endereço de byte, independentemente da largura de acesso.

machine.mem8

Acessador de memória de 8 bits indexável. mem8[addr] lê um int no intervalo 0-255 a partir do byte em addr; mem8[addr] = value escreve os 8 bits inferiores de value. addr deve estar alinhado em 1 byte (qualquer endereço).

machine.mem16

Acessador de memória de 16 bits (halfword) indexável. mem16[addr] lê um int no intervalo 0-65535; mem16[addr] = value escreve os 16 bits inferiores. addr deve estar alinhado em 2 bytes.

machine.mem32

Acessador de memória de 32 bits (word) indexável. mem32[addr] lê um int no intervalo 0-0xFFFFFFFF; mem32[addr] = value escreve os 32 bits inferiores. addr deve estar alinhado em 4 bytes.

Exemplo de uso (os registradores são específicos de um microcontrolador STM32H7 – nas OpenMV Cam H7 / H7 Plus / Pure Thermal, o pino P0 do header está ligado 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

Funções relacionadas a reset

machine.reset() → None

Faz o hard reset do dispositivo de maneira semelhante a pressionar o botão RESET externo.

machine.soft_reset() → None

Realiza um soft reset do interpretador, apagando todos os objetos Python e reinicializando o heap do Python.

machine.reset_cause() → int

Obtém a causa do reset. Veja as constantes para os possíveis valores de retorno.

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

Reinicia a câmera em seu bootloader de DFU / download serial, pronta para ser regravada com um novo firmware. Esta chamada nunca retorna; a placa reinicia diretamente no bootloader.

O argumento value é aceito para compatibilidade entre portas, mas é ignorado em todas as placas suportadas pela OpenMV.

Funções relacionadas a interrupções

As funções a seguir permitem o controle sobre interrupções. Alguns sistemas exigem interrupções para operar corretamente, de modo que desabilitá-las por longos períodos pode comprometer funcionalidades essenciais; por exemplo, watchdog timers podem disparar inesperadamente. As interrupções só devem ser desabilitadas pela menor quantidade de tempo possível e, em seguida, reabilitadas ao seu estado anterior. Por exemplo:

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

Desabilita as solicitações de interrupção. Retorna o estado anterior do IRQ, que deve ser considerado um valor opaco. Esse valor de retorno deve ser passado para a função enable_irq() para restaurar as interrupções ao seu estado original, anterior à chamada de disable_irq().

machine.enable_irq(state: int) → None

Reabilita as solicitações de interrupção. O parâmetro state deve ser o valor que foi retornado pela chamada mais recente à função disable_irq().

Funções relacionadas a energia

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

Retorna as frequências de clock do MCU.

Nas portas STM32 (todas as OpenMV Cam M4/M7/H7/H7+/PT/N6 e as variantes da marca Arduino), o valor de retorno é uma tupla dos clocks internos em Hz. No STM32N6 (OpenMV Cam N6), a tupla é (CPUCLK, SYSCLK, HCLK, PCLK1, PCLK2, PCLK4, PCLK5); nas demais câmeras STM32, é (SYSCLK, HCLK, PCLK1, PCLK2).

Na porta mimxrt (OpenMV Cam RT1062) e na porta alif (OpenMV Cam AE3), o valor de retorno é um único inteiro – a frequência da CPU em Hz.

Chamar freq(hz) para definir o clock levanta NotImplementedError em todas as placas suportadas pela OpenMV.

machine.idle() → None

Bloqueia o clock da CPU, útil para reduzir o consumo de energia a qualquer momento, durante períodos curtos ou longos. Os periféricos continuam funcionando e a execução é retomada assim que qualquer interrupção for disparada, ou no máximo um milissegundo após a CPU ter sido pausada.

Recomenda-se chamar esta função dentro de qualquer loop apertado que esteja verificando continuamente uma mudança externa (ou seja, polling). Isso reduzirá o consumo de energia sem impactar significativamente o desempenho. Para reduzir ainda mais o consumo de energia, veja as funções lightsleep(), time.sleep() e time.sleep_ms().

machine.sleep() → None

Nota

Esta função está obsoleta; use lightsleep() sem argumentos.

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

Interrompe a execução e entra em um estado de baixo consumo de energia com retenção total da RAM e dos periféricos. O clock do MCU é bloqueado; quando a função retorna, a execução é retomada a partir do ponto em que lightsleep() foi chamada, com todos os subsistemas ainda operacionais.

Se time_ms for especificado, ele é a duração máxima do sleep em milissegundos. Com ou sem timeout, a execução pode ser retomada antecipadamente se qualquer fonte de wake configurada for disparada (uma IRQ de Pin, um alarme de RTC, uma interrupção de periférico habilitada, …). As fontes de wake devem ser configuradas antes da chamada.

A economia de energia é mais modesta do que a de deepsleep(), mas o wake-up é instantâneo e nenhum estado é perdido.

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

Interrompe a execução e entra no estado de mais baixo consumo de energia disponível. O conteúdo da RAM, o estado dos periféricos e as conexões de rede podem ser todos perdidos. Quando o MCU acorda, ele inicializa a partir do começo do script principal, de forma semelhante a um power-on ou hard reset; reset_cause() então retornará DEEPSLEEP_RESET, para que o script possa distinguir um wake de deepsleep de outras causas de reset.

Se time_ms for especificado, o MCU agenda um wake-up após essa quantidade de milissegundos (ou antes, se outra fonte de wake configurada disparar primeiro). Não passe nada para dormir até que uma fonte de wake externa seja disparada.

Esta chamada nunca retorna – trate a execução retomada no início do script principal, condicionada a reset_cause().

Funções diversas

machine.unique_id() → bytes

Retorna um objeto bytes contendo um identificador único para esta placa. O valor é lido do hardware do MCU (tipicamente o número de série do dispositivo programado de fábrica), de modo que é estável entre reinicializações e difere de uma placa para outra.

O comprimento depende da família do MCU – 12 bytes no STM32, 8 bytes nas portas mimxrt e alif. Se sua aplicação precisar de um ID de comprimento fixo, faça o slice ou o hash do valor retornado.

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

Mede a largura de um único pulso em pin e retorna sua duração em microssegundos.

pin deve estar configurado como uma entrada digital.

pulse_level é a polaridade do pulso a ser medida: 1 para um pulso alto, 0 para um pulso baixo.

A função funciona em duas fases. Primeiro, se o pino ainda não estiver em pulse_level, ela aguarda o pino fazer a transição para pulse_level (o início do pulso). Em seguida, ela mede o tempo em que o pino permanece em pulse_level antes de fazer a transição de volta (o fim do pulso). O tempo medido é retornado em microssegundos.

timeout_us limita cada fase de forma independente (de modo que, no pior caso, a chamada dura até 2 * timeout_us). Em caso de timeout, a função retorna um valor negativo identificando qual fase atingiu o timeout:

• -2 – timeout aguardando a borda de subida (o pino nunca atingiu pulse_level).

• -1 – timeout aguardando a borda de descida (o pulso foi mais longo do que timeout_us).

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

Transmite data fazendo bit-banging no pin especificado. O argumento encoding especifica como os bits são codificados, e timing é uma especificação de temporização específica da codificação.

As codificações suportadas são:

• 0 para modulação por duração de pulso “high low”. Isso transmitirá os bits 0 e 1 como pulsos temporizados, começando pelo bit mais significativo. O timing deve ser uma tupla de quatro valores em nanossegundos no formato (high_time_0, low_time_0, high_time_1, low_time_1). Por exemplo, (400, 850, 800, 450) é a especificação de temporização para LEDs RGB WS2812 a 800kHz.

A precisão da temporização depende do hardware; MCUs mais rápidos produzem pulsos mais precisos (tipicamente dezenas de nanossegundos).

Nota

Para controlar fitas WS2812 / NeoPixel, veja o módulo neopixel para uma API de nível mais alto.

Constantes

As constantes abaixo são retornadas por reset_cause() e identificam por que o MCU foi resetado pela última vez. Disponíveis nas portas STM32 e mimxrt; a porta alif (OpenMV Cam AE3) atualmente não expõe constantes de causa de reset, e seu reset_cause() sempre retorna 0.

machine.PWRON_RESET: int

Reset causado pela aplicação de energia ao chip. Portas STM32 e mimxrt.

machine.WDT_RESET: int

Reset causado pela expiração do watchdog timer. Portas STM32 e mimxrt.

machine.SOFT_RESET: int

Reset causado por soft_reset() (o interpretador Python reiniciou sem um reset de hardware). Portas STM32 e mimxrt.

machine.HARD_RESET: int

Reset causado pela ativação do pino NRST (botão de reset externo). Apenas portas STM32.

machine.DEEPSLEEP_RESET: int

Reset causado pelo wake do deep-sleep. Apenas portas STM32.

Classes

• classe Pin – controla pinos de E/S
• classe Signal – controlar e detectar dispositivos de E/S externos
• classe LED – controle portátil do LED embutido na placa
• classe ADC – conversão analógico-digital
• classe PWM – modulação por largura de pulso
• classe UART – barramento de comunicação serial duplex
• classe SPI – um protocolo de barramento Serial Peripheral Interface (lado do controlador)
• classe SoftSPI – barramento SPI emulado por software
• classe I2C – um protocolo serial de dois fios
• classe SoftI2C – barramento I2C emulado por software
• classe I2CTarget – um dispositivo alvo I2C
• classe I2S – protocolo de barramento Inter-IC Sound
• classe CAN – protocolo Controller Area Network
• classe RTC – relógio de tempo real
• classe Timer – timer virtual periódico / de disparo único
• classe WDT – watchdog timer
• classe SDCard – driver de cartão SD / MMC
• classe Counter – contador de pulsos
• classe Encoder – decodificador de quadratura