machine — fonctions liées au matériel

Le module machine contient des fonctions spécifiques liées au matériel d’une carte particulière. La plupart des fonctions de ce module permettent d’obtenir un accès direct et non restreint au contrôle des blocs matériels d’un système (comme le CPU, les minuteurs, les bus, etc.).

Accès mémoire

Le module expose trois objets indexables utilisés pour l’accès mémoire brut. Chacun se comporte comme un tableau creux indexé par adresse d’octet : value = memN[addr] lit, memN[addr] = value écrit. L’adresse est toujours une adresse d’octet, quelle que soit la largeur d’accès.

machine.mem8

Accesseur mémoire 8 bits indexable. mem8[addr] lit un int dans la plage 0-255 depuis l’octet à addr ; mem8[addr] = value écrit les 8 bits de poids faible de value. addr doit être aligné sur 1 octet (toute adresse).

machine.mem16

Accesseur mémoire 16 bits (demi-mot) indexable. mem16[addr] lit un int dans la plage 0-65535 ; mem16[addr] = value écrit les 16 bits de poids faible. addr doit être aligné sur 2 octets.

machine.mem32

Accesseur mémoire 32 bits (mot) indexable. mem32[addr] lit un int dans la plage 0-0xFFFFFFFF ; mem32[addr] = value écrit les 32 bits de poids faible. addr doit être aligné sur 4 octets.

Exemple d’utilisation (les registres sont spécifiques à un microcontrôleur STM32H7 – sur l’OpenMV Cam H7 / H7 Plus / Pure Thermal, la broche d’en-tête P0 est câblée à 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

Fonctions liées à la réinitialisation

machine.reset() → None

Effectue une réinitialisation matérielle de l’appareil d’une manière similaire à un appui sur le bouton RESET externe.

machine.soft_reset() → None

Effectue une réinitialisation logicielle de l’interpréteur, en supprimant tous les objets Python et en réinitialisant le tas Python.

machine.reset_cause() → int

Obtient la cause de la réinitialisation. Voir les constantes pour les valeurs de retour possibles.

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

Réinitialise la caméra dans son programme d’amorçage DFU / téléchargement série, prête à être reprogrammée avec un nouveau micrologiciel. Cet appel ne retourne jamais ; la carte redémarre directement dans le programme d’amorçage.

L’argument value est accepté pour des raisons de compatibilité entre ports mais est ignoré sur toutes les cartes prises en charge par OpenMV.

Fonctions liées aux interruptions

Les fonctions suivantes permettent de contrôler les interruptions. Certains systèmes nécessitent que les interruptions fonctionnent correctement, aussi les désactiver pendant de longues périodes peut compromettre des fonctionnalités essentielles, par exemple les minuteurs de surveillance peuvent se déclencher de façon inattendue. Les interruptions ne devraient être désactivées que pendant une durée minimale, puis réactivées à leur état précédent. Par exemple

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

Désactive les requêtes d’interruption. Renvoie l’état IRQ précédent qui doit être considéré comme une valeur opaque. Cette valeur de retour doit être passée à la fonction enable_irq() pour restaurer les interruptions à leur état d’origine, avant l’appel à disable_irq().

machine.enable_irq(state: int) → None

Réactive les requêtes d’interruption. Le paramètre state doit être la valeur renvoyée par le plus récent appel à la fonction disable_irq().

Fonctions liées à l’alimentation

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

Renvoie les fréquences d’horloge du MCU.

Sur les ports STM32 (toutes les OpenMV Cam M4/M7/H7/H7+/PT/N6 et les variantes de marque Arduino), la valeur de retour est un tuple des horloges internes en Hz. Sur le STM32N6 (OpenMV Cam N6), le tuple est (CPUCLK, SYSCLK, HCLK, PCLK1, PCLK2, PCLK4, PCLK5) ; sur les autres caméras STM32, il s’agit de (SYSCLK, HCLK, PCLK1, PCLK2).

Sur le port mimxrt (OpenMV Cam RT1062) et le port alif (OpenMV Cam AE3), la valeur de retour est un entier unique – la fréquence CPU en Hz.

Appeler freq(hz) pour régler l’horloge lève NotImplementedError sur toutes les cartes prises en charge par OpenMV.

machine.idle() → None

Coupe l’horloge du CPU, utile pour réduire la consommation d’énergie à tout moment, pendant des périodes courtes ou longues. Les périphériques continuent de fonctionner et l’exécution reprend dès qu’une interruption est déclenchée, ou au plus tard une milliseconde après la mise en pause du CPU.

Il est recommandé d’appeler cette fonction à l’intérieur de toute boucle serrée qui vérifie continuellement un changement externe (c.-à-d. par interrogation). Cela réduira la consommation d’énergie sans impacter significativement les performances. Pour réduire davantage la consommation d’énergie, voir les fonctions lightsleep(), time.sleep() et time.sleep_ms().

machine.sleep() → None

Note

Cette fonction est obsolète, utilisez plutôt lightsleep() sans argument.

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

Arrête l’exécution et entre dans un état de faible consommation avec rétention complète de la RAM et des périphériques. L’horloge du MCU est coupée ; lorsque la fonction retourne, l’exécution reprend à partir du point où lightsleep() a été appelé, avec tous les sous-systèmes toujours opérationnels.

Si time_ms est spécifié, il s’agit de la durée de sommeil maximale en millisecondes. Avec ou sans délai d’expiration, l’exécution peut reprendre plus tôt si une source de réveil configurée se déclenche (une IRQ de Pin, une alarme RTC, une interruption de périphérique activée, …). Les sources de réveil doivent être configurées avant l’appel.

L’économie d’énergie est plus modeste qu’avec deepsleep() mais le réveil est instantané et aucun état n’est perdu.

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

Arrête l’exécution et entre dans l’état de plus faible consommation disponible. Le contenu de la RAM, l’état des périphériques et les connexions réseau peuvent tous être perdus. Lorsque le MCU se réveille, il démarre depuis le début du script principal, comme lors d’une mise sous tension ou d’une réinitialisation matérielle ; reset_cause() renverra alors DEEPSLEEP_RESET afin que le script puisse distinguer un réveil de deepsleep des autres causes de réinitialisation.

Si time_ms est spécifié, le MCU planifie un réveil après ce nombre de millisecondes (ou plus tôt, si une autre source de réveil configurée se déclenche en premier). Ne passez rien pour dormir jusqu’à ce qu’une source de réveil externe se déclenche.

Cet appel ne retourne jamais – gérez la reprise de l’exécution en haut du script principal, conditionnée par reset_cause().

Fonctions diverses

machine.unique_id() → bytes

Renvoie un objet bytes contenant un identifiant unique pour cette carte. La valeur est lue depuis le matériel du MCU (généralement le numéro de série de l’appareil programmé en usine), elle est donc stable d’un redémarrage à l’autre et diffère d’une carte à l’autre.

La longueur dépend de la famille de MCU – 12 octets sur STM32, 8 octets sur les ports mimxrt et alif. Si votre application a besoin d’un ID de longueur fixe, découpez ou hachez la valeur renvoyée.

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

Mesure la largeur d’une seule impulsion sur pin et renvoie sa durée en microsecondes.

pin doit être configurée comme entrée numérique.

pulse_level est la polarité de l’impulsion à chronométrer : 1 pour une impulsion haute, 0 pour une impulsion basse.

La fonction fonctionne en deux phases. D’abord, si la broche n’est pas déjà à pulse_level, elle attend que la broche passe à pulse_level (le début de l’impulsion). Ensuite, elle mesure le temps pendant lequel la broche reste à pulse_level avant de revenir (la fin de l’impulsion). Le temps mesuré est renvoyé en microsecondes.

timeout_us borne chaque phase indépendamment (de sorte qu’un appel dans le pire des cas dure jusqu’à 2 * timeout_us). En cas d’expiration du délai, la fonction renvoie une valeur négative identifiant quelle phase a expiré :

• -2 – expiration en attendant le front montant (la broche n’a jamais atteint pulse_level).

• -1 – expiration en attendant le front descendant (l’impulsion était plus longue que timeout_us).

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

Transmet data en bit-banging sur la pin spécifiée. L’argument encoding spécifie comment les bits sont encodés, et timing est une spécification de chronométrage propre à l’encodage.

Les encodages pris en charge sont :

• 0 pour la modulation de durée d’impulsion « haut bas ». Cela transmettra les bits 0 et 1 sous forme d’impulsions chronométrées, en commençant par le bit de poids fort. Le timing doit être un quadruplet de nanosecondes au format (high_time_0, low_time_0, high_time_1, low_time_1). Par exemple, (400, 850, 800, 450) est la spécification de chronométrage pour les LED RGB WS2812 à 800kHz.

La précision du chronométrage dépend du matériel ; les MCU plus rapides produisent des impulsions plus précises (généralement des dizaines de nanosecondes).

Note

Pour contrôler les bandeaux WS2812 / NeoPixel, voir le module neopixel pour une API de plus haut niveau.

Constantes

Les constantes ci-dessous sont renvoyées par reset_cause() et identifient pourquoi le MCU s’est réinitialisé pour la dernière fois. Disponibles sur les ports STM32 et mimxrt ; le port alif (OpenMV Cam AE3) n’expose pas actuellement les constantes de cause de réinitialisation et son reset_cause() renvoie toujours 0.

machine.PWRON_RESET: int

Réinitialisation causée par la mise sous tension de la puce. Ports STM32 et mimxrt.

machine.WDT_RESET: int

Réinitialisation causée par l’expiration du minuteur de surveillance. Ports STM32 et mimxrt.

machine.SOFT_RESET: int

Réinitialisation causée par soft_reset() (l’interpréteur Python a redémarré sans réinitialisation matérielle). Ports STM32 et mimxrt.

machine.HARD_RESET: int

Réinitialisation causée par l’assertion de la broche NRST (bouton de réinitialisation externe). Ports STM32 uniquement.

machine.DEEPSLEEP_RESET: int

Réinitialisation causée par le réveil après un sommeil profond. Ports STM32 uniquement.

Classes

• classe Pin – contrôle des broches d’E/S
• class Signal – contrôler et détecter des périphériques d’E/S externes
• classe LED – contrôle portable des LED embarquées
• classe ADC – conversion analogique-numérique
• classe PWM – modulation de largeur d’impulsion
• classe UART – bus de communication série bidirectionnel
• class SPI – un protocole de bus Serial Peripheral Interface (côté contrôleur)
• class SoftSPI – bus SPI émulé de manière logicielle
• class I2C – un protocole série à deux fils
• class SoftI2C – bus I2C émulé par logiciel
• class I2CTarget – un périphérique cible I2C
• classe I2S – protocole de bus Inter-IC Sound
• classe CAN – protocole Controller Area Network
• classe RTC – horloge en temps réel
• class Timer – minuteur virtuel périodique / à coup unique
• classe WDT – minuteur de surveillance (watchdog)
• class SDCard – pilote de carte SD / MMC
• classe Counter – compteur d’impulsions
• classe Encoder – décodeur en quadrature