machine — funções relacionadas com o hardware

O módulo machine contém funções específicas relacionadas com o hardware de uma determinada placa. A maioria das funções neste módulo permitem obter acesso directo e irrestrito e controlo dos blocos de hardware de um sistema (como CPU, temporizadores, buses, etc.).

Acesso à memória

O módulo expõe três objectos subscritos utilizados para acesso directo à memória. Cada um comporta-se 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

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

machine.mem16

Acessor de memória de 16 bits (meia palavra) subscritível. mem16[addr] lê um int no intervalo 0-65535; mem16[addr] = value escreve os 16 bits menos significativos. addr deve estar alinhado a 2 bytes.

machine.mem32

Acessor de memória de 32 bits (palavra) subscritível. mem32[addr] lê um int no intervalo 0-0xFFFFFFFF; mem32[addr] = value escreve os 32 bits menos significativos. addr deve estar alinhado a 4 bytes.

Exemplo de utilização (os registos são específicos de um microcontrolador STM32H7 – na OpenMV Cam H7 / H7 Plus / Pure Thermal, o pino do cabeçalho P0 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 com reset

machine.reset() → None

Faz o reset total do dispositivo de forma semelhante a pressionar o botão RESET externo.

machine.soft_reset() → None

Efectua um soft reset do interpretador, eliminando todos os objectos Python e reiniciando o heap Python.

machine.reset_cause() → int

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

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

Reinicia a câmara para o seu bootloader DFU / de descarga série, pronto para ser reprogramado com novo firmware. Esta chamada nunca retorna; a placa reinicia directamente para o bootloader.

O argumento value é aceite por compatibilidade entre ports, mas é ignorado em todas as placas suportadas pelo OpenMV.

Funções relacionadas com interrupções

As funções seguintes permitem controlar as interrupções. Alguns sistemas requerem interrupções para funcionar correctamente, pelo que desactivá-las por longos períodos pode comprometer funcionalidades essenciais; por exemplo, os temporizadores watchdog podem disparar inesperadamente. As interrupções devem ser desactivadas apenas pelo tempo mínimo necessário e depois reactivadas para o 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

Desactiva os pedidos de interrupção. Devolve o estado IRQ anterior, que deve ser considerado um valor opaco. Este valor de retorno deve ser passado à função enable_irq() para restaurar as interrupções ao seu estado original, antes de disable_irq() ter sido chamada.

machine.enable_irq(state: int) → None

Reactiva os pedidos de interrupção. O parâmetro state deve ser o valor devolvido pela chamada mais recente à função disable_irq().

Funções relacionadas com energia

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

Devolve as frequências de clock do MCU.

Nos ports STM32 (todas as OpenMV Cam M4/M7/H7/H7+/PT/N6 e as variantes de marca Arduino) o valor de retorno é um tuplo dos clocks internos em Hz. Na STM32N6 (OpenMV Cam N6) o tuplo é (CPUCLK, SYSCLK, HCLK, PCLK1, PCLK2, PCLK4, PCLK5); nas outras câmaras STM32 é (SYSCLK, HCLK, PCLK1, PCLK2).

No port mimxrt (OpenMV Cam RT1062) e no port 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 lança NotImplementedError em todas as placas suportadas pelo OpenMV.

machine.idle() → None

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

Recomenda-se chamar esta função dentro de qualquer ciclo apertado que esteja continuamente a verificar uma mudança externa (isto é, polling). Isto reduzirá o consumo de energia sem impactar significativamente o desempenho. Para reduzir ainda mais o consumo de energia, consulte as funções lightsleep(), time.sleep() e time.sleep_ms().

machine.sleep() → None

Nota

Esta função está descontinuada; utilize lightsleep() sem argumentos.

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

Para a execução e entra num estado de baixo consumo com total retenção de RAM e periféricos. O clock do MCU é desactivado; 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, é a duração máxima de suspensão em milissegundos. Com ou sem timeout, a execução pode ser retomada antecipadamente se qualquer fonte de activação configurada disparar (um IRQ de Pin, um alarme de RTC, uma interrupção de periférico activada, …). As fontes de activação devem ser configuradas antes da chamada.

A poupança de energia é mais modesta do que deepsleep() mas o acordar é instantâneo e não se perde nenhum estado.

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

Para a execução e entra no estado de baixo consumo mais profundo disponível. O conteúdo da RAM, o estado dos periféricos e as ligações de rede podem ser todos perdidos. Quando o MCU acorda, arranca desde o início do script principal, de forma semelhante a uma ligação à corrente ou reset total; reset_cause() devolverá então DEEPSLEEP_RESET para que o script possa distinguir um acordar de deepsleep de outras causas de reset.

Se time_ms for especificado, o MCU agenda um acordar após esse número de milissegundos (ou mais cedo, se outra fonte de activação configurada disparar primeiro). Passe nada para dormir até que uma fonte de activação externa accione.

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

Funções diversas

machine.unique_id() → bytes

Devolve um objecto 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), pelo que é estável entre reinicializações e difere de uma placa para outra.

O comprimento depende da família do MCU – 12 bytes em STM32, 8 bytes nos ports mimxrt e alif. Se a sua aplicação necessitar de um ID de comprimento fixo, corte ou faça hash do valor devolvido.

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

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

pin deve estar configurado como entrada digital.

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

A função funciona em duas fases. Primeiro, se o pino não estiver já em pulse_level, aguarda que o pino transite para pulse_level (o início do pulso). Depois mede o tempo que o pino permanece em pulse_level antes de transitar de volta (o fim do pulso). O tempo medido é devolvido em microssegundos.

timeout_us limita cada fase independentemente (pelo que uma chamada no pior caso dura até 2 * timeout_us). Em caso de timeout, a função devolve um valor negativo identificando qual a fase que expirou:

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

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

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

Transmite data por 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 de duração de pulso «alto baixo». Isto transmitirá os bits 0 e 1 como pulsos temporizados, começando pelo bit mais significativo. O timing deve ser um tuplo de quatro nanosegundos 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 nanosegundos).

Nota

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

Constantes

As constantes abaixo são devolvidas por reset_cause() e identificam o motivo do último reset do MCU. Disponíveis nos ports STM32 e mimxrt; o port alif (OpenMV Cam AE3) não expõe actualmente constantes de causa de reset e o seu reset_cause() devolve sempre 0.

machine.PWRON_RESET: int

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

machine.WDT_RESET: int

Reset causado pela expiração do temporizador watchdog. Ports STM32 e mimxrt.

machine.SOFT_RESET: int

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

machine.HARD_RESET: int

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

machine.DEEPSLEEP_RESET: int

Reset causado por acordar do deep-sleep. Apenas ports STM32.

Classes

• classe Pin – controlar pinos I/O
• classe Signal – controlo e leitura de dispositivos de E/S externos
• classe LED – controlo portátil do LED integrado
• classe ADC – conversão analógico-digital
• classe PWM – modulação por largura de pulso
• classe UART – bus de comunicação série duplex
• classe SPI – protocolo de barramento de interface periférica série (lado do controlador)
• classe SoftSPI – barramento SPI emulado por software
• classe I2C – um protocolo série 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 – temporizador virtual periódico / de disparo único
• classe WDT – temporizador watchdog
• classe SDCard – controlador de cartão SD / MMC
• classe Counter – contador de impulsos
• classe Encoder – descodificador em quadratura