Sovol на mainline Klipper

Архитектура

Mon, 01 Jan 0001 00:00:00 +0000

Архитектура системы#

Справочное описание Sovol Zero как с завода, снятое с работающей машины — файловая система хоста, конфиг Klipper, рантайм MCU, git-remote-ы. Оно нужно под миграцию: точно знать, какое железо и софт в игре и какие куски вендор-специфичные, а какие сток.

Sovol Zero — CoreXY-принтер, индустриализированная производная Voron 0, с областью печати 150×150×150 мм в закрытом корпусе. На нём крутится Klipper на Linux-хосте, который общается с несколькими STM32 MCU по CANbus. Внутренне Sovol зовёт его «SV08 mini» — вендорский пакет прошивки идёт как SV08mini_Update_Package-*.deb, и CAN-голову он делит с SV08 Max — хотя продаётся только как Sovol Zero.

Поверх стоковой прошивки

Mon, 01 Jan 0001 00:00:00 +0000

Runbook — миграция на месте поверх стоковой прошивки#

Принтер работает, и ты мигрируешь поверх него. Вендорская ОС остаётся, приклад и прошивка MCU переезжают на upstream, а ОС — опциональный последний шаг. Это путь инкрементального де-вендоринга.

Каждый шаг ниже — ссылка в компонент, который делает работу; эта страница только про порядок.

1. Сначала забэкапь всё#

Rsync вендорского стека, SWD-дамп тулхеда и, желательно, полный образ eMMC. Бэкапы — это то, что делает любой последующий шаг обратимым. → Восстановление: сначала бэкап

Простая установка

Mon, 01 Jan 0001 00:00:00 +0000

Простая установка — для большинства#

Страница с чистого листа запекает всё в образ офлайн, руками. Тебе так не обязательно. Есть путь подружелюбнее: прошей базовый образ, дай ему подняться и ответь на короткий визард по SSH — тот же first-run опыт, что и на любой плате Armbian. Никакой правки ext4, никакого debugfs.

Две вещи делают это простым на Zero:

У платы есть слот microSD, и H616 грузит SD раньше eMMC. Так что можно гонять всё с microSD — без ридера, без снятия модуля, без риска для стоковой eMMC. Оставь eMMC в покое как заводской бэкап, или перенеси систему на неё позже.
Первый вход по SSH запускает дружелюбный setup-визард Armbian (armbian-firstlogin): он заставляет сменить пароль root, создаёт твоего пользователя и спрашивает locale + timezone — прямо в SSH-сессии.

Используй образ Sovobian для всего этого — это upstream Armbian CB1 с уже запечённым оверлеем eMMC 40 МГц, и он несёт ядро 6.12.68, где встроенный Ethernet работает из коробки. Обычный образ BTT CB1 гонит eMMC на 3× валидированного клока (смотри разницу CB1) — не используй его.

Сборка прошивки

Mon, 01 Jan 0001 00:00:00 +0000

Сборка прошивки#

Прошивку MCU (Katapult + Klipper) можно собрать либо на самом хосте принтера, либо на Mac / Linux-машине, а потом скопировать .bin. Оба дают идентичные образы — выбирай, что под рукой.

Тулчейн#

На хосте принтера (Allwinner H616 платы Sovol Zero, Debian aarch64)#

arm-none-eabi-gcc уже установлен — это вендорская же цепочка сборки. Клонируй исходники и собирай на месте; никакой доп-настройки и ни одной из macOS-причуд ниже:

make CROSS_PREFIX=arm-none-eabi-

На macOS#

brew install --cask gcc-arm-embedded

Он ставится в /Applications/ArmGNUToolchain/<version>/arm-none-eabi/bin/ (например, 15.2.rel1) и не добавляется в PATH. Собирай с полным префиксом и переопредели CPP:

Стек KIAUH

Mon, 01 Jan 0001 00:00:00 +0000

Стек прикладного слоя через KIAUH#

Всё выше Klipper — Moonraker, Mainsail, Crowsnest — уже сток upstream, так что самая быстрая чистая установка — это dw-0/kiauh. Склонируй его и ставь по порядку: Klipper, Moonraker, Mainsail, Mainsail-Config, Crowsnest.

Наведи хост Klipper на тот же чекаут master, из которого собраны твои MCU, с venv из его requirements.txt, и выстави [update_manager klipper] channel: dev в moonraker.conf, чтобы он трекал master.

Два постустановочных фикса#

Оба из опыта на этой плате:

Ванильный Armbian

Mon, 01 Jan 0001 00:00:00 +0000

Ванильный Armbian на плате Sovol Zero#

Миграция Klipper оставляет стоковый образ ОС от Sovol нетронутым — Klipper живёт в /home/sovol, так что замена слоя Klipper никогда не переписывает rootfs или загрузчик. Для полностью вендор-фри машины последний слой — это ОС на eMMC. Это более трудный, деструктивный шаг (он переписывает всё загрузочное устройство).

Это проверенный от начала до конца рецепт ванильного Armbian на стоковом 8 ГБ eMMC-модуле — без кастомной сборки ОС, без замены модуля. Оригинальный разбор Armbian-на-Zero — asnajder/zero-config, на нём это и строится; где они расходятся (в первую очередь на 8 ГБ модуле), разница объяснена ниже.

Есть eMMC-ридер

Mon, 01 Jan 0001 00:00:00 +0000

Runbook — сборка с чистого листа с eMMC-ридером#

Путь, которым реально идёт восстановление или свежая сборка: сначала ОС, приклад сверху, MCU обычно последними — и часто их вообще не трогают, потому что слой 2 пережил то, что убило слой 3. Это порядок, проверенный от начала до конца на референсной машине.

1. Проинвентаризируй бэкапы#

Минимум: набор конфигов (git-репозиторий или любая копия) и состояние MCU. Уже-mainline MCU тут не нужны; вендорские MCU требуют шагов прошивки ниже. Полный образ eMMC превращает это в восстановление вместо пересборки. → Восстановление

Конфиг Klipper

Mon, 01 Jan 0001 00:00:00 +0000

Перевод конфига на mainline#

Вендорский printer.cfg как есть на upstream Klipper не заводится — несколько секций завязаны на поведение, которое есть только в вендорской прошивке. Переведи их с вендорского конфига; остальное переносится как есть.

Eddy на software I2C#

Вендор гонял LDC1612 по аппаратному i2c2, но только потому, что его F103-прошивка тащит обходы errata аппаратного I2C у STM32F1, которых на mainline нет; на mainline аппаратный i2c2 кидает START_NACK → shutdown. Используй bitbang:

Прошивка по SWD

Mon, 01 Jan 0001 00:00:00 +0000

Прошивка по SWD через Flipper Zero (DAP Link)#

Katapult тулхеда работает только по запросу и не восстанавливается по CAN, если приложение сломалось, так что SWD-пробник — это страховка. Подойдёт любой CMSIS-DAP-пробник — клон ST-Link V2 или Flipper Zero с приложением DAP Link.

Проверенный охват. Всё здесь тестировалось только на тулхеде F103 и только с Flipper Zero (приложение DAP Link). ST-Link должен вести себя так же (это стандартный SWD), а раздел про H750 ниже — рассуждение, а не проверка. Правки и дополнения приветствуются — открой PR.

Распиновка тулхеда и SWD

Mon, 01 Jan 0001 00:00:00 +0000

Распиновка тулхеда и SWD-хедер#

Переписано с официального pin-definition от Sovol (Motherboard/Extra_Pin_definition.pdf в Sovol3d/SOVOL-ZERO) — смотри тот PDF ради полной картинки платы с подписями. MCU тулхеда — это STM32F103 (extruder_mcu), шелкография платы MINI-ZJB-V1.0.

Коннекторы#

Коннектор	Пины (как на шелкографии)
Вентилятор охлаждения	`24V` · PWM `PA6` · FG `PA1`
Вентилятор (верхний)	`24V` · PWM `PA7` · FG `PA2`
Вентилятор модели	`24V` · PWM `PB0` · FG `PA3`
Термистор сопла	`PA5` · `GND`
Нагревательный блок	`GND` · `24V` · `PB1` · `GND` · `PA4`
Нагреватель	`24V` · MC_HEATER `PB7`
Питание 24 В	`GND` · `24V`
Мотор экструдера	DIR `PA9` · STEP `PA8` · EN `PA11` · UART `PA12`
Концевик оси X	`PA10` · `GND` · `5V`
Концевик / датчик	`5V` · `GND` · `PC15` · `PC14`
Датчик eddy current	`5V3` · `GND` · `PB10` (SCL) · `PB11` (SDA)
Связь с мейнбордом (CAN)	CANL · `GND` · CANH (CAN_R `PB8` · CAN_T `PB9`)
SWD-хедер (шелк `5V3 IO CK G`)	`5V3` = 3.3 В · `IO` = SWDIO (`PA13`) · `CK` = SWCLK (`PA14`) · `G` = GND

Коннектор eddy-датчика выводит PB10/PB11. На mainline Klipper гоняй LDC1612 через software I2C на этих пинах, а не через аппаратный i2c2 — см. страницу конфига Klipper.

Восстановление

Mon, 01 Jan 0001 00:00:00 +0000

Runbook — восстановление машины, которая не поднимается#

Маршрутизируй по тому, что реально отвалилось. Поскольку слой 2 переживает слой 3, большинство восстановлений уже́, чем кажется — мёртвая ОС не трогает MCU, а неудачная прошивка приложения не трогает ОС.

Чеклист бэкапов и подробные откаты живут на странице восстановления; здесь — маршрутизация.

ОС не грузится#

MCU в порядке. Пересобери только ОС, потом переподключись.

Есть полный образ eMMC → восстанови его: один dd обратно, и ты там же, где был.
Образа нет → пересобери с чистого листа: с eMMC-ридером, или на месте, если ридера нет.
Затем восстанови конфиг и подтверди klippy ready с обоими CAN-UUID — это и доказывает, что MCU выжили.

Если умерла сразу после апгрейда ядра / apt — это регрессия onboard-ethernet, а не мёртвое железо.

Миграция MCU

Mon, 01 Jan 0001 00:00:00 +0000

Миграция MCU — оба MCU на mainline#

Чистый способ полностью перевести оба MCU на upstream Klipper — приложение и загрузчик, ни одного вендорского байта в прошивке. Собери всё из одного и того же коммита Klipper master (см. почему master). Порядок такой: собрать все четыре образа, прошить тулхед один раз по SWD, потом мейнборд через USB-Katapult.

Что нужно#

SWD-программатор — ST-Link V2 (клон за ~$3) или Flipper Zero с приложением DAP Link. Нужен один раз, чтобы забутстрапить тулхед: вендорский Katapult работает только по запросу и не восстанавливается по CAN, так что ты первый раз прошиваешь CAN-совместимый mainline Katapult на тулхед по SWD и больше голову не вскрываешь.
ARM-тулчейн — arm-none-eabi-gcc (уже на хосте принтера) или brew install --cask gcc-arm-embedded на macOS. См. Сборку прошивки.
openocd ≥ 0.11 для прошивки по SWD.
SSH-доступ к принтеру.

Сначала забэкапь#

Прежде чем что-то стирать, сними откат — особенно SWD-дамп тулхеда. Полный чеклист бэкапов (вендорский стек, SWD-дамп, образ eMMC) — на странице восстановления. Тот, что важнее всего здесь:

Плагины

Mon, 01 Jan 0001 00:00:00 +0000

Плагины и допы venv#

Дополнения, которые эта машина реально гоняет поверх стокового стека KIAUH.

scipy — нужен eddy-пробе#

Поставь scipy в venv Klipper:

~/klippy-env/bin/pip install scipy

Без него калибровка eddy-пробы падает. Если PyPI виснет при скачивании с платы, подсунь колёса вручную — смотри troubleshooting.

sovol_codes — коды экрана-крутилки#

Вендорская прошивка показывает числовые коды на экране-крутилке (101/103, диапазон shutdown 60+); mainline показывает человекочитаемые сообщения. Чтобы сохранить коды на upstream Klipper, поставь опциональный плагин sovol_codes.py:

С чистого листа (eMMC-ридер)

Mon, 01 Jan 0001 00:00:00 +0000

Установка с чистого листа с eMMC-ридером#

Самый чистый путь ОС: снять eMMC-модуль, прошить его офлайн в USB-ридере, запечь всё, что нужно первой загрузке, и включить настроенную машину. Это ровно та последовательность, которой (пере)собирали референсную машину — дважды — так что каждый шаг пережил контакт с реальностью.

Что нужно: eMMC-модуль в USB-ридере, Linux-машина или VM для офлайн-правок (macOS не может писать ext4 — см. заметку про офлайн-правки ниже), и MCU уже на mainline Katapult + Klipper (см. Миграцию MCU). Если MCU были на mainline раньше, они на нём и остаются — слой 2 переживает слой 3.

Калибровка

Mon, 01 Jan 0001 00:00:00 +0000

Откалибруй и проверь#

Оба MCU на mainline, конфиг переведён, плагины на месте — теперь откалибруй eddy-пробу и движение, а потом докажи это пластиком.

Eddy и tap#

Гоняй по порядку, SAVE_CONFIG после каждого:

LDC_CALIBRATE_DRIVE_CURRENT
PROBE_EDDY_CURRENT_CALIBRATE — строит таблицу частота→высота
PROBE_EDDY_CURRENT_TAP_CALIBRATE — задаёт tap_threshold

Натяжение ремня#

Цель — ~110 Гц при щипке XY-ремней на их 150-мм пролёте. (Z-ремень с завода ~137 Гц, но это пролёт 21.5 см — другая длина, так что два числа не сравнивай.) Туже — только вылизывает графики шейпера на бумаге и добавляет ringing. Клипперовский тест схожести ремней тут ненадёжен — акселерометр на голове шумит на standstill от гудения тока удержания, так что показания скачут от прогона к прогону. Проверяй натяжение на слух или тюнером в телефоне (Android годится; шумодав iPhone портит показание).

На месте, без eMMC-ридера

Mon, 01 Jan 0001 00:00:00 +0000

Переустановка ОС без eMMC-ридера#

Нет ридера, и не хочешь снимать модуль? Можно положить свежую ОС на eMMC прямо с работающей платы. Фокус в слоте microSD: H616 грузит SD раньше eMMC, так что ты загружаешь свежий образ с карты и оттуда клонируешь его на eMMC.

Обходного пути по USB нет — плата не выводит порт USB-C / OTG, так что обычный маршрут sunxi-fel + U-Boot ums, чтобы достать eMMC по USB, отпадает (смотри почему FEL отпадает). Загрузка с SD и клонирование — единственный путь без ридера.

Допы

Mon, 01 Jan 0001 00:00:00 +0000

Допы — опциональное железо и практики#

Дополнения, которые не входят в ядро миграции, но заслужили своё место на реальной машине.

USB WiFi-донгл (когда встроенный радиомодуль умирает)#

Встроенный RTL8189FTV — известная единая точка отказа: на этом юните он умер по вине БП (mmc: error -110 whilst initialising SDIO card на каждой загрузке, в том числе на стоковой прошивке, через ~21 попытку на двух стеках ядра; программное оживление — передёргивание питания чипа через его GPIO, более длинный post-power-on-delay-ms, более низкая частота SDIO — ничего не меняет). Если видишь эту сигнатуру, прекращай дебажить и втыкай донгл в один из портов USB-A на плате.

Обновляемый Armbian

Mon, 01 Jan 0001 00:00:00 +0000

Как держать Armbian обновляемым#

Опасение, что апгрейд apt «потеряет dts» и сломает eMMC, в основном беспочвенно, а реальное ограничение уже, чем кажется. Эта страница разделяет два этих вопроса.

Экспериментально в одном месте. Всё про то, почему ядро на hold, подтверждено и задокументировано. Путь с hold (переход на более новое ядро с сохранением встроенного Ethernet) пока не проверен на Zero — он помечен ниже. Сделай полный бэкап перед тем, как это тестировать.

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Troubleshooting и тюнинг#

То, что кусает при работе Sovol Zero на mainline Klipper, и как это разгрести. Только факты и фиксы — полные процедуры живут на страницах слоёв.

Прошивка и CAN#

canbus_query / flashtool.py -q показывает 0 нод#

Если Klipper остановлен, запрос, возвращающий Total 0 uuids, — это нормально: эти инструменты перечисляют только неинициализированные / bootloader-ноды, а сконфигурированная в Klipper app-нода не отвечает. Читай это как «всё крутит своё приложение», а не «шина мертва». Запусти Klipper (или переведи ноду в её bootloader), чтобы увидеть её в запросе.

Восстановление

Mon, 01 Jan 0001 00:00:00 +0000

Восстановление и бэкапы#

Что делает каждый шаг в каждом пути обратимым и как вернуть машину, которая не грузится. Восстановление — это в основном история про бэкапы: сними правильные снапшоты, прежде чем что-то трогать, и мёртвый слой станет восстановлением вместо пересборки.

Сначала бэкап — чеклист#

Сними это, прежде чем что-то стирать. Именно они делают каждый последующий шаг обратимым.

Вендорский стек (на уровне файлов, возобновляемый rsync — не сырой dd по WiFi): вендорский ~/klipper как git bundle, ~/printer_data/config, ~/printer_data/build/*.bin, и сборочные конфиги под каждый чип ~/klipper/.config* (полезные затравки, даже несмотря на устаревшие flash-офсеты).

Ресурсы

Mon, 01 Jan 0001 00:00:00 +0000

Плагин и патчи#

Два артефакта живут в репозитории как исходники под версионным контролем и задокументированы здесь. Они остаются кодом — сайт их описывает, репозиторий их хранит.

`sovol_codes` — плагин кодов экрана-крутилки#

Вендорский форк Klipper показывает числовые коды на экране-крутилке (101, 103, диапазон shutdown 60+), редактируя upstream-файлы ядра на месте — klippy/extras/homing.py, klippy/klippy.py, klippy/kinematics/corexy.py. Это связывает продуктовый UI с ядром Klipper, и поэтому принтер застрял на сквошнутом вендорском снапшоте вместо трекинга upstream.

Sovol на mainline Klipper

Архитектура

Архитектура системы#

Поверх стоковой прошивки

Runbook — миграция на месте поверх стоковой прошивки#

1. Сначала забэкапь всё#

Простая установка

Простая установка — для большинства#

Сборка прошивки

Сборка прошивки#

Тулчейн#

На хосте принтера (Allwinner H616 платы Sovol Zero, Debian aarch64)#

На macOS#

Стек KIAUH

Стек прикладного слоя через KIAUH#

Два постустановочных фикса#

Ванильный Armbian

Ванильный Armbian на плате Sovol Zero#

Есть eMMC-ридер

Runbook — сборка с чистого листа с eMMC-ридером#

1. Проинвентаризируй бэкапы#

Конфиг Klipper

Перевод конфига на mainline#

Eddy на software I2C#

Прошивка по SWD

Прошивка по SWD через Flipper Zero (DAP Link)#

Распиновка тулхеда и SWD

Распиновка тулхеда и SWD-хедер#

Коннекторы#

Восстановление

Runbook — восстановление машины, которая не поднимается#

ОС не грузится#

Миграция MCU

Миграция MCU — оба MCU на mainline#

Что нужно#

Сначала забэкапь#

Плагины

Плагины и допы venv#

scipy — нужен eddy-пробе#

sovol_codes — коды экрана-крутилки#

С чистого листа (eMMC-ридер)

Установка с чистого листа с eMMC-ридером#

Калибровка

Откалибруй и проверь#

Eddy и tap#

Натяжение ремня#

На месте, без eMMC-ридера

Переустановка ОС без eMMC-ридера#

Допы

Допы — опциональное железо и практики#

USB WiFi-донгл (когда встроенный радиомодуль умирает)#

Обновляемый Armbian

Как держать Armbian обновляемым#

Troubleshooting

Troubleshooting и тюнинг#

Прошивка и CAN#

canbus_query / flashtool.py -q показывает 0 нод#

Восстановление

Восстановление и бэкапы#

Сначала бэкап — чеклист#

Ресурсы

Плагин и патчи#

sovol_codes — плагин кодов экрана-крутилки#

`sovol_codes` — плагин кодов экрана-крутилки#