Удалённое управление 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 удалит все файлы с подключённой SD-карты и выдаст неблокирующее предупреждение. Точка монтирования будет сохранена.

  • 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

Это заставит устройство войти в свой загрузчик. Загрузчик зависит от конкретной платы — подробности см. в разделе Recovery and debug pins в кратком справочнике вашей платы.

Автоматическое подключение и программный сброс

Подключение и отключение выполняются автоматически в начале и в конце работы инструмента, если такие команды не указаны явно. Автоматическое подключение выполнит поиск первого доступного 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 на устройстве. См. Управление пакетами.