Pico Sync Tool (pico_sync.py)

pico_sync.py — компактний CLI-інструмент для зручної роботи з Raspberry Pi Pico / Pico W під MicroPython.
Він надає зручні команди для синхронізації файлів, перегляду файлової системи, 
базові операції з файлами на пристрої, моніторингу логів та перезавантаження плати.

---

📁 1. Призначення pico_sync.py

Мета інструмента — зробити розробку на MicroPython максимально схожою на роботу з локальним проєктом.

🔹 Можливості:

- 🔄 Синхронізація директорії src/ на Pico


- 🧠 Дельта-синхронізація: оновлюються лише змінені файли


- 🗑 Автовидалення зайвих файлів на Pico


- 🧼 Автоматичне очищення порожніх директорій


- ⛔ Ігнорування файлів через .picoignore (підтримка *, **, dir/ - лише всередині src/)


- 📂 Перегляд файлової системи (--ls)


- 📄 Читання файлів (--cat)


- ✏️ Редагування файлів через nano (--nano)


- 🔍 Пошук та вибір USB-порту Pico (--search_port)


- 🔌 Живий серійний монітор (--monitor)


- 🔁 Програмне перезавантаження Pico (--reboot)

Також інструмент автоматично створює відсутні директорії на Pico та працює поверх mpremote.

---

📂 2. Рекомендована структура проєкту

Щоб інструмент працював без зайвих питань, рекомендується така структура:

project_root/
│
├── pico_sync.py          # інструмент
├── .picoignore           # правила ігнорування файлів
│
└── src/                  # код, який синхронізується з Pico

⚠️ Важливо:

1. .picoignore працює Тільки для файлів всередині src/
2. Синхронізується виключно директорія src/ - файли за межами src/ ніколи не синхронізуються.

---

📜 3. Файл .picoignore

Правила ігнорування. Формат аналогічний .gitignore.

Приклади:

Ігнорувати кеші

__pycache__/
*.pyc

Рекурсивно ігнорувати всі .log-файли

**/*.log

Конкретний файл

config/local_settings.py

Директорія

tests/

Підтримуються патерни:

Патерн	Опис
*	будь-які символи в межах директорії
**	рекурсивний матч (будь-який рівень вкладеності)
?	один символ
dir/	вся директорія
*.ext	маска файлів

---

4. 🔧 Технічні деталі роботи

Delta-sync (інтелектуальна синхронізація)

Delta-sync працює на основі порівняння SHA-256:

1. Для кожного локального файлу обчислюється SHA-256.
2. На Pico через mpremote викликається функція, яка повертає SHA-256 віддаленого файлу.
3. Якщо хеші збігаються → файл пропускається.
4. Якщо хеші різні або файл відсутній → файл завантажується.
5. Після завершення всі файли, яких немає локально у src/, видаляються з Pico.
6. Порожні директорії також очищаються.

Це робить синхронізацію швидкою навіть для великих проєктів.

Використання порту --port

Після вибору порту він зберігається у змінній середовища:

os.environ["MPREMOTE_PORT"] = args.port

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

BAUD = 115200 — пояснення

BAUD = 115200 — це стандартна швидкість серійного порту MicroPython на RP2040. Вона не пов’язана з mpremote, але використовується у режимі моніторингу (--monitor), бо Pico друкує текст у REPL саме з такою швидкістю, якщо користувач її не змінював.

5. Допомога та приклади використання

📘 Отримати довідку:

python pico_sync.py --help

Приклад виводу:

usage: pico_sync.py [-h] [--port PORT] [--src SRC] 
                    [--sync] [--ls PATH] [--cat FILE] [--nano FILE] 
                    [--search_port] [--check_update] 
                    [--reboot] [--monitor]

Pico Sync Tool — sync/ls/cat/nano for Raspberry Pi Pico

options:
  -h, --help      Показати довідку
  --port PORT     USB порт Pico, використовується і для mpremote (default: /dev/ttyACM0)
  --src SRC       Локальна директорія для синхронізації (default: src)
  --sync          Синхронізувати src → Pico (default: False)
  --ls PATH       Показати список файлів у директорії на Pico (default: None)
  --cat FILE      Вивести вміст файлу з Pico (default: None)
  --nano FILE     Редагувати файл через nano (default: None)
  --search_port   Інтерактивний пошук serial Pico-портів та вибір Pico-порту (default: False)
  --check_update  Перевірити наявність оновлень Pico Sync Tool (default: False)
  --reboot        Софт-ресет плати через mpremote (default: False)
  --monitor       Моніторинг серійного порту Pico у реальному часі (default: False)

🔍 Пошук порту Pico

python pico_sync.py --search_port

Приклад:

Доступні серійні порти:

0) ⭐ /dev/ttyACM0 USB Serial Device [VID=0x2E8A]
1) /dev/ttyUSB0 CP2102 USB-UART

Оберіть номер порту:

Після вибору порт автоматично підставляється у виконання команд.

🔄 Синхронізація проекту

✔ Стандартна синхронізація:

python pico_sync.py --sync

✔ Вказати нестандартний src:

python pico_sync.py --src my_src --sync

📂 Перегляд файлової системи Pico

✔ Список файлів:

python pico_sync.py --ls /
python pico_sync.py --ls /spm

📄 Читання файлу з Pico

python pico_sync.py --cat /main.py

✏️ Редагування файлу через nano

python pico_sync.py --nano /config/settings.py

Механізм:

1. завантажує файл у тимчасовий файл
2. відкриває nano
3. після збереження — автоматично завантажує файл назад на Pico

🗑 Автовидалення файлів на Pico + очищення директорій

Під час --sync:

• файли, яких немає локально (src/), автоматично видаляються:

• порожні директорії також видаляються

---

Монітор серійного порту:

python pico_sync.py --monitor

Монітор автоматично перепідключається, якщо Pico:

• перезавантажився
• змінив свій USB-порт (ACM0 → ACM1)
• тимчасово зник із системи

Перезавантажити Pico:

python pico_sync.py --reboot

Виконує програмний reset через mpremote reset. Це еквівалент натискання кнопки BOOT+RUN, але без фізичного втручання.

📘 6. Інструкція користувача

✔ Крок 1. Встановити залежності

pip install pyserial mpremote

✔ Крок 2. Підготувати структуру проєкту

project/
├── pico_sync.py
├── .picoignore
└── src/

✔ Крок 3. Підключити Pico через USB

✔ Крок 4. Знайти порт (рекомендовано)

python pico_sync.py --search_port

✔ Крок 5. Синхронізувати

python pico_sync.py --sync

✔ Крок 6. Переглядати або редагувати файли

python pico_sync.py --ls /
python pico_sync.py --nano /main.py

✔ Крок 7. Оновлювати зміни

python pico_sync.py --sync