Readme и его основные элементы

WARNING

Readme - самый важный элемент вашего репозитория и будущих Unit, от того как вы его заполните будет зависеть лёгкость эксплуатации Unit другими людьми. Старайтесь заполнить каждый из пунктов содержищихся в данном разделе.

Пример стандартного заполнения readme для различных Unit:

Wifi 4pin PWM вентилятор

Description

Когда другие Пользователи Pepeunit переходят по ссылке на репозиторий, они первым делом захотят прочитать описание будущего Unit. Опишите в данном пункте функциональные возможности устройства, желательно просто привести возможности по пунктам, чтобы читать было проще.

Пример легко читаемого функционального описания

Регулирует обороты вентилятора в зависимости от температуры, чем больше температура тем больше обороты.
Публикует текущую температуру и скважность.
Позволяет включить вентилятор на N секунд по команде.

Пример тяжело читаемого описания:

Аппаратно-программный комплекс предназначен для управления вентиляционным узлом с учетом термодинамических параметров окружающей среды. Система реализует интеллектуальную адаптацию вращательных характеристик вентилятора: повышение температуры приводит к пропорциональному увеличению частоты вращения устройства, обеспечивая эффективное охлаждение. Одновременно предусмотрена возможность публикации телеметрических данных, включая текущие значения температурного показателя и коэффициента скважности, что осуществляется посредством стандартизированных протоколов передачи данных. Кроме того, комплекс поддерживает функционал кратковременной активации вентилятора, позволяя включать его на заданный интервал времени N секунд по внешним управляющим командам. Такое решение обеспечивает высокоадаптивное управление тепловыми процессами и возможность интеграции в сложные инфраструктурные системы.

Software platform

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

Примеры

Python v3.11
Micropython v1.24.1
GO v1.23.4
Vue v3.5.13
React v19.0
C++ v23
...

Firmware format

Чтобы Пользователи могли быстро понять Компилируемый ваш Unit или Интерпритируемый добавьте в данном пункте один из двух возможных вариантов:

Интерпритируемый
Компилируемый

Данный параметр при создании Repo в Pepeunit влияет на первую установку и способ доставки программных обновлений

Hardware platform

Здесь указывается тип физических устройств на которые Пользователи могут ориентироваться при создании физического Unit

Примеры

esp32 (требуется >= 1МБ flash памяти)
PC - Linux, Mac, Win
Rpi 3B+

Required physical components

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

Пример

Микроконтроллер esp32
PWM 4pin вентилятор, например FFB1212EH
Датчик температуры DS18B20
1х резистор 4.7кОм
Провода

Operating Scheme

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

WARNING

Ввиду того что картинки достаточно большие по размеру, а объём пространства репозитория будет нарастать с каждым новым изменением. Гораздо проще воспользоваться внешними хостингами картинок, которые позволяют получить статическую ссылку на изображение.

Пример вставки картинки в md

![img](https://i.ibb.co/QQJ6h70/schema-fan-4pin-unit.png)

Эта же картинка но уже с рендером

3D Models

Укажите здесь ссылки на 3D модели элементов Unit в различных форматах, чтобы Пользователи могли распечатать их на 3D принтерах. Отдавайте приоритет формату stl, т.к. он может быть использован в любой программе трассировки 3D печати.

Пример

stl - Корпус
m3d - Корпус

Physical IO

Данный пункт актуален только для Unit на основе микроконтроллеров, так как здесь нужно описать какие физические IO пины используются.

Пример

machine.Pin(0) настроен на отдачу PWM сигнала c частотой 10000Гц и разрешением 16бит
machine.Pin(4) настроен на получение цифрового значения температуры от датчика DS18B20

env_example.json

Отобразите env_example.json. Это нужно для опытных Пользователей - по переменным окружения можно оценить возможности настройки Unit. Подробное описание структуры 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
}

Env variable assignment

Опишите какие переменные, отличные от стандартных, вы добавили в env_example.json. Чем подробнее тем лучше.

Пример

WIFI_SSID - имя сети WiFi в которой будет работать устройство
WIFI_PASS - пароль от сети WiFI в которой будет работать устройство
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

schema_example.json

Отобразите schema_example.json . Это нужно для опытных Пользователей - по данной схеме можно очень быстро оценить, что может Unit. Подробное описание структуры 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"
    ]
}

Assignment of Device Topics

Опишите какие форматы данных отдают ваши Output и какие форматы принимают Input. Постарайтесь добавить примеры.

Пример

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

Work algorithm

Расскижите о логике работы вашего Unit, возможно другие Пользователи захотят внести вклад и им будет гораздо проще, если они будут знать подробности о том как работают различные режимы вашего Unit.

Пример

Алгоритм работы с момента нажатия кнопки включения:

Подключение к WiFI
Инициализация датчика DS18B20
Подключение к MQTT Брокеру
Каждые PUBLISH_SEND_INTERVAL секунд публикуются сообщения в current_fan_speed_percentage/pepeunit и current_temp/pepeunit

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

python

    def convert_temp_to_duty(x) -> int:
    temp_min = settings.TEMP_MIN
    temp_max = settings.TEMP_MAX
    duty_min = settings.DUTY_MIN
    duty_max = settings.DUTY_MAX
    
    if x < temp_min:
        return 8192
    
    if x > temp_max:
        return 65532
    
    y = ((x - temp_min) * (duty_max - duty_min)) / (temp_max - temp_min) + duty_min
    return int(round(y))

Алгоритм работы в момент получения сообщения из set_fan_state/pepeunit

Устройство получает сообщение формата {"sleep": 15, "duty": 65535}
Устанавливается скважность равная duty
Устойство засыпает на sleep секунд

Readme и его основные элементы ​

Description ​

Software platform ​

Firmware format ​

Hardware platform ​

Required physical components ​

Operating Scheme ​

3D Models ​

Physical IO ​

env_example.json ​

Env variable assignment ​

schema_example.json ​

Assignment of Device Topics ​

Work algorithm ​

Readme и его основные элементы

Description

Software platform

Firmware format

Hardware platform

Required physical components

Operating Scheme

3D Models

Physical IO

env_example.json

Env variable assignment

schema_example.json

Assignment of Device Topics

Work algorithm