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

Пройдя последовательно данный алгоритм, вы создадите свой первый Unit

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

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

Какую основную задачу будет решать мой Unit ?
Какие физические элементы будут у моего Unit ?
Какие данные Unit будет публиковать ?
Какое управляющее воздействие будет допускать Unit ?
Компилируемый или Интерпритируемый будет мой Unit ?

Например

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

Создание удалённого репозитория

Перейдите в удобный вам инстанс Gitlab или Github:

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

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

Откройте склонированный репозиторий любым удобным для вас редактором кода
Создайте следующий минимальный набор пустых файлов:
- env_example.json
- .gitignore
- LICENSE - на ваш вкус
- readme.md
- schema_example.json

Заполнение .gitignore

Впишите следующий набор дирректорий и файлов:

gitignore

env.json
schema.json
tmp

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

Заполнение schema_example.json

INFO

Подробно о заполнении schema_example.json

Копируем в файл schema_example.json стандартные топики:

json

{
    "input_base_topic": [
        "update/pepeunit",
        "schema_update/pepeunit",
        "env_update/pepeunit"
    ],
    "output_base_topic": [
        "state/pepeunit"
    ]
}

Стандартные топики

В данном пункте нужно определиться какие стандартные функции Pepeunit вы хотите реализовать:

Хочется рабочую систему обновлений
Хочется обновлять схему и окружение при помощи стандартных MQTT команд
Хочется отправлять состояние, чтобы его потом читать в меню Pepeunit

Исходя из хотелок - оставляем все топики, которые мы уже добавили на схему, вы можете удалить те, которые вам не хочется реализовывать

Пользовательские топики

Пользовательские топики - это шаблоны будущих UnitNode, вам нужно заполнить их самостоятельно и придумать имена, исходя из требований проекта.

В input_topic добавим set_fan_state/pepeunit, Unit подпишется на него и будет получать управляющие команды
В output_topic добавим два: current_fan_speed_percentage/pepeunit, current_temp/pepeunit - в эти топики будем публиковать текущее состояние

Добавляем нужные топики в schema_example.json:

json

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

WARNING

В процессе разработки может потребоваться изменение schema_example.json - это абсолютно нормально. Добавьте или удалите топики и актуализируйте Readme. Pepeunit подстроится и добавит/удалит UnitNode.

Заполнение env_example.json

INFO

Подробно о заполнении env_example.json

Скопируйте в файл env_example.json стандартные переменные Pepeunit, так как это пример для заполнения Пользователями - все значения должны быть обезличены:

json

{
    "PEPEUNIT_URL": "unit.example.com",
    "PEPEUNIT_APP_PREFIX": "/pepeunit",
    "PEPEUNIT_API_ACTUAL_PREFIX": "/api/v1",
    "HTTP_TYPE": "https",
    "MQTT_URL": "emqx.example.com",
    "MQTT_PORT": 1883,
    "PEPEUNIT_TOKEN": "jwt_token",
    "SYNC_ENCRYPT_KEY": "32_bit_encrypt_key",
    "SECRET_KEY": "32_bit_secret_key",
    "PING_INTERVAL": 30,
    "STATE_SEND_INTERVAL": 300
}

Распишите мотивацию для добавления дополнительных переменных:

WIFI_SSID - для подключения к WiFi точно понадобится название сети
WIFI_PASS - для подключения к WiFi точно будет нужен пароль
PUBLISH_SEND_INTERVAL - хочу настраивать частоту отравки сообщений в Pepeunit
DUTY_MIN - хочу иметь возможность ограничить минимальную скорость вентилятора
DUTY_MAX - хочу иметь возможность ограничить максимальную скорость вентилятора
TEMP_MIN - хочу настраивать температуру ниже которой скорость будет DUTY_MIN
TEMP_MAX - хочу настраивать температуру выше которой скорость будет TEMP_MAX

Теперь добавьте данные переменные в обезличенном виде в env_example.json, получится следующее:

json

{
    "WIFI_SSID": "My_Perfect_Wifi_SSID",
    "WIFI_PASS": "Strong_Password",
    "PUBLISH_SEND_INTERVAL": 10,
    "DUTY_MIN": 8192,
    "DUTY_MAX": 65535,
    "TEMP_MIN": 30,
    "TEMP_MAX": 60,
    "PEPEUNIT_URL": "unit.example.com",
    "PEPEUNIT_APP_PREFIX": "/pepeunit",
    "PEPEUNIT_API_ACTUAL_PREFIX": "/api/v1",
    "HTTP_TYPE": "https",
    "MQTT_URL": "emqx.example.com",
    "MQTT_PORT": 1883,
    "PEPEUNIT_TOKEN": "jwt_token",
    "SYNC_ENCRYPT_KEY": "32_bit_encrypt_key",
    "SECRET_KEY": "32_bit_secret_key",
    "PING_INTERVAL": 30,
    "STATE_SEND_INTERVAL": 300
}

WARNING

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

Первичное заполнение Readme

Используя документацию по общей структуре Readme заполните пункты:

Description
Firmware format
Hardware platform
Required physical components
env_example.json
schema_example.json

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

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

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

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

Для продолжения разработки вам нужно будет отправлять и получать управляющее воздействие на Unit. Очень удобно для этого использовать инстанс Pepeunit, которому вы доверяете. Нужно выполнить два шага на этом инстасе:

Создайте Repo на основе вашего Git репозитория из Gitlab и Github
Создайте Unit:
- Обязательно сделайте его обновляемым в ручную, чтобы чётко контролировать таргет версию
- Заполните переменные окружения
- Скачайте архив с env.json и schema.json

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

INFO

В процессе разработки вы сможете заходить в тестовый Unit и видеть какие данные он отправляет в Output UnitNode, создавать для него управляющее воздействие через Input UnitNode, а также же отлаживать систему обновлений.

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

Для создания функционала - итеративно прорабатывайте аспекты работы вашего кода, начните c тестирования библиотек получения данных с датчиков и постепенно идите в сторону реализации отправки данных, получения управляющего воздействия и интеграции с Pepeunit.

Здесь всё индивидуально, разработчики Pepeunit могут лишь облегчить вам работу предоставив примеры для разных языков программирования:

INFO

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

Актуализация документации

Актуализируйте и дозаполните все пункты документации, согласно руководству. Пользователи скажут вам Большое Спасибо.

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

Readme заполнен, функционал готов, всё работает корректно. Самое время присвоить Тег для вашего последнего коммита:

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

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

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

INFO

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

< 1.0.0 являются beta версиями
>= 1.0.0 стабильны

DANGER

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

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

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

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

Создание удалённого репозитория ​

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

Заполнение .gitignore ​

Заполнение schema_example.json ​

Стандартные топики ​

Пользовательские топики ​

Заполнение env_example.json ​

Первичное заполнение Readme ​

Первый коммит и git push ​

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

Наполнение Unit функционалом ​

Актуализация документации ​

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

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

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

Создание удалённого репозитория

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

Заполнение .gitignore

Заполнение schema_example.json

Стандартные топики

Пользовательские топики

Заполнение env_example.json

Первичное заполнение Readme

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

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

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

Актуализация документации

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