pepeunit.toml

INFO

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

toml

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

[images]
schema = "https://i.ibb.co/QQJ6h70/schema-fan-4pin-unit.png"

[files]
"Документация `4Pin` вентилятора" = "https://www.delta-fan.com/products/ffb1212eh.html"

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

[env_description]
WIFI_SSID = "Имя сети WiFi"
WIFI_PASS = "Пароль от сети WiFi"
PWM_FAN_PIN = "Номер `Pin` отвечающий за управляющее воздействие на Вентилятор"
DS18B20_PIN_NUM = "Номер `Pin` отвечающий за получение данных от датчика `ds18b20`"
REGULATOR_OPERATING_RANGE = "Частота работы регулятора в миллисекундах"
PUBLISH_SEND_INTERVAL = "Частота публикации данных в `current_fan_speed_percentage/pepeunit` и `current_temp/pepeunit` в секундах"
DUTY_MIN = "Минимальная скважность `PWM 16bit`, которую можно установить"
DUTY_MAX = "Максимальная скважность `PWM 16bit`, которую можно установить" 
TEMP_MIN = "Температура в градусах цельсия, ниже которой скважность будет `DUTY_MIN`"
TEMP_MAX = "Температура в градусах цельсия, выше которой скважность будет соответствовать `DUTY_MAX`"

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

[work_algorithm]
steps = [
  "Подключение к `WiFi`",
  "Инициализация клиета `pepeunit_micropython_client`",
  "Инициализация датчика `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
`images`	Предназначен для отображения визуальной информации, здесь могут быть схемы работы Unit, фото готового Unit или любая другая визуальная информация	Каждая пара ключ-значение будет выделена в отдельный элемент c уровнем `##`
`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