Telegram-бот¶

BamDude включає вбудованого Telegram-бота (aiogram 3.x) для повного керування принтерами, моніторингу та сповіщень безпосередньо з Telegram.

Огляд¶

Telegram-бот забезпечує:

Статус принтерів -- Перегляд усіх принтерів зі статусом у реальному часі
Керування друком -- Пауза, зупинка та відновлення друків
Знімки з камери -- Перегляд живих зображень з камери, з кнопками керування просто під фото
Пропуск бракованої деталі -- Виключити одну деталь посеред друку замість втрати всієї плити
Керування швидкістю -- Зміна швидкості друку на льоту
Друк з бібліотеки -- Перегляд та запуск друків з файлової бібліотеки
Надсилання файлу боту -- Файл потрапляє в бібліотеку, і його одразу можна надрукувати
Керування чергою -- Перегляд та управління чергою друку
Калібрування -- Запуск процедур калібрування принтера
Обслуговування -- Перегляд та виконання завдань обслуговування
Статистика -- Перегляд статистики друку
Активні сповіщення -- Інлайн-кнопки при завершенні, помилці, прогресі друку

Налаштування¶

Крок 1: Створення Telegram-бота¶

Відкрийте Telegram і знайдіть @BotFather
Надішліть /newbot і дотримуйтесь інструкцій
Оберіть ім'я та юзернейм для бота
Скопіюйте токен бота, наданий BotFather

Крок 2: Налаштування в BamDude¶

Перейдіть до Settings > Notifications
Додайте провайдер сповіщень Telegram
Вставте токен бота
Увімкніть провайдер
Бот почне автоматичний полінг

Конфіг на рівні бота навмисно мінімальний (m045)

Telegram-провайдер тримає лише name, токен бота, enabled і опційний розклад щоденного дайджесту (daily_digest_enabled + daily_digest_time). Per-event opt-in, тихий час і per-chat digest opt-in живуть у кожному TelegramChat — див. Per-Chat Notification Preferences нижче. 24 поля on_* і quiet_hours_*, які shared з email / ntfy / pushover / discord / webhook / homeassistant / callmebot, для telegram нормалізовані до dispatch-transparent значень (on_*=True, quiet_hours_enabled=False) — на поведінку бота вони більше не впливають.

Крок 3: Авторизація чату¶

Відкрийте бота в Telegram і надішліть /start
Бот зареєструє ваш чат
Перейдіть до Settings > Notifications > Telegram Chats у BamDude
Авторизуйте чат і призначте групу (роль)

Джерело токена бота

Токен бота зчитується з першого увімкненого провайдера сповіщень Telegram у базі даних.

Перевірка прав на кожне повідомлення

Кожна команда та натискання на інлайн-кнопку проходить через auth_middleware перед запуском обробника. Middleware шукає чат у telegram_chats, визначає призначену йому групу і відхиляє дію, якщо група не має відповідного права resource:action (наприклад, printers:control, archives:read). Неавторизовані чати побачать "У вас немає прав" / "You don't have permission" замість виконання дії.

Команди¶

Бот реєструє лише невеликий набір slash-команд; усе інше керується reply-клавіатурою, що /start розгортає. Сприймайте кнопки клавіатури (📋 Принтери / 🖨️ Черга / 📊 Стата / 📷 Камера / тощо) як основну навігацію — введення /printers чи /queue не зматчить жоден handler і бот провалиться у unknown-command.

Команда	Опис
`/start`	Реєстрація чату та головне reply-меню
`/help`	Показати доступні команди
`/status`	Швидкий статус усіх принтерів
`/camera`	Camera snapshot picker

Інлайн-меню¶

Бот використовує інлайн-кнопки для навігації замість текстових команд:

Список принтерів -- Натисніть на принтер для деталей, керування або камери
Дії друку -- Пауза, зупинка, відновлення з підтвердженням
Пресети швидкості -- Кнопки швидкого налаштування швидкості
Камера -- Запит живого знімка
Калібрування -- Запуск вирівнювання столу, компенсації вібрації тощо
Черга -- Пагінований перегляд черги з індикаторами статусу

Знімки з камери¶

Запитуйте знімки з камери безпосередньо в Telegram:

Оберіть принтер зі списку
Натисніть Camera
Знімок надсилається як фото-повідомлення

/camera робить те саме без походу в список принтерів: одразу знімок, якщо принтер один, або вибір, якщо їх кілька.

Кнопки приходять разом із фото¶

Якщо принтер друкує, а чат має право керувати ним, знімок приходить із тими самими кнопками, що й картка принтера: Пауза або Продовжити, Стоп, Швидкість і Пропустити об'єкт. У цьому й сенс: побачити проблему і відреагувати на неї не має означати вихід із чату.

Це ті самі кнопки, зібрані в одному місці, тож розійтися з кнопками на картці принтера вони не можуть. Стан читається в момент знімка, а не успадковується з екрана, з якого ви прийшли.

Чат лише з правом перегляду отримує звичайне фото — так само як і фото з принтера, що не друкує.

Стоп перепитує

Стоп завершує друк і викидає всі деталі плити, а тут він стоїть просто під картинкою, на яку ви щойно глянули. Він просить підтвердження — і в боті загалом, не лише під фото.

Пропуск об'єктів¶

Виключити одну браковану деталь і дати решті плити додрукуватися. Натисніть Пропустити об'єкт на картці принтера або під знімком з камери.

Бот надсилає плиту, знято згори, з номерованою позначкою на кожному об'єкті, а під нею — клавіатуру з тих самих номерів. Натисніть номер, звірте назву, яку бот називає у відповідь, і підтвердіть.

Позначки розкладає той самий код, що й накладка у вебі, тож один номер означає одну й ту саму деталь і в боті, і в браузері.
Уже пропущені об'єкти лишаються на екрані — сірими й без реакції. Їх не прибирають, бо це зсунуло б усі сусідні кнопки.
Великі плити гортаються посторінково, по п'ятнадцять об'єктів.

Пропуск неможливо скасувати, тому бот підтверджує за назвою, а не голим «ви впевнені?», і пояснює себе, коли допомогти не може:

Що ви бачите	Що це означає
Немає кнопки Пропустити об'єкт	Принтер відрапортував, що взагалі не вміє пропускати деталі
«Цю плиту нарізано без міток об'єктів»	При нарізці потрібні обидві опції — Label objects і Exclude objects; див. Керування принтером
«У друці лишився один об'єкт»	Пропустити його — це завершити друк, а для цього є Стоп
Список без картинки	У цьому 3MF немає рендера плити згори. Бот не малюватиме позначки на ¾-вигляді натомість — вони переконливо вказали б не на ті деталі

Надсилання файлу боту¶

Перешліть або завантажте документ у чат — і він потрапить у файлову бібліотеку.

Надішліть файл
Оберіть, у яку папку бібліотеки він належить (за замовчуванням пропонується папка Telegram, що створюється при першому використанні)
Бот зберігає його з тими самими перевірками, мініатюрами й виявленням дублікатів, що й завантаження через веб

Якщо файл готовий до друку, бот одразу пропонує надрукувати його або додати в чергу. Моделі та STL теж приймаються — це цілком нормальні файли бібліотеки — і бот прямо каже, що надрукувати їх не можна, доки вони не нарізані, замість того щоб пропонувати кнопку, яка впаде на принтері.

Telegram Bot API обмежує завантаження 20 МБ. Більший файл відхиляється одразу, за назвою та з названим лімітом, а не після очікування.

Друк з бібліотеки (Scene/FSM)¶

Запуск друку з файлової бібліотеки через інтерактивний потік:

Натисніть Print from Library в головному меню
Перегляньте файли з пагінацією
Оберіть файл
Оберіть цільовий принтер
Підтвердіть для друку або додавання в чергу

Потік використовує FSM (скінченний автомат) aiogram для багатокрокових взаємодій.

Додавання принтера (Scene)¶

Додайте новий принтер безпосередньо з Telegram:

Введіть IP-адресу принтера
Введіть код доступу (8-значний код з мережевих налаштувань принтера)
BamDude підключається, автоматично визначає модель та серійний номер принтера і додає його в базу
Підтвердіть додавання

Без mDNS-автодискаверингу

Сцена додавання принтера в Telegram явно запитує IP + код доступу -- автоматичного пошуку в LAN зсередини бота немає. Знайдіть IP на екрані принтера (Settings > Network) перед запуском потоку.

Активні сповіщення¶

Сповіщення, надіслані в Telegram, включають інлайн-кнопки дій:

Сповіщення	Дії
Print Complete	Очистити стіл
Print Failed	Очистити стіл
Maintenance Due	Позначити виконаним
Print Progress	Пауза / Зупинка

Брак… у повідомленні про завершення і після Стіл очищено / Повторити друк: по повідомленню на деталь з кнопками 0–5 (інше… — ввести число), без браку, готово завершує. Потрібне право очищати стіл і принтер у межах чату.

Multi-чат ролі та авторизація¶

BamDude трактує кожен Telegram-чат (приватний або груповий) як незалежну ідентичність зі своєю роллю. Додавайте скільки завгодно чатів — типові розкладки:

Приватний чат власника — група Administrators, отримує всі події.
Груповий чат майстерні — Operators, лише події життєвого циклу друку.
Чат "тільки читання" — група Viewers, бачить статус, але не може ставити на паузу / зупиняти.

Бот спільний за токеном, ізольований за роллю: один бот-юзер обслуговує усі чати, але auth_middleware resolve-ить per-chat групу на кожне натискання перед запуском обробника. Чат без групи (авто-реєстрований, pending setup) нічого не читає і нічого не робить, поки адмін не призначить групу у Settings → Notifications → Telegram Chats.

За бажанням прив'яжіть чат до користувача системи BamDude (user_id) для аудит-логування. Прив'язка не перебиває прав групи — група є авторитетом над тим, що може робити чат.

Per-chat налаштування сповіщень¶

Кожен Telegram-чат має власну конфігурацію сповіщень, редаговану у Settings → Notifications → Telegram Chats → . Жодне з цих налаштувань не тече між чатами — їх задають окремо для кожного.

Фільтр подій¶

Виберіть, які з 23 типів подій (backend/app/models/telegram_chat.py::ALL_NOTIFY_EVENTS) цей чат має отримувати. Після m045 це єдина authority для per-event фільтра в telegram — provider-row на рівні бота більше не гейтує події. Дефолти відображають те, що цікавить більшість операторів:

Дефолтно увімкнено
`print_complete`, `print_failed`, `print_stopped`, `plate_not_empty`, `queue_job_waiting`, `queue_job_skipped`, `queue_job_failed`

Усе інше (print_start, print_progress, printer_offline, maintenance_due, AMS humidity/temperature, події черги тощо) opt-in. Чат майстерні може передплатити лише print_failed; адмінський чат — взагалі все.

should_notify(event_type) запускається на кожне сповіщення: чат має бути активним, поза quiet hours, і подія має бути в його списку увімкнених, перш ніж повідомлення піде.

Поріг проміжного прогресу¶

Біля чекбокса «Проміжний прогрес» кожен чат несе мінімальну тривалість: повідомлення 25/50/75% глушаться для друків, коротших за стільки хвилин (порожньо або 0 = слати завжди). По-чатово — 60-хвилинний поріг адміна не вирішує за чат оператора, якому треба 10. Як оцінюється тривалість — див. Notifications.

Скоуп принтерів¶

Чат можна обмежити конкретними принтерами — всі, один чи кілька — у налаштуваннях чату. Скоуп працює в обидва боки: сповіщення приходять лише від принтерів чату, і сам бот показує та керує лише ними (список принтерів, камери, черга, керування; кнопка зі старого повідомлення на принтер поза скоупом відхиляється). Події без прив'язки до принтера (тестові повідомлення, загальнофермові новини) досі доходять до кожного чату. Це замінило старий провайдерський фільтр принтера — для telegram прив'язку провайдера міграція переносить на наявні чати і очищує, як і кожен інший провайдерський важіль.

Тихі години (quiet hours)¶

Глушити сповіщення у щоденному вікні (наприклад, 22:00 → 07:00). Підтримуються як вікна одного дня (08:00 → 18:00), так і нічні (22:00 → 07:00) — порівняння автоматично огинає північ.

Поле	Призначення
`quiet_hours_enabled`	Master перемикач on/off
`quiet_hours_start`	Час старту, `HH:MM` (24h)
`quiet_hours_end`	Час закінчення, `HH:MM` (24h)

Тихі години стосуються усіх подій цього чату — per-event override-у немає. Пари з фільтром подій тримають критичні події увімкненими і заглушують ненайважливіші.

Щоденний digest¶

Перемикач daily_digest на чаті opt-in-ить його у щоденне summary-повідомлення. Час дайджесту задається на боті, а не на чаті — кожен opt-in-нутий чат отримує digest у момент, заданий у daily_digest_time provider-row-а. Картка чату показує бейдж 📅 HH:MM з часом бота, коли обидва кінці opt-in, або амбер digest off — коли чат opt-in, а на боті digest вимкнений (тоді toggle на чаті no-op, доки на боті не ввімкнуть).

Дві захисні рейки в dispatch-шляху:

Skip-on-empty queue: коли non-digest подія fire-ить з provider daily_digest_enabled=True, але жоден чат не має daily_digest=True, BamDude взагалі не пише подію в notification_digest_queue — таблиця не накопичує рядки, які ніхто не прочитає.
Окремий digest-send шлях: telegram digest send іде через _send_telegram_digest_to_chats(provider, title, body), що фан-аутить тільки чатам з daily_digest=True і обходить per-event-фільтр should_notify(...). Цей шлях також виправляє pre-refactor silent bug, де legacy-код проганяв digest body через should_notify("unknown") і відкидав кожен чат — черга накопичувалась, але до жодного чату digest не доходив.

Інтернаціоналізація¶

Усі рядки інтерфейсу бота перекладаються. Рядки зберігаються в backend/app/data/telegram_ui_{lang}.json і доступні через t(lang, "telegram_ui", "key").

Наразі підтримуються: англійська (en), українська (uk).

Поради¶

Форматування MarkdownV2

Весь динамічний текст, надісланий ботом, використовує формат Telegram MarkdownV2. Спеціальні символи автоматично екрануються через escape_md().

Підтримка групових чатів

Бот працює як у приватних, так і в групових чатах. Кожен чат авторизується незалежно зі своїми правами.

Маршрутизація сповіщень

Різні чати можуть отримувати різні події сповіщень. Налаштуйте події сповіщень для кожного чату у веб-інтерфейсі.