Обновлены вспомогательные файлы и скрипты
This commit is contained in:
+164
@@ -0,0 +1,164 @@
|
||||
# Проект разработки для ПЛК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>"
|
||||
```
|
||||
Reference in New Issue
Block a user