MicroPython fjärrstyrning: mpremote

Kommandoradsverktyget mpremote tillhandahåller en integrerad uppsättning verktyg för att fjärrinteragera med, hantera filsystemet på och automatisera en MicroPython-enhet via en seriell anslutning. Det fungerar med alla OpenMV Cam-enheter över deras seriella USB-anslutning och är ett kommandoradsalternativ till OpenMV IDE för skript- och automatiseringsflöden.

För att använda mpremote installerar du det först via pip:

$ pip install --user mpremote

Eller via pipx:

$ pipx install mpremote

Det enklaste sättet att använda det här verktyget är helt enkelt att anropa det utan några argument:

$ mpremote

Det här kommandot upptäcker och ansluter automatiskt till den första tillgängliga seriella USB-enheten och tillhandahåller en interaktiv terminal som du kan använda för att komma åt REPL och programmets utdata. Seriella portar öppnas i exklusivt läge, så om du kör en andra (eller tredje, osv.) instans av mpremote ansluter den till efterföljande seriella enheter, om några är tillgängliga.

Dessutom låter pipx dig köra mpremote direkt utan att först installera det:

$ pipx run mpremote ...args

Kommandon

mpremote har stöd för att ges en serie kommandon på kommandoraden som utför olika åtgärder i tur och ordning på en fjärransluten MicroPython-enhet. Se exempelavsnittet nedan för att få en uppfattning om hur detta fungerar och för några vanliga kombinationer av kommandon.

Varje kommando har formen <command name> [--options] [args...]. För kommandon som stöder flera argument (t.ex. en lista med filer) kan argumentlistan avslutas med +.

Om inget kommando anges är standardkommandot repl. Om något kommando behöver komma åt enheten och ingen tidigare connect har angetts, läggs dessutom ett implicit connect auto till.

För att få enheten i ett känt tillstånd inför ett åtgärdskommando (utom repl), kommer mpremote när anslutningen är upprättad att stoppa eventuella program som körs och utföra en mjuk återställning av enheten innan det första kommandot körs. Du kan styra detta beteende med kommandona resume och soft-reset. Se automatisk anslutning och automatisk mjuk återställning för mer information.

Flera kommandon kan anges och de körs sekventiellt.

Den fullständiga listan över kommandon som stöds är:

connect

Anslut till en angiven enhet via namn:

$ mpremote connect <device>

<device> kan vara något av följande:

• list: lista tillgängliga enheter

• auto: anslut till den första tillgängliga seriella USB-porten

• id:<serial>: anslut till enheten med USB-serienumret <serial> (den andra kolumnen i utdata från kommandot connect list)

• port:<path>: anslut till enheten med den angivna sökvägen (den första kolumnen i utdata från kommandot connect list

• rfc2217://<host>:<port>: anslut till enheten med seriell över TCP (t.ex. en nätverksansluten seriell port baserad på RFC2217)

• valfritt giltigt enhetsnamn/sökväg, för att ansluta till den enheten

Obs: Istället för att använda kommandot connect finns det flera fördefinierade genvägar för vanliga enhetssökvägar. Till exempel är genvägskommandot a0 likvärdigt med connect /dev/ttyACM0 (Linux), eller c1 för COM1 (Windows).

Obs: Alternativet auto upptäcker endast seriella USB-portar, dvs. en seriell port som har ett tillhörande USB VID/PID (dvs. CDC/ACM- eller FTDI-liknande enheter). Andra typer av seriella portar upptäcks inte automatiskt.

disconnect

Koppla från den aktuella enheten:

$ mpremote disconnect

Efter en frånkoppling aktiveras automatisk mjuk återställning.

resume

Behåll det befintliga tolktillståndet för efterföljande kommandon:

$ mpremote resume

Detta inaktiverar automatisk mjuk återställning. Detta är användbart om du vill köra ett efterföljande kommando på ett kort utan att först utföra en mjuk återställning av det.

soft-reset

Utför en mjuk återställning av enheten:

$ mpremote soft-reset

Detta rensar Python-heapen och startar om tolken. Det förhindrar också att det efterföljande kommandot utlöser automatisk mjuk återställning.

repl

Gå in i REPL på den anslutna enheten:

$ mpremote repl [--options]

Alternativen är:

• --escape-non-printable, för att skriva ut icke-utskrivbara byte/tecken som deras hexkod

• --capture <file>, för att fånga utdata från REPL-sessionen till den angivna filen

• --inject-code <string>, för att ange tecken som ska injiceras i REPL när Ctrl-J trycks ned. Detta gör att du kan automatisera ett vanligt kommando.

• --inject-file <file>, för att ange en fil som ska injiceras i REPL när Ctrl-K trycks ned. Detta gör att du kan köra en fil (t.ex. innehållande någon användbar uppstartskod, eller till och med programmet du för närvarande arbetar med).

Medan kommandot repl körs kan du använda Ctrl-] eller Ctrl-x för att avsluta.

Obs: Namnet ”REPL” här återspeglar den vanliga användningen av detta kommando för att komma åt den Read Eval Print Loop som körs på MicroPython-enheten. Strikt sett fungerar kommandot repl bara som en terminal (eller ”seriell monitor”) för att komma åt enheten. Eftersom detta kommando inte utlöser det automatiska återställningsbeteendet innebär det att om ett program för närvarande körs måste du först avbryta det med Ctrl-C för att komma till REPL, vilket sedan låter dig komma åt programtillståndet. Du kan också använda mpremote soft-reset repl för att få en ”ren” REPL med allt programtillstånd rensat.

eval

Utvärdera och skriv ut resultatet av ett Python-uttryck:

$ mpremote eval <string>

exec

Kör den angivna Python-koden:

$ mpremote exec <string>

Som standard visar mpremote exec all utdata från uttrycket tills det avslutas. Flaggan --no-follow kan anges för att återgå omedelbart och låta enheten köra uttrycket i bakgrunden.

run

Kör ett skript från det lokala filsystemet:

$ mpremote run <file.py>

Detta kör filen direkt från RAM på enheten utan att kopiera den till filsystemet. Detta är ett mycket användbart sätt att iterera under utvecklingen av en enda kodbit utan att behöva oroa sig för att distribuera den till filsystemet.

Som standard visar mpremote run all utdata från skriptet tills det avslutas. Flaggan --no-follow kan anges för att återgå omedelbart och låta enheten köra skriptet i bakgrunden.

fs

Kör filsystemskommandon på enheten:

$ mpremote fs <sub-command>

<sub-command> kan vara:

• cat <file..> för att visa innehållet i en fil eller filer på enheten

• ls för att lista den aktuella katalogen

• ls <dirs...> för att lista de angivna katalogerna

• cp [-rf] <src...> <dest> för att kopiera filer

• rm [-r] <src...> för att ta bort filer eller mappar på enheten

• mkdir <dirs...> för att skapa kataloger på enheten

• rmdir <dirs...> för att ta bort kataloger på enheten

• touch <file..> för att skapa filerna (om de inte redan finns)

• sha256sum <file..> för att beräkna SHA256-summan av filer

• tree [-vsh] <dirs...> för att skriva ut ett träd över de angivna katalogerna

Kommandot cp använder en konvention där ett inledande : representerar en fjärrsökväg. Utan ett inledande : avses en lokal sökväg. Detta baseras på den konvention som används av Secure Copy Protocol-klienten (scp).

Så till exempel kopierar mpremote fs cp main.py :main.py main.py från den aktuella lokala katalogen till fjärrfilsystemet, medan mpremote fs cp :main.py main.py kopierar main.py från enheten tillbaka till den aktuella katalogen.

Kommandot mpremote rm -r accepterar både relativa och absoluta sökvägar. Använd : för att referera till den aktuella fjärrarbetskatalogen (cwd) för att tillåta att ett katalogträd tas bort från enhetens standardsökväg (t.ex. /flash, /). Använd -v/--verbose för att se vilka filer som tas bort.

Till exempel:

• mpremote rm -r :libs tar bort katalogen libs och alla dess underordnade objekt från enheten.

• mpremote rm -rv :/sd tar bort alla filer från ett monterat SD-kort och resulterar i en icke-blockerande varning. Monteringen behålls.

• mpremote rm -rv :/ tar bort alla filer på enheten, inklusive alla som finns i monterade vfs såsom /sd eller /flash. Efter att alla mappar och filer har tagits bort returnerar detta även ett fel för att efterlikna unix-beteendet rm -rf /.

Varning

Det finns inget stöd för att återställa filer som tagits bort med mpremote rm -r :. Använd med försiktighet.

Kommandot tree skriver ut ett träd över de angivna katalogerna. Med alternativet --size/-s skrivs storleken på varje fil ut, eller använd --human/-h för att använda ett mer lättläst format. Obs: Katalogstorlek skrivs endast ut när enhetens filsystem rapporterar en storlek som inte är noll. Alternativet -v kan användas för att inkludera namnet på den seriella enheten i utdata.

Alla andra kommandon antar implicit att sökvägen är en fjärrsökväg, men : kan valfritt användas för tydlighetens skull.

Alla filsystemsunderkommandon tar emot flera sökvägsargument, så om det finns ett annat kommando i sekvensen måste du använda + för att avsluta argumenten, t.ex.

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

Detta kopierar filen till enheten och går sedan in i REPL. + förhindrar att "repl" tolkas som en sökväg.

Kommandot cp stöder alternativet -r för att göra en rekursiv kopia. Som standard hoppar cp över att kopiera filer till fjärrenheten om SHA256-hashen för käll- och målfilen matchar. För att tvinga fram en kopiering oavsett hash använder du alternativet -f.

Obs: För bekvämlighets skull är alla filsystemsunderkommandon även aliasade som vanliga kommandon, dvs. du kan skriva mpremote cp ... istället för mpremote fs cp ....

df

Fråga efter ledigt/använt utrymme på enheten:

$ mpremote df

Kommandot df skriver ut statistik över storlek/använt/ledigt för enhetens filsystem, liknande Unix-kommandot df.

edit

Redigera en fil på enheten:

$ mpremote edit <files...>

Kommandot edit kopierar varje fil från enheten till en lokal temporär katalog och startar sedan din redigerare för varje fil (definierad av miljövariabeln $EDITOR). Om redigeraren avslutas korrekt kopieras den uppdaterade filen tillbaka till enheten.

mip

Installera paket från micropython-lib (eller GitHub) med verktyget mip:

$ mpremote mip install <packages...>

Se Pakethantering för mer information.

mount

Montera den lokala katalogen på fjärrenheten:

$ mpremote mount [options] <local-dir>

Detta gör att fjärrenheten kan se den lokala värdkatalogen som om den vore dess eget filsystem. Detta är användbart vid utveckling och undviker behovet av att kopiera filer till enheten medan du arbetar med dem.

Enheten installerar en filsystemsdrivrutin, som sedan monteras i enhetens VFS som /remote, vilken använder den seriella anslutningen till mpremote som en sidokanal för att komma åt filer. Enheten får sin aktuella arbetskatalog (via os.chdir) inställd på /remote så att importer och filåtkomst sker där istället för standardfilsystemsökvägen medan monteringen är aktiv.

Obs: Om kommandot mount inte följs av en annan åtgärd i sekvensen läggs ett repl-kommando implicit till i slutet av sekvensen.

Under användning utlöser Ctrl-D en mjuk återställning som vanligt, men monteringen återansluts automatiskt. Om enheten dock har en main.py som körs vid uppstart kan ommonteringen inte ske. I detta fall kan en mjuk omstart i råläge användas: Ctrl-A Ctrl-D för att starta om, sedan Ctrl-B för att komma tillbaka till den vanliga repl, varvid monteringen kommer att vara redo.

Alternativen är:

• -l, --unsafe-links: Som standard genereras ett fel om enheten kommer åt en fil eller katalog som ligger utanför (en eller flera katalognivåer upp) den lokala katalog som är monterad. Detta alternativ inaktiverar denna kontroll för symboliska länkar, vilket gör att enheten kan följa symboliska länkar utanför den lokala katalogen.

unmount

Avmontera den lokala katalogen från fjärrenheten:

$ mpremote umount

Detta sker automatiskt när mpremote avslutas, men det kan användas i en sekvens för att avmontera en tidigare montering innan efterföljande kommandon körs.

romfs

Hantera ROMFS-partitioner på enheten:

$ mpremote romfs <sub-command>

<sub-command> kan vara:

• romfs query för att lista alla tillgängliga ROMFS-partitioner och deras storlek

• romfs [-o <output>] build <source> för att skapa en ROMFS-avbild från den angivna källkatalogen; standardutdatafilen är källan med .romfs tillagt

• romfs [-p <partition>] deploy <source> för att distribuera en ROMFS-avbild till enheten; skapar även en temporär ROMFS-avbild om källan är en katalog

Underkommandona build och deploy stöder båda alternativet -m/--mpy för att automatiskt kompilera .py-filer till .mpy när ROMFS-avbilden skapas. Detta alternativ är aktiverat som standard, men fungerar endast om Python-paketet mpy_cross har installerats (t.ex. via pip install mpy_cross). Om paketet inte är installerat skrivs en varning ut och .py-filerna förblir som de är. Kompilering av .py-filer kan inaktiveras med alternativet --no-mpy.

rtc

Ställ in/hämta enhetens klocka (RTC):

$ mpremote rtc

Detta frågar enhetens RTC efter den aktuella tiden och skriver ut den som en datetime-tupel.

$ mpremote rtc --set

Detta ställer in enhetens RTC till värd-PC:ns aktuella tid.

sleep

Vänta (fördröj) innan nästa kommando körs:

$ mpremote sleep 0.5

Detta pausar körningen av kommandosekvensen under den angivna varaktigheten i sekunder, t.ex. för att vänta på att enheten gör något.

reset

Hård återställning av enheten:

$ mpremote reset

Obs: hård återställning är likvärdigt med machine.reset().

bootloader

Gå in i startladdaren:

$ mpremote bootloader

Detta gör att enheten går in i sin startladdare. Startladdaren är kortspecifik — se avsnittet Recovery and debug pins i kortets snabbreferens för detaljer.

Automatisk anslutning och mjuk återställning

Anslutning och frånkoppling sker automatiskt vid start och slut av verktygets körning, om sådana kommandon inte anges explicit. Automatisk anslutning söker efter den första tillgängliga seriella USB-enheten.

När mpremote har anslutit till en enhet utför det automatiskt en mjuk återställning av enheten vid behov. Detta rensar Python-heapen och startar om tolken, vilket säkerställer att efterföljande Python-kod körs i en ny miljö. Automatisk mjuk återställning utförs första gången ett av följande kommandon körs: mount, eval, exec, run, fs. Efter att en mjuk återställning har utförts för första gången görs den inte automatiskt igen förrän ett disconnect-kommando utfärdas.

Beteendet för automatisk mjuk återställning kan styras med kommandot resume. Detta kan vara användbart för att använda kommandot eval för att inspektera enhetens tillstånd. Kommandot soft-reset kan användas för att utföra en explicit mjuk återställning mitt i en sekvens av kommandon.

Genvägar

Genvägar kan definieras med makrosystemet. Inbyggda genvägar är:

• devs: Alias för connect list

• a0, a1, a2, a3: Alias för connect /dev/ttyACMn

• u0, u1, u2, u3: Alias för connect /dev/ttyUSBn

• c0, c1, c2, c3: Alias för connect COMn

• cat, edit, ls, cp, rm, mkdir, rmdir, touch: Alias för fs <sub-command>

Ytterligare genvägar kan definieras i användarkonfigurationsfilen mpremote/config.py, som finns i användarkonfigurationskatalogen. Rätt plats för varje operativsystem bestäms med hjälp av modulen platformdirs.

Detta är vanligtvis: - $XDG_CONFIG_HOME/mpremote/config.py - $HOME/.config/mpremote/config.py - $env:LOCALAPPDATA/mpremote/config.py

Filen config.py bör definiera en ordbok med namnet commands. Nycklarna i denna ordbok är genvägarna och värdena är antingen en sträng eller en lista med strängar:

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

Kommandot c33 ersätts av connect id:334D335C3138.

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

Kommandot test ersätts av mount . exec "import test".

Genvägar kan också ta emot argument. Till exempel:

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

Att köra mpremote multiply 3 7 ställer in x och y som variabler på enheten och utvärderar sedan uttrycket x*y.

En exempelfil config.py kan se ut så här:

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

Exempel

mpremote

Anslut till den första tillgängliga enheten och kör implicit kommandot repl.

mpremote a1

Anslut till enheten på /dev/ttyACM1 (Linux) och kör implicit kommandot repl. Se genvägar ovan.

mpremote c1

Anslut till enheten på COM1 (Windows) och kör implicit kommandot repl. Se genvägar ovan.

mpremote connect /dev/ttyUSB0

Ange explicit vilken enhet som ska anslutas till och kör, som ovan, implicit kommandot repl.

mpremote a1 ls

Anslut till enheten på /dev/ttyACM1 och kör sedan kommandot ls.

Det är likvärdigt med mpremote connect /dev/ttyACM1 fs ls.

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

Kör det angivna Python-kommandot och visa eventuell utdata. Detta är likvärdigt med att skriva kommandot vid REPL-prompten.

mpremote eval 1/2 eval 3/4

Utvärdera varje uttryck i tur och ordning och skriv ut resultaten.

mpremote a0 eval 1/2 a1 eval 3/4

Utvärdera 1/2 på enheten på /dev/ttyACM0, sedan 3/4 på enheten på /dev/ttyACM1, och skriv ut varje resultat.

mpremote resume exec "print_state_info()" soft-reset

Anslut till enheten utan att utlösa en mjuk återställning och kör funktionen print_state_info() (t.ex. för att ta reda på information om det aktuella programtillståndet), utlös sedan en mjuk återställning.

mpremote reset sleep 0.5 bootloader

Utför en hård återställning av enheten, vänta 500 ms tills den blir tillgänglig och gå sedan in i startladdaren.

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

Uppdatera kopian av utils/driver.py på enheten och kör sedan det lokala skriptet test.py på enheten. test.py kopieras aldrig till enhetens filsystem, utan körs istället från RAM.

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

Uppdatera kopian av utils/driver.py på enheten och kör sedan app.py på enheten.

Detta är ett vanligt utvecklingsflöde för att uppdatera en enda fil och sedan starta om programmet. I detta scenario skulle din main.py på enheten också göra import app.

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

Uppdatera kopian av utils/driver.py på enheten, utlös sedan en mjuk återställning för att starta om programmet och övervaka sedan utdata via kommandot repl.

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

Samma som ovan, men uppdatera först hela utils-katalogen.

mpremote mount .

Montera den aktuella lokala katalogen vid /remote på enheten och starta en repl-session som använder /remote som arbetskatalog.

mpremote mount . exec "import demo"

Efter montering av den aktuella lokala katalogen körs demo.py från den monterade katalogen.

mpremote mount app run test.py

Efter montering av den lokala katalogen app som /remote på enheten körs den lokala test.py från värdens aktuella katalog utan att den kopieras till filsystemet.

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

Efter montering av den aktuella lokala katalogen körs demo.py från den monterade katalogen varje gång Ctrl-J trycks ned.

Du måste först trycka på Ctrl-D för att återställa tolktillståndet (vilket bevarar monteringen) innan du trycker på Ctrl-J för att importera om demo.py.

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

Samma som ovan, men kör innehållet i den lokala filen demo.py i REPL varje gång Ctrl-K trycks ned. Som ovan, använd Ctrl-D för att först återställa tolktillståndet.

mpremote cat boot.py

Visar innehållet i boot.py på enheten.

mpremote edit utils/driver.py

Redigera utils/driver.py på enheten med din lokala $EDITOR.

mpremote cp :main.py .

Kopiera main.py från enheten till den lokala katalogen.

mpremote cp main.py :

Kopiera main.py från den lokala katalogen till enheten.

mpremote cp :a.py :b.py

Kopiera a.py på enheten till b.py på enheten.

mpremote cp -r dir/ :

Kopiera rekursivt den lokala katalogen dir till fjärrenheten.

mpremote cp a.py b.py : + repl

Kopiera a.py och b.py från den lokala katalogen till enheten och kör sedan kommandot repl.

mpremote mip install aioble

Installera paketet aioble från micropython-lib till enheten. Se Pakethantering.

mpremote mip install github:org/repo@branch

Installera paketet från den angivna grenen i org/repo på GitHub till enheten. Se Pakethantering.

mpremote mip install gitlab:org/repo@branch

Installera paketet från den angivna grenen i org/repo på GitLab till enheten. Se Pakethantering.

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

Installera paketet functools från micropython-lib till katalogen /flash/third-party på enheten. Se Pakethantering.