# Проект разработки для ПЛК210 (ОВЕН)

## Описание проекта

- **ПЛК:** ОВЕН ПЛК210
- **Среда разработки:** CODESYS 3.5 SP17 Patch 3
- **Основной язык программирования:** ST (Structured Text / МЭК 61131-3)

## Правила работы ИИ-ассистента с этим репозиторием (Strict Rules)

1. **Бинарник — источник истины:** Файлы `.st` в `plc_src/` — это лишь зеркало. Никакие правки в `.st` не считаются примененными, пока пользователь не прогонит скрипт импорта в CODESYS.
2. **Паспорт файла неизменен:** Секция `(* ... *)` в начале `.st` файлов содержит служебные метаданные для Python-скриптов. **Категорически запрещено** удалять или изменять структуры этих заголовков.
3. **Запрет гадания API:** Использовать ТОЛЬКО те функциональные блоки, функции и типы из внешних библиотек, которые явно описаны в `libs/<ИмяБиблиотеки>_API.md`. Если блока нет — запросить сигнатуру у пользователя.
4. **Безопасность циклов:** Никогда не использовать неограниченные циклы `WHILE` или `REPEAT`. Вся циклическая логика должна опираться на естественный цикл задачи CODESYS (Main Task), иначе сработает **Watchdog** ПЛК.
5. **Атомарность:** При модификации файла вносить изменения минимально необходимыми диффами. Не переписывать весь блок без необходимости.
6. **Новые объекты — только с подтверждением:** Создание нового POU/GVL/DUT (объекта, которого раньше не было в проекте) — необратимое изменение структуры проекта при реальном импорте. Не создавай новый файл с новым объектом молча в рамках другой задачи — явно предупреди пользователя и дождись подтверждения.
7. **Не гадать по существующим символам проекта:** Если нужно сослаться на переменную/POU/тип, которые предположительно уже есть в проекте (не создаются заново) — проверь их в `plc_src/` (grep/поиск по имени), а не полагайся на память или правдоподобное совпадение.

---

## Архитектура проекта и структуры данных

### Иерархия вызова программ (Main Task)

- `PLC_PRG`: Главный цикл управления. Содержит только вызов подпрограмм (POU).

### Сеть и протоколы

- **Modbus TCP Master и Slave:** Порты `Ethernet1 / Ethernet2`
- **Modbus RTU:** Интерфейсы `RS-485-1 / RS-485-2`
- Modbus не могут быть экспортированы в .st файл

### Глоссарий сокращений

<!-- Расшифровка предметных сокращений в именах POU/переменных, которые не покрываются Hungarian-нотацией типов ниже. -->

-

---

## Структура репозитория

```text
.
├── <Проект>.project            # бинарный проект CODESYS — источник истины для компиляции
├── plc_src/                    # текстовый экспорт POU/GVL/DUT — ИМЕННО ЭТИ ФАЙЛЫ читает и правит ИИ-ассистент
│   ├── <Устройство>/
│   │   ├── POU/
│   │   ├── GVL/
│   │   └── DUT/
│   └── _common/
├── tools/
│   ├── export_plc_src.py       # скрипт экспорта .project -> plc_src (текст)
│   └── import_plc_src.py       # скрипт импорта plc_src (текст) -> .project
├── libs/
│   └── <ИмяБиблиотеки>_API.md  # справочник по FB/FUNCTION самописной библиотеки (файл может отсутствовать)
└── Algoritm.md                 # Основной алгоритм работы (файл может отсутствовать)
```

`plc_src/` генерируется скриптом `tools/export_plc_src.py` из `.project` через CODESYS Scripting API.
Это НЕ исходный код в привычном смысле — это зеркало текущего состояния `.project`, нужное для того, чтобы у git был человекочитаемый дифф, а у ИИ-ассистента — текстовые файлы для правки.

---

## Рабочий цикл правки логики (важно!)

Перенос правок туда-обратно автоматизирован через пару скриптов, но применяется он **не мгновенно** — между правкой `.st`-файла и тем, что окажется в проекте, есть шаг, который делает пользователь руками в CODESYS. Порядок действий:

1. ИИ-ассистент правит `.st`-файл(ы) в `plc_src/...`. Заголовок-паспорт файла (блок `(* ... *)` в начале, с полями Project/Device/Path/Name/Type) **не трогать и не удалять** — по нему `import_plc_src.py` определяет, в какой POU/METHOD/GVL/DUT проекта записать текст.
2. Пользователь открывает проект в CODESYS и запускает `tools/import_plc_src.py`.
3. Компилирует и тестирует проект в CODESYS как обычно.
4. **Перед коммитом перезапускает `tools/export_plc_src.py`**, чтобы `plc_src/` снова точно соответствовал `.project` — иначе дифф в git будет показывать код, которого уже нет в бинарнике (или наоборот — не будет показывать то, что уже есть).
5. Коммитит `.project` и `plc_src/` вместе.

ИИ-ассистент: никогда не считай правку `.st`-файла уже применённой к `.project` — это только предложение изменения. Реальный эффект появится только после того, как пользователь прогонит `import_plc_src.py` (сам, руками) и подтвердит результат.

**ИИ-ассистент никогда не запускает `import_plc_src.py` (и команду CODESYS.exe, вызывающую его) самостоятельно — это исключительно ручной шаг пользователя.**

---

## Особенности формата .st файлов (важно при правке)

- Один `.st`-файл может содержать несколько блоков подряд: основной POU и дописанные METHOD/PROPERTY/ACTION (каждый со своим заголовком-паспортом). Если добавляешь новый METHOD/ACTION в существующий POU — дописывай его в конец того же файла со своим заголовком, а не создавай отдельный файл.
- Для ACTION в заголовке не бывает декларации, только implementation — так и должно быть.
- `END_PROGRAM` / `END_FUNCTION_BLOCK` / `END_METHOD` и т.п. в конце блока — оставляй, их пишет `export_plc_src.py`, а `import_plc_src.py` сам их убирает перед отправкой в API. Не убирай их сам и не убирай случайно при правке.
- Новый POU/GVL/DUT, которого раньше не было — можно создавать новым файлом с правильным заголовком (см. правило 6 выше про обязательное подтверждение); `import_plc_src.py` создаст объект в проекте автоматически (`get_or_create_*`). Но: сигнатуры создания через API в скрипте помечены как версионно-хрупкие — если создание упадёт с ошибкой, это ожидаемо, надо смотреть Tools → Scripting → API нужной версии.

---

## Что нельзя трогать без согласования

<!-- Конкретные POU/цепи/переменные, критичные для безопасности — правки в них только после явного обсуждения, а не как побочный эффект другой задачи. -->

-

---

## Библиотека (внешний проект)

Есть самописная библиотека — отдельный CODESYS-проект, её исходники в этот репозиторий **не включаются**.

- Справочник по публичному API лежит в `libs/<ИмяБиблиотеки>_API.md`
- Там для каждого FB/FUNCTION: сигнатура, VAR_INPUT/VAR_OUTPUT/VAR_IN_OUT с типами, краткое описание
- **ИИ-ассистент: используй только то, что описано в `libs/<ИмяБиблиотеки>_API.md`.** Не придумывай сигнатуры блоков библиотеки, которых нет в справочнике — если нужного блока/параметра там нет, спроси, а не предполагай

---

## Соглашения по коду

### Именование элементов (Hungarian Notation / Prefix System)

**Физические входы/выходы**, привязанные к модулям, — в `VAR_GLOBAL` RAW_IO:
- `RDI_` — Raw Digital Input
- `RDO_` — Raw Digital Output
- `RAI_` — Raw Analog Input
- `RAO_` — Raw Analog Output

**Входы/выходы после присвоения и нормировки** — в `VAR_GLOBAL` IO:
- `DI_` — Digital Input
- `DO_` — Digital Output
- `AI_` — Analog Input
- `AO_` — Analog Output

**Типы POU:**
- `FB_` — Функциональный блок
- `FC_` — Функция
- `DUT_` — Пользовательский тип данных (Struct, Enum)

### Правила форматирования и стиля

1. **Язык:** код, имена переменных и блоков — на **английском языке**; комментарии и документация — на **русском**.
2. **Автоматы состояний (State Machines):** всегда использовать `CASE ... OF`, не заменять его цепочкой `IF ... ELSIF`, если по сути нужен автомат.
3. **Безопасность:**
   - деление на ноль и выход за границы массива должны быть явно заблокированы проверками *до* операции.
4. **Таймеры:** использовать только стандартные `TON`, `TOF`, `TP` из библиотеки `Standard`.
5. **Циклы:** без неограниченных `WHILE`/`REPEAT` — см. правило 4 в разделе Strict Rules выше (иначе сработает Watchdog).

---

## Особенности оборудования ПЛК210

- **Retain-память:** Энергонезависимые переменные объявлять строго в секции `VAR RETAIN` или `VAR PERSISTENT`. Использовать экономно.
- **Встроенные входы/выходы:** Использовать таргетные переменные из дерева `ПЛК210 -> Входы/Выходы`. Сырые переменные в RAW_IO, именно их привязку делать через `IO_Mapping`.
- **Флеш-память:** Избегать частой циклической записи файлов во внутреннюю память ПЛК (использовать буферизацию в RAM).

---

## Полезные команды

Запуск экспорта из командной строки (без открытия GUI CODESYS):

```powershell
"C:\Program Files (x86)\CODESYS 3.5.17.30\CODESYS\Common\CODESYS.exe" ^
  --Profile="CODESYS V3.5 SP17 Patch 3" --runscript="tools/export_plc_src.py" ^
  --project="<путь к .project>"
```

Запуск импорта из командной строки (без открытия GUI CODESYS):

```powershell
"C:\Program Files (x86)\CODESYS 3.5.17.30\CODESYS\Common\CODESYS.exe" ^
  --Profile="CODESYS V3.5 SP17 Patch 3" --runscript="tools/import_plc_src.py" ^
  --project="<путь к .project>"
```