Différences entre versions de « MicroPython-Hack-RShell »
Ligne 185 : | Ligne 185 : | ||
=== Fichier de commandes RSheel === | === Fichier de commandes RSheel === | ||
− | -f | + | -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. | Spécifie un fichier de commandes à exécuter par RShell. Cela vous permet de créer des scripts de commandes RShell. |
Version du 10 décembre 2016 à 16:00
Préambule
Voici une traduction libre de la documentation de l'outil RShell écrit par Daniel 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 connexion Bluetooth série.
Il est aussi beaucoup plus complet que Ampy (Adafruit), il faudra donc investir un peu plus de temps pour le maîtriser.
Vous trouverez RShell ici sur GitHub
RShell sur ESP8266
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 |
rshell --port /dev/ttyUSB0 --baud 115200 --buffer-size 128 --editor nano
Nous avons également un petit script shell rsheel-esp8266.sh pour faciliter faciliter le démarrage de rshell pour un esp8266.
RShell: Remote Shell for 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.
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 comme décrit ici).
PC ou /flash ou /sdcard
RShell utilise une notation particulière pour les échanges de fichiers. |
Lorsque vous utilisez des commandes RShell, les répertoires /flash et /sdcard (si vous utilisez une carte SD) sont considérés comme étant sur la carte MicroPython.
Tous les autres répertoires sont réputés être sur l'hôte (votre Ordinateur).
Nécessite une version récente de MicroPython
RShell utilise unhexlify apparu dans les versions récentes du Firmware MicroPython. La fonction 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 sudo n'est pas nécessaire. 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 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 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:
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>
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):
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
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
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 EDITOR, --editor
Spécifie l'éditeur de texte à utiliser avec la commande 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'.
Note de MCHobby:
Pour les débutants, nous recommandons l'usage de l'éditeur nano plus abordable que 'vi'.
Fichier de commandes RSheel
-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.
Note de MCHobby:
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.
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
Specifies the serial port which should be used to talk to the MicroPython board. You can set the RSHELL\_PORT environment variable to specify the default port to be used, if --port is not specified on the command line.
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
Specifies the username to use when logging into a WiPy over telnet. If no username is specified, then the username from the RSHELL_USER environment variable is used. If the RSHELL_USER environment variable doesn't exist then the default username 'micro' is used.
Mot de passe (via Telnet)
-w PASSWORD, --password PASSWORD
Specified the password to use when logging into a WiPy over telnet. If no password is specified, then the password from the RSHELL_PASSWORD environment variable is used. If the RSHELL_PASSWORD environment variable doesn't exist then the default password 'python' is used.
Commande
If a command is specified, then that command will be executed and rshell will exit. Examples:
rshell cp somefile.py /flash rshell repl ~ pyb.bootloader() ~
File System
rshell can be connected to multiple pyboards simultaneously. If the board module exists on the pyboard (i.e. a file named board.py somewhere in the module search path) and it contains an attribute called name then the pyboard will use that name. If the board module can't be imported then the board will be named, pyboard or wipy. Names will have -1 (or some other number) to make the board name unique.
You can access the internal flash on the first board connected using /flash and the sd card on the first board connected can be accessed using /sd.
For all other connected pyboards, you can use /board-name/flash or /board-name/sd (you can see the board names using the boards command).
The boards command will show all of the connected pyboards, along with all of the directories which map onto that pyboard.
Commandes
args
args [arguments...]
Debug function for verifying argument parsing. This function just prints out each argument that it receives.
boards
boards
Lists all of the boards that rshell is currently connected to, their names, and the connection.
cat
cat FILENAME...
Concatinates files and sends to stdout.
cd
cd DIRECTORY
Changes the current directory. ~ expansion is supported, and cd - goes to the previous directory.
connect
connect TYPE TYPE_PARAMS connect serial port [baud] connect telnet ip-address-or-name
Connects a pyboard to rshell. rshell can be connected to multiple pyboards simultaneously.
cp
cp SOURCE DEST cp SOURCE... DIRECTORY
Copies the SOURCE file to DEST. DEST may be a filename or a directory name. If more than one source file is specified, then the destination should be a directory.
echo
echo TEXT...
Display a line of text.
edit
edit filename
If the file is on a pyboard, it copies the file to host, invokes an editor and if any changes were made to the file, it copies it back to the pyboard.
The editor which is used defaults to vi, but can be overridem using either the --editor command line option when rshell.py is invoked, or by using the RSHELL\_EDITOR, VISUAL or EDITOR environment variables (they are tried in the order listed).
filesize
filesize FILE
Prints the size of the file, in bytes. This function is primarily testing.
filetype
filetype FILE
Prints the type of file (dir or file). This function is primarily for testing.
help
help [COMMAND]
List available commands with no arguments, or detailed help when a command is provided.
ls
Utilisation:
ls [-a] [-l] FILE...
List directory contents.
positional arguments: FILE Files or directories to list
optional arguments: -h, --help show this help message and exit -a, --all do not ignore hidden files -l, --long use a long listing format
mkdir
mkdir DIRECTORY...
Creates one or more directories.
repl
repl [board-name] [~ line][ ~]
Enters into the regular REPL with the MicroPython board. Use Control-X to exit REPL mode and return the shell. It may take a second or two before the REPL exits.
If you provide a board-name then rshell will connect to that board, otherwise it will connect to the default board (first connected board).
If you provide a tilde followed by a space (~ ) then anything after the tilde will be entered as if you typed it on the command line.
If you want the repl to exit, end the line with the ~ character.
For example, you could use:
rshell.py repl ~ pyb.bootloader()~
and it will boot the pyboard into DFU.
rm
Removes files or directories (directories must be empty).
rm [-r|--recursive][-f|--force] FILE...
positional arguments: FILE File to remove
optional arguments: -h, --help show this help message and exit -r, --recursive remove directories and their contents recursively -f, --force ignore nonexistant files and arguments
shell
The shell command can also be abbreviated using the exclamation point.
shell some-command !some-command
This will invoke a command, and return back to rshell. Example:
!make deploy
will flash the pyboard.