Download the PHP package hopex/bambulab-sdk without Composer

Bambu Lab API для PHP

Полностью типизированный PHP 8.4 SDK для локального управления принтерами Bambu Lab.

Пакет предоставляет типизированный API для работы с состоянием принтера, заданиями печати, файлами, камерой, температурой, вентиляторами, подсветкой, прошивкой, HMS-сообщениями и событиями в реальном времени.

Проект является неофициальным SDK сообщества и не связан с Bambu Lab.

Возможности

• MQTT
• FTPS
• Camera
• Printer State
• Events
• Firmware
• HMS
• Files
• Temperature
• Fans
• Light
• Automatic reconnect

Требования

• PHP 8.4 или новее;
• расширение ext-curl;
• расширение ext-json;
• расширение ext-openssl;
• доступ к принтеру по локальной сети;
• включённый LAN Mode;
• действующий Access Code принтера.

SDK использует несколько локальных сервисов принтера:

• MQTT для команд и состояния;
• FTPS для работы с файлами;
• отдельное TLS-соединение для камеры.

Поддержка конкретных возможностей зависит от модели принтера и версии прошивки.

Установка

Настройка принтера

Перед использованием SDK:

1. Подключите принтер и PHP-приложение к одной локальной сети.
2. Включите LAN Mode в настройках принтера.
3. Получите Access Code.
4. Определите локальный IP-адрес принтера.
5. Получите серийный номер принтера.

Не рекомендуется открывать MQTT, FTPS и порт камеры напрямую в интернет.

Быстрый старт

Жизненный цикл клиента

Подключение

По умолчанию клиент активирует MQTT-подписку и запрашивает полное состояние принтера.

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

Обработка входящих сообщений

Одна итерация MQTT-цикла:

Блокирующий цикл:

Остановка активного цикла:

Отключение

Состояние принтера

PrinterState хранит накопленное состояние принтера.

Принтер часто отправляет только изменившиеся поля. SDK рекурсивно объединяет частичные сообщения с ранее полученным состоянием.

Получение полного накопленного payload:

Текущее задание печати

Текущее задание представлено объектом CurrentPrintJob.

Доступные вспомогательные методы:

При локальном запуске облачные идентификаторы, например taskId и projectId, могут отсутствовать.

Состояния G-code

Состояние печати представлено enum GcodeState.

Вспомогательные методы:

Состояние FAILED может означать как реальную ошибку, так и ручную отмену задания.

Ожидание состояния

Ожидание запуска печати:

Ожидание одного из нескольких состояний:

Ожидание пользовательского условия:

Управление печатью

Запуск задания

Файл должен быть предварительно загружен на принтер.

Пауза

Продолжение

Остановка

После ручной отмены принтер обычно сообщает состояние FAILED.

Запрос полного состояния

G-code

Отправка одной команды:

Отправка нескольких команд:

Произвольный G-code может запустить движение механизмов, нагрев и другие опасные операции. Проверяйте команды перед отправкой.

Подсветка

Включение:

Выключение:

Получение текущего состояния:

Температура

Температура сопла:

Температура стола:

Получение текущих значений:

Настроенные ограничения SDK:

Корректная безопасная температура зависит от модели принтера, сопла, стола и используемого материала.

Вентиляторы

Управление вентиляторами выполняется через FanApi.

Альтернативно можно использовать проценты.

Остановка вентилятора:

Перед использованием дополнительного вентилятора рекомендуется проверить возможности принтера:

При использовании заведомо отсутствующей возможности SDK может выбросить UnsupportedCapabilityException.

Файлы

Работа с файловой системой принтера выполняется через FTPS.

Типизированный список

Только файлы

Только директории

Только модели 3MF

Фильтрация по расширению

Можно передавать расширение с точкой или без неё:

Поиск элемента

Проверка существования

Пользовательская фильтрация

Загрузка

Скачивание

Удаление

Файловые операции используют собственное FTPS-соединение и не зависят от активного MQTT-цикла.

Камера

Получение одного JPEG-кадра:

Сохранение кадра:

Дополнительные представления:

Поддержка камеры зависит от модели принтера и используемого локального протокола.

Текущая реализация TcpCameraTransport предназначена для совместимых локальных TLS-потоков камеры.

Информация об устройстве

Состояние периферии:

Возможности принтера

Возможности определяются по фактическому состоянию, полученному от принтера.

До полной синхронизации некоторые значения могут быть равны null.

Прошивка

Запрос актуальной информации:

Получение основной версии:

Получение модулей:

Получение состояния обновления:

Первая версия API прошивки предназначена только для чтения данных. Установка и откат прошивки не поддерживаются.

HMS

HMS содержит сообщения диагностики, предупреждения и аппаратные ошибки принтера.

Предупреждения:

Ошибки:

Проверки:

Не все прошивки передают человекочитаемое описание и уровень сообщения. В таком случае SDK сохраняет исходные данные и использует уровень UNKNOWN.

События

Обработчики событий вызываются синхронно во время tick(), run() или runWithReconnect().

Начало печати

Пауза и продолжение

Завершение и отмена

Определение ручной отмены является эвристическим, поскольку принтер обычно использует состояние FAILED.

Изменение задания

Изменение прогресса и слоя

Оставшееся время

Температура, свет и HMS

Отмена подписки

Удаление всех подписок:

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

Для длительно работающих процессов можно использовать runWithReconnect().

Параметры политики переподключения

После успешного переподключения клиент:

1. создаёт новое MQTT-соединение;
2. повторно активирует подписку;
3. запрашивает полное состояние;
4. сохраняет зарегистрированные обработчики событий;
5. продолжает цикл обработки сообщений.

Одна итерация с автоматическим восстановлением:

Явное переподключение:

Пользовательские реализации

Основные механизмы SDK построены на контрактах.

MQTT-транспорт

Файловый транспорт

Транспорт камеры

Это позволяет заменить стандартную реализацию, например при интеграции с другим MQTT-клиентом, файловым шлюзом или собственным сервисом камеры.

Исключения

Все исключения SDK наследуются от:

Общая обработка:

Основные группы исключений:

• ошибки подключения и транспорта;
• ошибки переподключения;
• ошибки сериализации MQTT;
• ошибки файловых операций;
• ошибки камеры;
• ошибки G-code;
• попытка использовать неподдерживаемую возможность.

Исключения разнесены по соответствующим feature-модулям.

Совместимость и ограничения

• SDK ориентирован на локальное управление принтером.
• Поведение протокола может отличаться между моделями и прошивками.
• Некоторые поля состояния могут отсутствовать.
• Не все функции протестированы на всех сериях Bambu Lab.
• AMS API пока не является приоритетным модулем.
• Потоковое видео камеры пока не поддерживается.
• Обновление и откат прошивки не поддерживаются.
• HMS может возвращать только код без текстового описания.
• FAILED не всегда означает аппаратную неисправность.
• SDK не предоставляет облачную авторизацию Bambu Lab.

Документация

Полная документация по каждому модулю будет доступна отдельно:

Открыть документацию

Планируемые разделы:

• начало работы;
• клиент и подключение;
• состояние принтера;
• управление печатью;
• G-code;
• файлы;
• камера;
• температура;
• вентиляторы;
• подсветка;
• устройство;
• прошивка;
• HMS;
• события;
• переподключение;
• исключения;
• расширение SDK;
• архитектура.

Безопасность

Не публикуйте в репозитории:

• Access Code;
• серийный номер принтера;
• внутренний IP-адрес, если это нежелательно;
• файлы конфигурации с учётными данными.

Используйте переменные окружения:

Не открывайте локальные сервисы принтера напрямую в интернет.

Статус проекта

SDK находится в активной разработке.

Перед выпуском стабильной версии рекомендуется зафиксировать:

• поддерживаемые модели;
• поддерживаемые версии PHP;
• список протестированных прошивок;
• правила обратной совместимости;
• формат версионирования.

Участие в разработке

Сообщения об ошибках и Pull Request приветствуются.

Перед отправкой изменений:

1. проверьте соответствие структуры feature-first архитектуре;
2. сохраняйте строгую типизацию;
3. добавляйте документацию на русском языке;
4. не добавляйте зависимость от Laravel в основной пакет;
5. не ломайте существующие публичные контракты без необходимости.

Лицензия

Проект распространяется по лицензии MIT.