Установка TreeDPrint-агента на Raspberry Pi

Перед началом

Чтобы поставить агент TreeDPrint на Raspberry Pi, понадобится:

• Raspberry Pi. Подходит RPi 4, RPi 5, RPi Zero 2 W. RPi 3 тоже работает, но не поддерживает режим USB-gadget — для неё сценарии Wi-Fi или Ethernet.
• microSD-карта 8 ГБ или больше, прошитая Raspberry Pi OS (рекомендуется свежий релиз, не старее Bookworm). Удобнее всего — официальный Raspberry Pi Imager: при записи он сразу попросит задать имя пользователя, пароль и Wi-Fi.
• Подключение к сети. Нужно одно из: Wi-Fi (та же сеть, где принтеры), Ethernet-кабель до роутера, или USB Type-C от RPi к компьютеру. См. способы подключения.
• Питание. «Родной» БП с поддержкой 5 В / 3 А (или USB-C ↔ USB-C кабель к адаптеру с Power Delivery — см. какой нужен кабель).
• Логин и пароль к Raspberry Pi — те, что вы задали при записи карты. Не помните? См. сброс пароля.

Способы подключения

RPi должна быть видна установщику. Самый простой путь — Wi-Fi или Ethernet (RPi и компьютер в одной сети). USB Type-C нужен, только если положить RPi в сеть проблематично.

Я не помню логин или пароль RPi

SSH-логин и пароль — это учётка самой Raspberry Pi. Не путайте с паролем от Wi-Fi и не путайте с паролем от TreeDPrint — это три разные вещи.

Если вы записывали карту через Raspberry Pi Imager, логин и пароль задавались в окне «Расширенные настройки» (значок шестерёнки). По умолчанию логин — pi, но мог быть заменён.

Если пароль забыт — проще всего перезаписать карту. Все данные на ней будут потеряны (для свежей RPi это нормально):

1. Скачайте и установите Raspberry Pi Imager.
2. Вытащите microSD-карту из RPi и вставьте в компьютер.
3. В Imager: Choose OS → Raspberry Pi OS (64-bit).
4. В Imager: Choose Storage → ваша SD-карта.
5. Перед записью нажмите шестерёнку и задайте:
   • имя пользователя (можно pi);
   • пароль — запишите его;
   • включите SSH;
   • задайте Wi-Fi (если планируете подключать по Wi-Fi).
6. Запишите карту, вставьте в RPi, включите.
7. Дождитесь, когда RPi появится в сети (1–2 минуты), и запускайте установщик TreeDPrint снова.

Какой нужен кабель для USB Type-C

Если выбрали сценарий USB Type-C, успех зависит от кабеля и порта. Неправильный кабель — самая частая причина, почему RPi не загружается, перезагружается циклически или сообщает об undervoltage.

Что нужно

• USB-C ↔ USB-C кабель: оба разъёма овальные, с обеих сторон одинаковые.
• Кабель должен поддерживать Power Delivery (PD) — это про передачу 5 В / 3 А или больше. Простые «зарядные» USB-A → USB-C на это не способны.
• Желательно короткий (до 1 м) и не самый бюджетный — на длинных кабелях падает напряжение.

Что НЕ подойдёт

• USB-A → USB-C (обычная зарядка от телефона). Прямоугольный разъём с одной стороны → овальный с другой. Такие кабели практически никогда не дают нужного тока.
• Кабели «только для зарядки» без линий передачи данных — RPi может включиться, но компьютер её не увидит.
• Очень длинные (2 м+) или тонкие кабели — даже «правильные» по разъёмам они часто проседают по напряжению.

Куда втыкать

• В порт компьютера с поддержкой PD — обычно это порт, в который вы заряжаете телефон. На ноутбуках Apple, ThinkPad, XPS и т.д. это, как правило, порт зарядки.
• Если PD-портов на компе нет — используйте качественный адаптер питания (например, родной БП Apple на 30 Вт+) и подключайте RPi к нему. Связь с компьютером тогда — через Wi-Fi или Ethernet.

Что такое undervoltage и почему RPi сообщает о нём

Undervoltage (буквально «недонапряжение») — сообщение ядра Linux о том, что входное напряжение на USB-C упало ниже допустимого порога (4.63 В для RPi 4 / 5).

Это значит, что блок питания, кабель или порт не дают RPi нужный ток. Симптомы: микро-зависания, спонтанные перезагрузки, невозможность подключить периферию, отказ загружаться.

Установщик TreeDPrint проверяет это сообщение в системных логах (dmesg). Если оно появилось — он покажет вам диалог и предложит открыть этот раздел.

Что делать:

• заменить кабель на нормальный USB-C ↔ USB-C (см. какой нужен кабель);
• подключить RPi к адаптеру питания, а не к USB-порту ноутбука;
• выключить лишнюю периферию (вторая SD-карта, USB-хаб с диском);
• после замены — перезагрузить RPi, чтобы сообщение перестало появляться, и повторить установку.

RPi не появилась после переключения в USB-режим

Установщик включает на RPi режим USB-gadget и ждёт, пока компьютер увидит её как сетевой адаптер. Если этого не произошло за минуту-две — попробуйте по порядку:

1. Переткните USB-кабель. Иногда контакт устанавливается не с первого раза, особенно с новыми кабелями.
2. Попробуйте другой USB-порт компьютера. Не все порты поддерживают передачу данных и питание одновременно. Используйте порт с маркировкой PD (если есть).
3. Подождите дольше. Первая загрузка RPi после смены режима может занимать до 2 минут. Не отключайте питание, пока идёт загрузка.
4. Проверьте undervoltage. Если RPi постоянно перезагружается — это почти наверняка питание или кабель.
5. Попробуйте сценарий Wi-Fi или Ethernet (см. способы подключения) — это быстрее, чем разбираться с USB.
6. Если ничего не помогло — пришлите в поддержку логи установщика (кнопка «Технические детали» внизу диалога с ошибкой).

Инсталлер не находит RPi в сети

Установщик сканирует вашу локальную сеть на 22-м порту (SSH). Если RPi не появляется — обычно дело в одном из следующих:

• Гостевая Wi-Fi-сеть. Многие роутеры по умолчанию включают «гостевой» Wi-Fi с изоляцией клиентов — устройства в нём не видят друг друга. Проверьте, что и компьютер, и RPi в одной «основной» сети.
• Изоляция клиентов / AP isolation. Та же история, но настроена явно в админке роутера. Зайдите в настройки Wi-Fi и отключите Client Isolation / AP Isolation.
• RPi ещё не загрузилась. После включения первой загрузке нужно 1–2 минуты. Если карта только что записана — ещё дольше (расширение файловой системы).
• Неправильная Wi-Fi сеть на RPi. Если задавали Wi-Fi через Pi Imager — перепроверьте, что SSID совпадает. Кириллица и пробелы в SSID — частый источник проблем.
• VPN на компьютере. VPN-клиенты подменяют таблицу маршрутов и могут «увести» сканирование в туннель. Отключите VPN на время установки.
• Антивирус / firewall. Некоторые антивирусы блокируют сканирование портов. Если ничего не помогает — временно отключите защиту в реальном времени.
• mDNS не работает. На корпоративных сетях часто запрещён multicast. Установщик умеет искать и без mDNS — просто скан занимает чуть дольше (10–15 секунд).

Если ничего не подошло — попробуйте сценарий USB Type-C: он не зависит от настроек сети.

macOS

Отдельного .app-инсталлера для macOS пока нет.

Распространение любого установочного приложения под macOS требует членства в Apple Developer Program и прохождения ритуалов нотаризации — мы не стали тратить на это цикл разработки, пока приоритет у самого продукта. Хорошая новость: под macOS достаточно одного похода в Терминал. Один раз, не сложно.

Откройте Терминал (Cmd+Space → «Terminal») и выполните:

curl -sSL https://treedprint.ru/install.sh | bash -s -- --token <provisioning_token>

Подставьте <provisioning_token> — это токен, который выдаёт личный кабинет:

1. Откройте «Аккаунт» в TreeDPrint.
2. Нажмите «Добавить устройство», задайте имя.
3. Раскройте блок «Установка вручную через SSH».
4. Скопируйте оттуда токен (строка --token …).
5. Подставьте его в команду выше и запустите в Терминале на RPi (по SSH из Терминала Mac: ssh pi@<ip-rpi>, потом — команда выше).

Токен живёт 10 минут. Не успели — сгенерируйте новый в той же модалке.

Linux

Под Linux отдельного GUI-инсталлера тоже нет — для большинства юзеров это лишняя обёртка.

Откройте терминал и выполните:

curl -sSL https://treedprint.ru/install.sh | bash -s -- --token <provisioning_token>

<provisioning_token> — токен из вашего личного кабинета: «Аккаунт» → «Добавить устройство» → «Установка вручную через SSH». Скопируйте оттуда всю команду — в ней токен уже подставлен.

Команда запускается на самой RPi (зайдите по ssh pi@<ip-rpi> с вашей Linux-машины и выполните её там).