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

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

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

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

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

Например

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

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

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

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

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

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

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

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

gitignore

env.json
schema.json
tmp

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

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

.pepeignore позволяет убрать файлы из итогового архива генерируемого Pepeunit. Синтаксис аналогичен .gitignore.

Например:

pepeignore

.git
.gitignore
.pepeignore
env_example.json
schema_example.json
docs
model
README.md
LICENSE

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

INFO

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

В заполненом состоянии schema_example.json будет выглядеть вот так:

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"
    ]
}

Стандартные топики - `input_base_topic` и `output_base_topic`

При использовании клиентских библиотек: Micropython, Golang и Python - можно указывать все топики из input_base_topic и output_base_topic, они будут корректно работать.

Если вы создаёте облегчённую версию, без библиотек, то вы можете оставить только те топики, которые вам нужны и реализовать работу с ними самостоятельно.

INFO

Подробнее о возможностях input_base_topic - стандартные MQTT команды

Подробнее о возможностях output_base_topic - cтандартные топики состояния

Пользовательские топики - `input_topic` и `output_topic`

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

В input_topic добавим set_fan_state/pepeunit - Unit подпишется на него и будет получать управляющие команды
В 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 будет выглядеть вот так:

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,
    "MIN_LOG_LEVEL": "Debug",
    "MAX_LOG_LENGTH": 64
}

WARNING

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

Зарезервированные env переменные

При использовании клиентских библиотек: Micropython, Golang и Python - нужно указывать полный набор зарезервированных переменных: Подробно о заполнении env_example.json.

Переменные разработчика

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

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

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 функционалом

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

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

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

Разработчики 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 ​

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

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

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

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

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

Зарезервированные env переменные ​

Переменные разработчика ​

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

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

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

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

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

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

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

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

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

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

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

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

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

Стандартные топики - `input_base_topic` и `output_base_topic`

Пользовательские топики - `input_topic` и `output_topic`

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

Зарезервированные env переменные

Переменные разработчика

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

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

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

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

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

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