Control la distanță MicroPython: mpremote¶

Instrumentul de linie de comandă mpremote oferă un set integrat de utilitare pentru a interacționa la distanță cu un dispozitiv MicroPython, a gestiona sistemul său de fișiere și a-l automatiza printr-o conexiune serială. Funcționează cu toate camerele OpenMV Cam prin conexiunea lor serială USB și este o alternativă în linie de comandă la OpenMV IDE pentru fluxurile de lucru de scriptare și automatizare.

Pentru a folosi mpremote, instalați-l mai întâi prin pip:

$ pip install --user mpremote

Sau prin pipx:

$ pipx install mpremote

Cel mai simplu mod de a folosi acest instrument este pur și simplu invocându-l fără niciun argument:

$ mpremote

Această comandă detectează și se conectează automat la primul dispozitiv serial USB disponibil și oferă un terminal interactiv pe care îl puteți folosi pentru a accesa REPL-ul și ieșirea programului dvs. Porturile seriale sunt deschise în mod exclusiv, astfel încât rularea unei a doua (sau a treia etc.) instanțe a mpremote se va conecta la dispozitivele seriale ulterioare, dacă sunt disponibile.

În plus, pipx vă permite, de asemenea, să rulați direct mpremote fără a-l instala mai întâi:

$ pipx run mpremote ...args

Comenzi¶

mpremote acceptă primirea unei serii de comenzi date în linia de comandă, care vor efectua diverse acțiuni în succesiune pe un dispozitiv MicroPython la distanță. Consultați secțiunea de exemple de mai jos pentru a vă face o idee despre cum funcționează acest lucru și pentru câteva combinații obișnuite de comenzi.

Fiecare comandă are forma <command name> [--options] [args...]. Pentru comenzile care acceptă mai multe argumente (de exemplu, o listă de fișiere), lista de argumente poate fi terminată cu +.

Dacă nu se specifică nicio comandă, comanda implicită este repl. În plus, dacă orice comandă are nevoie să acceseze dispozitivul și nu a fost specificat anterior niciun connect, atunci se adaugă un connect auto implicit.

Pentru a aduce dispozitivul într-o stare cunoscută pentru orice comandă de acțiune (cu excepția repl), după conectare mpremote va opri orice program care rulează și va efectua un soft-reset asupra dispozitivului înainte de a rula prima comandă. Puteți controla acest comportament folosind comenzile resume și soft-reset. Consultați auto-conectarea și auto-soft-reset pentru mai multe detalii.

Pot fi specificate mai multe comenzi, iar acestea vor fi rulate secvențial.

Lista completă a comenzilor acceptate este:

connect ¶

Se conectează la dispozitivul specificat după nume:

$ mpremote connect <device>

<device> poate fi unul dintre:

list: listează dispozitivele disponibile
auto: se conectează la primul port serial USB disponibil
id:<serial>: se conectează la dispozitivul cu numărul serial USB <serial> (a doua coloană din ieșirea comenzii connect list)
port:<path>: se conectează la dispozitivul cu calea dată (prima coloană din ieșirea comenzii connect list
rfc2217://<host>:<port>: se conectează la dispozitiv folosind conexiunea serială prin TCP (de exemplu, un port serial în rețea bazat pe RFC2217)
orice nume/cale de dispozitiv valid(ă), pentru a vă conecta la acel dispozitiv

Notă: În locul folosirii comenzii connect, există mai multe scurtături predefinite pentru căi de dispozitive obișnuite. De exemplu, comanda scurtătură a0 este echivalentă cu connect /dev/ttyACM0 (Linux), sau c1 pentru COM1 (Windows).

Notă: Opțiunea auto va detecta doar porturile seriale USB, adică un port serial care are asociat un VID/PID USB (adică dispozitive de tip CDC/ACM sau FTDI). Alte tipuri de porturi seriale nu vor fi detectate automat.

disconnect ¶

Deconectează dispozitivul curent:

$ mpremote disconnect

După o deconectare, auto-soft-reset este activat.

resume ¶

Menține starea existentă a interpretorului pentru comenzile ulterioare:

$ mpremote resume

Acest lucru dezactivează auto-soft-reset. Este util dacă doriți să rulați o comandă ulterioară pe o placă fără a efectua mai întâi un soft-reset asupra acesteia.

soft-reset ¶

Efectuează un soft-reset al dispozitivului:

$ mpremote soft-reset

Acest lucru va goli heap-ul Python și va reporni interpretorul. De asemenea, împiedică comanda ulterioară să declanșeze auto-soft-reset.

repl ¶

Intră în REPL pe dispozitivul conectat:

$ mpremote repl [--options]

Opțiunile sunt:

--escape-non-printable, pentru a afișa octeții/caracterele neimprimabile sub forma codului lor hexazecimal
--capture <file>, pentru a captura ieșirea sesiunii REPL în fișierul dat
--inject-code <string>, pentru a specifica caractere de injectat în REPL când se apasă Ctrl-J. Acest lucru vă permite să automatizați o comandă obișnuită.
--inject-file <file>, pentru a specifica un fișier de injectat în REPL când se apasă Ctrl-K. Acest lucru vă permite să rulați un fișier (de exemplu, conținând cod de configurare util, sau chiar programul la care lucrați în prezent).

În timp ce comanda repl rulează, puteți folosi Ctrl-] sau Ctrl-x pentru a ieși.

Notă: Numele „REPL” de aici reflectă utilizarea obișnuită a acestei comenzi pentru a accesa bucla Read Eval Print care rulează pe dispozitivul MicroPython. Strict vorbind, comanda repl funcționează doar ca un terminal (sau „monitor serial”) pentru a accesa dispozitivul. Deoarece această comandă nu declanșează comportamentul de auto-reset, aceasta înseamnă că, dacă un program rulează în prezent, va trebui mai întâi să-l întrerupeți cu Ctrl-C pentru a ajunge la REPL, ceea ce vă va permite apoi să accesați starea programului. Puteți, de asemenea, să folosiți mpremote soft-reset repl pentru a obține un REPL „curat”, cu toată starea programului golită.

eval ¶

Evaluează și afișează rezultatul unei expresii Python:

$ mpremote eval <string>

exec ¶

Execută codul Python dat:

$ mpremote exec <string>

În mod implicit, mpremote exec va afișa orice ieșire a expresiei până când aceasta se termină. Indicatorul --no-follow poate fi specificat pentru a reveni imediat și a lăsa dispozitivul să ruleze expresia în fundal.

run ¶

Rulează un script din sistemul de fișiere local:

$ mpremote run <file.py>

Acest lucru va executa fișierul direct din RAM pe dispozitiv, fără a-l copia în sistemul de fișiere. Acesta este un mod foarte util de a itera asupra dezvoltării unei singure bucăți de cod fără a fi nevoie să vă preocupați de implementarea sa în sistemul de fișiere.

În mod implicit, mpremote run va afișa orice ieșire a scriptului până când acesta se termină. Indicatorul --no-follow poate fi specificat pentru a reveni imediat și a lăsa dispozitivul să ruleze scriptul în fundal.

fs ¶

Execută comenzi de sistem de fișiere pe dispozitiv:

$ mpremote fs <sub-command>

<sub-command> poate fi:

cat <file..> pentru a afișa conținutul unui fișier sau al unor fișiere de pe dispozitiv
ls pentru a lista directorul curent
ls <dirs...> pentru a lista directoarele date
cp [-rf] <src...> <dest> pentru a copia fișiere
rm [-r] <src...> pentru a elimina fișiere sau foldere de pe dispozitiv
mkdir <dirs...> pentru a crea directoare pe dispozitiv
rmdir <dirs...> pentru a elimina directoare de pe dispozitiv
touch <file..> pentru a crea fișierele (dacă nu există deja)
sha256sum <file..> pentru a calcula suma SHA256 a fișierelor
tree [-vsh] <dirs...> pentru a afișa un arbore al directoarelor date

Comanda cp folosește o convenție în care un : la început reprezintă o cale la distanță. Fără un : la început înseamnă o cale locală. Aceasta se bazează pe convenția folosită de clientul Secure Copy Protocol (scp).

Astfel, de exemplu, mpremote fs cp main.py :main.py copiază main.py din directorul local curent în sistemul de fișiere la distanță, în timp ce mpremote fs cp :main.py main.py copiază main.py de pe dispozitiv înapoi în directorul curent.

Comanda mpremote rm -r acceptă atât căi relative, cât și absolute. Folosiți : pentru a face referire la directorul de lucru curent la distanță (cwd), pentru a permite eliminarea unui arbore de directoare din calea implicită a dispozitivului (de exemplu, /flash, /). Folosiți -v/--verbose pentru a vedea fișierele care sunt eliminate.

De exemplu:

mpremote rm -r :libs va elimina directorul libs și toate elementele sale subordonate de pe dispozitiv.
mpremote rm -rv :/sd va elimina toate fișierele de pe un card SD montat și va genera un avertisment neblocant. Montarea va fi păstrată.
mpremote rm -rv :/ va elimina toate fișierele de pe dispozitiv, inclusiv pe cele aflate în sisteme vfs montate, precum /sd sau /flash. După eliminarea tuturor folderelor și fișierelor, aceasta va returna, de asemenea, o eroare pentru a imita comportamentul unix rm -rf /.

Atenționare

Nu există o modalitate acceptată de a recupera fișierele eliminate de mpremote rm -r :. Vă rugăm să folosiți cu precauție.

Comanda tree va afișa un arbore al directoarelor date. Folosirea opțiunii --size/-s va afișa dimensiunea fiecărui fișier, sau folosiți --human/-h pentru a utiliza un format mai ușor de citit de către oameni. Notă: Dimensiunea directorului este afișată doar atunci când o dimensiune diferită de zero este raportată de sistemul de fișiere al dispozitivului. Opțiunea -v poate fi folosită pentru a include numele dispozitivului serial în ieșire.

Toate celelalte comenzi presupun implicit că această cale este o cale la distanță, dar : poate fi folosit opțional pentru claritate.

Toate sub-comenzile de sistem de fișiere acceptă mai multe argumente de cale, așa că, dacă există o altă comandă în secvență, trebuie să folosiți + pentru a termina argumentele, de exemplu:

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

Acest lucru va copia fișierul pe dispozitiv și apoi va intra în REPL. + împiedică interpretarea "repl" ca o cale.

Comanda cp acceptă opțiunea -r pentru a face o copie recursivă. În mod implicit, cp va omite copierea fișierelor pe dispozitivul la distanță dacă hash-ul SHA256 al fișierului sursă și al celui de destinație se potrivesc. Pentru a forța o copiere indiferent de hash, folosiți opțiunea -f.

Notă: Pentru comoditate, toate sub-comenzile de sistem de fișiere sunt, de asemenea, aliasate ca comenzi obișnuite, adică puteți scrie mpremote cp ... în loc de mpremote fs cp ....

df ¶

Interoghează spațiul liber/folosit al dispozitivului:

$ mpremote df

Comanda df va afișa statistici de dimensiune/folosit/liber pentru sistemul de fișiere al dispozitivului, similar cu comanda Unix df.

edit ¶

Editează un fișier de pe dispozitiv:

$ mpremote edit <files...>

Comanda edit va copia fiecare fișier de pe dispozitiv într-un director temporar local și apoi va lansa editorul dvs. pentru fiecare fișier (definit de variabila de mediu $EDITOR). Dacă editorul se închide cu succes, fișierul actualizat va fi copiat înapoi pe dispozitiv.

mip ¶

Instalează pachete din micropython-lib (sau GitHub) folosind instrumentul mip:

$ mpremote mip install <packages...>

Consultați Gestionarea pachetelor pentru mai multe informații.

mount ¶

Montează directorul local pe dispozitivul la distanță:

$ mpremote mount [options] <local-dir>

Acest lucru permite dispozitivului la distanță să vadă directorul gazdei locale ca și cum ar fi propriul său sistem de fișiere. Este util pentru dezvoltare și evită necesitatea de a copia fișiere pe dispozitiv în timp ce lucrați la ele.

Dispozitivul instalează un driver de sistem de fișiere, care este apoi montat în VFS-ul dispozitivului ca /remote, care folosește conexiunea serială către mpremote ca un canal secundar pentru a accesa fișierele. Dispozitivul își va seta directorul de lucru curent (prin os.chdir) la /remote, astfel încât importurile și accesarea fișierelor să aibă loc acolo în loc de calea implicită a sistemului de fișiere cât timp montarea este activă.

Notă: Dacă comanda mount nu este urmată de o altă acțiune în secvență, o comandă repl va fi adăugată implicit la sfârșitul secvenței.

În timpul utilizării, Ctrl-D va declanșa un soft-reset ca de obicei, dar montarea va fi reconectată automat. Totuși, dacă unitatea are un main.py care rulează la pornire, remontarea nu poate avea loc. În acest caz, poate fi folosită o repornire soft în mod raw: Ctrl-A Ctrl-D pentru a reporni, apoi Ctrl-B pentru a reveni la REPL-ul normal, moment în care montarea va fi gata.

Opțiunile sunt:

-l, --unsafe-links: În mod implicit, va fi generată o eroare dacă dispozitivul accesează un fișier sau un director care se află în afara (cu unul sau mai multe niveluri de director mai sus) directorului local care este montat. Această opțiune dezactivează această verificare pentru legăturile simbolice, permițând dispozitivului să urmărească legături simbolice în afara directorului local.

unmount ¶

Demontează directorul local de pe dispozitivul la distanță:

$ mpremote umount

Acest lucru se întâmplă automat când mpremote se termină, dar poate fi folosit într-o secvență pentru a demonta o montare anterioară înainte de rularea comenzilor ulterioare.

romfs ¶

Gestionează partițiile ROMFS de pe dispozitiv:

$ mpremote romfs <sub-command>

<sub-command> poate fi:

romfs query pentru a lista toate partițiile ROMFS disponibile și dimensiunea lor
romfs [-o <output>] build <source> pentru a crea o imagine ROMFS din directorul sursă dat; fișierul de ieșire implicit este sursa la care se adaugă .romfs
romfs [-p <partition>] deploy <source> pentru a implementa o imagine ROMFS pe dispozitiv; va crea, de asemenea, o imagine ROMFS temporară dacă sursa este un director

Sub-comenzile build și deploy acceptă ambele opțiunea -m/--mpy pentru a compila automat fișierele .py în .mpy la crearea imaginii ROMFS. Această opțiune este activată în mod implicit, dar funcționează doar dacă pachetul Python mpy_cross a fost instalat (de exemplu, prin pip install mpy_cross). Dacă pachetul nu este instalat, atunci se afișează un avertisment, iar fișierele .py rămân așa cum sunt. Compilarea fișierelor .py poate fi dezactivată cu opțiunea --no-mpy.

rtc ¶

Setează/citește ceasul dispozitivului (RTC):

$ mpremote rtc

Acest lucru va interoga RTC-ul dispozitivului pentru ora curentă și o va afișa ca un tuplu datetime.

$ mpremote rtc --set

Acest lucru va seta RTC-ul dispozitivului la ora curentă a PC-ului gazdă.

sleep ¶

Pauză (întârziere) înainte de executarea comenzii următoare:

$ mpremote sleep 0.5

Acest lucru va întrerupe execuția secvenței de comenzi pentru durata specificată în secunde, de exemplu pentru a aștepta ca dispozitivul să facă ceva.

reset ¶

Efectuează un reset hardware al dispozitivului:

$ mpremote reset

Notă: resetul hardware este echivalent cu machine.reset().

bootloader ¶

Intră în bootloader:

$ mpremote bootloader

Acest lucru va face dispozitivul să intre în bootloader-ul său. Bootloader-ul este specific plăcii — consultați secțiunea Recovery and debug pins din referința rapidă a plăcii dvs. pentru detalii.

Auto-conectare și soft-reset¶

Conectarea și deconectarea se vor face automat la începutul și la sfârșitul execuției instrumentului, dacă astfel de comenzi nu sunt date explicit. Conectarea automată va căuta primul dispozitiv serial USB disponibil.

Odată conectat la un dispozitiv, mpremote va efectua automat un soft-reset asupra dispozitivului dacă este necesar. Acest lucru golește heap-ul Python și repornește interpretorul, asigurându-se că codul Python ulterior se execută într-un mediu nou. Auto-soft-reset-ul se efectuează prima dată când se execută una dintre următoarele comenzi: mount, eval, exec, run, fs. După efectuarea unui soft-reset pentru prima dată, acesta nu va mai fi efectuat din nou automat, până când se emite o comandă disconnect.

Comportamentul de auto-soft-reset poate fi controlat de comanda resume. Acest lucru poate fi util pentru a folosi comanda eval pentru a inspecta starea dispozitivului. Comanda soft-reset poate fi folosită pentru a efectua un soft-reset explicit în mijlocul unei secvențe de comenzi.

Scurtături¶

Scurtăturile pot fi definite folosind sistemul de macrocomenzi. Scurtăturile încorporate sunt:

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

Scurtături suplimentare pot fi definite în fișierul de configurare al utilizatorului mpremote/config.py, aflat în Directorul de Configurare al Utilizatorului. Locația corectă pentru fiecare sistem de operare este determinată folosind modulul platformdirs.

Aceasta este de obicei: - $XDG_CONFIG_HOME/mpremote/config.py - $HOME/.config/mpremote/config.py - $env:LOCALAPPDATA/mpremote/config.py

Fișierul config.py ar trebui să definească un dicționar numit commands. Cheile acestui dicționar sunt scurtăturile, iar valorile sunt fie un șir de caractere, fie o listă de șiruri de caractere:

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

Comanda c33 este înlocuită cu connect id:334D335C3138.

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

Comanda test este înlocuită cu mount . exec "import test".

Scurtăturile pot accepta, de asemenea, argumente. De exemplu:

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

Rularea mpremote multiply 3 7 va seta x și y ca variabile pe dispozitiv, apoi va evalua expresia x*y.

Un exemplu de config.py ar putea arăta astfel:

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.
}

Exemple¶

mpremote

Se conectează la primul dispozitiv disponibil și rulează implicit comanda repl.

mpremote a1

Se conectează la dispozitivul de la /dev/ttyACM1 (Linux) și rulează implicit comanda repl. Consultați scurtăturile de mai sus.

mpremote c1

Se conectează la dispozitivul de la COM1 (Windows) și rulează implicit comanda repl. Consultați scurtăturile de mai sus.

mpremote connect /dev/ttyUSB0

Specifică explicit la ce dispozitiv să se conecteze și, ca mai sus, rulează implicit comanda repl.

mpremote a1 ls

Se conectează la dispozitivul de la /dev/ttyACM1 și apoi rulează comanda ls.

Este echivalent cu mpremote connect /dev/ttyACM1 fs ls.

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

Rulează comanda Python specificată și afișează orice ieșire. Acest lucru este echivalent cu tastarea comenzii la promptul REPL.

mpremote eval 1/2 eval 3/4

Evaluează fiecare expresie pe rând și afișează rezultatele.

mpremote a0 eval 1/2 a1 eval 3/4

Evaluează 1/2 pe dispozitivul de la /dev/ttyACM0, apoi 3/4 pe dispozitivul de la /dev/ttyACM1, afișând fiecare rezultat.

mpremote resume exec "print_state_info()" soft-reset

Se conectează la dispozitiv fără a declanșa un soft reset și execută funcția print_state_info() (de exemplu, pentru a afla informații despre starea curentă a programului), apoi declanșează un soft-reset.

mpremote reset sleep 0.5 bootloader

Efectuează un reset hardware al dispozitivului, așteaptă 500ms pentru ca acesta să devină disponibil, apoi intră în bootloader.

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

Actualizează copia fișierului utils/driver.py de pe dispozitiv, apoi execută scriptul local test.py pe dispozitiv. test.py nu este niciodată copiat în sistemul de fișiere al dispozitivului, ci este rulat din RAM.

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

Actualizează copia fișierului utils/driver.py de pe dispozitiv, apoi execută app.py pe dispozitiv.

Acesta este un flux de lucru obișnuit de dezvoltare pentru a actualiza un singur fișier și apoi a reporni programul. În acest scenariu, main.py de pe dispozitiv ar face, de asemenea, import app.

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

Actualizează copia fișierului utils/driver.py de pe dispozitiv, apoi declanșează un soft-reset pentru a reporni programul, și apoi monitorizează ieșirea prin comanda repl.

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

La fel ca mai sus, dar actualizează mai întâi întregul director utils.

mpremote mount .

Montează directorul local curent la /remote pe dispozitiv și pornește o sesiune repl care va folosi /remote ca director de lucru.

mpremote mount . exec "import demo"

După montarea directorului local curent, execută demo.py din directorul montat.

mpremote mount app run test.py

După montarea directorului local app ca /remote pe dispozitiv, execută fișierul local test.py din directorul curent al gazdei fără a-l copia în sistemul de fișiere.

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

După montarea directorului local curent, execută demo.py din directorul montat de fiecare dată când se apasă Ctrl-J.

Va trebui mai întâi să apăsați Ctrl-D pentru a reseta starea interpretorului (ceea ce va păstra montarea) înainte de a apăsa Ctrl-J pentru a reimporta demo.py.

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

La fel ca mai sus, dar execută conținutul fișierului local demo.py la REPL de fiecare dată când se apasă Ctrl-K. Ca mai sus, folosiți Ctrl-D pentru a reseta mai întâi starea interpretorului.

mpremote cat boot.py

Afișează conținutul fișierului boot.py de pe dispozitiv.

mpremote edit utils/driver.py

Editează utils/driver.py de pe dispozitiv folosind $EDITOR-ul dvs. local.

mpremote cp :main.py .

Copiază main.py de pe dispozitiv în directorul local.

mpremote cp main.py :

Copiază main.py din directorul local pe dispozitiv.

mpremote cp :a.py :b.py

Copiază a.py de pe dispozitiv în b.py pe dispozitiv.

mpremote cp -r dir/ :

Copiază recursiv directorul local dir pe dispozitivul la distanță.

mpremote cp a.py b.py : + repl

Copiază a.py și b.py din directorul local pe dispozitiv, apoi rulează comanda repl.

mpremote mip install aioble

Instalează pachetul aioble din micropython-lib pe dispozitiv. Consultați Gestionarea pachetelor.

mpremote mip install github:org/repo@branch

Instalează pachetul din ramura specificată de la org/repo de pe GitHub pe dispozitiv. Consultați Gestionarea pachetelor.

mpremote mip install gitlab:org/repo@branch

Instalează pachetul din ramura specificată de la org/repo de pe GitLab pe dispozitiv. Consultați Gestionarea pachetelor.

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

Instalează pachetul functools din micropython-lib în directorul /flash/third-party de pe dispozitiv. Consultați Gestionarea pachetelor.