Contrôle à distance de MicroPython : mpremote¶

L’outil en ligne de commande mpremote fournit un ensemble intégré d’utilitaires permettant d’interagir à distance avec un appareil MicroPython, de gérer son système de fichiers et de l’automatiser via une connexion série. Il fonctionne avec toutes les OpenMV Cam grâce à leur connexion série USB et constitue une alternative en ligne de commande à OpenMV IDE pour les flux de travail de scriptage et d’automatisation.

Pour utiliser mpremote, installez-le d’abord via pip :

$ pip install --user mpremote

Ou via pipx :

$ pipx install mpremote

La façon la plus simple d’utiliser cet outil consiste à l’invoquer sans aucun argument :

$ mpremote

Cette commande détecte et se connecte automatiquement au premier appareil série USB disponible, et fournit un terminal interactif que vous pouvez utiliser pour accéder au REPL et à la sortie de votre programme. Les ports série sont ouverts en mode exclusif, de sorte que l’exécution d’une deuxième (ou troisième, etc.) instance de mpremote se connectera aux appareils série suivants, le cas échéant.

De plus, pipx vous permet aussi d’exécuter directement mpremote sans installation préalable :

$ pipx run mpremote ...args

Commandes¶

mpremote permet de spécifier une série de commandes en ligne de commande qui effectueront diverses actions de manière séquentielle sur un appareil MicroPython distant. Consultez la section des exemples ci-dessous pour avoir une idée de son fonctionnement et de quelques combinaisons de commandes courantes.

Chaque commande est de la forme <command name> [--options] [args...]. Pour les commandes qui prennent en charge plusieurs arguments (par exemple une liste de fichiers), la liste d’arguments peut être terminée par +.

Si aucune commande n’est spécifiée, la commande par défaut est repl. De plus, si une commande a besoin d’accéder à l’appareil et qu’aucun connect antérieur n’a été spécifié, alors un connect auto implicite est ajouté.

Afin de mettre l’appareil dans un état connu pour toute commande d’action (sauf repl), une fois connecté, mpremote arrêtera tout programme en cours d’exécution et effectuera une réinitialisation logicielle de l’appareil avant d’exécuter la première commande. Vous pouvez contrôler ce comportement à l’aide des commandes resume et soft-reset. Consultez connexion automatique et réinitialisation logicielle automatique pour plus de détails.

Plusieurs commandes peuvent être spécifiées et elles seront exécutées de manière séquentielle.

La liste complète des commandes prises en charge est la suivante :

connect ¶

Se connecter à l’appareil spécifié par son nom :

$ mpremote connect <device>

<device> peut être l’un des éléments suivants :

list : liste les appareils disponibles
auto : se connecte au premier port série USB disponible
id:<serial> : se connecte à l’appareil portant le numéro de série USB <serial> (la deuxième colonne de la sortie de la commande connect list)
port:<path> : se connecte à l’appareil situé au chemin indiqué (la première colonne de la sortie de la commande connect list
rfc2217://<host>:<port> : se connecte à l’appareil via une liaison série sur TCP (par exemple un port série en réseau basé sur RFC2217)
tout nom/chemin d’appareil valide, pour se connecter à cet appareil

Note : Au lieu d’utiliser la commande connect, il existe plusieurs raccourcis prédéfinis pour les chemins d’appareils courants. Par exemple, la commande raccourci a0 équivaut à connect /dev/ttyACM0 (Linux), ou c1 pour COM1 (Windows).

Note : L’option auto ne détecte que les ports série USB, c’est-à-dire un port série associé à un VID/PID USB (autrement dit des appareils de type CDC/ACM ou FTDI). Les autres types de ports série ne seront pas détectés automatiquement.

disconnect ¶

Déconnecter l’appareil actuel :

$ mpremote disconnect

Après une déconnexion, la réinitialisation logicielle automatique est activée.

resume ¶

Conserver l’état actuel de l’interpréteur pour les commandes suivantes :

$ mpremote resume

Cela désactive la réinitialisation logicielle automatique. C’est utile si vous souhaitez exécuter une commande ultérieure sur une carte sans la réinitialiser au préalable.

soft-reset ¶

Effectuer une réinitialisation logicielle de l’appareil :

$ mpremote soft-reset

Cela videra le tas (heap) Python et redémarrera l’interpréteur. Cela empêche également la commande suivante de déclencher la réinitialisation logicielle automatique.

repl ¶

Accéder au REPL sur l’appareil connecté :

$ mpremote repl [--options]

Les options sont :

--escape-non-printable, pour afficher les octets/caractères non imprimables sous forme de leur code hexadécimal
--capture <file>, pour enregistrer la sortie de la session REPL dans le fichier indiqué
--inject-code <string>, pour spécifier des caractères à injecter dans le REPL lorsque Ctrl-J est pressé. Cela vous permet d’automatiser une commande courante.
--inject-file <file>, pour spécifier un fichier à injecter dans le REPL lorsque Ctrl-K est pressé. Cela vous permet d’exécuter un fichier (par exemple contenant du code de configuration utile, ou même le programme sur lequel vous travaillez actuellement).

Pendant l’exécution de la commande repl, vous pouvez utiliser Ctrl-] ou Ctrl-x pour quitter.

Note : Le nom « REPL » reflète ici l’usage courant de cette commande pour accéder à la boucle de lecture-évaluation-affichage (Read Eval Print Loop) qui s’exécute sur l’appareil MicroPython. À proprement parler, la commande repl fonctionne simplement comme un terminal (ou « moniteur série ») pour accéder à l’appareil. Comme cette commande ne déclenche pas le comportement de réinitialisation automatique, cela signifie que si un programme est en cours d’exécution, vous devrez d’abord l’interrompre avec Ctrl-C pour accéder au REPL, ce qui vous permettra ensuite d’accéder à l’état du programme. Vous pouvez aussi utiliser mpremote soft-reset repl pour obtenir un REPL « propre » avec tout l’état du programme effacé.

eval ¶

Évaluer et afficher le résultat d’une expression Python :

$ mpremote eval <string>

exec ¶

Exécuter le code Python indiqué :

$ mpremote exec <string>

Par défaut, mpremote exec affichera toute sortie de l’expression jusqu’à ce qu’elle se termine. Le drapeau --no-follow peut être spécifié pour retourner immédiatement et laisser l’appareil exécuter l’expression en arrière-plan.

run ¶

Exécuter un script depuis le système de fichiers local :

$ mpremote run <file.py>

Cela exécutera le fichier directement depuis la RAM de l’appareil sans le copier dans le système de fichiers. C’est une manière très utile d’itérer sur le développement d’un seul morceau de code sans avoir à se soucier de son déploiement sur le système de fichiers.

Par défaut, mpremote run affichera toute sortie du script jusqu’à ce qu’il se termine. Le drapeau --no-follow peut être spécifié pour retourner immédiatement et laisser l’appareil exécuter le script en arrière-plan.

fs ¶

Exécuter des commandes de système de fichiers sur l’appareil :

$ mpremote fs <sub-command>

<sub-command> peut être :

cat <file..> pour afficher le contenu d’un ou plusieurs fichiers sur l’appareil
ls pour lister le répertoire courant
ls <dirs...> pour lister les répertoires indiqués
cp [-rf] <src...> <dest> pour copier des fichiers
rm [-r] <src...> pour supprimer des fichiers ou des dossiers sur l’appareil
mkdir <dirs...> pour créer des répertoires sur l’appareil
rmdir <dirs...> pour supprimer des répertoires sur l’appareil
touch <file..> pour créer les fichiers (s’ils n’existent pas déjà)
sha256sum <file..> pour calculer la somme SHA256 de fichiers
tree [-vsh] <dirs...> pour afficher une arborescence des répertoires indiqués

La commande cp utilise une convention où un : en début de chemin représente un chemin distant. Sans : en début de chemin, il s’agit d’un chemin local. Ceci est basé sur la convention utilisée par le client Secure Copy Protocol (scp).

Ainsi, par exemple, mpremote fs cp main.py :main.py copie main.py du répertoire local courant vers le système de fichiers distant, tandis que mpremote fs cp :main.py main.py copie main.py de l’appareil vers le répertoire courant.

La commande mpremote rm -r accepte à la fois les chemins relatifs et absolus. Utilisez : pour faire référence au répertoire de travail distant courant (cwd) afin de permettre la suppression d’une arborescence de répertoires depuis le chemin par défaut de l’appareil (par exemple /flash, /). Utilisez -v/--verbose pour voir les fichiers en cours de suppression.

Par exemple :

mpremote rm -r :libs supprimera le répertoire libs et tous ses éléments enfants de l’appareil.
mpremote rm -rv :/sd supprimera tous les fichiers d’une carte SD montée et générera un avertissement non bloquant. Le montage sera conservé.
mpremote rm -rv :/ supprimera tous les fichiers de l’appareil, y compris ceux situés dans les vfs montés tels que /sd ou /flash. Après avoir supprimé tous les dossiers et fichiers, cela renverra également une erreur pour imiter le comportement de rm -rf / sous Unix.

Avertissement

Il n’existe aucun moyen pris en charge de récupérer les fichiers supprimés par mpremote rm -r :. À utiliser avec précaution.

La commande tree affichera une arborescence des répertoires indiqués. L’option --size/-s affichera la taille de chaque fichier, ou utilisez --human/-h pour utiliser un format plus lisible par l’humain. Note : la taille des répertoires n’est affichée que lorsqu’une taille non nulle est rapportée par le système de fichiers de l’appareil. L’option -v peut être utilisée pour inclure le nom de l’appareil série dans la sortie.

Toutes les autres commandes supposent implicitement que le chemin est un chemin distant, mais le : peut éventuellement être utilisé pour plus de clarté.

Toutes les sous-commandes de système de fichiers acceptent plusieurs arguments de chemin, donc s’il y a une autre commande dans la séquence, vous devez utiliser + pour terminer les arguments, par exemple :

$ mpremote fs cp main.py :main.py + repl

Cela copiera le fichier sur l’appareil puis accédera au REPL. Le + empêche que "repl" soit interprété comme un chemin.

La commande cp prend en charge l’option -r pour effectuer une copie récursive. Par défaut, cp ignorera la copie de fichiers vers l’appareil distant si le hachage SHA256 du fichier source et du fichier de destination correspond. Pour forcer une copie indépendamment du hachage, utilisez l’option -f.

Note : Pour plus de commodité, toutes les sous-commandes de système de fichiers sont également disponibles comme commandes régulières, c’est-à-dire que vous pouvez écrire mpremote cp ... au lieu de mpremote fs cp ....

df ¶

Interroger l’espace libre/utilisé de l’appareil :

$ mpremote df

La commande df affichera les statistiques de taille/utilisé/libre du système de fichiers de l’appareil, à la manière de la commande Unix df.

edit ¶

Éditer un fichier sur l’appareil :

$ mpremote edit <files...>

La commande edit copiera chaque fichier de l’appareil vers un répertoire temporaire local puis lancera votre éditeur pour chaque fichier (défini par la variable d’environnement $EDITOR). Si l’éditeur se ferme correctement, le fichier mis à jour sera recopié sur l’appareil.

mip ¶

Installer des paquets depuis micropython-lib (ou GitHub) à l’aide de l’outil mip :

$ mpremote mip install <packages...>

Consultez Gestion des paquets pour plus d’informations.

mount ¶

Monter le répertoire local sur l’appareil distant :

$ mpremote mount [options] <local-dir>

Cela permet à l’appareil distant de voir le répertoire de l’hôte local comme s’il s’agissait de son propre système de fichiers. C’est utile pour le développement et évite d’avoir à copier les fichiers sur l’appareil pendant que vous travaillez dessus.

L’appareil installe un pilote de système de fichiers, qui est ensuite monté dans le VFS de l’appareil sous /remote, qui utilise la connexion série vers mpremote comme canal auxiliaire pour accéder aux fichiers. Le répertoire de travail courant de l’appareil (via os.chdir) sera défini sur /remote afin que les imports et l’accès aux fichiers s’y produisent au lieu du chemin du système de fichiers par défaut tant que le montage est actif.

Note : Si la commande mount n’est pas suivie d’une autre action dans la séquence, une commande repl sera implicitement ajoutée à la fin de la séquence.

Pendant l’utilisation, Ctrl-D déclenchera une réinitialisation logicielle comme d’habitude, mais le montage sera automatiquement reconnecté. Si l’appareil exécute toutefois un main.py au démarrage, le remontage ne peut pas avoir lieu. Dans ce cas, un redémarrage logiciel en mode brut peut être utilisé : Ctrl-A Ctrl-D pour redémarrer, puis Ctrl-B pour revenir au repl normal, moment auquel le montage sera prêt.

Les options sont :

-l, --unsafe-links : Par défaut, une erreur est levée si l’appareil accède à un fichier ou un répertoire situé en dehors (d’un ou plusieurs niveaux de répertoire au-dessus) du répertoire local qui est monté. Cette option désactive cette vérification pour les liens symboliques, permettant à l’appareil de suivre des liens symboliques en dehors du répertoire local.

unmount ¶

Démonter le répertoire local de l’appareil distant :

$ mpremote umount

Cela se produit automatiquement lorsque mpremote se termine, mais cela peut être utilisé dans une séquence pour démonter un montage antérieur avant l’exécution des commandes suivantes.

romfs ¶

Gérer les partitions ROMFS sur l’appareil :

$ mpremote romfs <sub-command>

<sub-command> peut être :

romfs query pour lister toutes les partitions ROMFS disponibles et leur taille
romfs [-o <output>] build <source> pour créer une image ROMFS à partir du répertoire source indiqué ; le fichier de sortie par défaut est la source à laquelle est ajouté .romfs
romfs [-p <partition>] deploy <source> pour déployer une image ROMFS sur l’appareil ; créera également une image ROMFS temporaire si la source est un répertoire

Les sous-commandes build et deploy prennent toutes deux en charge l’option -m/--mpy pour compiler automatiquement les fichiers .py en .mpy lors de la création de l’image ROMFS. Cette option est activée par défaut, mais ne fonctionne que si le paquet Python mpy_cross a été installé (par exemple via pip install mpy_cross). Si le paquet n’est pas installé, un avertissement est affiché et les fichiers .py restent en l’état. La compilation des fichiers .py peut être désactivée avec l’option --no-mpy.

rtc ¶

Définir/lire l’horloge de l’appareil (RTC) :

$ mpremote rtc

Cela interrogera le RTC de l’appareil pour obtenir l’heure actuelle et l’affichera sous forme de tuple datetime.

$ mpremote rtc --set

Cela réglera le RTC de l’appareil sur l’heure actuelle du PC hôte.

sleep ¶

Patienter (délai) avant d’exécuter la commande suivante :

$ mpremote sleep 0.5

Cela suspendra l’exécution de la séquence de commandes pendant la durée spécifiée en secondes, par exemple pour attendre que l’appareil fasse quelque chose.

reset ¶

Réinitialisation matérielle de l’appareil :

$ mpremote reset

Note : la réinitialisation matérielle équivaut à machine.reset().

bootloader ¶

Accéder au programme d’amorçage :

$ mpremote bootloader

Cela fera entrer l’appareil dans son programme d’amorçage. Le programme d’amorçage est spécifique à la carte — consultez la section Recovery and debug pins de la référence rapide de votre carte pour plus de détails.

Connexion automatique et réinitialisation logicielle¶

La connexion et la déconnexion seront effectuées automatiquement au début et à la fin de l’exécution de l’outil, si de telles commandes ne sont pas explicitement données. La connexion automatique recherchera le premier appareil série USB disponible.

Une fois connecté à un appareil, mpremote effectuera automatiquement une réinitialisation logicielle de l’appareil si nécessaire. Cela vide le tas (heap) Python et redémarre l’interpréteur, garantissant que le code Python ultérieur s’exécute dans un environnement neuf. La réinitialisation logicielle automatique est effectuée la première fois que l’une des commandes suivantes est exécutée : mount, eval, exec, run, fs. Après avoir effectué une réinitialisation logicielle pour la première fois, elle ne sera plus effectuée automatiquement, jusqu’à ce qu’une commande disconnect soit émise.

Le comportement de la réinitialisation logicielle automatique peut être contrôlé par la commande resume. Cela peut être utile pour utiliser la commande eval afin d’inspecter l’état de l’appareil. La commande soft-reset peut être utilisée pour effectuer une réinitialisation logicielle explicite au milieu d’une séquence de commandes.

Raccourcis¶

Les raccourcis peuvent être définis à l’aide du système de macros. Les raccourcis intégrés sont :

devs : Alias de connect list
a0, a1, a2, a3 : Alias de connect /dev/ttyACMn
u0, u1, u2, u3 : Alias de connect /dev/ttyUSBn
c0, c1, c2, c3 : Alias de connect COMn
cat, edit, ls, cp, rm, mkdir, rmdir, touch : Alias de fs <sub-command>

Des raccourcis supplémentaires peuvent être définis dans le fichier de configuration utilisateur mpremote/config.py, situé dans le répertoire de configuration utilisateur. L’emplacement correct pour chaque système d’exploitation est déterminé à l’aide du module platformdirs.

Il s’agit généralement de : - $XDG_CONFIG_HOME/mpremote/config.py - $HOME/.config/mpremote/config.py - $env:LOCALAPPDATA/mpremote/config.py

Le fichier config.py doit définir un dictionnaire nommé commands. Les clés de ce dictionnaire sont les raccourcis et les valeurs sont soit une chaîne, soit une liste de chaînes :

"c33": "connect id:334D335C3138",

La commande c33 est remplacée par connect id:334D335C3138.

"test": ["mount", ".", "exec", "import test"],

La commande test est remplacée par mount . exec "import test".

Les raccourcis peuvent également accepter des arguments. Par exemple :

"multiply x=4 y=7": "eval x*y",

L’exécution de mpremote multiply 3 7 définira x et y comme variables sur l’appareil, puis évaluera l’expression x*y.

Un exemple de config.py pourrait ressembler à :

commands = {
    "c33": "connect id:334D335C3138", # Connect to a specific device by ID.
    "bl": "bootloader", # Shorter alias for bootloader.
    "double x=4": "eval x*2",  # x is an argument, with default 4
    "wl_scan": ["exec", """
import network
wl = network.WLAN()
wl.active(1)
for ap in wl.scan():
    print(ap)
""",], # Print out nearby WiFi networks.
    "wl_ipconfig": [
"exec",
"import network; sta_if = network.WLAN(network.WLAN.IF_STA); print(sta_if.ipconfig('addr4'))",
], # Print ip address of station interface.
    "test": ["mount", ".", "exec", "import test"], # Mount current directory and run test.py.
    "demo": ["run", "path/to/demo.py"], # Execute demo.py on the device.
}

Exemples¶

mpremote

Se connecter au premier appareil disponible et exécuter implicitement la commande repl.

mpremote a1

Se connecter à l’appareil situé à /dev/ttyACM1 (Linux) et exécuter implicitement la commande repl. Consultez les raccourcis ci-dessus.

mpremote c1

Se connecter à l’appareil situé à COM1 (Windows) et exécuter implicitement la commande repl. Consultez les raccourcis ci-dessus.

mpremote connect /dev/ttyUSB0

Spécifier explicitement l’appareil auquel se connecter et, comme ci-dessus, exécuter implicitement la commande repl.

mpremote a1 ls

Se connecter à l’appareil situé à /dev/ttyACM1 puis exécuter la commande ls.

Cela équivaut à mpremote connect /dev/ttyACM1 fs ls.

mpremote exec "import micropython; micropython.mem_info()"

Exécuter la commande Python spécifiée et afficher toute sortie. Cela équivaut à saisir la commande à l’invite du REPL.

mpremote eval 1/2 eval 3/4

Évaluer chaque expression à tour de rôle et afficher les résultats.

mpremote a0 eval 1/2 a1 eval 3/4

Évaluer 1/2 sur l’appareil situé à /dev/ttyACM0, puis 3/4 sur l’appareil situé à /dev/ttyACM1, en affichant chaque résultat.

mpremote resume exec "print_state_info()" soft-reset

Se connecter à l’appareil sans déclencher de réinitialisation logicielle et exécuter la fonction print_state_info() (par exemple pour obtenir des informations sur l’état actuel du programme), puis déclencher une réinitialisation logicielle.

mpremote reset sleep 0.5 bootloader

Effectuer une réinitialisation matérielle de l’appareil, attendre 500 ms qu’il devienne disponible, puis accéder au programme d’amorçage.

mpremote cp utils/driver.py :utils/driver.py + run test.py

Mettre à jour la copie de utils/driver.py sur l’appareil, puis exécuter le script test.py local sur l’appareil. test.py n’est jamais copié sur le système de fichiers de l’appareil, il est plutôt exécuté depuis la RAM.

mpremote cp utils/driver.py :utils/driver.py + exec "import app"

Mettre à jour la copie de utils/driver.py sur l’appareil, puis exécuter app.py sur l’appareil.

Il s’agit d’un flux de développement courant consistant à mettre à jour un seul fichier puis à redémarrer votre programme. Dans ce scénario, votre main.py sur l’appareil devrait également effectuer import app.

mpremote cp utils/driver.py :utils/driver.py + soft-reset repl

Mettre à jour la copie de utils/driver.py sur l’appareil, puis déclencher une réinitialisation logicielle pour redémarrer votre programme, puis surveiller la sortie via la commande repl.

mpremote cp -r utils/ :utils/ + soft-reset repl

Identique à ci-dessus, mais en mettant d’abord à jour l’intégralité du répertoire utils.

mpremote mount .

Monter le répertoire local courant sous /remote sur l’appareil et démarrer une session repl qui utilisera /remote comme répertoire de travail.

mpremote mount . exec "import demo"

Après avoir monté le répertoire local courant, exécute demo.py depuis le répertoire monté.

mpremote mount app run test.py

Après avoir monté le répertoire local app sous /remote sur l’appareil, exécute le fichier test.py local depuis le répertoire courant de l’hôte sans le copier sur le système de fichiers.

mpremote mount . repl --inject-code "import demo"

Après avoir monté le répertoire local courant, exécute demo.py depuis le répertoire monté chaque fois que Ctrl-J est pressé.

Vous devrez d’abord presser Ctrl-D pour réinitialiser l’état de l’interpréteur (ce qui préservera le montage) avant de presser Ctrl-J pour réimporter demo.py.

mpremote mount app repl --inject-file demo.py

Identique à ci-dessus, mais exécute le contenu du fichier local demo.py au REPL chaque fois que Ctrl-K est pressé. Comme ci-dessus, utilisez Ctrl-D pour réinitialiser d’abord l’état de l’interpréteur.

mpremote cat boot.py

Affiche le contenu de boot.py sur l’appareil.

mpremote edit utils/driver.py

Éditer utils/driver.py sur l’appareil à l’aide de votre $EDITOR local.

mpremote cp :main.py .

Copier main.py de l’appareil vers le répertoire local.

mpremote cp main.py :

Copier main.py du répertoire local vers l’appareil.

mpremote cp :a.py :b.py

Copier a.py sur l’appareil vers b.py sur l’appareil.

mpremote cp -r dir/ :

Copier récursivement le répertoire local dir vers l’appareil distant.

mpremote cp a.py b.py : + repl

Copier a.py et b.py du répertoire local vers l’appareil, puis exécuter la commande repl.

mpremote mip install aioble

Installer le paquet aioble depuis micropython-lib sur l’appareil. Consultez Gestion des paquets.

mpremote mip install github:org/repo@branch

Installer le paquet depuis la branche spécifiée à org/repo sur GitHub sur l’appareil. Consultez Gestion des paquets.

mpremote mip install gitlab:org/repo@branch

Installer le paquet depuis la branche spécifiée à org/repo sur GitLab sur l’appareil. Consultez Gestion des paquets.

mpremote mip install --target /flash/third-party functools

Installer le paquet functools depuis micropython-lib dans le répertoire /flash/third-party sur l’appareil. Consultez Gestion des paquets.