Kendali jarak jauh MicroPython: mpremote

Alat baris perintah mpremote menyediakan sekumpulan utilitas terintegrasi untuk berinteraksi dari jarak jauh, mengelola sistem berkas, dan mengotomatiskan perangkat MicroPython melalui koneksi serial. Alat ini bekerja dengan semua OpenMV Cam melalui koneksi serial USB, dan merupakan alternatif baris perintah untuk OpenMV IDE dalam alur kerja skrip dan otomasi.

Untuk menggunakan mpremote, instal terlebih dahulu melalui pip:

$ pip install --user mpremote

Atau melalui pipx:

$ pipx install mpremote

Cara paling sederhana menggunakan alat ini adalah dengan menjalankannya tanpa argumen apa pun:

$ mpremote

Perintah ini secara otomatis mendeteksi dan terhubung ke perangkat serial USB pertama yang tersedia, lalu menyediakan terminal interaktif yang dapat digunakan untuk mengakses REPL dan keluaran program Anda. Port serial dibuka dalam mode eksklusif, sehingga menjalankan instans kedua (atau ketiga, dll) dari mpremote akan terhubung ke perangkat serial berikutnya, jika ada yang tersedia.

Selain itu, pipx juga memungkinkan Anda menjalankan mpremote secara langsung tanpa menginstalnya terlebih dahulu:

$ pipx run mpremote ...args

Perintah

mpremote mendukung pemberian serangkaian perintah di baris perintah yang akan melakukan berbagai tindakan secara berurutan pada perangkat MicroPython jarak jauh. Lihat bagian contoh di bawah untuk memahami cara kerjanya dan beberapa kombinasi perintah yang umum.

Setiap perintah berbentuk <command name> [--options] [args...]. Untuk perintah yang mendukung beberapa argumen (misalnya daftar berkas), daftar argumen dapat diakhiri dengan +.

Jika tidak ada perintah yang ditentukan, perintah default adalah repl. Selain itu, jika ada perintah yang perlu mengakses perangkat dan tidak ada perintah connect sebelumnya, maka connect auto akan ditambahkan secara implisit.

Agar perangkat berada dalam keadaan yang diketahui untuk setiap perintah tindakan (kecuali repl), setelah terhubung mpremote akan menghentikan program yang sedang berjalan dan melakukan soft-reset perangkat sebelum menjalankan perintah pertama. Anda dapat mengontrol perilaku ini menggunakan perintah resume dan soft-reset. Lihat koneksi otomatis dan auto-soft-reset untuk detail lebih lanjut.

Beberapa perintah dapat ditentukan dan akan dijalankan secara berurutan.

Daftar lengkap perintah yang didukung adalah:

connect

Hubungkan ke perangkat yang ditentukan berdasarkan nama:

$ mpremote connect <device>

<device> dapat berupa salah satu dari:

  • list: menampilkan daftar perangkat yang tersedia

  • auto: menghubungkan ke port serial USB pertama yang tersedia

  • id:<serial>: menghubungkan ke perangkat dengan nomor serial USB <serial> (kolom kedua dari keluaran perintah connect list)

  • port:<path>: menghubungkan ke perangkat dengan jalur yang diberikan (kolom pertama dari keluaran perintah connect list

  • rfc2217://<host>:<port>: menghubungkan ke perangkat menggunakan serial melalui TCP (misalnya port serial jaringan berbasis RFC2217)

  • nama/jalur perangkat yang valid, untuk terhubung ke perangkat tersebut

Catatan: Alih-alih menggunakan perintah connect, tersedia beberapa pintasan yang telah ditentukan untuk jalur perangkat umum. Misalnya perintah pintasan a0 setara dengan connect /dev/ttyACM0 (Linux), atau c1 untuk COM1 (Windows).

Catatan: Opsi auto hanya akan mendeteksi port serial USB, yaitu port serial yang memiliki USB VID/PID terkait (perangkat CDC/ACM atau gaya FTDI). Jenis port serial lainnya tidak akan terdeteksi secara otomatis.

disconnect

Putuskan koneksi perangkat saat ini:

$ mpremote disconnect

Setelah pemutusan koneksi, auto-soft-reset diaktifkan.

resume

Pertahankan status interpreter yang ada untuk perintah berikutnya:

$ mpremote resume

Ini menonaktifkan auto-soft-reset. Ini berguna jika Anda ingin menjalankan perintah berikutnya pada papan tanpa melakukan soft-reset terlebih dahulu.

soft-reset

Lakukan soft-reset pada perangkat:

$ mpremote soft-reset

Ini akan membersihkan heap Python dan memulai ulang interpreter. Ini juga mencegah perintah berikutnya memicu auto-soft-reset.

repl

Masuk ke REPL pada perangkat yang terhubung:

$ mpremote repl [--options]

Opsi yang tersedia adalah:

  • --escape-non-printable, untuk mencetak byte/karakter yang tidak dapat dicetak sebagai kode hex-nya

  • --capture <file>, untuk menangkap keluaran sesi REPL ke berkas yang diberikan

  • --inject-code <string>, untuk menentukan karakter yang akan disuntikkan ke REPL saat Ctrl-J ditekan. Ini memungkinkan Anda mengotomatiskan perintah yang umum.

  • --inject-file <file>, untuk menentukan berkas yang akan disuntikkan ke REPL saat Ctrl-K ditekan. Ini memungkinkan Anda menjalankan berkas (misalnya berisi kode pengaturan yang berguna, atau bahkan program yang sedang Anda kerjakan).

Saat perintah repl berjalan, Anda dapat menggunakan Ctrl-] atau Ctrl-x untuk keluar.

Catatan: Nama "REPL" di sini mencerminkan penggunaan umum perintah ini untuk mengakses Read Eval Print Loop yang berjalan pada perangkat MicroPython. Secara ketat, perintah repl hanya berfungsi sebagai terminal (atau "monitor serial") untuk mengakses perangkat. Karena perintah ini tidak memicu perilaku auto-reset, ini berarti jika sebuah program sedang berjalan, Anda harus terlebih dahulu menghentikannya dengan Ctrl-C untuk masuk ke REPL, yang kemudian memungkinkan Anda mengakses status program. Anda juga dapat menggunakan mpremote soft-reset repl untuk mendapatkan REPL yang "bersih" dengan semua status program dihapus.

eval

Evaluasi dan cetak hasil ekspresi Python:

$ mpremote eval <string>

exec

Jalankan kode Python yang diberikan:

$ mpremote exec <string>

Secara default, mpremote exec akan menampilkan keluaran dari ekspresi sampai selesai. Flag --no-follow dapat ditentukan untuk segera kembali dan membiarkan perangkat menjalankan ekspresi di latar belakang.

run

Jalankan skrip dari sistem berkas lokal:

$ mpremote run <file.py>

Ini akan mengeksekusi berkas langsung dari RAM pada perangkat tanpa menyalinnya ke sistem berkas. Ini adalah cara yang sangat berguna untuk melakukan iterasi pengembangan sebuah potongan kode tanpa harus khawatir tentang menyebarkannya ke sistem berkas.

Secara default, mpremote run akan menampilkan keluaran dari skrip sampai selesai. Flag --no-follow dapat ditentukan untuk segera kembali dan membiarkan perangkat menjalankan skrip di latar belakang.

fs

Jalankan perintah sistem berkas pada perangkat:

$ mpremote fs <sub-command>

<sub-command> dapat berupa:

  • cat <file..> untuk menampilkan isi berkas atau beberapa berkas pada perangkat

  • ls untuk menampilkan direktori saat ini

  • ls <dirs...> untuk menampilkan direktori yang diberikan

  • cp [-rf] <src...> <dest> untuk menyalin berkas

  • rm [-r] <src...> untuk menghapus berkas atau folder pada perangkat

  • mkdir <dirs...> untuk membuat direktori pada perangkat

  • rmdir <dirs...> untuk menghapus direktori pada perangkat

  • touch <file..> untuk membuat berkas (jika belum ada)

  • sha256sum <file..> untuk menghitung jumlah SHA256 dari berkas

  • tree [-vsh] <dirs...> untuk mencetak struktur pohon dari direktori yang diberikan

Perintah cp menggunakan konvensi di mana tanda : di awal mewakili jalur jarak jauh. Tanpa tanda : di awal berarti jalur lokal. Ini didasarkan pada konvensi yang digunakan oleh klien Secure Copy Protocol (scp).

Misalnya, mpremote fs cp main.py :main.py menyalin main.py dari direktori lokal saat ini ke sistem berkas jarak jauh, sedangkan mpremote fs cp :main.py main.py menyalin main.py dari perangkat kembali ke direktori saat ini.

Perintah mpremote rm -r menerima jalur relatif maupun absolut. Gunakan : untuk merujuk ke direktori kerja jarak jauh saat ini (cwd) agar pohon direktori dapat dihapus dari jalur default perangkat (misalnya /flash, /). Gunakan -v/--verbose untuk melihat berkas yang sedang dihapus.

Sebagai contoh:

  • mpremote rm -r :libs akan menghapus direktori libs dan semua item di dalamnya dari perangkat.

  • mpremote rm -rv :/sd akan menghapus semua berkas dari SDCard yang dipasang dan menghasilkan peringatan non-blokir. Mount akan dipertahankan.

  • mpremote rm -rv :/ akan menghapus semua berkas pada perangkat, termasuk yang ada di vfs yang dipasang seperti /sd atau /flash. Setelah menghapus semua folder dan berkas, ini juga akan mengembalikan error untuk meniru perilaku rm -rf / pada unix.

Peringatan

Tidak ada cara yang didukung untuk memulihkan berkas yang dihapus oleh mpremote rm -r :. Harap gunakan dengan hati-hati.

Perintah tree akan mencetak struktur pohon dari direktori yang diberikan. Menggunakan opsi --size/-s akan mencetak ukuran setiap berkas, atau gunakan --human/-h untuk format yang lebih mudah dibaca manusia. Catatan: Ukuran direktori hanya dicetak jika ukuran non-nol dilaporkan oleh sistem berkas perangkat. Opsi -v dapat digunakan untuk menyertakan nama perangkat serial dalam keluaran.

Semua perintah lainnya secara implisit mengasumsikan jalur adalah jalur jarak jauh, tetapi tanda : dapat digunakan secara opsional untuk kejelasan.

Semua sub-perintah sistem berkas menerima beberapa argumen jalur, sehingga jika ada perintah lain dalam urutan, Anda harus menggunakan + untuk mengakhiri argumen, misalnya

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

Ini akan menyalin berkas ke perangkat lalu masuk ke REPL. Tanda + mencegah "repl" diinterpretasikan sebagai jalur.

Perintah cp mendukung opsi -r untuk membuat salinan rekursif. Secara default cp akan melewati penyalinan berkas ke perangkat jarak jauh jika hash SHA256 berkas sumber dan tujuan cocok. Untuk memaksa penyalinan terlepas dari hash, gunakan opsi -f.

Catatan: Untuk kemudahan, semua sub-perintah sistem berkas juga dijadikan alias sebagai perintah reguler, yaitu Anda dapat menulis mpremote cp ... alih-alih mpremote fs cp ....

df

Kueri ruang bebas/terpakai pada perangkat:

$ mpremote df

Perintah df akan mencetak statistik ukuran/terpakai/bebas untuk sistem berkas perangkat, mirip dengan perintah df pada Unix.

edit

Edit berkas pada perangkat:

$ mpremote edit <files...>

Perintah edit akan menyalin setiap berkas dari perangkat ke direktori sementara lokal lalu membuka editor Anda untuk setiap berkas (ditentukan oleh variabel lingkungan $EDITOR). Jika editor keluar dengan sukses, berkas yang diperbarui akan disalin kembali ke perangkat.

mip

Instal paket dari micropython-lib (atau GitHub) menggunakan alat mip:

$ mpremote mip install <packages...>

Lihat Manajemen paket untuk informasi lebih lanjut.

mount

Pasang direktori lokal pada perangkat jarak jauh:

$ mpremote mount [options] <local-dir>

Ini memungkinkan perangkat jarak jauh melihat direktori host lokal seolah-olah itu adalah sistem berkasnya sendiri. Ini berguna untuk pengembangan, dan menghindari kebutuhan menyalin berkas ke perangkat saat Anda sedang mengerjakannya.

Perangkat menginstal driver sistem berkas, yang kemudian dipasang di VFS perangkat sebagai /remote, yang menggunakan koneksi serial ke mpremote sebagai saluran samping untuk mengakses berkas. Direktori kerja saat ini perangkat (melalui os.chdir) akan diatur ke /remote sehingga impor dan akses berkas akan terjadi di sana alih-alih jalur sistem berkas default selama mount aktif.

Catatan: Jika perintah mount tidak diikuti oleh tindakan lain dalam urutan, perintah repl akan ditambahkan secara implisit di akhir urutan.

Selama penggunaan, Ctrl-D akan memicu soft-reset seperti biasa, tetapi mount akan secara otomatis terhubung kembali. Jika unit memiliki main.py yang berjalan saat startup, pemasangan ulang tidak dapat terjadi. Dalam kasus ini, reboot soft mode mentah dapat digunakan: Ctrl-A Ctrl-D untuk reboot, kemudian Ctrl-B untuk kembali ke repl normal di mana mount akan siap.

Opsi yang tersedia adalah:

  • -l, --unsafe-links: Secara default error akan muncul jika perangkat mengakses berkas atau direktori yang berada di luar (satu atau lebih level direktori di atas) direktori lokal yang dipasang. Opsi ini menonaktifkan pemeriksaan ini untuk tautan simbolis, memungkinkan perangkat mengikuti tautan simbolis di luar direktori lokal.

unmount

Lepaskan direktori lokal dari perangkat jarak jauh:

$ mpremote umount

Ini terjadi secara otomatis saat mpremote berakhir, tetapi dapat digunakan dalam urutan untuk melepaskan mount sebelumnya sebelum perintah berikutnya dijalankan.

romfs

Kelola partisi ROMFS pada perangkat:

$ mpremote romfs <sub-command>

<sub-command> dapat berupa:

  • romfs query untuk menampilkan daftar semua partisi ROMFS yang tersedia dan ukurannya

  • romfs [-o <output>] build <source> untuk membuat citra ROMFS dari direktori sumber yang diberikan; berkas keluaran default adalah nama sumber yang ditambahkan dengan .romfs

  • romfs [-p <partition>] deploy <source> untuk menyebarkan citra ROMFS ke perangkat; juga akan membuat citra ROMFS sementara jika sumber adalah direktori

Sub-perintah build dan deploy keduanya mendukung opsi -m/--mpy untuk mengompilasi berkas .py ke .mpy secara otomatis saat membuat citra ROMFS. Opsi ini diaktifkan secara default, tetapi hanya berfungsi jika paket Python mpy_cross telah diinstal (misalnya melalui pip install mpy_cross). Jika paket tidak diinstal, peringatan akan dicetak dan berkas .py tetap apa adanya. Kompilasi berkas .py dapat dinonaktifkan dengan opsi --no-mpy.

rtc

Atur/dapatkan jam perangkat (RTC):

$ mpremote rtc

Ini akan mengkueri RTC perangkat untuk waktu saat ini dan mencetaknya sebagai tuple datetime.

$ mpremote rtc --set

Ini akan mengatur RTC perangkat ke waktu saat ini di PC host.

sleep

Tidur (tunda) sebelum menjalankan perintah berikutnya:

$ mpremote sleep 0.5

Ini akan menjeda eksekusi urutan perintah selama durasi yang ditentukan dalam detik, misalnya untuk menunggu perangkat melakukan sesuatu.

reset

Hard reset perangkat:

$ mpremote reset

Catatan: hard reset setara dengan machine.reset().

bootloader

Masuk ke bootloader:

$ mpremote bootloader

Ini akan membuat perangkat masuk ke bootloader-nya. Bootloader bersifat spesifik untuk papan — lihat bagian Recovery and debug pins di referensi cepat papan Anda untuk detail lebih lanjut.

Koneksi otomatis dan soft-reset

Koneksi dan pemutusan akan dilakukan secara otomatis di awal dan akhir eksekusi alat, jika perintah tersebut tidak diberikan secara eksplisit. Koneksi otomatis akan mencari perangkat serial USB pertama yang tersedia.

Setelah terhubung ke perangkat, mpremote akan secara otomatis melakukan soft-reset pada perangkat jika diperlukan. Ini membersihkan heap Python dan memulai ulang interpreter, memastikan bahwa kode Python berikutnya dieksekusi dalam lingkungan yang bersih. Auto soft-reset dilakukan pertama kali salah satu perintah berikut dieksekusi: mount, eval, exec, run, fs. Setelah melakukan soft-reset untuk pertama kalinya, ini tidak akan dilakukan lagi secara otomatis, sampai perintah disconnect dikeluarkan.

Perilaku auto-soft-reset dapat dikontrol oleh perintah resume. Ini mungkin berguna untuk menggunakan perintah eval guna memeriksa status perangkat. Perintah soft-reset dapat digunakan untuk melakukan soft reset eksplisit di tengah urutan perintah.

Pintasan

Pintasan dapat didefinisikan menggunakan sistem makro. Pintasan bawaan adalah:

  • devs: Alias untuk connect list

  • a0, a1, a2, a3: Alias untuk connect /dev/ttyACMn

  • u0, u1, u2, u3: Alias untuk connect /dev/ttyUSBn

  • c0, c1, c2, c3: Alias untuk connect COMn

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

Pintasan tambahan dapat didefinisikan dalam berkas konfigurasi pengguna mpremote/config.py, yang terletak di Direktori Konfigurasi Pengguna. Lokasi yang tepat untuk setiap OS ditentukan menggunakan modul platformdirs.

Biasanya ini adalah: - $XDG_CONFIG_HOME/mpremote/config.py - $HOME/.config/mpremote/config.py - $env:LOCALAPPDATA/mpremote/config.py

Berkas config.py harus mendefinisikan kamus bernama commands. Kunci kamus ini adalah pintasan dan nilainya berupa string atau daftar-string:

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

Perintah c33 diganti dengan connect id:334D335C3138.

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

Perintah test diganti dengan mount . exec "import test".

Pintasan juga dapat menerima argumen. Sebagai contoh:

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

Menjalankan mpremote multiply 3 7 akan mengatur x dan y sebagai variabel pada perangkat, lalu mengevaluasi ekspresi x*y.

Contoh berkas config.py mungkin terlihat seperti:

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

Contoh

mpremote

Hubungkan ke perangkat pertama yang tersedia dan jalankan perintah repl secara implisit.

mpremote a1

Hubungkan ke perangkat di /dev/ttyACM1 (Linux) dan jalankan perintah repl secara implisit. Lihat pintasan di atas.

mpremote c1

Hubungkan ke perangkat di COM1 (Windows) dan jalankan perintah repl secara implisit. Lihat pintasan di atas.

mpremote connect /dev/ttyUSB0

Tentukan secara eksplisit perangkat mana yang akan dihubungkan, dan seperti di atas, jalankan perintah repl secara implisit.

mpremote a1 ls

Hubungkan ke perangkat di /dev/ttyACM1 lalu jalankan perintah ls.

Ini setara dengan mpremote connect /dev/ttyACM1 fs ls.

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

Jalankan perintah Python yang ditentukan dan tampilkan keluaran apa pun. Ini setara dengan mengetikkan perintah di prompt REPL.

mpremote eval 1/2 eval 3/4

Evaluasi setiap ekspresi secara berurutan dan cetak hasilnya.

mpremote a0 eval 1/2 a1 eval 3/4

Evaluasi 1/2 pada perangkat di /dev/ttyACM0, lalu 3/4 pada perangkat di /dev/ttyACM1, mencetak setiap hasil.

mpremote resume exec "print_state_info()" soft-reset

Hubungkan ke perangkat tanpa memicu soft reset dan jalankan fungsi print_state_info() (misalnya untuk mengetahui informasi tentang status program saat ini), lalu picu soft reset.

mpremote reset sleep 0.5 bootloader

Hard-reset perangkat, tunggu 500ms agar tersedia, lalu masuk ke bootloader.

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

Perbarui salinan utils/driver.py pada perangkat, lalu jalankan skrip lokal test.py pada perangkat. test.py tidak pernah disalin ke sistem berkas perangkat, melainkan dijalankan dari RAM.

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

Perbarui salinan utils/driver.py pada perangkat, lalu jalankan app.py pada perangkat.

Ini adalah alur kerja pengembangan yang umum untuk memperbarui satu berkas dan kemudian memulai ulang program Anda. Dalam skenario ini, main.py Anda pada perangkat juga akan melakukan import app.

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

Perbarui salinan utils/driver.py pada perangkat, lalu picu soft-reset untuk memulai ulang program Anda, dan kemudian pantau keluaran melalui perintah repl.

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

Sama seperti di atas, tetapi perbarui seluruh direktori utils terlebih dahulu.

mpremote mount .

Pasang direktori lokal saat ini di /remote pada perangkat dan mulai sesi repl yang akan menggunakan /remote sebagai direktori kerja.

mpremote mount . exec "import demo"

Setelah memasang direktori lokal saat ini, jalankan demo.py dari direktori yang dipasang.

mpremote mount app run test.py

Setelah memasang direktori lokal app sebagai /remote pada perangkat, jalankan lokal test.py dari direktori saat ini host tanpa menyalinnya ke sistem berkas.

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

Setelah memasang direktori lokal saat ini, jalankan demo.py dari direktori yang dipasang setiap kali Ctrl-J ditekan.

Anda harus terlebih dahulu menekan Ctrl-D untuk mereset status interpreter (yang akan mempertahankan mount) sebelum menekan Ctrl-J untuk mengimpor ulang demo.py.

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

Sama seperti di atas, tetapi menjalankan isi berkas lokal demo.py di REPL setiap kali Ctrl-K ditekan. Seperti di atas, gunakan Ctrl-D untuk mereset status interpreter terlebih dahulu.

mpremote cat boot.py

Menampilkan isi boot.py pada perangkat.

mpremote edit utils/driver.py

Edit utils/driver.py pada perangkat menggunakan $EDITOR lokal Anda.

mpremote cp :main.py .

Salin main.py dari perangkat ke direktori lokal.

mpremote cp main.py :

Salin main.py dari direktori lokal ke perangkat.

mpremote cp :a.py :b.py

Salin a.py pada perangkat ke b.py pada perangkat.

mpremote cp -r dir/ :

Salin secara rekursif direktori lokal dir ke perangkat jarak jauh.

mpremote cp a.py b.py : + repl

Salin a.py dan b.py dari direktori lokal ke perangkat, lalu jalankan perintah repl.

mpremote mip install aioble

Instal paket aioble dari micropython-lib ke perangkat. Lihat Manajemen paket.

mpremote mip install github:org/repo@branch

Instal paket dari cabang yang ditentukan di org/repo pada GitHub ke perangkat. Lihat Manajemen paket.

mpremote mip install gitlab:org/repo@branch

Instal paket dari cabang yang ditentukan di org/repo pada GitLab ke perangkat. Lihat Manajemen paket.

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

Instal paket functools dari micropython-lib ke direktori /flash/third-party pada perangkat. Lihat Manajemen paket.