`time` — fonctions liées au temps¶

Le module time fournit des fonctions permettant d’obtenir la date et l’heure actuelles, de mesurer des intervalles de temps et de réaliser des délais.

Époque de référence : les OpenMV Cam basées sur Alif et i.MX RT utilisent l’époque POSIX du 1970-01-01 00:00:00 UTC. Les OpenMV Cam basées sur STM32 utilisent une époque du 2000-01-01 00:00:00 UTC. L’année de référence peut être déterminée à l’exécution avec gmtime(0)[0].

Maintien de la date et de l’heure calendaires réelles : cela nécessite une horloge temps réel (RTC). Sur l’OpenMV Cam, l’heure système est fournie par l’objet machine.RTC. L’heure calendaire actuelle peut être réglée avec machine.RTC().datetime(tuple) et est maintenue par l’un des moyens suivants :

Une pile de sauvegarde (un composant facultatif sur certaines OpenMV Cam).
Un protocole de temps réseau tel que ntptime (nécessite une connexion réseau).
Un réglage manuel à chaque mise sous tension. La RTC est alors généralement maintenue lors des réinitialisations logicielles, mais est perdue en cas de coupure d’alimentation, sauf si une pile de sauvegarde est installée.

Si l’heure calendaire n’est pas maintenue, les fonctions ci-dessous qui font référence à l’heure absolue actuelle ne se comporteront pas comme prévu.

Fonctions¶

time.gmtime(secs: int | None = None) → Tuple[int, int, int, int, int, int, int, int]¶

time.localtime(secs: int | None = None) → Tuple[int, int, int, int, int, int, int, int]¶

Convertit le temps secs, exprimé en secondes depuis l’époque de référence (voir ci-dessus), en un 8-tuple contenant : (year, month, mday, hour, minute, second, weekday, yearday) Si secs n’est pas fourni ou vaut None, l’heure actuelle de la RTC est utilisée.

La fonction gmtime() renvoie un tuple date-heure en UTC, et localtime() renvoie un tuple date-heure en heure locale.

Le format des entrées du 8-tuple est le suivant :

year inclut le siècle (par exemple 2014).
month va de 1 à 12
mday va de 1 à 31
hour va de 0 à 23
minute va de 0 à 59
second va de 0 à 59
weekday va de 0 à 6 pour lundi à dimanche
yearday va de 1 à 366

time.mktime(date_time_tuple: Tuple[int, int, int, int, int, int, int, int]) → int¶: C’est la fonction inverse de localtime. Son argument est un 8-tuple complet exprimant un temps comme le fait localtime. Elle renvoie un entier correspondant au nombre de secondes écoulées depuis l’époque de référence.

time.sleep(seconds: float) → None¶

Met en pause pendant le nombre de secondes indiqué. seconds peut être un nombre à virgule flottante, afin de mettre en pause pendant une fraction de seconde. Pour des délais plus fins ou uniquement entiers, utilisez les fonctions sleep_ms() et sleep_us().

L’appel de sleep(), y compris sleep(0), garantit l’appel des fonctions de rappel en attente.

time.sleep_ms(ms: int) → None¶

Délai du nombre de millisecondes indiqué, qui doit être positif ou nul.

Cette fonction introduira un délai d’au moins le nombre de millisecondes indiqué, mais peut prendre plus de temps si d’autres traitements doivent avoir lieu, par exemple des gestionnaires d’interruption ou d’autres threads. Passer 0 pour ms permettra tout de même à ces autres traitements de s’exécuter. Utilisez sleep_us() pour des délais plus précis.

L’appel de sleep_ms(), y compris sleep_ms(0), garantit l’appel des fonctions de rappel en attente.

time.sleep_us(us: int) → None¶

Délai du nombre de microsecondes indiqué, qui doit être positif ou nul.

Cette fonction tente de fournir un délai précis d’au moins us microsecondes, mais peut prendre plus de temps si le système a d’autres traitements de priorité supérieure à effectuer.

time.ticks_ms() → int¶

Renvoie un compteur de millisecondes croissant ayant un point de référence arbitraire, qui repasse à zéro après une certaine valeur.

La valeur de bouclage n’est pas explicitement exposée, mais nous l’appellerons TICKS_MAX pour simplifier la discussion. La période des valeurs est TICKS_PERIOD = TICKS_MAX + 1. TICKS_PERIOD est garantie d’être une puissance de deux, mais peut par ailleurs varier d’un portage à l’autre. La même valeur de période est utilisée pour toutes les fonctions ticks_ms(), ticks_us() et ticks_cpu() (par souci de simplicité). Ainsi, ces fonctions renverront une valeur dans la plage [0 .. TICKS_MAX], incluse, soit au total TICKS_PERIOD valeurs. Notez que seules des valeurs non négatives sont utilisées. La plupart du temps, vous devriez considérer les valeurs renvoyées par ces fonctions comme opaques. Les seules opérations disponibles pour elles sont les fonctions ticks_diff() et ticks_add() décrites ci-dessous.

Remarque : effectuer des opérations mathématiques standard (+, -) ou utiliser des opérateurs relationnels (<, <=, >, >=) directement sur ces valeurs donnera un résultat invalide. Effectuer des opérations mathématiques puis passer leurs résultats comme arguments à ticks_diff() ou ticks_add() donnera également des résultats invalides en sortie de ces dernières fonctions.

time.ticks_us() → int¶: Comme ticks_ms() ci-dessus, mais en microsecondes.

time.ticks_cpu() → int¶: Semblable à ticks_ms() et ticks_us(), mais avec la résolution la plus élevée possible dans le système. Il s’agit généralement des cycles du CPU, d’où le nom de la fonction. Mais il ne s’agit pas nécessairement d’une horloge CPU ; une autre source de temps disponible dans un système (par exemple un minuteur haute résolution) peut être utilisée à la place. L’unité de temps exacte (résolution) de cette fonction n’est pas spécifiée au niveau du module time, mais la documentation d’un portage particulier peut fournir des informations plus précises. Cette fonction est destinée à des évaluations de performances très fines ou à des boucles temps réel très serrées. Évitez de l’utiliser dans du code portable. Elle est disponible sur toutes les OpenMV Cam.

time.ticks_add(ticks: int, delta: int) → int¶

Décale une valeur de ticks d’un nombre donné, qui peut être positif ou négatif. Étant donné une valeur ticks, cette fonction permet de calculer la valeur de ticks delta ticks avant ou après elle, en suivant la définition arithmétique modulaire des valeurs de ticks (voir ticks_ms() ci-dessus). Le paramètre ticks doit être le résultat direct d’un appel aux fonctions ticks_ms(), ticks_us() ou ticks_cpu() (ou d’un appel précédent à ticks_add()). En revanche, delta peut être un nombre entier arbitraire ou une expression numérique. ticks_add() est utile pour calculer des échéances d’événements ou de tâches. (Remarque : vous devez utiliser la fonction ticks_diff() pour travailler avec des échéances.)

Exemples

# Find out what ticks value there was 100ms ago
print(ticks_add(time.ticks_ms(), -100))

# Calculate deadline for operation and test for it
deadline = ticks_add(time.ticks_ms(), 200)
while ticks_diff(deadline, time.ticks_ms()) > 0:
    do_a_little_of_something()

# Find out TICKS_MAX used by this port
print(ticks_add(0, -1))

time.ticks_diff(ticks1: int, ticks2: int) → int¶

Mesure la différence de ticks entre les valeurs renvoyées par les fonctions ticks_ms(), ticks_us() ou ticks_cpu(), sous la forme d’une valeur signée pouvant déborder par bouclage.

L’ordre des arguments est le même que pour l’opérateur de soustraction : ticks_diff(ticks1, ticks2) a la même signification que ticks1 - ticks2. Cependant, les valeurs renvoyées par les fonctions ticks_ms(), etc. peuvent boucler, de sorte qu’utiliser directement la soustraction sur elles produira un résultat incorrect. C’est pourquoi ticks_diff() est nécessaire : elle implémente une arithmétique modulaire (ou plus précisément en anneau) afin de produire un résultat correct même pour des valeurs ayant bouclé (tant qu’elles ne sont pas trop éloignées l’une de l’autre, voir ci-dessous). La fonction renvoie une valeur signée dans la plage [-TICKS_PERIOD/2 .. TICKS_PERIOD/2-1] (c’est la définition typique de la plage des entiers binaires signés en complément à deux). Si le résultat est négatif, cela signifie que ticks1 s’est produit plus tôt dans le temps que ticks2. Sinon, cela signifie que ticks1 s’est produit après ticks2. Cela n’est vrai que si ticks1 et ticks2 sont distants l’un de l’autre d’au plus TICKS_PERIOD/2-1 ticks. Si cette condition n’est pas remplie, un résultat incorrect sera renvoyé. Plus précisément, si deux valeurs de ticks sont distantes de TICKS_PERIOD/2-1 ticks, c’est cette valeur que la fonction renverra. En revanche, si TICKS_PERIOD/2 ticks de temps réel se sont écoulés entre elles, la fonction renverra -TICKS_PERIOD/2 à la place, c’est-à-dire que la valeur du résultat bouclera vers la plage négative des valeurs possibles.

Justification informelle des contraintes ci-dessus : supposez que vous soyez enfermé dans une pièce sans aucun moyen de surveiller l’écoulement du temps, hormis une horloge standard à 12 graduations. Alors, si vous regardez le cadran maintenant, sans le regarder à nouveau pendant 13 heures (par exemple si vous tombez dans un long sommeil), il pourra vous sembler, en regardant enfin de nouveau, qu’une seule heure s’est écoulée. Pour éviter cette erreur, il suffit de regarder l’horloge régulièrement. Votre application doit faire de même. La métaphore du « sommeil trop long » s’applique aussi directement au comportement de l’application : ne laissez pas votre application exécuter une seule tâche trop longtemps. Exécutez les tâches par étapes et effectuez les relevés de temps entre elles.

ticks_diff() est conçue pour s’adapter à divers modèles d’utilisation, parmi lesquels :

L’interrogation périodique avec délai d’expiration. Dans ce cas, l’ordre des événements est connu et vous ne traiterez que des résultats positifs de ticks_diff()

# Wait for GPIO pin to be asserted, but at most 500us
start = time.ticks_us()
while pin.value() == 0:
    if time.ticks_diff(time.ticks_us(), start) > 500:
        raise TimeoutError

La planification d’événements. Dans ce cas, le résultat de ticks_diff() peut être négatif si un événement est en retard

# This code snippet is not optimized
now = time.ticks_ms()
scheduled_time = task.scheduled_time()
if ticks_diff(scheduled_time, now) > 0:
    print("Too early, let's nap")
    sleep_ms(ticks_diff(scheduled_time, now))
    task.run()
elif ticks_diff(scheduled_time, now) == 0:
    print("Right at time!")
    task.run()
elif ticks_diff(scheduled_time, now) < 0:
    print("Oops, running late, tell task to run faster!")
    task.run(run_faster=true)

Remarque : ne passez pas de valeurs de time() à ticks_diff() ; vous devez utiliser sur elles les opérations mathématiques normales. Notez toutefois que time() peut (et finira par) déborder également. C’est ce que l’on appelle le https://en.wikipedia.org/wiki/Year_2038_problem .

time.time() → int¶: Renvoie le nombre de secondes, sous forme d’entier, écoulées depuis l’époque de référence, en supposant que la RTC sous-jacente est réglée et maintenue comme décrit ci-dessus. Si aucune RTC n’est réglée, cette fonction renvoie le nombre de secondes écoulées depuis un point de référence temporel propre au portage (pour les cartes embarquées sans RTC sauvegardée par pile, généralement depuis la mise sous tension ou la réinitialisation). Si vous souhaitez développer une application MicroPython portable, vous ne devez pas compter sur cette fonction pour fournir une précision supérieure à la seconde. Si vous avez besoin d’une précision plus élevée avec des horodatages absolus, utilisez time_ns(). Si des temps relatifs sont acceptables, utilisez alors les fonctions ticks_ms() et ticks_us(). Si vous avez besoin de l’heure calendaire, gmtime() ou localtime() sans argument est un meilleur choix.

Différence avec CPython

Dans CPython, cette fonction renvoie le nombre de secondes écoulées depuis l’époque Unix (1970-01-01 00:00 UTC) sous forme de valeur à virgule flottante, généralement avec une précision de l’ordre de la microseconde. Sur l’OpenMV Cam, elle renvoie un entier avec une précision d’une seconde – le matériel ne peut pas représenter à la fois une longue plage temporelle et une précision inférieure à la seconde dans un nombre à virgule flottante – et l’époque diffère selon la carte (voir Époque de référence ci-dessus). Sans RTC sauvegardée par pile qui ait été réglée, elle compte plutôt les secondes écoulées depuis la mise sous tension ou la réinitialisation.

time.time_ns() → int¶: Semblable à time(), mais renvoie le nombre de nanosecondes écoulées depuis l’époque de référence, sous forme d’entier (généralement un grand entier, qui sera donc alloué sur le tas).

Constructeurs¶

class time.clock¶

Renvoie un objet clock.

Méthodes¶

tick() → None¶: Commence à suivre le temps écoulé.

fps() → float¶

Arrête de suivre le temps écoulé et renvoie le nombre actuel d’images par seconde (FPS).

Appelez toujours tick avant d’appeler cette fonction.

avg() → float¶

Arrête de suivre le temps écoulé et renvoie le temps écoulé moyen actuel, en millisecondes.

Appelez toujours tick avant d’appeler cette fonction.

reset() → None¶: Réinitialise l’objet clock.

time — fonctions liées au temps¶

Fonctions¶

Constructeurs¶

Méthodes¶

`time` — fonctions liées au temps¶