Версионирование I/O Map

Урок 4 · Монтаж и пусконаладка контроллера · 10 мин · theory

Зачем инженеру умного дома система контроля версий?

На первый взгляд, инструменты вроде Git могут показаться избыточными для инженера-инсталлятора, чья основная задача — физический монтаж и настройка оборудования. Однако, как только проект выходит за рамки одной комнаты, а количество подключенных датчиков и реле превышает десяток, управление конфигурацией превращается в сложную и чреватую ошибками задачу. Карта входов-выходов (I/O Map) — это цифровой двойник вашей монтажной схемы, и относиться к ней нужно с той же серьезностью, что и к физическим подключениям.

> 💡 Подсказка: Даже для небольших проектов использование Git — это признак профессионализма и гарантия от случайных ошибок, которые могут стоить часов работы на объекте.

Проблемы ручного учёта версий I/O Map

Представьте типичную ситуацию на объекте. Вы создали I/O Map в виде таблицы Excel. Через неделю заказчик попросил поменять назначение двух реле. Вы внесли изменения и сохранили файл как `io_map_v2.xlsx`. Затем, в процессе отладки, вы обнаружили, что перепутали аналоговые входы для датчиков CO2 и влажности. Вы исправляете это и сохраняете файл как `io_map_v2_fix.xlsx`. Через месяц к проекту подключается ваш коллега, и вы отправляете ему по почте файл `io_map_final_для_коллеги.xlsx`.

К чему приводит такой подход?

Путаница в файлах: Какой из файлов является самым актуальным? Что именно было изменено в версии "fix" по сравнению с "v2"? Ручной поиск отличий в большой таблице — источник новых ошибок.
Потеря данных: Случайное удаление файла, сбой жесткого диска или перезапись актуальной версии старой копией могут привести к полной потере часов, а то и дней работы. Восстанавливать I/O Map по памяти на сложном объекте — ночной кошмар инженера.
Сложности в командной работе: Два инженера не могут одновременно и безопасно вносить изменения в один и тот же файл. Это приводит к простоям или, что хуже, к конфликтующим версиям, когда работа одного затирает изменения другого.

Git как индустриальный стандарт

Система контроля версий (VCS) — это программное обеспечение, которое отслеживает все изменения в наборе файлов с течением времени. Она позволяет вам сохранять "снимки" проекта на разных этапах, просматривать историю изменений, возвращаться к любой предыдущей версии и эффективно работать в команде. Git — это самая популярная в мире распределенная система контроля версий. Сравнение ручного подхода с Git можно представить так:

| Ручной подход (`итоговая_карта_final.xlsx`) | Подход с Git |

| :------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------- |

| Десятки файлов с запутанными именами. | Один файл `io_map.csv` в одной папке. Вся история хранится внутри Git. |

| Чтобы понять, что изменилось, нужно открывать два файла и сравнивать их глазами. | Команда `git diff` мгновенно показывает все измененные строки между любыми двумя версиями. |

| Откат к старой версии — это поиск нужного файла и надежда, что он тот самый. | Откат к любой версии осуществляется одной командой (`git checkout`). |

| Командная работа — это пересылка файлов по почте и ручное слияние изменений. | Командная работа строится на ветках и слияниях, что позволяет вести параллельную разработку без потерь. |

Для инженера автоматизации I/O Map, конфигурационные файлы Node-RED (`flows.json`) и скрипты — это такой же код, как и для программиста. Применение Git к этим файлам переводит вашу работу с любительского на профессиональный уровень, обеспечивая надежность, отслеживаемость и масштабируемость ваших проектов.

---

Практика: Настройка Git на контроллере HI

Контроллер HI работает под управлением ОС Debian, что дает нам доступ ко всему многообразию инструментов Linux, включая Git. Настройка производится один раз для каждого проекта и занимает не более 5-10 минут.

> ⚠️ Внимание: Никогда не добавляйте в репозиторий файлы, содержащие пароли, API-ключи или другие секретные данные. Всегда используйте `.gitignore` для их исключения из версионирования.

1. Установка Git

Подключитесь к контроллеру по SSH. Первым делом обновим список пакетов и установим Git.

# Обновляем списки пакетов
sudo apt-get update

# Устанавливаем Git
sudo apt-get install git -y

После завершения установки, проверьте, что Git установлен корректно:

git --version

Вы должны увидеть ответ вроде `git version 2.30.2`.

2. Первоначальная настройка

Каждый "снимок" состояния (коммит) в Git имеет автора. Необходимо указать vaše имя и адрес электронной почты. Эта информация будет записываться в историю изменений.

# Укажите ваше настоящее имя
git config --global user.name "Ivan Petrov"

# Укажите ваш рабочий email
git config --global user.email "i.petrov@yourcompany.com"

Эти настройки сохраняются глобально для пользователя и их не нужно будет вводить для каждого нового проекта на этом контроллере.

3. Инициализация репозитория

Перейдите в директорию вашего проекта, где будет храниться I/O Map и другие конфигурационные файлы. Например, создадим папку `/opt/hi-projects/hotel-gamma`.

# Создаем директорию проекта и переходим в нее
mkdir -p /opt/hi-projects/hotel-gamma
cd /opt/hi-projects/hotel-gamma

Теперь "превратим" эту папку в репозиторий Git. Это делается одной командой:

git init

Вы увидите сообщение `Initialized empty Git repository in /opt/hi-projects/hotel-gamma/.git/`. Это означает, что Git создал в вашей папке скрытую подпапку `.git`. В ней будет храниться вся магия: история изменений, ветки и другие метаданные. Никогда не редактируйте и не удаляйте файлы внутри папки `.git` вручную!

4. Создание файла `.gitignore`

Чтобы случайно не добавить в историю изменений временные файлы, логи или файлы с паролями, создается специальный файл `.gitignore`. Git будет игнорировать все файлы и папки, перечисленные в нем.

Создадим этот файл с помощью текстового редактора `nano`:

nano .gitignore

Вставьте в него следующее содержимое, адаптированное для проектов на контроллере HI:

# Файлы логов
*.log
logs/

# Временные файлы операционной системы
.DS_Store
Thumbs.db

# Конфигурационные файлы Node-RED, которые могут содержать секреты
# Если вы не храните секреты в settings.js, можно его не игнорировать
# settings.js
# flows_cred.json

# Резервные копии редакторов
*~
*.swp
*.swo

# Системные и кэш-файлы
.idea/
.vscode/

Нажмите `Ctrl+X`, затем `Y` и `Enter`, чтобы сохранить файл. Теперь Git готов к работе с вашим проектом.

---

Первый коммит и семантическое версионирование (SemVer)

После инициализации репозитория и настройки `.gitignore` можно приступать к отслеживанию изменений. Основной рабочий процесс в Git состоит из двух шагов: подготовка изменений к сохранению и их фиксация с осмысленным комментарием.

> 🔗 Связанный материал: Изменения в I/O Map напрямую влияют на структуру топиков MQTT. Вспомните правила из урока COURSE-03-M04-L04 "Именование топиков MQTT", чтобы коммиты были консистентными и отражали изменения в иерархии топиков.

Жизненный цикл файла в Git

Каждый файл в вашем рабочем каталоге может находиться в одном из нескольких состояний:

Untracked (неотслеживаемый): Файл новый, Git о нем еще не знает.

Unmodified (неизмененный): Файл уже был сохранен в Git и с тех пор не менялся.

Modified (измененный): В файл были внесены изменения после последнего сохранения.

Staged (подготовленный/индексированный): Вы пометили измененный файл как готовый к сохранению в следующем "снимке".

Команда `git status` — ваш главный помощник. Она показывает текущее состояние всех файлов в проекте.

Первое сохранение: `git add` и `git commit`

Давайте создадим нашу первую версию I/O Map. В директории проекта создайте файл `io_map.csv` следующего содержания:

ID,Тип,Назначение,Клемма контроллера,MQTT топик
RL-01,Relay,Освещение, Гостиная, Зона 1,1,hi/room/living_room/light/zone1
UI-01,Discrete,Выключатель, Гостиная, Зона 1,1,hi/room/living_room/switch/zone1

Теперь посмотрим, что видит Git:

git status

Ответ будет примерно таким:

Untracked files:
  (use "git add ..." to include in what will be committed)
        .gitignore
        io_map.csv

Git видит два новых, неотслеживаемых файла. Давайте добавим их в "область подготовки" (staging area) с помощью команды `git add`.

# Добавляем оба файла для отслеживания
git add .gitignore io_map.csv

Если вы снова выполните `git status`, то увидите, что файлы теперь в разделе `Changes to be committed`.

Теперь зафиксируем эти изменения в истории с помощью команды `git commit`. Коммит всегда должен сопровождаться осмысленным сообщением, описывающим суть изменений.

git commit -m "feat: Initial commit with I/O map for living room"

Флаг `-m` позволяет указать сообщение прямо в командной строке. Поздравляем, вы сделали свой первый коммит! Вся история проекта теперь надежно сохранена.

Семантическое версионирование (SemVer) для I/O Map

Чтобы история изменений была не просто набором коммитов, а структурированной летописью проекта, применяется стандарт Семантического версионирования (SemVer). Версия задается в формате `MAJOR.MINOR.PATCH`.

PATCH (Патч): Увеличивается при внесении обратно совместимых исправлений ошибок. Для I/O Map это может быть исправление опечатки, добавление комментария. Например, `1.0.0` -> `1.0.1`.
MINOR (Минор): Увеличивается при добавлении нового функционала, который не ломает существующий. Для I/O Map это добавление нового датчика, нового реле, новой группы освещения. Например, `1.0.1` -> `1.1.0`.
MAJOR (Мажор): Увеличивается при внесении изменений, которые несовместимы с предыдущей версией. Для I/O Map это удаление устройства, перекоммутация существующего реле на другую нагрузку (что ломает старый MQTT топик), полная реорганизация системы. Например, `1.1.0` -> `2.0.0`.

| Тип изменения в I/O Map | Пример сообщения коммита | Изменение версии |

| :---------------------------------------------------------- | :------------------------------------------------- | :--------------- |

| Исправление опечатки в названии MQTT топика | `fix: Correct typo in living room light topic` | `PATCH` |

| Добавление датчика протечки в ванной | `feat: Add water leak sensor for bathroom (UI-02)` | `MINOR` |

| Назначение реле `RL-01` с освещения на управление розетками | `refactor!: Reroute RL-01 to control sockets` | `MAJOR` |

Использование префиксов (`fix:`, `feat:`, `refactor!:`) называется "Conventional Commits" и помогает автоматизировать генерацию журнала изменений.

---

Ведение журнала изменений (Changelog)

История коммитов в Git — это подробный технический лог для инженеров. Однако заказчику, менеджеру проекта или коллеге из смежного отдела нужен более высокоуровневый и понятный документ. Для этой цели служит файл `CHANGELOG.md`.

> ℹ️ Информация: Файл CHANGELOG.md — это не просто технический лог. Он должен быть понятен не только инженерам, но и менеджерам проекта, которые следят за прогрессом работ.

Стандарт "Keep a Changelog"

Changelog — это файл, который ведется вручную и содержит список всех заметных изменений для каждой версии проекта. Он пишется на языке Markdown (`.md`) для удобства форматирования.

Стандарт "Keep a Changelog" предлагает простую и понятную структуру для каждой версии:

Added: для нового функционала (например, добавили управление климатом).
Changed: для изменений в существующем функционале (например, изменили логику работы выключателя).
Deprecated: для функционала, который скоро будет удален.
Removed: для удаленного функционала (например, убрали датчик движения).
Fixed: для исправленных ошибок.
Security: для исправлений уязвимостей.

Практика документирования изменений в I/O Map

Давайте создадим файл `CHANGELOG.md` в корне нашего проекта:

nano CHANGELOG.md

И добавим в него запись о нашей первой версии, а также заготовку для будущих изменений:

# Журнал изменений

Вся информация о заметных изменениях в проекте будет документироваться в этом файле.
Формат основан на Keep a Changelog, 
и проект придерживается Семантического Версионирования.

[Unreleased]

Added
[1.0.0] - 2023-10-27

Added
Инициализация проекта автоматизации для объекта "Отель Гамма".
Добавлена карта входов-выходов (I/O Map) для управления освещением и выключателем в гостиной (1 зона).
Настроены MQTT топики для реле `RL-01` и дискретного входа `UI-01`.

Сохраните файл. Теперь добавим и закоммитим его:

git add CHANGELOG.md
git commit -m "docs: Add CHANGELOG.md with initial version 1.0.0"

Теперь, когда вы добавите в проект, например, датчик протечки (что является `MINOR` изменением), ваш процесс будет выглядеть так:

Изменяете файл `io_map.csv`.

Обновляете секцию `[Unreleased]` в `CHANGELOG.md`, добавляя пункт в `Added`.

Делаете коммит: `git commit -m "feat: Add water leak sensor"`.

Когда вы готовы выпустить версию `1.1.0`, вы переименовываете заголовок `[Unreleased]` в `[1.1.0] - <сегодняшняя дата>`.

Связь коммитов и Changelog:

Коммит отвечает на вопросы "ЧТО?" и "КАК?". Пример: `git log` покажет, что была добавлена строка в `io_map.csv`.
Changelog отвечает на вопрос "ЗАЧЕМ?". Пример: `CHANGELOG.md` объяснит, что "была добавлена система контроля протечек в санузле для повышения безопасности".

---

Ветвление (Branching): безопасное тестирование изменений

Одна из самых мощных возможностей Git — это ветвление (branching). Ветка — это, по сути, независимая линия разработки. Вы можете создать новую ветку, чтобы безопасно работать над новой задачей (например, добавить управление теплым полом), не затрагивая основную, стабильную конфигурацию, которая в данный момент работает на объекте.

> ⚠️ Внимание: Золотое правило: перед слиянием (merge) ветки с экспериментальными изменениями в `main`, всегда тщательно тестируйте новую конфигурацию на учебном стенде или в нерабочее время.

Концепция веток в Git

По умолчанию, при инициализации репозитория создается одна ветка, которая обычно называется `main` (или `master` в старых версиях Git). Эта ветка должна всегда содержать стабильную, протестированную и рабочую версию конфигурации вашего объекта. Любые эксперименты, добавление нового функционала или сложные исправления должны производиться в отдельных ветках.

Предположим, заказчик попросил вас интегрировать систему управления климатом (HVAC). Это большая и сложная задача, которая может занять несколько дней и потребует множества тестов. Вместо того чтобы вносить изменения прямо в `main`, рискуя нарушить работающее освещение, вы создаете для этой задачи отдельную ветку.

Создание и переключение между ветками

Давайте создадим новую ветку для нашей задачи по HVAC.

# Создаем новую ветку с именем 'feature/hvac-integration'
git branch feature/hvac-integration

Эта команда только создала ветку, но мы все еще находимся в `main`. Чтобы переключиться на новую ветку и начать в ней работать, используйте команду `git checkout`.

git checkout feature/hvac-integration

Или можно создать и сразу переключиться на новую ветку одной командой:

git checkout -b feature/hvac-integration

Теперь любые изменения, которые вы будете делать в файлах `io_map.csv` или `flows.json`, будут происходить только внутри этой ветки и не затронут ветку `main`. Вы можете спокойно добавлять новые Modbus-устройства, реле для управления фанкойлами, делать коммиты. В любой момент вы можете переключиться обратно в стабильную ветку: `git checkout main`.

Слияние веток (Merge)

После того, как вы полностью реализовали и протестировали управление климатом в ветке `feature/hvac-integration`, ее необходимо "влить" в основную ветку `main`, чтобы новая функциональность стала частью рабочей системы. Этот процесс называется слиянием (merge).

Сначала переключитесь на ветку, в которую вы хотите влить изменения (т.е. на `main`).

git checkout main

Затем выполните команду `git merge`, указав имя ветки, из которой вы хотите забрать изменения.

git merge feature/hvac-integration

Git автоматически применит все коммиты, сделанные в ветке `feature/hvac-integration`, к вашей основной ветке. После этого новая функциональность станет доступна в `main`, а ветку `feature/hvac-integration` можно удалить, так как она свою задачу выполнила.

---

Итоги и лучшие практики

Версионирование конфигурационных файлов — это не усложнение, а необходимая мера для профессионального подхода к автоматизации объектов. Это ваш страховой полис от случайных ошибок, инструмент для эффективной командной работы и надежная летопись эволюции вашего проекта.

📋 Ключевые понятия:

Система контроля версий (VCS): Инструмент для отслеживания истории изменений файлов.
Git: Самая популярная распределенная VCS.
Репозиторий: Папка проекта, находящаяся под контролем Git.
Коммит (Commit): "Снимок" состояния проекта в определенный момент времени.
Ветвление (Branching): Создание независимых линий разработки для безопасной работы над новыми задачами.
Слияние (Merge): Интеграция изменений из одной ветки в другую.
Семантическое версионирование (SemVer): Стандарт `MAJOR.MINOR.PATCH` для осмысленной нумерации версий.
Changelog: Человекочитаемый журнал изменений для команды и заказчиков.
.gitignore: Файл, указывающий Git, какие файлы и папки следует игнорировать.

Лучшие практики, которые стоит сделать привычкой:

Коммитьте часто, но осмысленно. Сделайте коммит после каждого логически завершенного действия. Не "поправил все", а "добавил датчик температуры в спальне". Один коммит — одно логическое изменение.

Пишите понятные сообщения к коммитам. Используйте стандарт "Conventional Commits" (`feat:`, `fix:`, `docs:`). Ваш коллега (и вы сами через месяц) будете благодарны за ясное описание того, что было сделано. "Обновил файл" — плохое сообщение. "feat: Add control for kitchen sockets (RL-05, RL-06)" — хорошее.

Используйте ветки для любых нетривиальных изменений. Добавляете поддержку нового устройства? Сложная отладка? Создайте ветку. Ветка `main` должна быть всегда в рабочем состоянии, как "золотой" эталон конфигурации на объекте.

Полный цикл работы. Полный цикл обновления проекта на удаленном сервере (который мы рассмотрим позже) выглядит как `git add` -> `git commit` -> `git push`. Для локальной работы достаточно первых двух шагов.

Относитесь к I/O Map как к коду. Карта входов-выходов — это фундамент всей логики вашей системы автоматизации. Ее целостность, версионность и читаемость так же важны, как и качество физического монтажа.

Что дальше

В следующем уроке мы рассмотрим, как связать наш локальный Git-репозиторий на контроллере с удаленным сервером (например, GitLab или GitHub), чтобы обеспечить централизованное хранение, резервное копирование и командную работу над проектами.