machine — funciones relacionadas con el hardware

El módulo machine contiene funciones específicas relacionadas con el hardware de una placa en particular. La mayoría de las funciones de este módulo permiten lograr un acceso y control directos y sin restricciones de los bloques de hardware de un sistema (como la CPU, los temporizadores, los buses, etc.).

Acceso a memoria

El módulo expone tres objetos suscriptables que se usan para el acceso a memoria sin procesar. Cada uno se comporta como un array disperso indexado por dirección de byte: value = memN[addr] lee, memN[addr] = value escribe. La dirección es siempre una dirección de byte, independientemente del ancho de acceso.

machine.mem8

Accesor de memoria suscriptable de 8 bits. mem8[addr] lee un int en el rango 0-255 del byte en addr; mem8[addr] = value escribe los 8 bits bajos de value. addr debe estar alineado a 1 byte (cualquier dirección).

machine.mem16

Accesor de memoria suscriptable de 16 bits (media palabra). mem16[addr] lee un int en el rango 0-65535; mem16[addr] = value escribe los 16 bits bajos. addr debe estar alineado a 2 bytes.

machine.mem32

Accesor de memoria suscriptable de 32 bits (palabra). mem32[addr] lee un int en el rango 0-0xFFFFFFFF; mem32[addr] = value escribe los 32 bits bajos. addr debe estar alineado a 4 bytes.

Ejemplo de uso (los registros son específicos de un microcontrolador STM32H7 – en la OpenMV Cam H7 / H7 Plus / Pure Thermal el pin de cabecera P0 está conectado 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

Funciones relacionadas con el reinicio

machine.reset() → None

Reinicia por hardware el dispositivo de forma similar a pulsar el botón externo RESET.

machine.soft_reset() → None

Realiza un reinicio por software del intérprete, eliminando todos los objetos de Python y reiniciando el montículo de Python.

machine.reset_cause() → int

Obtiene la causa del reinicio. Consulta las constantes para conocer los posibles valores de retorno.

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

Reinicia la cámara en su gestor de arranque (bootloader) de DFU / descarga serie, lista para ser reprogramada con nuevo firmware. Esta llamada nunca regresa; la placa se reinicia directamente en el gestor de arranque (bootloader).

El argumento value se acepta por compatibilidad entre puertos, pero se ignora en todas las placas compatibles con OpenMV.

Funciones relacionadas con interrupciones

Las siguientes funciones permiten controlar las interrupciones. Algunos sistemas requieren interrupciones para funcionar correctamente, por lo que deshabilitarlas durante largos periodos puede comprometer la funcionalidad básica; por ejemplo, los temporizadores de vigilancia (watchdog) pueden dispararse de forma inesperada. Las interrupciones solo deben deshabilitarse durante el mínimo tiempo posible y luego volver a habilitarse a su estado anterior. Por ejemplo:

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

Deshabilita las solicitudes de interrupción. Devuelve el estado de IRQ anterior, que debe considerarse un valor opaco. Este valor de retorno debe pasarse a la función enable_irq() para restaurar las interrupciones a su estado original, anterior a la llamada a disable_irq().

machine.enable_irq(state: int) → None

Vuelve a habilitar las solicitudes de interrupción. El parámetro state debe ser el valor devuelto por la llamada más reciente a la función disable_irq().

Funciones relacionadas con la energía

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

Devuelve las frecuencias de reloj del MCU.

En los puertos STM32 (todas las OpenMV Cam M4/M7/H7/H7+/PT/N6 y las variantes de marca Arduino) el valor de retorno es una tupla de los relojes internos en Hz. En la STM32N6 (OpenMV Cam N6) la tupla es (CPUCLK, SYSCLK, HCLK, PCLK1, PCLK2, PCLK4, PCLK5); en las demás cámaras STM32 es (SYSCLK, HCLK, PCLK1, PCLK2).

En el puerto mimxrt (OpenMV Cam RT1062) y en el puerto alif (OpenMV Cam AE3) el valor de retorno es un único entero – la frecuencia de la CPU en Hz.

Llamar a freq(hz) para fijar el reloj lanza NotImplementedError en todas las placas compatibles con OpenMV.

machine.idle() → None

Cierra el reloj de la CPU, útil para reducir el consumo de energía en cualquier momento durante periodos cortos o largos. Los periféricos siguen funcionando y la ejecución se reanuda en cuanto se dispara cualquier interrupción, o como máximo un milisegundo después de que la CPU se haya pausado.

Se recomienda llamar a esta función dentro de cualquier bucle estrecho que esté comprobando continuamente un cambio externo (es decir, sondeo). Esto reducirá el consumo de energía sin afectar significativamente al rendimiento. Para reducir aún más el consumo de energía, consulta las funciones lightsleep(), time.sleep() y time.sleep_ms().

machine.sleep() → None

Nota

Esta función está obsoleta, usa lightsleep() en su lugar sin argumentos.

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

Detiene la ejecución y entra en un estado de bajo consumo con retención total de la RAM y los periféricos. El reloj del MCU se cierra; cuando la función regresa, la ejecución se reanuda desde el punto en que se llamó a lightsleep() con todos los subsistemas todavía operativos.

Si se especifica time_ms, es la duración máxima de la suspensión en milisegundos. Con o sin tiempo de espera, la ejecución puede reanudarse antes si se dispara cualquier fuente de despertar configurada (una IRQ de Pin, una alarma de RTC, una interrupción de periférico habilitada, …). Las fuentes de despertar deben configurarse antes de la llamada.

El ahorro de energía es más modesto que el de deepsleep(), pero el despertar es instantáneo y no se pierde ningún estado.

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

Detiene la ejecución y entra en el estado de bajo consumo más profundo disponible. El contenido de la RAM, el estado de los periféricos y las conexiones de red pueden perderse por completo. Cuando el MCU despierta, arranca desde el inicio del script principal, de forma similar a un encendido o un reinicio por hardware; reset_cause() devolverá entonces DEEPSLEEP_RESET para que el script pueda distinguir un despertar desde deepsleep de otras causas de reinicio.

Si se especifica time_ms, el MCU programa un despertar después de esa cantidad de milisegundos (o antes, si otra fuente de despertar configurada se dispara primero). No pases nada para dormir hasta que se dispare una fuente de despertar externa.

Esta llamada nunca regresa – gestiona la ejecución reanudada al principio del script principal, condicionada a reset_cause().

Funciones varias

machine.unique_id() → bytes

Devuelve un objeto bytes que contiene un identificador único de esta placa. El valor se lee del hardware del MCU (normalmente el número de serie del dispositivo programado de fábrica), por lo que es estable entre reinicios y difiere de una placa a otra.

La longitud depende de la familia del MCU – 12 bytes en STM32, 8 bytes en los puertos mimxrt y alif. Si tu aplicación necesita un ID de longitud fija, corta o aplica un hash al valor devuelto.

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

Mide el ancho de un único pulso en pin y devuelve su duración en microsegundos.

pin debe estar configurado como una entrada digital.

pulse_level es la polaridad del pulso a medir: 1 para un pulso alto, 0 para un pulso bajo.

La función funciona en dos fases. Primero, si el pin no está ya en pulse_level, espera a que el pin pase a pulse_level (el inicio del pulso). Luego mide el tiempo que el pin permanece en pulse_level antes de volver a cambiar (el final del pulso). El tiempo medido se devuelve en microsegundos.

timeout_us limita cada fase de forma independiente (de modo que una llamada en el peor de los casos dura hasta 2 * timeout_us). Si se agota el tiempo de espera, la función devuelve un valor negativo que identifica qué fase agotó su tiempo:

• -2 – se agotó el tiempo esperando el flanco de subida (el pin nunca alcanzó pulse_level).

• -1 – se agotó el tiempo esperando el flanco de bajada (el pulso fue más largo que timeout_us).

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

Transmite data mediante bit-banging en el pin especificado. El argumento encoding especifica cómo se codifican los bits, y timing es una especificación de temporización específica de la codificación.

Las codificaciones admitidas son:

• 0 para la modulación de duración de pulso «alto bajo». Esto transmitirá los bits 0 y 1 como pulsos temporizados, empezando por el bit más significativo. El timing debe ser una tupla de cuatro nanosegundos con el formato (high_time_0, low_time_0, high_time_1, low_time_1). Por ejemplo, (400, 850, 800, 450) es la especificación de temporización para los LED RGB WS2812 a 800kHz.

La precisión de la temporización depende del hardware; los MCU más rápidos producen pulsos más ajustados (normalmente decenas de nanosegundos).

Nota

Para controlar tiras WS2812 / NeoPixel, consulta el módulo neopixel para una API de más alto nivel.

Constantes

Las constantes siguientes son devueltas por reset_cause() e identifican por qué se reinició el MCU por última vez. Disponibles en los puertos STM32 y mimxrt; el puerto alif (OpenMV Cam AE3) no expone actualmente constantes de causa de reinicio y su reset_cause() siempre devuelve 0.

machine.PWRON_RESET: int

Reinicio causado por la aplicación de alimentación al chip. Puertos STM32 y mimxrt.

machine.WDT_RESET: int

Reinicio causado por la expiración del temporizador de vigilancia (watchdog). Puertos STM32 y mimxrt.

machine.SOFT_RESET: int

Reinicio causado por soft_reset() (el intérprete de Python se reinició sin un reinicio por hardware). Puertos STM32 y mimxrt.

machine.HARD_RESET: int

Reinicio causado por la activación del pin NRST (botón de reinicio externo). Solo puertos STM32.

machine.DEEPSLEEP_RESET: int

Reinicio causado por el despertar desde deep-sleep. Solo puertos STM32.

Clases

• clase Pin – control de pines de E/S
• class Signal – controlar y detectar dispositivos de E/S externos
• clase LED – control portátil del LED integrado en la placa
• clase ADC – conversión de analógico a digital
• clase PWM – modulación por ancho de pulso
• clase UART – bus de comunicación serie dúplex
• class SPI – un protocolo de bus de interfaz periférica serie (lado del controlador)
• class SoftSPI – bus SPI emulado por software
• clase I2C – un protocolo serie de dos hilos
• clase SoftI2C – bus I2C emulado por software
• clase I2CTarget – un dispositivo target de I2C
• clase I2S – protocolo de bus Inter-IC Sound
• clase CAN – protocolo Controller Area Network
• clase RTC – reloj de tiempo real
• class Timer – temporizador virtual periódico / de un solo disparo
• clase WDT – temporizador de vigilancia (watchdog)
• class SDCard – controlador de tarjetas SD / MMC
• clase Counter – contador de pulsos
• clase Encoder – decodificador de cuadratura