Modifications

Sauter à la navigation Sauter à la recherche

MicroPython-Hack-RShell (voir la source)

Version du 10 juillet 2020 à 12:20

19 484 octets ajoutés ,  10 juillet 2020 à 12:20
→‎RShell sur ESP32 (M5Stack)
Ligne 1 : Ligne 1 : −
{{traduction}}
+
= Préambule =
−
== RShell: Remote Shell for MicroPython ==
+
[[Fichier:RShell-logo.jpg|480x]]
   −
Voici une traduction libre de la documentation de l'outil RSheel écrit par Daniel Hylands.
+
Voici une traduction libre de la documentation de l'outil RShell écrit par Dave Hylands.
 +
 
 +
C'est un outil très intéressant pour réaliser des développements MicroPython, RShell fonctionne avec de nombreuses cartes MicroPython dont PyBoard, ESP8266, Teensy et toutes carte MicroPython ayant une invite REPL sur un port série.
 +
 
 +
C'est tellement génial que cela fonctionne même via une [[MicroPython-bluetooth|connexion Bluetooth série]].
 +
 
 +
RShell est aussi beaucoup plus complet que [[FEATHER-CHARGER-FICHIER-MICROPYTHON|Ampy]] (Adafruit), il faudra donc investir un peu plus de temps pour le maîtriser. Ses fonctionnalités avancées sauront se faire apprécier. 
    
Vous trouverez [https://github.com/dhylands/rshell RShell ici sur GitHub]
 
Vous trouverez [https://github.com/dhylands/rshell RShell ici sur GitHub]
 +
 +
== Source & version ==
 +
Source: [https://github.com/dhylands/rshell RShell ici sur GitHub]
 +
* Dec 13, 2016 - Traduction jusqu'à révision 480945c du Apr 30, 2016
 +
 +
== RShell sur ESP8266 ==
 +
 +
{{ambox-stop|text=Il est impératif de réduire la taille du buffer à 128 octets sur un ESP8266 sinon vous risquez d'écraser le système de fichier votre ESP8266... auquel cas il faudra reflasher votre carte}}
 +
 +
<nowiki>rshell --port /dev/ttyUSB0 --baud 115200 --buffer-size 128 --editor nano</nowiki>
 +
 +
Nous avons également un petit script shell [https://github.com/mchobby/esp8266-upy/blob/master/rshell-esp8266.sh rsheel-esp8266.sh] pour faciliter faciliter le démarrage de rshell pour un esp8266.
 +
 +
== RShell sur ESP32 (M5Stack) ==
 +
 +
L'outil RShell ne détecte pas automatiquement le port série associé au M5Stack. Il sera donc nécessaire de le stipuler au lancement de RShell.
 +
 +
<nowiki>rshell --port /dev/ttyUSB0 --editor nano</nowiki>
 +
 +
Sur un système Linux, il est facile d'identifier le port série dans les messages envoyés par le noyaux Linux lors de la connexion de l'ESP32 sur un port USB.
 +
 +
Brancher l'ESP32 / M5-Core puis exécuter la commande {{fname|dmesg}} dans un terminal pour collecter les messages de débogage.
 +
 +
<nowiki>[441990.881362] usb 2-3.2: new full-speed USB device number 16 using xhci_hcd
 +
[441990.983365] usb 2-3.2: New USB device found, idVendor=10c4, idProduct=ea60
 +
[441990.983368] usb 2-3.2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
 +
[441990.983370] usb 2-3.2: Product: CP2104 USB to UART Bridge Controller
 +
[441990.983371] usb 2-3.2: Manufacturer: Silicon Labs
 +
[441990.983373] usb 2-3.2: SerialNumber: 01DB6B96
 +
[441990.984594] cp210x 2-3.2:1.0: cp210x converter detected
 +
[441990.985755] usb 2-3.2: cp210x converter now attached to ttyUSB0</nowiki>
 +
 +
il s'agit ici du port '''ttyUSB0''' et donc du périphérique '''/dev/ttyUSB0'''
 +
 +
== RShell sur WiPy/WiPy2 ==
 +
Nous recommandons vivement de modifier le mot de passe et utilisateur par défaut de votre WiPy/WiPy 2.
 +
 +
Voici des exemples concernant les plateformes WiPy et WiPy2.
 +
 +
Exemple avec WiPy et WiPy 2:
 +
<nowiki>rshell --port 192.168.2.200 --user micro --password python --editor nano</nowiki>
 +
 +
= RShell: Shell distant pour MicroPython =
 +
== Qu'est ce que RSHell? ==
 +
Le shell distant (en ''remote'') pour MicroPython
 +
 +
RShell est un simple shell qui est exécuté sur un hôte et utilise le more raw-REPL de Micropython pour envoyer des commandes vers une carte micro python.
 +
 +
Cela permet:
 +
* d'obtenir des informations sur le système de fichier
 +
* de transférer des fichiers vers ou depuis la carte
 +
* d'établir une session REPL.
 +
 +
Comme il est possible d'invoquer REPL, RShell peut également être utilisé comme un émulateur terminal.
 +
 +
{{underline|Note:}}
 +
 +
Avec RShell, il est possible de désactiver le périphérique de stockage USB (dit "USB Mass Storage") de la carte MicroPython tout en restant capable de copier des fichiers via RShell.
 +
 +
Le grand bénéfice de cette approche est de permettre le transfert de fichier et REPL par l'intermédiaire d'une simple connexion série (filaire, USB et '''Port-Série via Bluetooth''' [[MicroPython-bluetooth|comme décrit ici]]).
 +
 +
== PC ou /flash ou /sdcard ou /pyboard ==
 +
{{ambox|text=RShell utilise une notation particulière pour les échanges de fichiers.}}
 +
 +
Lorsque vous utilisez des commandes RShell, les répertoires {{fname|/flash}} et {{fname|/sdcard}} (si vous utilisez une carte SD) sont considérés comme étant sur la carte MicroPython.
 +
 +
Dans certains cas, comme pour l'ESP8266, c'est le répertoire {{fname|/pyboard}} qu'il faut utiliser à la place de {{fname|/flash}}. En cas de doute, l'utilisation de la commande {{fname|boards}} permet de lister les cartes connectées (et répertoires distants associés).
 +
 +
Tous les autres répertoires sont réputés être sur l'hôte (votre Ordinateur).
 +
 +
== Nécessite une version récente de MicroPython ==
 +
{{ambox-stop|text=RShell utilise {{fname|unhexlify}} apparu dans les versions récentes du Firmware MicroPython. La fonction {{fname|ubinascii.unhexlify}} est apparu dans la version v1.4.3-28-ga3a14b9 (19 mai 2015) de MicroPython. }}
 +
 +
Si la version de votre Firmware est trop vieille alors rshell produira le message suivant:
 +
 +
>./rshell.py
 +
rshell needs MicroPython firmware with ubinascii.unhexlify
 +
 +
== Installation de RShell ==
 +
Vous pouvez installer rshell en utilisant PIP, l'installateur de paquet python:
 +
 +
sudo pip3 install rshell
 +
 +
Si vous utilisez un ''virtualenv'' python alors le {{fname|sudo}} n'est pas nécessaire. {{fname|rshell}} utilise Python3.
 +
 +
Tous les tests ont étés réalisé sur Python 3.4.0.
 +
 +
Si vous êtes un utilisateur Linux Debian/Ubuntu/Mint vous pouvez installer pip3 avec la commande suivante:
 +
 +
sudo apt-get install python3-pip
 +
 +
== Exemple de session ==
 +
Voici un exemple de session RShell avec un carte MicroPython Pyboard (toute neuve).
 +
 +
Dans cet exemple, nous:
 +
* Copions le fichier {{fname|hello.py}} présent sur le PC vers la Pyboard,
 +
* Vérifions que le fichier est bien présent sur la carte,
 +
* Affichons le contenu du fichier {{fname|hello.py}} présent sur la carte Pyboard
 +
* Passons finalement en session REPL pour importer le fichier dans l'interpréteur MicroPython.
 +
 +
Vous allons démarrer notre session RShell à l'aide de la commande:
 +
 +
dom@linux-mint-machine ~ $ rshell
 +
 +
RShell vous affiche un message d'accueil puis nous pouvons débuter notre session d'exemple:
 +
 +
<nowiki>
 +
    Welcome to rshell. Use Control-D to exit.
 +
    /home/dhylands/Dropbox/micropython/rshell> ls -l /flash
 +
      529 May 21 17:34 README.txt
 +
      286 May 21 17:34 boot.py
 +
        34 May 21 17:34 main.py
 +
      2436 May 21 17:34 pybcdc.inf
 +
    /home/dhylands/Dropbox/micropython/rshell> cp hello.py /flash
 +
    /home/dhylands/Dropbox/micropython/rshell> ls -l /flash
 +
      529 May 21 17:34 README.txt
 +
      286 May 21 17:34 boot.py
 +
        21 May 21 17:35 hello.py
 +
        34 May 21 17:34 main.py
 +
      2436 May 21 17:34 pybcdc.inf
 +
    /home/dhylands/Dropbox/micropython/rshell> cat /flash/hello.py
 +
    print('Hello World')
 +
    /home/dhylands/Dropbox/micropython/rshell> repl
 +
    Entering REPL. Use Control-X to exit.
 +
 +
    Micro Python v1.4.3-28-ga3a14b9 on 2015-05-21; PYBv1.0 with STM32F405RG
 +
    Type "help()" for more information.
 +
    >>>
 +
    >>> import hello
 +
    Hello World
 +
    >>>
 +
    /home/dhylands/Dropbox/micropython/rshell>
 +
</nowiki>
 +
 +
== Options de l'utilitaire RSHell ==
 +
L'utilitaire RShell se démarre en ligne de commande. Cet utilitaire accepte également différents paramètres optionnels.
 +
 +
=== Aide ===
 +
-h, --help
 +
 +
Affiche une liste des options de RShell. Vous devriez obtenir l'affichage suivant (ou nous avons traduit les "grandes lignes" en Français):
 +
 +
<nowiki>
 +
    usage: rshell [options] [command]
 +
 +
    Remote Shell for a MicroPython board.
 +
 +
    Argument positionnels:
 +
      cmd                  commande optionnel à exécuter
 +
 +
    Argument positionnel:
 +
      -h, --help            Affiche le message d'aide et quitter le programme
 +
      -b BAUD, --baud BAUD  fixe le débit utilisé (115200 par défaut)
 +
      --buffer-size BUFFER_SIZE
 +
                            Fixe la taille du buffer (mémoire tamppon) utilisé pour les transfert (512 octets/bytes par défaut)
 +
      -p PORT, --port PORT  Port série à utiliser ('/dev/ttyACM0' par défaut)
 +
      -u USER, --user USER  Le nom d'utilisateur à utiliser ('micro' par défaut. Pour le WiPy et sa connexion Telnet)
 +
      -w PASSWORD, --password PASSWORD
 +
                            Fixe le mot de passe à utiliser ('python' par défaut. Pour le WiPy et sa connexion Telnet)
 +
      -e EDITOR, --editor EDITOR
 +
                            Determine l'éditeur à utiliser ('vi' par défaut)
 +
      -f FILENAME, --file FILENAME
 +
                            Spécifier une fichier de commande à traiter.
 +
      -d, --debug          Activer le mode de débogage
 +
      -n, --nocolor        Désactiver la l'affichage en couleur
 +
      --wait                Délais d'attente sur le port série
 +
      --timing              Afficher les informations de temps pour chaque commande
 +
      --quiet              Désactive l'affichage de message de sortie (utile pour les tests)
 +
 +
    Vous pouvez spécifier le port série à utiliser dans la
 +
    variable d'environnement RSHELL_PORT
 +
</nowiki>
 +
 +
=== Débit (baud rate) ===
 +
-b BAUD, --baud BAUD
 +
 +
Permet de fixer le débit de la communication série (en bauds). Si ce paramètre n'est pas spécifié alors RShell utilise la valeur de la variable d'environnement RSHELL_BAUD .
 +
 +
Si la variable d'environnement RSHELL_BAUD n'est pas définie alors la valeur par défaut (115200 bauds) est utilisé.
 +
 +
=== Mémoire tampon (buffer) ===
 +
--buffer-size TAILLE
 +
 +
Permet de définir la taille de la mémoire tampon utilisé durant le transfert entre l'hôte et la carte PyBoard.
 +
 +
S'il la taille du buffer n'est pas spécifié, alors la valeur de la variable d'environnement RSHELL_BUFFER_SIZE .
 +
 +
Si la variable d'environnement RSHELL_BUFFER_SIZE n'est pas définie alors la mémoire tampon est fixée à 512 .
 +
 +
=== Débogage ===
 +
-d, --debug
 +
 +
Activer le mode de déboggage. Cela affiche le script MicroPython envoyé en raw REPL sur la carte MicroPython.
 +
Les informations renvoyées par la carte MicroPython sont également affichées.
 +
 +
=== Editeur de texte ===
 +
-e EDITEUR, --editor EDITEUR
 +
 +
Spécifie l'éditeur de texte à utiliser avec la commande {{fname|edit}}.
 +
 +
S'il n'y a pas de valeur spécifié alors RShell recherche les variables d'environnement RSHELL_EDITOR, VISUAL et EDITOR.
 +
 +
Si aucune de ces variable d'environnement existe alors RShell utilise l'éditeur 'vi'.
 +
 +
<small>{{underline|Note de MCHobby:}}<br />
 +
Pour les débutants, nous recommandons l'usage de l'éditeur {{fname|nano}} plus abordable que 'vi'.</small>
 +
 +
=== Fichier de commandes RShell ===
 +
-f NOM_FICHIER, --file NOM_FICHIER
 +
 +
Spécifie un fichier de commandes à exécuter par RShell. Cela vous permet de créer des scripts de commandes RShell.
 +
 +
<small>{{underline|Note de MCHobby:}}<br />
 +
De tels fichiers scripts peuvent être utilisés pour réaliser des scripts d'initialisation pour cartes MicroPython. Bien pratique si vous devez distribuer (ou même en production) une série de carte MicroPython embarquant un logiciel spécifique.</small>
 +
 +
=== Couleur du terminal ===
 +
-n, --nocolor
 +
 +
Par défaut, RShell utilise les codes d'échappement couleur ANSI pour afficher l'invite de commande et la sortie de la commande ls.
 +
 +
Cette option permet de désactiver la génération des séquences d'échappement couleur.
 +
 +
=== Attendre le prompt ===
 +
--wait
 +
 +
Si vous avez spécifié un port série alors ce paramètre indique combien de temps RShell doit attendre l'établissement de la connexion.
 +
 +
La valeur par défaut est 0 secondes, ce qui informe RShell qu'il doit rendre la main immédiatement.
 +
 +
=== Port série ===
 +
  -p PORT, --port PORT
 +
 +
Spécifie le port série qui doit être utilisé pour dialoguer avec la carte MicroPython.
 +
 +
Vous pouvez utiliser la variable d'environnement RSHELL_PORT pour spécifier le port à utiliser si vous ne voulez pas spécifier le port avec l'option --port dans la ligne de commande.
 +
 +
=== Mode silencieux ===
 +
--quiet
 +
 +
Cette option permet de désactiver le message d'acceuil RShell (celui affiché lorsque vous démarrez RShell). Cette options est plutôt utilisée avec des scripts de test.
 +
 +
=== Profilage ===
 +
--timing
 +
 +
Si l'option ''timing'' est spécifiée alors RShell indique la quantité de temps nécessaire pour l'exécution de chaque commande..
 +
 +
=== Utilisateur (via Telnet) ===
 +
-u UTILISATEUR, --user UTILISATEUR
 +
 +
Spécifie le nom d'utilisateur qui doit être utilisé lors de la connexion Telnet sur un Wipy.
 +
 +
Si le nom d'utilisateur n'est pas spécifié alors RShell utilise la valeur de la variable d'environnement RSHELL_USER .
 +
 +
Si la variable d'environnement n'est pas définie alors RShell utilisera la valeur par défaut ('micro').
 +
 +
=== Mot de passe (via Telnet) ===
 +
-w MOT_DE_PASSE, --password MOT_DE_PASSE
 +
 +
Spécifie le mot de passe qui doit être utilisé lors de la connexion Telnet sur un Wipy.
 +
 +
Si le nom d'utilisateur n'est pas spécifié alors RShell utilise la valeur de la variable d'environnement RSHELL_PASSWORD .
 +
 +
Si la variable d'environnement n'est pas définie alors RShell utilisera la valeur par défaut ('python').
 +
 +
=== Spécifier une commande ===
 +
Si une commande est spécifiée lors de l'appel de RSHell alors cette commande est exécutée et RShell termine son exécution juste après.
 +
 +
Exemples:
 +
 +
rshell cp un-fichier.py /flash
 +
rshell repl ~ pyb.bootloader() ~
 +
 +
== Le système de fichier de RShell ==
 +
RShell est capable de se connecter sur plusieurs cartes en même temps. Il utilise des noms différents pour identifier chaque carte PyBoard.
 +
 +
Si la carte embarque un module board (un fichier nommé {{fname|board.py}} comme sur la carte PyBoard) et qu'il contient un attribut appelé {{fname|name}} alors la carte utilisera ce nom!
 +
 +
Si le module {{fname|board}} ne peut pas être importé alors la carte sera nommée "pyboard" ou "wipy". Le nom sera accompagné de -1 (ou un autre nombre) de façon à avoir un nom unique pour chaque carte.
 +
 +
Vous pouvez avoir accès à la mémoire flash interne de la première carte connectée en utilisant le {{fname|/flash}} et à la carte SD de la première carte connectée en utilisant {{fname|/sd}}.
 +
 +
Pour toutes les autres cartes connectées sur RShell, vous pouvez utiliser {{fname|/nom-de-carte/flash}} ou {{fname|/nom-de-carte/sd}}
 +
 +
Vous pouvez utiliser la commande {{fname|boards}} pour identifier tous les cartes connectées et leur ''nom-de-carte''.
 +
 +
La commande {{fname|boards}} présente toutes les carte connectés avec le répertoire d'accès (port série) correspondant à la carte.
 +
 +
== Commandes ==
 +
Voici une liste des commandes que vous pouvez utiliser dans RShell.
 +
 +
=== args ===
 +
args [arguments...]
 +
 +
Fonction de débogage utilisé pour pour vérifier le ''parsing'' des arguments dans l'interpréteur RShell. Cette fonction affiche chacun des arguments reçu par la commande.
 +
 +
=== boards ===
 +
boards
 +
 +
Liste/affiche toutes les cartes actuellement connectés sur RSHell, leurs nomst et point de connexion.
 +
 +
Voici un exemple de résultat (avec un carte Feather Huzzah ESP8266 sous MicroPython):
 +
 +
[[Fichier:MicroPython-Hack-RShell-boards.png]]
 +
 +
=== cat ===
 +
cat FILENAME...
 +
 +
Concatène les fichier et envoi le contenu sur stdout.
 +
 +
<small>{{underline|Note de MCHobby:}}<br />
 +
A l'identique de la commande {{fname|cat}} sur Linux, elle permet d'afficher le contenu d'un fichier sur l'écran (la sortie standard aussi dite ''stdout'').</small>
 +
 +
=== cd ===
 +
cd REPERTOIRE
 +
 +
Chanqe le répertoire courant de RShell. L'extension ~ est supportée et {{fname|cd -}} permet de revenir au répertoire précédent.
 +
 +
=== connect ===
 +
connect TYPE TYPE_PARAMS
 +
connect serial port-serie [baud]
 +
connect telnet adresse-ip-OU-nom
 +
 +
Connecte une carte sur RShell. rshell est capable de se connecter sur plusieurs PyBoard simultanément.
 +
 +
=== cp ===
 +
cp SOURCE DESTINATION
 +
cp SOURCE... REPERTOIRE
 +
 +
Copie le fichier SOURCE vers la DESTINATION.
 +
 +
DESTINATION peut-être le nom d'un fichier ou le nom d'un répertoire. Si plus d'une SOURCE est spécifiée alors la DESTINATION devrait être un répertoire.
 +
 +
<small>{{underline|Note de MCHobby:}}<br />
 +
C'est la commande {{fname|cp}} vous permettra de transférer des fichiers entre votre ordinateur et votre/vos carte(s) MicroPython.</small>
 +
 +
=== echo ===
 +
echo TEXTE...
 +
 +
Affiche une ligne de texte.
 +
 +
=== edit ===
 +
edit nom-du-fichier
 +
 +
Permet d'éditer un fichier dans l'éditeur configuré dans RShell.
 +
 +
Si le fichier est sur une carte MicroPython ALORS:
 +
# Le fichier est copié sur l'hôte,
 +
# L'éditeur est invoqué,
 +
# Et si le fichier à été modifié
 +
## le fichier modifié est renvoyé vers la carte MicroPython.
 +
 +
L'éditeur par défaut est '''vi''' mais peut être mais peut être modifié en utilisant l'option --editor en ligne de commande. Vous pouvez également modifier l'éditeur par défaut en utilisant l'une des variables d'environnement suivantes RSHELL_EDITOR, VISUAL ou EDITOR (ces variables sont testées dans l'ordre indiqué).
 +
 +
=== filesize ===
 +
filesize FILE
 +
 +
Affiche la taille du fichier (en bytes/octets). ''Cette commande est en cours d'évaluatation''.
 +
 +
=== filetype ===
 +
filetype FICHIER
 +
 +
Affiche le type de fichier: '''dir''' pour répertoire ou '''file''' pour fichier. ''Cette commande est en cours d'évaluation''.
 +
 +
=== help ===
 +
help [COMMANDE]
 +
 +
Affiche une liste des commandes disponible (sans argument), ou affiche une aide détaillée su un COMMANDE est spécifiée en paramètre.
 +
 +
=== ls ===
 +
ls [-a] [-l] FICHIER...
 +
 +
Affiche le contenu d'un répertoire.
 +
 +
Arguments positionnels:
 +
* '''FICHIER''' : Fichiers ou répertoires à lister
 +
 +
Arguments optionnels:
 +
* '''-h, --help''' : Affiche ce message d'aide puis rend la main.
 +
* '''-a, --all''' : Affiche tous les fichiers (y compris les fichiers cachés)
 +
* '''-l, --long''' : Utilise le format long de type "listing"
 +
 +
=== mkdir ===
 +
mkdir REPERTOIRE...
 +
 +
Crée un ou plusieurs répertoires.
 +
 +
=== repl ===
 +
repl [nom-de-la-carte] [~ ligne][ ~]
 +
 +
Entre en mode REPL standard avec la carte MicroPython.
 +
 +
Utilisez Control-X pour sortir du mode REPL et revenir au shell. La carte MicroPython peut avoir besoin d'une seconde ou deux pour sortie du mode REPL.
 +
 +
Si ''nom-de-la-carte'' est fournit en argument alors RShell essaye de se connecter sur cette carte. A défaut, RShell se connecte sur la la première carte connectée.
 +
 +
Si la ligne de commande contient un caractère tilde suivit d'un espace (~ ) alors tout ce qui se trouve après le tilde est envoyé vers REPL comme si vous l'aviez saisit au clavier dans la session REPL.
 +
 +
Si vous voulez sortir de REPL alors terminé votre ligne par le caractère tilde (~).
 +
 +
Par exemple, vous pouvez saissir:
 +
 +
rshell.py repl ~ pyb.bootloader()~
 +
 +
Ce qui aura pour effet de démarrer la carte en mode DFU (''Device Firmware Update'').
 +
 +
=== rm ===
 +
rm [-r|--recursive][-f|--force] FICHIER...
 +
 +
Efface un fichier ou un répertoire du système de fichier (les répertoires doivents être vides).
 +
 +
Argument positionnel:
 +
* '''FICHIER''' : Fichier ou répertoire à effacer
 +
 +
Arguments optionnels:
 +
* '''-h, --help''' : Affiche le message d'aide (en anglais) et termine l'exécution
 +
* '''-r, --recursive''' : Efface récursivement les répertoires et leurs contenus
 +
* '''-f, --force''' : Ignore les fichier existant (et arguments inexistants)
 +
 +
=== shell ===
 +
shell commande-shell
 +
!commande-shell
 +
 +
Ceci invoke une commande dans le shell de votre système d'exploitation puis rend la main à RShell.
 +
 +
La commande {{fname|shell}} peut être remplacée par son abréviation {{fname|!}}.
 +
 +
Exemple:
 +
!make deploy
 +
 +
Dans l'exemple ci-dessus, l'utilitaire {{fname|make}} est appelé avec l'argument ''deploy'' dans le shell du système d'exploitation. Cela permet, en autre, de pouvoir flasher une carte PyBoard.
Admin
Bureaucrates, Administrateurs
29 837

modifications

Récupérée de « https://wiki.mchobby.be/index.php?title=Spécial:MobileDiff/21138...28981 »

Menu de navigation