Дистанційне керування MicroPython: mpremote

Інструмент командного рядка mpremote надає інтегрований набір утиліт для дистанційної взаємодії з пристроєм MicroPython, керування його файловою системою та автоматизації роботи через послідовне з’єднання. Він працює з усіма камерами OpenMV Cam через їхнє USB послідовне з’єднання та є альтернативою командного рядка до OpenMV IDE для скриптів і автоматизованих робочих процесів.

Щоб використовувати mpremote, спочатку встановіть його через pip:

$ pip install --user mpremote

Або через pipx:

$ pipx install mpremote

Найпростіший спосіб використання цього інструменту — запустити його без аргументів:

$ mpremote

Ця команда автоматично виявляє та підключається до першого доступного USB послідовного пристрою і надає інтерактивний термінал, який можна використовувати для доступу до REPL та виводу вашої програми. Послідовні порти відкриваються у виключному режимі, тому запуск другого (або третього тощо) екземпляра mpremote підключиться до наступних послідовних пристроїв, якщо такі доступні.

Крім того, pipx також дозволяє безпосередньо запускати mpremote без попереднього встановлення:

$ pipx run mpremote ...args

Команди

mpremote підтримує виконання серії команд, вказаних у командному рядку, які виконують різні дії послідовно на віддаленому пристрої MicroPython. Перегляньте розділ прикладів нижче, щоб отримати уявлення про те, як це працює, та деякі типові комбінації команд.

Кожна команда має вигляд <command name> [--options] [args...]. Для команд, що підтримують кілька аргументів (наприклад, список файлів), список аргументів можна завершити символом +.

Якщо команду не вказано, команда за замовчуванням — repl. Крім того, якщо будь-яка команда потребує доступу до пристрою, а раніше connect не був вказаний, то неявно додається connect auto.

Щоб привести пристрій у відомий стан для будь-якої команди дії (крім repl), після підключення mpremote зупинить будь-яку запущену програму та виконає м’яке скидання пристрою перед запуском першої команди. Ви можете контролювати цю поведінку за допомогою команд resume та soft-reset. Детальніше дивіться автопідключення та автоматичне м’яке скидання.

Можна вказати кілька команд, і вони будуть виконані послідовно.

Повний список підтримуваних команд:

connect

Підключитися до вказаного пристрою за іменем:

$ mpremote connect <device>

<device> може бути одним із:

  • list: список доступних пристроїв

  • auto: підключення до першого доступного USB послідовного порту

  • id:<serial>: підключення до пристрою з серійним номером USB <serial> (другий стовпець виводу команди connect list)

  • port:<path>: підключення до пристрою за вказаним шляхом (перший стовпець виводу команди connect list

  • rfc2217://<host>:<port>: підключення до пристрою через послідовний зв’язок по TCP (наприклад, мережевий послідовний порт на основі RFC2217)

  • будь-яке допустиме ім’я/шлях до пристрою для підключення до нього

Примітка: Замість використання команди connect існують кілька заздалегідь визначених скорочень для типових шляхів до пристроїв. Наприклад, скорочення a0 еквівалентне connect /dev/ttyACM0 (Linux) або c1 для COM1 (Windows).

Примітка: Параметр auto виявляє лише USB послідовні порти, тобто послідовний порт, якому відповідає USB VID/PID (тобто CDC/ACM або пристрої типу FTDI). Інші типи послідовних портів не виявляються автоматично.

disconnect

Відключити поточний пристрій:

$ mpremote disconnect

Після відключення вмикається автоматичне м’яке скидання.

resume

Зберегти поточний стан інтерпретатора для наступних команд:

$ mpremote resume

Це вимикає автоматичне м’яке скидання. Корисно, якщо потрібно виконати наступну команду на платі без попереднього м’якого скидання.

soft-reset

Виконати м’яке скидання пристрою:

$ mpremote soft-reset

Це очистить купу Python та перезапустить інтерпретатор. Також запобігає тому, щоб наступна команда ініціювала автоматичне м’яке скидання.

repl

Увійти в REPL на підключеному пристрої:

$ mpremote repl [--options]

Параметри:

  • --escape-non-printable, для виведення недрукованих байтів/символів у вигляді їх шістнадцяткового коду

  • --capture <file>, для захоплення виводу сесії REPL до вказаного файлу

  • --inject-code <string>, для вказання символів, які вводяться в REPL при натисканні Ctrl-J. Це дозволяє автоматизувати типову команду.

  • --inject-file <file>, для вказання файлу, який вводиться в REPL при натисканні Ctrl-K. Це дозволяє запустити файл (наприклад, що містить корисний код налаштування або навіть програму, над якою ви зараз працюєте).

Поки виконується команда repl, можна використовувати Ctrl-] або Ctrl-x для виходу.

Примітка: Назва «REPL» тут відображає типове використання цієї команди для доступу до циклу Read Eval Print Loop, що виконується на пристрої MicroPython. Строго кажучи, команда repl лише функціонує як термінал (або «монітор послідовного порту») для доступу до пристрою. Оскільки ця команда не ініціює поведінку автоскидання, це означає, що якщо зараз виконується програма, спочатку потрібно перервати її комбінацією Ctrl-C, щоб потрапити до REPL, що дозволить отримати доступ до стану програми. Також можна використовувати mpremote soft-reset repl, щоб отримати «чистий» REPL з очищеним станом програми.

eval

Обчислити та вивести результат виразу Python:

$ mpremote eval <string>

exec

Виконати вказаний код Python:

$ mpremote exec <string>

За замовчуванням mpremote exec відображатиме будь-який вивід виразу до його завершення. Можна вказати прапорець --no-follow для негайного повернення та залишення пристрою виконувати вираз у фоновому режимі.

run

Запустити скрипт з локальної файлової системи:

$ mpremote run <file.py>

Це виконує файл безпосередньо з оперативної пам’яті пристрою без копіювання його до файлової системи. Це дуже зручний спосіб ітеративної розробки окремого фрагменту коду без необхідності розгортати його у файловій системі.

За замовчуванням mpremote run відображатиме будь-який вивід скрипту до його завершення. Можна вказати прапорець --no-follow для негайного повернення та залишення пристрою виконувати скрипт у фоновому режимі.

fs

Виконати команди файлової системи на пристрої:

$ mpremote fs <sub-command>

<sub-command> може бути:

  • cat <file..> для відображення вмісту файлу або файлів на пристрої

  • ls для відображення вмісту поточного каталогу

  • ls <dirs...> для відображення вмісту вказаних каталогів

  • cp [-rf] <src...> <dest> для копіювання файлів

  • rm [-r] <src...> для видалення файлів або папок на пристрої

  • mkdir <dirs...> для створення каталогів на пристрої

  • rmdir <dirs...> для видалення каталогів на пристрої

  • touch <file..> для створення файлів (якщо вони ще не існують)

  • sha256sum <file..> для обчислення суми SHA256 файлів

  • tree [-vsh] <dirs...> для виведення дерева вказаних каталогів

Команда cp використовує угоду, де символ : на початку позначає віддалений шлях. Відсутність символу : на початку означає локальний шлях. Це засновано на угоді, яку використовує клієнт Secure Copy Protocol (scp).

Наприклад, mpremote fs cp main.py :main.py копіює main.py з поточного локального каталогу до віддаленої файлової системи, тоді як mpremote fs cp :main.py main.py копіює main.py з пристрою назад до поточного каталогу.

Команда mpremote rm -r приймає як відносні, так і абсолютні шляхи. Використовуйте : для позначення поточного віддаленого робочого каталогу (cwd), щоб дерево каталогів можна було видалити із стандартного шляху пристрою (наприклад, /flash, /). Використовуйте -v/--verbose для перегляду файлів, що видаляються.

Наприклад:

  • mpremote rm -r :libs видалить каталог libs та всі його дочірні елементи з пристрою.

  • mpremote rm -rv :/sd видалить усі файли з підключеної SDCard і спричинить незаблокуюче попередження. Монтування буде збережено.

  • mpremote rm -rv :/ видалить усі файли на пристрої, включаючи розміщені у підключених vfs, таких як /sd або /flash. Після видалення всіх папок і файлів також повернеться помилка для імітації поведінки Unix rm -rf /.

Попередження

Підтримуваного способу відновлення файлів, видалених за допомогою mpremote rm -r :, не існує. Будь ласка, використовуйте з обережністю.

Команда tree виводить дерево вказаних каталогів. Використання параметра --size/-s виводить розмір кожного файлу, або --human/-h для більш зручного для людини формату. Примітка: Розмір каталогу виводиться лише тоді, коли файлова система пристрою повідомляє ненульовий розмір. Параметр -v можна використовувати для включення імені послідовного пристрою у вивід.

Усі інші команди неявно вважають шлях віддаленим, але символ : може бути використаний за бажанням для зрозумілості.

Усі підкоманди файлової системи приймають кілька аргументів-шляхів, тому якщо в послідовності є ще одна команда, необхідно використати + для завершення аргументів, наприклад:

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

Це скопіює файл на пристрій, а потім увійде в REPL. Символ + запобігає інтерпретації "repl" як шляху.

Команда cp підтримує параметр -r для рекурсивного копіювання. За замовчуванням cp пропускатиме копіювання файлів на віддалений пристрій, якщо хеш SHA256 вихідного та цільового файлів збігається. Щоб примусово скопіювати незалежно від хешу, використовуйте параметр -f.

Примітка: Для зручності всі підкоманди файлової системи також є псевдонімами як звичайні команди, тобто можна писати mpremote cp ... замість mpremote fs cp ....

df

Запит вільного/використаного простору пристрою:

$ mpremote df

Команда df виводить статистику розміру/використано/вільно для файлової системи пристрою, аналогічно до команди Unix df.

edit

Редагувати файл на пристрої:

$ mpremote edit <files...>

Команда edit копіює кожен файл з пристрою до локального тимчасового каталогу, а потім запускає редактор для кожного файлу (визначений змінною середовища $EDITOR). Якщо редактор завершується успішно, оновлений файл копіюється назад на пристрій.

mip

Встановити пакети з micropython-lib (або GitHub) за допомогою інструменту mip:

$ mpremote mip install <packages...>

Детальніше дивіться Керування пакетами.

mount

Підключити локальний каталог до віддаленого пристрою:

$ mpremote mount [options] <local-dir>

Це дозволяє віддаленому пристрою бачити локальний каталог хоста так, ніби це власна файлова система. Це корисно для розробки та дозволяє уникнути необхідності копіювати файли на пристрій під час роботи з ними.

Пристрій встановлює драйвер файлової системи, який монтується у VFS пристрою як /remote. Він використовує послідовне з’єднання з mpremote як побічний канал для доступу до файлів. Поточний робочий каталог пристрою (через os.chdir) встановлюється у /remote, щоб імпорти та доступ до файлів відбувалися там замість стандартного шляху файлової системи, поки монтування активне.

Примітка: Якщо після команди mount у послідовності не йде інша дія, команда repl неявно додається в кінець послідовності.

Під час використання Ctrl-D ініціює м’яке скидання, як зазвичай, але монтування автоматично відновлюється. Однак якщо на пристрої є main.py, що запускається при старті, перемонтування не може відбутися. У цьому випадку можна використати м’яке перезавантаження в режимі raw: Ctrl-A Ctrl-D для перезавантаження, потім Ctrl-B для повернення до звичайного repl, після чого монтування буде готове.

Параметри:

  • -l, --unsafe-links: За замовчуванням буде видано помилку, якщо пристрій звертається до файлу або каталогу, що знаходиться за межами (на один або кілька рівнів вище) локального підключеного каталогу. Цей параметр вимикає цю перевірку для символічних посилань, дозволяючи пристрою переходити за символічними посиланнями за межі локального каталогу.

unmount

Відключити локальний каталог від віддаленого пристрою:

$ mpremote umount

Це відбувається автоматично при завершенні mpremote, але може використовуватися в послідовності для відключення раніше підключеного монтування перед виконанням наступних команд.

romfs

Керування розділами ROMFS на пристрої:

$ mpremote romfs <sub-command>

<sub-command> може бути:

  • romfs query для переліку всіх доступних розділів ROMFS та їх розміру

  • romfs [-o <output>] build <source> для створення образу ROMFS із вказаного вихідного каталогу; стандартний вихідний файл — вихідне ім’я з доданим розширенням .romfs

  • romfs [-p <partition>] deploy <source> для розгортання образу ROMFS на пристрої; також створює тимчасовий образ ROMFS, якщо джерело є каталогом

Підкоманди build та deploy обидві підтримують параметр -m/--mpy для автоматичної компіляції файлів .py у .mpy при створенні образу ROMFS. Цей параметр увімкнено за замовчуванням, але працює лише якщо встановлено пакет Python mpy_cross (наприклад, через pip install mpy_cross). Якщо пакет не встановлено, виводиться попередження та файли .py залишаються без змін. Компіляцію файлів .py можна вимкнути параметром --no-mpy.

rtc

Встановити/отримати час пристрою (RTC):

$ mpremote rtc

Це запитає RTC пристрою для отримання поточного часу та виведе його у вигляді кортежу datetime.

$ mpremote rtc --set

Це встановить RTC пристрою відповідно до поточного часу хост-комп’ютера.

sleep

Пауза (затримка) перед виконанням наступної команди:

$ mpremote sleep 0.5

Це призупинить виконання послідовності команд на вказану тривалість у секундах, наприклад, щоб дочекатися, поки пристрій виконає певну дію.

reset

Жорстке скидання пристрою:

$ mpremote reset

Примітка: жорстке скидання еквівалентне machine.reset().

bootloader

Увійти в завантажувач:

$ mpremote bootloader

Це переведе пристрій у режим завантажувача. Завантажувач залежить від плати — детальніше дивіться розділ Відновлення та контакти налагодження у короткому довіднику вашої плати.

Автопідключення та м’яке скидання

Підключення та відключення виконуватимуться автоматично на початку та в кінці виконання інструменту, якщо такі команди не вказані явно. Автоматичне підключення шукатиме перший доступний USB послідовний пристрій.

Після підключення до пристрою mpremote автоматично виконає м’яке скидання пристрою, якщо необхідно. Це очищує купу Python та перезапускає інтерпретатор, забезпечуючи виконання подальшого коду Python у чистому середовищі. Автоматичне м’яке скидання виконується при першому виконанні однієї з таких команд: mount, eval, exec, run, fs. Після першого м’якого скидання воно не виконуватиметься автоматично знову до видання команди disconnect.

Поведінка автоматичного м’якого скидання може контролюватися командою resume. Це може бути корисно для використання команди eval для перевірки стану пристрою. Команда soft-reset може використовуватися для явного м’якого скидання посеред послідовності команд.

Скорочення

Скорочення можна визначати за допомогою системи макросів. Вбудовані скорочення:

  • devs: Псевдонім для connect list

  • a0, a1, a2, a3: Псевдоніми для connect /dev/ttyACMn

  • u0, u1, u2, u3: Псевдоніми для connect /dev/ttyUSBn

  • c0, c1, c2, c3: Псевдоніми для connect COMn

  • cat, edit, ls, cp, rm, mkdir, rmdir, touch: Псевдоніми для fs <sub-command>

Додаткові скорочення можна визначити у файлі конфігурації користувача mpremote/config.py, розташованому в каталозі конфігурації користувача. Правильне розташування для кожної ОС визначається за допомогою модуля platformdirs.

Зазвичай це: - $XDG_CONFIG_HOME/mpremote/config.py - $HOME/.config/mpremote/config.py - $env:LOCALAPPDATA/mpremote/config.py

Файл config.py повинен визначати словник з іменем commands. Ключі цього словника — це скорочення, а значення — рядок або список рядків:

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

Команда c33 замінюється на connect id:334D335C3138.

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

Команда test замінюється на mount . exec "import test".

Скорочення також можуть приймати аргументи. Наприклад:

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

Запуск mpremote multiply 3 7 встановить x та y як змінні на пристрої, а потім обчислить вираз x*y.

Приклад файлу config.py може виглядати так:

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

Приклади

mpremote

Підключитися до першого доступного пристрою та неявно виконати команду repl.

mpremote a1

Підключитися до пристрою на /dev/ttyACM1 (Linux) та неявно виконати команду repl. Дивіться скорочення вище.

mpremote c1

Підключитися до пристрою на COM1 (Windows) та неявно виконати команду repl. Дивіться скорочення вище.

mpremote connect /dev/ttyUSB0

Явно вказати, до якого пристрою підключитися, та, як і вище, неявно виконати команду repl.

mpremote a1 ls

Підключитися до пристрою на /dev/ttyACM1 та виконати команду ls.

Це еквівалентно mpremote connect /dev/ttyACM1 fs ls.

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

Виконати вказану команду Python та відобразити будь-який вивід. Це еквівалентно введенню команди в REPL.

mpremote eval 1/2 eval 3/4

Обчислити кожен вираз по черзі та вивести результати.

mpremote a0 eval 1/2 a1 eval 3/4

Обчислити 1/2 на пристрої за адресою /dev/ttyACM0, потім 3/4 на пристрої за адресою /dev/ttyACM1, виводячи кожен результат.

mpremote resume exec "print_state_info()" soft-reset

Підключитися до пристрою без ініціювання м’якого скидання та виконати функцію print_state_info() (наприклад, щоб дізнатися інформацію про поточний стан програми), а потім ініціювати м’яке скидання.

mpremote reset sleep 0.5 bootloader

Жорстко скинути пристрій, зачекати 500 мс до його готовності, а потім увійти в завантажувач.

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

Оновити копію utils/driver.py на пристрої, а потім виконати локальний скрипт test.py на пристрої. test.py ніколи не копіюється до файлової системи пристрою — він запускається з оперативної пам’яті.

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

Оновити копію utils/driver.py на пристрої, а потім виконати app.py на пристрої.

Це типовий робочий процес розробки для оновлення одного файлу та перезапуску програми. У цьому сценарії ваш main.py на пристрої також виконуватиме import app.

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

Оновити копію utils/driver.py на пристрої, потім ініціювати м’яке скидання для перезапуску програми, а потім відстежувати вивід через команду repl.

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

Те саме, що й вище, але спочатку оновити весь каталог utils.

mpremote mount .

Підключити поточний локальний каталог як /remote на пристрої та розпочати сесію repl, яка використовуватиме /remote як робочий каталог.

mpremote mount . exec "import demo"

Після підключення поточного локального каталогу виконує demo.py з підключеного каталогу.

mpremote mount app run test.py

Після підключення локального каталогу app як /remote на пристрої виконує локальний test.py з поточного каталогу хоста без копіювання його до файлової системи.

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

Після підключення поточного локального каталогу виконує demo.py з підключеного каталогу кожного разу при натисканні Ctrl-J.

Спочатку потрібно натиснути Ctrl-D, щоб скинути стан інтерпретатора (що збереже монтування), а потім натиснути Ctrl-J для повторного імпорту demo.py.

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

Те саме, що й вище, але виконує вміст локального файлу demo.py в REPL кожного разу при натисканні Ctrl-K. Як і вище, спочатку використовуйте Ctrl-D для скидання стану інтерпретатора.

mpremote cat boot.py

Відображає вміст boot.py на пристрої.

mpremote edit utils/driver.py

Редагує utils/driver.py на пристрої за допомогою локального $EDITOR.

mpremote cp :main.py .

Копіює main.py з пристрою до локального каталогу.

mpremote cp main.py :

Копіює main.py з локального каталогу на пристрій.

mpremote cp :a.py :b.py

Копіює a.py на пристрої до b.py на пристрої.

mpremote cp -r dir/ :

Рекурсивно копіює локальний каталог dir до віддаленого пристрою.

mpremote cp a.py b.py : + repl

Копіює a.py та b.py з локального каталогу на пристрій, а потім виконує команду repl.

mpremote mip install aioble

Встановити пакет aioble з micropython-lib на пристрій. Дивіться Керування пакетами.

mpremote mip install github:org/repo@branch

Встановити пакет із вказаної гілки на org/repo у GitHub на пристрій. Дивіться Керування пакетами.

mpremote mip install gitlab:org/repo@branch

Встановити пакет із вказаної гілки на org/repo у GitLab на пристрій. Дивіться Керування пакетами.

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

Встановити пакет functools з micropython-lib до каталогу /flash/third-party на пристрої. Дивіться Керування пакетами.