Алгоритм создания Unit

TIP

1. Проработка идеи Unit
2. Создание репозитория Git
3. Создание базовой файловой структуры
4. Первый коммит
5. Создание тестового Unit в Pepeunit
6. Наполнение Unit программным функционалом
7. Создание pepeunit.toml и readme.md
8. Присвоение Тега

INFO

Данное руководство составлено на основе готового к работе Fan Regulator ds18b20

Проработка идеи Unit

Перед началом разработки Unit ответьте себе на следующие вопросы:

1. Какую основную задачу будет решать Unit ?
2. Какие физические элементы будут у Unit ?
3. Какие данные Unit будет публиковать ?
4. Какое управляющее воздействие будет допускать Unit ?
5. На каком языке будет написан Unit ?

Например

1. Unit будет регулировать температуру при помощи вентилятора
2. Понадобятся: esp32, 4pin вентилятор, температурный датчик ds18b20
3. Будет публиковаться: скважность PWM сигнала управления вентилятором и температура на датчике
4. Будет команда: включение на N секунд с заданной скоростью вращения
5. Micropython

Создание репозитория Git

Выберите инстанс GitLab или GitHub:

1. Создайте пустой репозиторий
2. Склонируйте его на свою ЭВМ

Создание базовой файловой структуры

TIP

Создайте в корне Git репозитория следующие пустые файлы:

• .gitignore
• .pepeignore
• schema_example.json
• env_example.json
• LICENSE

.gitignore

env.json
schema.json
tmp
.idea
.nvim

WARNING

Не забудьте указать папку с вашей IDE, это может быть: .idea, .nvim или любая другая

.pepeignore

.git
.gitignore
.pepeignore
LICENSE
env_example.json
schema_example.json
pepeunit.toml
readme.md

schema_example.json

{   
    "input_base_topic": [
        "update/pepeunit",
        "env_update/pepeunit",
        "schema_update/pepeunit",
        "log_sync/pepeunit"
    ],
    "output_base_topic": [
        "state/pepeunit",
        "log/pepeunit"
    ],
    "input_topic": [
        "set_fan_state/pepeunit"
    ],
    "output_topic": [
        "current_fan_speed_percentage/pepeunit",
        "current_temp/pepeunit"
    ]
}

Для соответствия проработанной идее Unit, к стандартным топикам input_base_topic и output_base_topic потребуются добавить ещё два типа топиков: input_topic и output_topic

Тип топика	Топик разработчика	Назначение
input_topic	set_fan_state/pepeunit	Unit подпишется на него и будет получать управляющие команды
output_topic	current_fan_speed_percentage/pepeunit	Будет использоваться для публикации скважности PWM
output_topic	current_temp/pepeunit	Будет использоваться для публикации данных с датчика температуры ds18b20

INFO

Подробнее о назначении каждого типа топиков

env_example.json

{   
    "WIFI_SSID": "ssid",
    "WIFI_PASS": "password",
    "PWM_FAN_PIN": 0,
    "DS18B20_PIN_NUM": 4,
    "REGULATOR_OPERATING_RANGE": 1000,
    "PUBLISH_SEND_INTERVAL": 1,
    "TEMP_MIN": 30,
    "TEMP_MAX": 60,
    "DUTY_MIN": 8192,
    "DUTY_MAX": 65535,
    "PU_DOMAIN": "unit.example.com",
    "PU_HTTP_TYPE": "https",
    "PU_APP_PREFIX": "/pepeunit",
    "PU_API_ACTUAL_PREFIX": "/api/v1",
    "PU_MQTT_HOST": "emqx.example.com",
    "PU_MQTT_PORT": 1883,
    "PU_MQTT_PING_INTERVAL": 30,
    "PU_AUTH_TOKEN": "jwt_token",
    "PU_SECRET_KEY": "32_bit_secret_key",
    "PU_ENCRYPT_KEY": "32_bit_encrypt_key",
    "PU_STATE_SEND_INTERVAL": 300,
    "PU_MIN_LOG_LEVEL": "Debug",
    "PU_MAX_LOG_LENGTH": 64
}

DANGER

Все переменные в env_example.json должны быть обезличены

Нужно продумать, за что будут отвечать переменные Разработчика Unit:

Название переменной	Назначение
WIFI_SSID	Название WiFi сети для подключения
WIFI_PASS	Пароль от WiFi сети для подключения
PWM_FAN_PIN	Позволит менять номер контакта подключения вентилятора
DS18B20_PIN_NUM	Позволит менять номер контакта, отвечающего за получение данных от датчика ds18b20
REGULATOR_OPERATING_RANGE	Позволит изменять частоту работы регулятора
PUBLISH_SEND_INTERVAL	Позволит настраивать скорость публикации в топик current_fan_speed_percentage/pepeunit и current_temp/pepeunit
DUTY_MIN	Позволит устанавливать минимальную скорость вентилятора
DUTY_MAX	Позволит устанавливать максимальную скорость вентилятора
TEMP_MIN	Позволит настраивать температуру, начиная с которой скорость будет DUTY_MIN
TEMP_MAX	Позволит настраивать температуру, начиная с которой скорость будет DUTY_MAX

WARNING

Переменные могут поменяться в процессе разработки - это абсолютно нормально. Добавьте или удалите переменные в env_example.json и актуализируйте pepeunit.toml и readme.md.

Pepeunit отобразит новые переменные Пользователям для ввода, когда они изменят таргет версию.

Первый коммит

После заполнения минимально нужных файлов, пора их закоммитить:

1. Переходим в консоль директории вашего проекта
2. git add . - добавляем все файлы в кандидаты на коммит
3. git commit -m "feat(init): initial files" - коммитим изменения
4. git push - отправляем изменения в ваш удалённый хостинг GitLab или GitHub

Создание тестового Unit в Pepeunit

Чтобы продолжить разработку Unit, нужно взаимодействовать с Pepeunit через MQTT, а также получить env.json и schema.json. Выбирите подходящий инстанс Pepeunit, которому вы доверяете. Выполните следующие шаги:

1. Создайте RepositoryRegistry
2. Создайте Repo
3. Создайте Unit
4. Настройте Unit для обновлений в ручную, чтобы чётко контролировать таргет версию
5. Заполните env у Unit
6. Скачайте Архив с env.json и schema.json

Полученные файлы env.json и schema.json нужно будет поместить в каталог вашего локального Git репозитория. Данные файлы будут содержать данные для подключения к Pepeunit, а также топики для публикации.

INFO

В процессе разработки можно заходить в тестовый Unit и видеть:

• какие данные Unit отправляет в Output UnitNode через систему DataPipe
• создавать для Unit управляющее воздействие через Input UnitNode

Наполнение Unit программным функционалом

WARNING

Не существует универсального алгоритма разработки Программного обеспечения. Разрабатывайте так, как удобно именно вам. Однако рекомендуем стараться следовать стандартным правилам частоты кода.

Когда у Unit в локальном репозитории есть обратная связь с Pepeunit, попробуйте следовать следующему алгоритму:

1. Протестировать, что клиентские библиотеки (Micropython, Golang и Python) корректно отправляют данные и получают стандартные команды
2. Получите данные от ваших физических датчиков, попробуйте вывести значения напрямую в консоль, без сетевых усложнений, чтобы понять что данные действительно поступают
3. Попробуйте отправить свои данные в output_topic, указанные в schema_example.json
4. Получите команды из input_topic и обработайте их так, как задумано в концепции вашего Unit
5. Внедрите переменные окружения из env_example.json для удалённой настройки вашего Unit

После этих шагов вы получите рабочий Unit, которой нужно протестировать в различных режимах работы.

WARNING

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

Создание pepeunit.toml и readme.md

INFO

Pepeunit расчитывает на машиночитаемое описание Unit в файле pepeunit.toml.

Чтобы добавить описание для Unit, нужно:

1. Создать в корне репозитория Unit файл pepeunit.toml
2. Сгенерировать readme.md на основе pepeunit.toml
3. Поместить сгенерированный readme.md в корень репозитория. Писать readme.md в ручную не требуется

DANGER

У всех Unit должна быть документация, чтобы Пользователи могли ими пользоваться.

Присвоение Тега

readme.md и pepeunit.toml заполнены, функционал готов, всё работает корректно. Время присвоить Тег для последнего коммита в репозитории:

1. Перейдите в консоль в директории вашего проекта
2. Выполните команду git tag 1.0.0
3. Выполните команду отправки во внешний репозиторий git push --tags

Есть ли ограничение на формат Тега ?

Нет, Тег может иметь любую структуру.

INFO

Pepeunit например использует везде: major.minor.fix:

DANGER

Тег будет сигнализировать Пользователям, что всё готово к эксплуатации и протестировано Разработчиком Unit.

Пользователи будут ожидать, что выбрав последний Тег, получат самую рабочую, самую актуальную версию Unit.