Vzdálené ovládání MicroPythonu: mpremote¶

Nástroj příkazové řádky mpremote poskytuje integrovanou sadu utilit pro vzdálenou interakci se zařízením s MicroPythonem, správu jeho souborového systému a automatizaci přes sériové připojení. Funguje se všemi kamerami OpenMV Cam přes jejich sériové připojení po USB a je alternativou k OpenMV IDE z příkazové řádky pro skriptovací a automatizační pracovní postupy.

Chcete-li mpremote používat, nejprve jej nainstalujte pomocí pip:

$ pip install --user mpremote

Nebo pomocí pipx:

$ pipx install mpremote

Nejjednodušší způsob, jak tento nástroj použít, je spustit jej bez jakýchkoli argumentů:

$ mpremote

Tento příkaz automaticky detekuje a připojí se k prvnímu dostupnému sériovému zařízení po USB a poskytne interaktivní terminál, který můžete použít pro přístup k REPL a výstupu vašeho programu. Sériové porty se otevírají v exkluzivním režimu, takže spuštění druhé (nebo třetí atd.) instance mpremote se připojí k dalším sériovým zařízením, pokud jsou nějaká dostupná.

pipx vám navíc umožňuje spustit mpremote přímo bez předchozí instalace:

$ pipx run mpremote ...args

Příkazy¶

mpremote podporuje zadání série příkazů na příkazové řádce, které postupně provedou různé akce na vzdáleném zařízení s MicroPythonem. Pro představu, jak to funguje, a pro některé běžné kombinace příkazů viz sekci s příklady níže.

Každý příkaz má tvar <command name> [--options] [args...]. U příkazů, které podporují více argumentů (např. seznam souborů), lze seznam argumentů ukončit znakem +.

Pokud není zadán žádný příkaz, výchozím příkazem je repl. Navíc pokud nějaký příkaz potřebuje přístup k zařízení a žádný dřívější connect nebyl zadán, přidá se implicitní connect auto.

Aby se zařízení dostalo do známého stavu pro libovolný akční příkaz (kromě repl), mpremote po připojení zastaví všechny běžící programy a před spuštěním prvního příkazu provede měkký reset zařízení. Toto chování můžete řídit pomocí příkazů resume a soft-reset. Více podrobností viz automatické připojení a automatický měkký reset.

Lze zadat více příkazů a budou spuštěny postupně.

Úplný seznam podporovaných příkazů je:

connect ¶

Připojí se k zadanému zařízení podle názvu:

$ mpremote connect <device>

<device> může být jedno z:

list: vypíše dostupná zařízení
auto: připojí se k prvnímu dostupnému sériovému portu po USB
id:<serial>: připojí se k zařízení se sériovým číslem USB <serial> (druhý sloupec ve výstupu příkazu connect list)
port:<path>: připojí se k zařízení se zadanou cestou (první sloupec ve výstupu příkazu connect list
rfc2217://<host>:<port>: připojí se k zařízení pomocí sériové komunikace přes TCP (např. síťový sériový port založený na RFC2217)
jakýkoli platný název/cesta zařízení pro připojení k danému zařízení

Poznámka: Místo příkazu connect existuje několik předdefinovaných zkratek pro běžné cesty zařízení. Například zkratkový příkaz a0 je ekvivalentní connect /dev/ttyACM0 (Linux) nebo c1 pro COM1 (Windows).

Poznámka: Možnost auto detekuje pouze sériové porty po USB, tj. sériový port, který má přidružené USB VID/PID (tj. zařízení typu CDC/ACM nebo FTDI). Jiné typy sériových portů nebudou automaticky detekovány.

disconnect ¶

Odpojí aktuální zařízení:

$ mpremote disconnect

Po odpojení je povolen automatický měkký reset.

resume ¶

Zachová existující stav interpretu pro následující příkazy:

$ mpremote resume

Toto zakáže automatický měkký reset. To je užitečné, pokud chcete spustit následující příkaz na desce, aniž byste ji nejprve měkce resetovali.

soft-reset ¶

Provede měkký reset zařízení:

$ mpremote soft-reset

Toto vymaže Python haldu a restartuje interpret. Také zabrání tomu, aby následující příkaz spustil automatický měkký reset.

repl ¶

Vstoupí do REPL na připojeném zařízení:

$ mpremote repl [--options]

Možnosti jsou:

--escape-non-printable, pro tisk netisknutelných bajtů/znaků jako jejich hexadecimální kód
--capture <file>, pro zachycení výstupu relace REPL do zadaného souboru
--inject-code <string>, pro zadání znaků, které se vloží do REPL po stisknutí Ctrl-J. To vám umožňuje automatizovat běžný příkaz.
--inject-file <file>, pro zadání souboru, který se vloží do REPL po stisknutí Ctrl-K. To vám umožňuje spustit soubor (např. obsahující nějaký užitečný inicializační kód nebo dokonce program, na kterém právě pracujete).

Když běží příkaz repl, můžete pomocí Ctrl-] nebo Ctrl-x jej ukončit.

Poznámka: Název „REPL“ zde odráží běžné použití tohoto příkazu pro přístup k Read Eval Print Loop běžícímu na zařízení s MicroPythonem. Přesně řečeno, příkaz repl funguje pouze jako terminál (nebo „sériový monitor“) pro přístup k zařízení. Protože tento příkaz nespouští chování automatického resetu, znamená to, že pokud aktuálně běží nějaký program, budete jej muset nejprve přerušit pomocí Ctrl-C, abyste se dostali do REPL, což vám pak umožní přístup ke stavu programu. Můžete také použít mpremote soft-reset repl k získání „čistého“ REPL s vymazaným veškerým stavem programu.

eval ¶

Vyhodnotí a vytiskne výsledek výrazu v Pythonu:

$ mpremote eval <string>

exec ¶

Spustí zadaný kód v Pythonu:

$ mpremote exec <string>

Ve výchozím nastavení mpremote exec zobrazí veškerý výstup výrazu, dokud neskončí. Lze zadat příznak --no-follow, který se okamžitě vrátí a nechá zařízení vyhodnocovat výraz na pozadí.

run ¶

Spustí skript z lokálního souborového systému:

$ mpremote run <file.py>

Toto spustí soubor přímo z RAM na zařízení, aniž by se kopíroval do souborového systému. To je velmi užitečný způsob, jak iterovat na vývoji jednoho kusu kódu, aniž byste se museli starat o jeho nasazení do souborového systému.

Ve výchozím nastavení mpremote run zobrazí veškerý výstup skriptu, dokud neskončí. Lze zadat příznak --no-follow, který se okamžitě vrátí a nechá zařízení spouštět skript na pozadí.

fs ¶

Provede příkazy souborového systému na zařízení:

$ mpremote fs <sub-command>

<sub-command> může být:

cat <file..> pro zobrazení obsahu souboru nebo souborů na zařízení
ls pro výpis aktuálního adresáře
ls <dirs...> pro výpis zadaných adresářů
cp [-rf] <src...> <dest> pro kopírování souborů
rm [-r] <src...> pro odstranění souborů nebo složek na zařízení
mkdir <dirs...> pro vytvoření adresářů na zařízení
rmdir <dirs...> pro odstranění adresářů na zařízení
touch <file..> pro vytvoření souborů (pokud ještě neexistují)
sha256sum <file..> pro výpočet kontrolního součtu SHA256 souborů
tree [-vsh] <dirs...> pro vytisknutí stromu zadaných adresářů

Příkaz cp používá konvenci, kde úvodní : představuje vzdálenou cestu. Bez úvodního : se jedná o lokální cestu. To je založeno na konvenci používané klientem Secure Copy Protocol (scp).

Takže například mpremote fs cp main.py :main.py zkopíruje main.py z aktuálního lokálního adresáře na vzdálený souborový systém, zatímco mpremote fs cp :main.py main.py zkopíruje main.py ze zařízení zpět do aktuálního adresáře.

Příkaz mpremote rm -r přijímá relativní i absolutní cesty. Použijte : pro odkaz na aktuální vzdálený pracovní adresář (cwd), aby bylo možné odstranit strom adresářů z výchozí cesty zařízení (např. /flash, /). Použijte -v/--verbose pro zobrazení odstraňovaných souborů.

Například:

mpremote rm -r :libs odstraní adresář libs a všechny jeho podřízené položky ze zařízení.
mpremote rm -rv :/sd odstraní všechny soubory z připojené SD karty a vyústí v neblokující varování. Připojení zůstane zachováno.
mpremote rm -rv :/ odstraní všechny soubory na zařízení, včetně těch umístěných v připojených vfs, jako jsou /sd nebo /flash. Po odstranění všech složek a souborů to také vrátí chybu, aby se napodobilo chování unixového rm -rf /.

Varování

Neexistuje žádný podporovaný způsob, jak obnovit soubory odstraněné pomocí mpremote rm -r :. Používejte prosím s opatrností.

Příkaz tree vytiskne strom zadaných adresářů. Použití možnosti --size/-s vytiskne velikost každého souboru, nebo použijte --human/-h pro použití více čitelného formátu. Poznámka: Velikost adresáře se tiskne pouze tehdy, když souborový systém zařízení hlásí nenulovou velikost. Možnost -v lze použít k zahrnutí názvu sériového zařízení do výstupu.

Všechny ostatní příkazy implicitně předpokládají, že cesta je vzdálená, ale : lze volitelně použít pro jasnost.

Všechny dílčí příkazy souborového systému přijímají více argumentů cesty, takže pokud je v sekvenci další příkaz, musíte použít + k ukončení argumentů, např.

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

Toto zkopíruje soubor na zařízení a poté vstoupí do REPL. + zabrání tomu, aby byl "repl" interpretován jako cesta.

Příkaz cp podporuje možnost -r pro rekurzivní kopírování. Ve výchozím nastavení cp přeskočí kopírování souborů na vzdálené zařízení, pokud se hash SHA256 zdrojového a cílového souboru shoduje. Pro vynucení kopírování bez ohledu na hash použijte možnost -f.

Poznámka: Pro pohodlí jsou všechny dílčí příkazy souborového systému také dostupné jako běžné příkazy, tj. můžete napsat mpremote cp ... místo mpremote fs cp ....

df ¶

Zjistí volné/použité místo na zařízení:

$ mpremote df

Příkaz df vytiskne statistiky velikosti/použitého/volného místa pro souborový systém zařízení, podobně jako unixový příkaz df.

edit ¶

Upraví soubor na zařízení:

$ mpremote edit <files...>

Příkaz edit zkopíruje každý soubor ze zařízení do lokálního dočasného adresáře a poté spustí váš editor pro každý soubor (definovaný proměnnou prostředí $EDITOR). Pokud editor úspěšně skončí, aktualizovaný soubor se zkopíruje zpět na zařízení.

mip ¶

Nainstaluje balíčky z micropython-lib (nebo GitHubu) pomocí nástroje mip:

$ mpremote mip install <packages...>

Více informací viz Správa balíčků.

mount ¶

Připojí lokální adresář na vzdálené zařízení:

$ mpremote mount [options] <local-dir>

To umožní vzdálenému zařízení vidět adresář lokálního hostitele, jako by to byl jeho vlastní souborový systém. To je užitečné pro vývoj a vyhýbá se potřebě kopírovat soubory na zařízení, zatímco na nich pracujete.

Zařízení nainstaluje ovladač souborového systému, který se poté připojí v VFS zařízení jako /remote, který používá sériové připojení k mpremote jako postranní kanál pro přístup k souborům. Zařízení bude mít svůj aktuální pracovní adresář (přes os.chdir) nastaven na /remote, takže importy a přístup k souborům budou probíhat tam místo výchozí cesty souborového systému, dokud je připojení aktivní.

Poznámka: Pokud po příkazu mount nenásleduje v sekvenci další akce, na konec sekvence se implicitně přidá příkaz repl.

Během používání Ctrl-D spustí měkký reset jako obvykle, ale připojení se automaticky znovu obnoví. Pokud však jednotka při spuštění spouští main.py, opětovné připojení nemůže proběhnout. V takovém případě lze použít měkký restart v raw režimu: Ctrl-A Ctrl-D pro restart, poté Ctrl-B pro návrat do normálního repl, ve kterém bude připojení připraveno.

Možnosti jsou:

-l, --unsafe-links: Ve výchozím nastavení se vyvolá chyba, pokud zařízení přistupuje k souboru nebo adresáři, který je mimo (o jednu nebo více úrovní adresářů výše) lokální adresář, který je připojen. Tato možnost zakáže tuto kontrolu pro symbolické odkazy, což umožní zařízení následovat symbolické odkazy mimo lokální adresář.

unmount ¶

Odpojí lokální adresář od vzdáleného zařízení:

$ mpremote umount

K tomu dochází automaticky, když mpremote skončí, ale lze jej použít v sekvenci k odpojení dřívějšího připojení před spuštěním následujících příkazů.

romfs ¶

Spravuje ROMFS oddíly na zařízení:

$ mpremote romfs <sub-command>

<sub-command> může být:

romfs query pro výpis všech dostupných ROMFS oddílů a jejich velikosti
romfs [-o <output>] build <source> pro vytvoření ROMFS obrazu ze zadaného zdrojového adresáře; výchozí výstupní soubor je zdroj s příponou .romfs
romfs [-p <partition>] deploy <source> pro nasazení ROMFS obrazu na zařízení; pokud je zdrojem adresář, vytvoří se také dočasný ROMFS obraz

Dílčí příkazy build a deploy oba podporují možnost -m/--mpy pro automatickou kompilaci souborů .py na .mpy při vytváření ROMFS obrazu. Tato možnost je ve výchozím nastavení povolena, ale funguje pouze tehdy, pokud byl nainstalován Python balíček mpy_cross (např. přes pip install mpy_cross). Pokud balíček není nainstalován, vytiskne se varování a soubory .py zůstanou tak, jak jsou. Kompilaci souborů .py lze zakázat možností --no-mpy.

rtc ¶

Nastaví/získá hodiny zařízení (RTC):

$ mpremote rtc

Toto se dotáže RTC zařízení na aktuální čas a vytiskne jej jako n-tici datetime.

$ mpremote rtc --set

Toto nastaví RTC zařízení na aktuální čas hostitelského PC.

sleep ¶

Pozastaví (zpozdí) provádění před spuštěním dalšího příkazu:

$ mpremote sleep 0.5

Toto pozastaví provádění sekvence příkazů na zadanou dobu v sekundách, např. aby se počkalo, až zařízení něco udělá.

reset ¶

Provede tvrdý reset zařízení:

$ mpremote reset

Poznámka: tvrdý reset je ekvivalentní machine.reset().

bootloader ¶

Vstoupí do bootloaderu:

$ mpremote bootloader

Toto přiměje zařízení vstoupit do svého bootloaderu. Bootloader je specifický pro danou desku — podrobnosti viz sekce Recovery and debug pins v rychlé referenci vaší desky.

Automatické připojení a měkký reset¶

Připojení a odpojení bude provedeno automaticky na začátku a na konci spuštění nástroje, pokud takové příkazy nejsou explicitně zadány. Automatické připojení vyhledá první dostupné sériové zařízení po USB.

Po připojení k zařízení mpremote v případě potřeby automaticky provede měkký reset zařízení. To vymaže Python haldu a restartuje interpret, čímž zajistí, že následující kód v Pythonu se spustí v čerstvém prostředí. Automatický měkký reset se provede při prvním spuštění jednoho z následujících příkazů: mount, eval, exec, run, fs. Po prvním provedení měkkého resetu se již znovu automaticky neprovede, dokud nebude vydán příkaz disconnect.

Chování automatického měkkého resetu lze řídit příkazem resume. To může být užitečné pro použití příkazu eval k prozkoumání stavu zařízení. Příkaz soft-reset lze použít k provedení explicitního měkkého resetu uprostřed sekvence příkazů.

Zkratky¶

Zkratky lze definovat pomocí systému maker. Vestavěné zkratky jsou:

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

Další zkratky lze definovat v uživatelském konfiguračním souboru mpremote/config.py, umístěném v adresáři uživatelské konfigurace. Správné umístění pro každý OS se určuje pomocí modulu platformdirs.

To je obvykle: - $XDG_CONFIG_HOME/mpremote/config.py - $HOME/.config/mpremote/config.py - $env:LOCALAPPDATA/mpremote/config.py

Soubor config.py by měl definovat slovník s názvem commands. Klíče tohoto slovníku jsou zkratky a hodnoty jsou buď řetězec, nebo seznam řetězců:

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

Příkaz c33 je nahrazen příkazem connect id:334D335C3138.

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

Příkaz test je nahrazen příkazem mount . exec "import test".

Zkratky mohou také přijímat argumenty. Například:

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

Spuštění mpremote multiply 3 7 nastaví x a y jako proměnné na zařízení a poté vyhodnotí výraz x*y.

Příklad config.py by mohl vypadat takto:

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

Příklady¶

mpremote

Připojí se k prvnímu dostupnému zařízení a implicitně spustí příkaz repl.

mpremote a1

Připojí se k zařízení na /dev/ttyACM1 (Linux) a implicitně spustí příkaz repl. Viz zkratky výše.

mpremote c1

Připojí se k zařízení na COM1 (Windows) a implicitně spustí příkaz repl. Viz zkratky výše.

mpremote connect /dev/ttyUSB0

Explicitně určí, ke kterému zařízení se připojit, a stejně jako výše implicitně spustí příkaz repl.

mpremote a1 ls

Připojí se k zařízení na /dev/ttyACM1 a poté spustí příkaz ls.

Je to ekvivalentní mpremote connect /dev/ttyACM1 fs ls.

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

Spustí zadaný příkaz v Pythonu a zobrazí veškerý výstup. Toto je ekvivalentní zadání příkazu na výzvě REPL.

mpremote eval 1/2 eval 3/4

Postupně vyhodnotí každý výraz a vytiskne výsledky.

mpremote a0 eval 1/2 a1 eval 3/4

Vyhodnotí 1/2 na zařízení na /dev/ttyACM0, poté 3/4 na zařízení na /dev/ttyACM1 a vytiskne každý výsledek.

mpremote resume exec "print_state_info()" soft-reset

Připojí se k zařízení bez spuštění měkkého resetu a spustí funkci print_state_info() (např. pro zjištění informací o aktuálním stavu programu), poté spustí měkký reset.

mpremote reset sleep 0.5 bootloader

Provede tvrdý reset zařízení, počká 500 ms, než bude dostupné, a poté vstoupí do bootloaderu.

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

Aktualizuje kopii utils/driver.py na zařízení a poté spustí lokální skript test.py na zařízení. test.py se nikdy nekopíruje do souborového systému zařízení, místo toho se spustí z RAM.

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

Aktualizuje kopii utils/driver.py na zařízení a poté spustí app.py na zařízení.

Toto je běžný vývojový pracovní postup pro aktualizaci jednoho souboru a následné opětovné spuštění programu. V tomto scénáři by váš main.py na zařízení také provedl import app.

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

Aktualizuje kopii utils/driver.py na zařízení, poté spustí měkký reset pro restart vašeho programu a následně sleduje výstup pomocí příkazu repl.

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

Stejné jako výše, ale nejprve aktualizuje celý adresář utils.

mpremote mount .

Připojí aktuální lokální adresář na /remote na zařízení a spustí relaci repl, která bude používat /remote jako pracovní adresář.

mpremote mount . exec "import demo"

Po připojení aktuálního lokálního adresáře spustí demo.py z připojeného adresáře.

mpremote mount app run test.py

Po připojení lokálního adresáře app jako /remote na zařízení spustí lokální test.py z aktuálního adresáře hostitele, aniž by jej kopíroval do souborového systému.

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

Po připojení aktuálního lokálního adresáře spustí demo.py z připojeného adresáře pokaždé, když je stisknuto Ctrl-J.

Nejprve budete muset stisknout Ctrl-D pro resetování stavu interpretu (což zachová připojení), než stisknete Ctrl-J pro opětovný import demo.py.

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

Stejné jako výše, ale spustí obsah lokálního souboru demo.py v REPL pokaždé, když je stisknuto Ctrl-K. Stejně jako výše použijte nejprve Ctrl-D pro resetování stavu interpretu.

mpremote cat boot.py

Zobrazí obsah boot.py na zařízení.

mpremote edit utils/driver.py

Upraví utils/driver.py na zařízení pomocí vašeho lokálního $EDITOR.

mpremote cp :main.py .

Zkopíruje main.py ze zařízení do lokálního adresáře.

mpremote cp main.py :

Zkopíruje main.py z lokálního adresáře na zařízení.

mpremote cp :a.py :b.py

Zkopíruje a.py na zařízení do b.py na zařízení.

mpremote cp -r dir/ :

Rekurzivně zkopíruje lokální adresář dir na vzdálené zařízení.

mpremote cp a.py b.py : + repl

Zkopíruje a.py a b.py z lokálního adresáře na zařízení a poté spustí příkaz repl.

mpremote mip install aioble

Nainstaluje balíček aioble z micropython-lib na zařízení. Viz Správa balíčků.

mpremote mip install github:org/repo@branch

Nainstaluje balíček ze zadané větve na org/repo na GitHubu na zařízení. Viz Správa balíčků.

mpremote mip install gitlab:org/repo@branch

Nainstaluje balíček ze zadané větve na org/repo na GitLabu na zařízení. Viz Správa balíčků.

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

Nainstaluje balíček functools z micropython-lib do adresáře /flash/third-party na zařízení. Viz Správa balíčků.