Add gcode.md

gcode.md

@@ -0,0 +1,460 @@
+# Ukuetis G-code v2
+
+Все команды делятся на две большие группы:
+
+- **Команды-настройки** (`P`-команды) — задают параметры работы печи: имя программы, термопару, максимальную температуру, допуски, коэффициенты PID, условия безопасности. Обычно располагаются в начале программы, но могут встречаться в любом месте — они применяются немедленно при исполнении.
+- **Команды-программы** (`K`-команды) — управляют непосредственно процессом обжига: задают линейный нагрев/охлаждение до заданной температуры (`K203`) или выдержку на температуре (`K107`). Исполняются последовательно и занимают время.
+
+---
+
+## Сводная таблица команд
+
+### Настройки (P-команды)
+
+| Код | Описание | Статус |
+|-----|----------|--------|
+| `P001` | Имя программы | v2 ↓ |
+| `P101` | Предупреждение/ошибка по отклонению скорости нагрева от плана | gcode.md |
+| `P102` | Предупреждение/ошибка по отклонению температуры от плана | gcode.md |
+| `P103` | Предупреждение/ошибка по превышению абсолютной температуры | gcode.md |
+| `P106` | Ограничение максимальной температуры печи | v2 ↓ |
+| `P150` | Допуск по температуре (абсолютный или процентный) | v2 ↓ |
+| `P177` | Метка времени последнего сохранения (Unix timestamp), используется для синхронизации | v2 ↓ |
+| `P200` | Настройка термопар (основная, альтернативная, внешняя, внутренняя) | v2 ↓ |
+| `P201` | Правила безопасности (по мощности нагревателя или по температуре термопары) | v2 ↓ |
+| `P202` | Название печи | v2 ↓ |
+| `P220` | Контроль средней PID-ошибки в скользящем окне | v2 ↓ |
+| `P301` | Период ШИМ | gcode.md |
+| `P302` | Параметры PID-регулятора (коэффициенты и профили по температуре) | v2 ↓ |
+| `P303` | Автонастройка PID | gcode.md |
+| `P304` | Выбор нагревателя | gcode.md |
+| `P305` | Максимальный процент использования нагревателя | gcode.md |
+| `P306` | Мощность нагревателя печи в Ваттах; используется для расчёта энергопотребления | v2 ↓ |
+| `P800` | Разработчик программы | v2 ↓ |
+| `P801` | Тип программы | v2 ↓ |
+| `P802` | Комментарий к программе | v2 ↓ |
+| `P850` | Расчётная длительность программы (только для UI, не исполняется) | v2 ↓ |
+
+### Команды-программы (K/M-команды)
+
+| Код | Описание | Статус |
+|-----|----------|--------|
+| `K001` | Версия интерпретатора (маркер совместимости) | gcode.md |
+| `K101` | Нагрев/охлаждение до температуры с заданной скоростью или временем | gcode.md |
+| `K107` | Быстрый выход на температуру с опциональной выдержкой | v2 ↓ |
+| `K110` | Нагрев/охлаждение до температуры с макс. скоростью и опциональной выдержкой | gcode.md |
+| `K120` | Выключить нагрев | gcode.md |
+| `K121` | Выключить нагрев при достижении пирометрического конуса | gcode.md |
+| `K122` | Выключить нагрев при достижении пирометрического конуса (с учётом охлаждения) | gcode.md |
+| `K150` | Отправить уведомление с произвольным сообщением | gcode.md |
+| `K151` | Ожидание действия оператора | gcode.md |
+| `K200` | Пауза на заданное время (нагрев выключен) | gcode.md |
+| `K203` | Линейный разгон/охлаждение до целевой температуры | v2 ↓ |
+| `M200` | Управление вентиляцией (0/100) | gcode.md |
+| `M201` | Управление приточкой (0/100) | gcode.md |
+| `M202` | Управление заслонкой (0/100) | gcode.md |
+
+> **v2 ↓** — команда задокументирована в этом файле ниже. **gcode.md** — код из старого чернового формата, приведён только для справки.
+
+---
+
+## Pretty G-code
+
+Pretty G-code — расширение формата, которое позволяет делать команды более читаемыми для человека, добавляя свободный текст прямо в строку команды.
+
+**Принцип работы парсера:**
+
+Парсер обрабатывает каждую строку по следующим правилам:
+1. Строка, начинающаяся с `;`, считается комментарием и игнорируется целиком.
+2. Всё после `;` в середине строки игнорируется (встроенный комментарий).
+3. Из остатка строки извлекаются токены вида `<Буква><Число>` — например `S1120`, `R130`, `H1.5`, `T600`. Всё, что не соответствует этому паттерну, **игнорируется**.
+4. Первый токен строки — это имя команды (например `K203`, `P106`). Остальные — её аргументы.
+
+**Исключения:**
+- `P001` — имя программы читается как произвольная строка (до `;` или конца строки), а не как набор токенов `<Буква><Число>`.
+- `P200` — аргументы (`MAINTK`, `C1`, `TK`) не соответствуют паттерну `<Буква><Число>` и разбираются как ключевые слова по собственным правилам команды.
+
+Благодаря этому правилу можно писать:
+```gcode
+K203 Move to S1120 °С with speed R130 °С/h
+```
+Парсер извлечёт из этой строки `K203`, `S1120`, `R130` и проигнорирует слова `Move`, `to`, `with`, `speed` и строку `°С/h`. Результат идентичен краткой записи `K203 S1120 R130`.
+
+---
+
+## K203 — линейный нагрев/охлаждение до целевой температуры
+
+```gcode
+K203 S1120 R130    ; Подъём температуры до 1120°C со скоростью 130°C/ч
+K203 S980 H1.5     ; Переход к 980°C за 1.5 часа (скорость вычисляется автоматически)
+K203 S600 M45      ; Охлаждение/нагрев до 600°C за 45 минут
+K203 S300          ; Мгновенное изменение сетпоинта до 300°C (без расчёта скорости)
+```
+
+**Pretty G-code (human-readable комментарии):**
+
+```gcode
+K203 Move to S1120 °С with speed R130 °С/h
+K203 Move to S980 °С in H1.5 hours
+K203 Move to S600 °С in M45 minutes
+K203 Move to S300 °С
+```
+
+**Параметры:**
+
+| Параметр | Описание |
+|---|---|
+| `S<температура °C>` | **Обязательно.** Положительное целевое значение. |
+| `R<°C/ч>` | Скорость нагрева/охлаждения. Взаимно исключается с `H`/`M`. |
+| `H<часы>` | Длительность в часах (может быть дробной). Используется для расчёта скорости. |
+| `M<минуты>` | Длительность в минутах (может быть дробной). Можно комбинировать с `H`. |
+
+**Особенности:**
+- Если заданы `H` и/или `M`, скорость вычисляется из текущей точки и целевой температуры.
+- При отсутствии `R`/`H`/`M` команда задаёт сетпоинт сразу, затем исполнитель ждёт стабилизации ~5 секунд.
+- Допускается охлаждение: целевая температура может быть ниже стартовой.
+
+---
+
+## K107 — быстрый выход на температуру с выдержкой
+
+```gcode
+K107 S1120         ; Дождаться стабилизации на 1120°C
+K107 S1030 H2      ; Выдержка 2 часа после выхода на 1030°C
+K107 S850 M30      ; Выдержка 30 минут после выхода на 850°C
+```
+
+**Pretty G-code (human-readable комментарии):**
+
+```gcode
+K107 Hold on S1220 °С for M5 minutes
+K107 Hold on S1030 °С for H3 hours
+```
+
+**Параметры:**
+
+| Параметр | Описание |
+|---|---|
+| `S<температура °C>` | **Обязательно.** Положительное целевое значение. |
+| `H<часы>` / `M<минуты>` | Необязательная выдержка после стабилизации. Можно комбинировать. |
+
+**Особенности:**
+- Сетпоинт устанавливается мгновенно. Исполнитель ждёт стабилизации ~20 секунд.
+- При наличии выдержки отсчёт начинается после стабилизации. Без выдержки команда завершается сразу после стабилизации.
+- Допускается переход на более низкую температуру.
+
+---
+
+## P177 — метка времени последнего сохранения
+
+```gcode
+P177 Updated at 09.03.2026, 17:17:18 U1773065838
+```
+
+**Особенности:**
+- Команда содержит метку времени Unix в параметре `U<секунды>`.
+- Текст до U-параметра (например `Updated at DD.MM.YYYY, HH:MM:SS`) игнорируется парсером.
+- Парсер извлекает только `U<целое_число>` — Unix timestamp в секундах.
+- Команда генерируется автоматически редактором при сохранении программы.
+- Используется для разрешения конфликтов при синхронизации между устройством и клиентом: побеждает файл с бо́льшим timestamp.
+- При отсутствии команды `P177` timestamp считается равным 0.
+
+---
+
+## P001 — имя программы
+
+```gcode
+P001 Bisque firing    ; Название загружаемой программы (для телеметрии и логов)
+```
+
+**Особенности:**
+- Строка имени начинается сразу после пробела и продолжается до конца строки или комментария `;`.
+- Последняя встреченная команда `P001` перезаписывает имя программы.
+- Имя сохраняется в прошивке и публикуется в MQTT.
+
+---
+
+## P106 — ограничение максимальной температуры печи
+
+```gcode
+P106 S1250    ; Установить предельную температуру 1250°C
+```
+
+**Pretty G-code (human-readable комментарии):**
+
+```gcode
+P106 Max temp: S1250 °С
+```
+
+**Параметры:**
+
+| Параметр | Описание |
+|---|---|
+| `S<°C>` | Целое положительное значение в градусах Цельсия. |
+
+При превышении предела срабатывает механизм безопасности и программа прерывается.
+
+---
+
+## P150 — допуск по температуре
+
+```gcode
+P150 D3    ; Разрешённое отклонение ±3°C
+P150 P2    ; Разрешённое отклонение ±2% от целевого значения
+```
+
+**Pretty G-code (human-readable комментарии):**
+
+```gcode
+P150 Temp tolerance in D3 °С
+P150 Temp tolerance in P0.8 %
+```
+
+**Особенности:**
+- Используйте `D<значение>` для абсолютного допуска в градусах.
+- Используйте `P<проценты>` для относительного допуска. Минимальное фактическое значение — 1°C (встроенное ограничение).
+- Последняя команда `P150` определяет активный режим допуска. `P0` переключает режим на процентный, но величина допуска берётся из последнего абсолютного значения.
+
+---
+
+## P200 — выбор основной термопары
+
+```gcode
+P200 MAINTK C1 TK    ; Основной канал C1, термопара типа K
+P200 MAINTK C1 TS    ; Основной канал C1, термопара типа S
+```
+
+**Особенности:**
+- Поддерживаются типы: `B`, `E`, `J`, `K`, `N`, `R`, `S`, `T` (буква после `T`).
+- Формат состоит из ключевого слова `MAINTK`, указания канала `C1` и типа термопары.
+- Последняя команда `P200` задаёт активный тип и публикует его в телеметрии.
+
+---
+
+## P201 — правило безопасности по мощности нагревателя
+
+```gcode
+P201 T800 P60    ; Прервать программу, если при мощности ≥60% температура ниже 800°C
+```
+
+**Pretty G-code (human-readable комментарии):**
+
+```gcode
+P201 Stop if T < T1000 °С & PWM > P100
+```
+
+**Параметры:**
+
+| Параметр | Описание |
+|---|---|
+| `T<°C>` | Целевая температура в °C (целое число). |
+| `P<проценты>` | Минимальная мощность нагревателя в процентах (0…100). |
+
+---
+
+## P202 — название печи
+
+```gcode
+P202 Plavka    ; Название печи
+```
+
+**Особенности:**
+- Строка значения читается как произвольный текст (до `;` или конца строки).
+- Используется как метаданные: публикуется в телеметрии и отображается в UI.
+- Последняя встреченная команда `P202` перезаписывает значение.
+
+---
+
+## P220 — контроль средней PID-ошибки
+
+```gcode
+P220 T25    ; Прервать программу при |ошибке PID| > 25°C в скользящем окне
+```
+
+**Pretty G-code (human-readable комментарии):**
+
+```gcode
+P220 Set max PID error T30 °С
+```
+
+**Параметры:**
+
+| Параметр | Описание |
+|---|---|
+| `T<°C>` | Положительное значение порога в градусах (до 2000°C). |
+
+**Особенности:**
+- Значение применяется сразу после команды и действует до следующего изменения.
+
+---
+
+## P302 — параметры PID-регулятора
+
+```gcode
+P302 P1.50 I0.0020 D0.25          ; Глобальные коэффициенты PID
+P302 P2.00 I0.0030 D0.40 T600     ; Профиль PID для температур ниже 600°C
+```
+
+**Pretty G-code (human-readable комментарии):**
+
+```gcode
+P302 Set PID: P1.5 I0.0015 D3 for T < T400 °C
+P302 Set PID: P1.5 I0.0015 D3
+```
+
+**Параметры:**
+
+| Параметр | Описание |
+|---|---|
+| `P<kp>` | Пропорциональный коэффициент (**обязателен**). |
+| `I<ki>` | Интегральный коэффициент (**обязателен**). |
+| `D<kd>` | Дифференциальный коэффициент (**обязателен**). |
+| `T<°C>` | Создаёт профиль, который применяется при температурах ниже указанного порога. |
+
+**Особенности:**
+- Обязательны все три аргумента: `P<kp>`, `I<ki>`, `D<kd>`.
+- Дополнительный параметр `T<температура>` создаёт профиль для температур ниже указанного порога. Можно задать до восьми профилей; они сортируются по возрастанию `T`.
+- Команда без `T` обновляет текущие коэффициенты PID немедленно.
+- Повторные вызовы `P302` допускаются в любом месте программы; последняя команда без `T` задаёт базовые параметры.
+
+---
+
+## P306 — мощность нагревателя печи
+
+```gcode
+P306 P9000    ; Мощность нагревателя 9000 Вт
+```
+
+**Pretty G-code (human-readable комментарии):**
+
+```gcode
+P306 Kiln power P9000 W
+P306 P3500
+```
+
+**Параметры:**
+
+| Параметр | Описание |
+|---|---|
+| `P<Ватты>` | **Обязательно.** Номинальная мощность нагревателя в Ваттах (целое положительное). |
+
+**Особенности:**
+- Мощность публикуется в MQTT в топик `/telemetry/gcode/kiln_power_w` при исполнении команды.
+- На основе заданной мощности и текущего PWM-процента контроллер каждую секунду интегрирует потреблённую энергию:
+
+  ```
+  E += kiln_power_w × pwm_percent / 100 × (1с / 3600)   [кВт·ч]
+  ```
+
+- Накопленная энергия с начала текущего обжига публикуется в MQTT в топик `/telemetry/gcode/current_energy_kwh`.
+- Счётчик обнуляется при каждом старте новой программы (переходе в статус `RUNNING`).
+- Если команда `P306` не задана, расчёт энергии не производится и топик не публикуется.
+- Последняя встреченная команда `P306` задаёт активную мощность и перезаписывает предыдущее значение.
+
+---
+
+## P800 — разработчик программы
+
+```gcode
+P800 OVO
+```
+
+**Особенности:**
+- Строка значения читается как произвольный текст (до `;` или конца строки).
+- Используется как метаданные программы: публикуется в телеметрии и отображается в UI.
+- Последняя встреченная команда `P800` перезаписывает значение.
+
+---
+
+## P801 — тип программы
+
+```gcode
+P801 Высокий
+```
+
+**Особенности:**
+- Строка значения читается как произвольный текст (до `;` или конца строки).
+- Задаёт классификацию или режим программы; используется как метаданные.
+- Последняя встреченная команда `P801` перезаписывает значение.
+
+---
+
+## P802 — комментарий к программе
+
+```gcode
+P802 Специальный режим для маленьких печей, которые быстро остывают: в нем есть медленное охлаждение в конце
+```
+
+**Особенности:**
+- Строка комментария читается как произвольный текст (до `;` или конца строки).
+- Используется как поясняющий текст к программе; отображается в UI.
+- Последняя встреченная команда `P802` перезаписывает значение.
+
+---
+
+## P850 — расчётная длительность программы
+
+```gcode
+P850 Firing and cooling to 300°C will take 1 day, 2 hours, 27 minutes S95270
+```
+
+**Параметры:**
+
+| Параметр | Описание |
+|---|---|
+| `S<секунды>` | Расчётная длительность в секундах (целое число). |
+
+**Особенности:**
+- Команда содержит расчётное время в параметре `S<секунды>`.
+- Текстовая часть строки (до параметра `S`) игнорируется парсером — это human-readable описание для удобства чтения файла.
+- Генерируется автоматически редактором при сохранении программы на основе расчёта длительности.
+- **Не исполняется прошивкой** — служит исключительно для отображения расчётного времени в UI.
+- При отсутствии команды `P850` длительность программы считается неизвестной.
+
+---
+
+## Пример последовательности
+
+**Стандартный G-code:**
+
+```gcode
+; Settings
+P001 "Stoneware cycle"              ; Название программы
+P200 MAINTK C1 TK                   ; Основной канал C1, термопара типа K
+P106 S1280                          ; Максимальная температура 1280°C
+P150 D3                             ; Допуск ±3°C
+P302 P1.30 I0.0025 D0.35 T600       ; PID-профиль для температур ниже 600°C
+P302 P1.10 I0.0015 D0.20            ; Базовые коэффициенты PID
+P201 T750 P70                       ; Аварийное условие по мощности
+P220 T20                            ; Контроль средней ошибки PID
+
+; Program
+K203 S600 R180                      ; Разгон до 600°C со скоростью 180°C/ч
+K203 S980 H1.5                      ; Переход к 980°C за 1.5 часа
+K107 S980 H0.5                      ; Выдержка 30 минут на 980°C
+K203 S1220 R80                      ; Подъём до 1220°C со скоростью 80°C/ч
+K107 S1220 M45                      ; Выдержка 45 минут
+K203 S300                           ; Плавное охлаждение до 300°C (сетпоинт снизится мгновенно, исполнитель дождётся стабилизации)
+
+```
+
+**Pretty G-code:**
+
+```gcode
+P001 Stoneware cycle
+P200 MAINTK C1 TK
+P106 Max temp: S1280 °С
+P150 Temp tolerance in D3 °С
+P302 Set PID: P1.30 I0.0025 D0.35 for T < T600
+P302 Set PID: P1.10 I0.0015 D0.20
+P201 Stop if T < T750 °С & PWM > P70
+P220 Set max PID error T20 °С
+
+K203 Move to S600 °С with speed R180 °С/h
+K203 Move to S980 °С in H1.5 hours
+K107 Hold on S980 °С in H0.5 hours
+K203 Move to S1220 °С with speed R80 °С/h
+K107 Hold on S1220 °С for M45 minutes
+K203 Move to S300 °С
+
+```