pepeunit.toml

INFO

pepeunit.toml будет использован в будущем для упрощения поиска по RepositoryRegisty между инстансами Pepeunit.

toml

[general]
name = "Fan Regulator ds18b20"
description = "Регулирует обороты вентилятора в зависимости от температуры. Публикует текущую температуру и `16bit` скважность. Позволяет включить вентилятор на `N` секунд по команде с любой скважностью"
language = "Micropython"
hardware = ["esp32", "esp32c3", "esp32s3", "ds18b20", "4pin fan", "резистор 4.7кОм", "wires"]
firmware = [
  {name = "RELEASE-1.1.1", link = "https://git.pepemoss.com/pepe/pepeunit/libs/pepeunit_micropython_client/-/releases/1.1.1"}
]
stack = ["pepeunit_micropython_client"]
version = "1.1.1"
license = "AGPL v3 License"
authors = [
    {name = "Ivan Serebrennikov", email = "admin@silberworks.com"}
]

[video]
video = {preview = "https://minio.pepemoss.com/public-data/video/base64_streaming_prev.jpg", link = "https://www.youtube.com/watch?v=r1CpkXD_MJY"}

[images]
schema = "https://minio.pepemoss.com/public-data/image/schema_fan_4pin_unit.png"

[models]
models = [
  {version = "v0", description = "Пример модели", link = "https://minio.pepemoss.com/public-data/model/control_panel_sh1106/v3/stl/capsule_insert.stl"},
  {version = "v0", description = "Пример модели", link = "https://minio.pepemoss.com/public-data/model/control_panel_sh1106/v3/stl/capsule_panel.stl"}
]

[files]
"Документация `4Pin PWM` вентилятора Delta" = "https://www.delta-fan.com/products/ffb1212eh.html"
"Документация `4Pin PWM` вентилятора Noctua" = "https://www.noctua.at/en/products/nf-f12-industrialppc-3000-pwm/specifications"

[physical_io]
"client.settings.PIN_FAN" = "Управление скважностью для работы Вентилятора"
"client.settings.PIN_DS18B20" = "Цифровое значение температуры от датчика `ds18b20`"

[env_description]
PIN_FAN = "Номер `Pin` отвечающий за управляющее воздействие на Вентилятор"
PIN_FAN_PWM_FREQUENCY = "Частота `PWM` сигнала в герцах"
PIN_DS18B20 = "Номер `Pin` отвечающий за получение данных от датчика `ds18b20`"
REGULATOR_OPERATING_RANGE = "Частота работы регулятора в миллисекундах"
REGULATOR_DUTY_MIN = "Минимальная скважность `PWM 16bit`, которую может установить регулятор"
REGULATOR_DUTY_MAX = "Максимальная скважность `PWM 16bit`, которую может установить регулятор" 
REGULATOR_TEMP_MIN = "Температура в градусах цельсия, ниже которой скважность будет `REGULATOR_DUTY_MIN`"
REGULATOR_TEMP_MAX = "Температура в градусах цельсия, выше которой скважность будет соответствовать `REGULATOR_DUTY_MAX`"
PUBLISH_SEND_INTERVAL = "Частота публикации данных в `current_fan_speed_percentage/pepeunit` и `current_temp/pepeunit` в миллисекундах"
PUC_WIFI_SSID = "Имя сети `WiFi`"
PUC_WIFI_PASS = "Пароль от сети `WiFi`"


[topic_assignment]
"set_fan_state/pepeunit" = "Принимает в качестве значения `json` - `{\"sleep\": 15, \"duty\": 65535}`, где `sleep` сообщаяет в течении скольки секунд вентилятор будут включен с `16 bit` скважностью `duty`"
"current_fan_speed_percentage/pepeunit" = "Текущее значение скважности в текстовом формате - `8192`"
"current_temp/pepeunit" = "Текущая температура в текстовом формате - `27.5`"

[work_algorithm]
steps = [
  "Подключение к `WiFi`",
  "Подключение к `MQTT` Брокеру",
  "Инициализация датчика `ds18b20` и `PWM`",
  "Запуск основного цикла",
  "Каждые `PUBLISH_SEND_INTERVAL` миллисекунд публикуются сообщения в `current_fan_speed_percentage/pepeunit` и `current_temp/pepeunit`",
  "Каждые `REGULATOR_OPERATING_RANGE` миллисекунд регулятор линейно преобразует температуру в скважность, по алгоритму из функции `main.py` `def convert_temp_to_duty`. Вычисленное значение устанавливается для Вентилятора как целевое",
  "При получении команды из `set_fan_state/pepeunit`, скважность `duty` устанавливается как целевая для Вентилятора и устройство засыпает на `sleep` секунд, далее начинается цикл обычного регулирования"
]

[installation]
steps = [
  "Установите образ `Micropython` указанный в `firmware` на `esp32`, как это сделано в [руководстве](https://micropython.org/download/ESP32_GENERIC/)",
  "Создайте `Unit` в `Pepeunit`",
  "Установите переменные окружения в `Pepeunit`",
  "Скачайте архив c программой из `Pepeunit`",
  "Распакуйте архив в директорию",
  "Загрузите файлы из директории на физическое устройство, например командой: `ampy -p /dev/ttyUSB0 -b 115200 put ./ .`",
  "Запустить устройство нажатием кнопки `reset`"
]

WARNING

Файлы .toml имеют ряд синтаксических правил заполнения:

Единый формат элементов списка []:
Допустимо Не допустимо
["esp32", "ds18b20", "4pin fan", "резистор 4.7кОм", "wires"] ["test", {name = "Ivan Serebrennikov"}]
Ключи, в которых есть особые символы, требуют обёртки "":
Требует Не требует
"current_temp/pepeunit" = "Текущая температура в текстовом формате - 27.5" WIFI_SSID = "Имя сети WiFi"

Допустимо	Не допустимо
`["esp32", "ds18b20", "4pin fan", "резистор 4.7кОм", "wires"]`	`["test", {name = "Ivan Serebrennikov"}]`

Требует	Не требует
`"current_temp/pepeunit" = "Текущая температура в текстовом формате - 27.5"`	`WIFI_SSID = "Имя сети WiFi"`

Структура pepeunit.toml

Раздел	Предназначение	readme.md формат
`general`	Содержит базовую информацию о Unit	Формируется таблица в шапке readme.md
`video`	Позволяет отобразить картинку `preview` с ссылкой на видео `link`, сгенерированный результат корректно отображается в GitLab и GitHub	Формирует кликабельное изображение и подписывает тег `## Video`
`images`	Предназначен для отображения визуальной информации, здесь могут быть схемы работы Unit, фото готового Unit или любая другая визуальная информация	Каждая пара ключ-значение будет выделена в отдельный элемент c уровнем `##`
`models`	Отображает таблицу моделей, позволяет указывать версию и описание	Формирует таблицу
`files`	Позволяет указывать файлы, например, `3D` модели или дополнительные материалы	Каждая пара ключ-значение будет отдельным элементом нумерованного списка
`physical_io`	Нужен для микроконтрллеров, даёт чёткое понимание, какой `IO Pin` для чего предназначен	Формирует таблицу
`env_description`	Описывает каждую env переменную, добавленную Разработчиком Unit	Формирует таблицу
`topic_assignment`	Описывает каждый UnitNode топик, добавленный Разработчиком Unit	Формирует таблицу
`work_algorithm`	Описывает последовательность работы Unit	Каждая пара ключ-значение будет отдельным элементом нумерованного списка
`installation`	Описывает последовательность шагов для корректного запуска Unit	Каждая пара ключ-значение будет отдельным элементом нумерованного списка

WARNING

Нюансы генерации pepeunit.toml -> readme.md:

Если раздел или элемент раздела не указан, то он не будет добавлен в readme.md
Т.к. текст парсится напрямую, можно указывать в тексте md символы форматирования, например: **, ``, __ и т.д.
Сложные элементы форматирования, наподобие блоков кода, нумерованных списков и таблиц, недоступны, т.к. ломают генерацию из-за ошибок парсинга
Если вам требуются расширенные возможности md, то сгенерируйте первичную версию на основе pepeunit.toml с добавлением в конец дополнительного блока ## Additional information. Таким образом, конечный Пользователь получит все преимущества ожидаемой схемы readme.md и ваше особое дополнение.

Заполнение pepeunit.toml general

Ключ	Пример значения	Комментарий
`name`	`"Fan Regulator ds18b20"`	Короткое название Unit, должно содержать только самую важную информацию
`description`	`"Регулирует обороты вентилятора в зависимости от температуры. Публикует текущую температуру и скважность. Позволяет включить вентилятор на` N `секунд по команде"`	`1-5` предложений, отражающих основной функционал Unit
`language`	`"Micropython"`	Язык программирования, на котором написан Unit
`hardware`	`["esp32", "ds18b20", "4pin fan", "резистор 4.7кОм", "wires"]`	Используемые физические компоненты
`firmware`	`[{name = "ESP32...0.0.bin", link = "https://git.pepe.../download"}]`	Набор данных о бинарных файлах, устанавливаемых напрямую на физические компоненты: интерпретаторы, бинарные файлы и т.д.ы
`stack`	`["pepeunit_micropython_client"]`	Набор библиотек, используемых в программе Unit
`version`	`"1.0.0"`	Текущая версия Unit
`license`	`"AGPL v3 License"`	Подробнее о лицензиях LICENSE
`authors`	`[{name = "Ivan Serebrennikov", email = "admin@silberworks.com"}]`	Список авторов Unit

WARNING

Особенности:

hardware, firmware и stack могут быть заполнены как текстовыми ключами, в примере для hardware, так и ссылками, как в примере для firmware. Но формат всех элементов списка должен быть единым: или все элементы текстовые, или все элменты ссылки

Заполнение блоков после general

INFO

Заполнение всех остальных блоков, происходит на основе примера

pepeunit.toml ​

Структура pepeunit.toml ​

Заполнение pepeunit.toml general ​

Заполнение блоков после general ​

pepeunit.toml

Структура pepeunit.toml

Заполнение pepeunit.toml general

Заполнение блоков после general