Algorithm for creating a Unit

TIP

1. Working out the Unit idea
2. Creating a Git repository
3. Creating the basic file structure
4. First commit
5. Creating a test Unit in Pepeunit
6. Filling the Unit with program logic
7. Creating pepeunit.toml and readme.md
8. Assigning a Tag

INFO

This guide is based on the ready-to-use Fan Regulator ds18b20.

Working out the Unit idea

Before you start developing a Unit, answer the following questions:

1. What main task will the Unit solve?
2. What physical components will the Unit have?
3. What data will the Unit publish?
4. What kind of control actions will the Unit accept?
5. In which language will the Unit be written?

For example

1. The Unit will regulate temperature using a fan.
2. You will need: esp32, a 4pin fan, and a ds18b20 temperature sensor.
3. It will publish the PWM duty cycle for the fan control signal and the measured temperature.
4. There will be a command to turn on the fan for N seconds at a given speed.
5. Micropython

Creating a Git repository

Choose a GitLab or GitHub instance:

1. Create an empty repository.
2. Clone it to your workstation.

Creating the basic file structure

TIP

Create the following empty files in the root of the Git repository:

• .gitignore
• .pepeignore
• schema_example.json
• env_example.json
• LICENSE

.gitignore

env.json
schema.json
tmp
.idea
.nvim

WARNING

Do not forget to specify the directory of your IDE; it can be .idea, .nvim, or any other.

.pepeignore

.git
.gitignore
.pepeignore
LICENSE
env_example.json
schema_example.json
pepeunit.toml
readme.md

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

To match the worked-out Unit concept, you need to add two more topic types to the standard input_base_topic and output_base_topic: input_topic and output_topic.

Topic type	Developer topic	Purpose
input_topic	set_fan_state/pepeunit	The Unit subscribes to it and receives control commands.
output_topic	current_fan_speed_percentage/pepeunit	Used to publish the PWM duty cycle.
output_topic	current_temp/pepeunit	Used to publish data from the ds18b20 temperature sensor.

INFO

More details about each topic type

env_example.json

{   
    "WIFI_SSID": "ssid",
    "WIFI_PASS": "password",
    "PWM_FAN_PIN": 0,
    "DS18B20_PIN_NUM": 4,
    "REGULATOR_OPERATING_RANGE": 1000,
    "PUBLISH_SEND_INTERVAL": 1,
    "TEMP_MIN": 30,
    "TEMP_MAX": 60,
    "DUTY_MIN": 8192,
    "DUTY_MAX": 65535,
    "PU_DOMAIN": "unit.example.com",
    "PU_HTTP_TYPE": "https",
    "PU_APP_PREFIX": "/pepeunit",
    "PU_API_ACTUAL_PREFIX": "/api/v1",
    "PU_MQTT_HOST": "emqx.example.com",
    "PU_MQTT_PORT": 1883,
    "PU_MQTT_PING_INTERVAL": 30,
    "PU_AUTH_TOKEN": "jwt_token",
    "PU_SECRET_KEY": "32_bit_secret_key",
    "PU_ENCRYPT_KEY": "32_bit_encrypt_key",
    "PU_STATE_SEND_INTERVAL": 300,
    "PU_MIN_LOG_LEVEL": "Debug",
    "PU_MAX_LOG_LENGTH": 64
}

DANGER

All variables in env_example.json must be anonymized.

You need to think through what each variable controlled by the Unit Developer will be responsible for:

Variable name	Purpose
WIFI_SSID	Name of the WiFi network to connect to.
WIFI_PASS	Password of the WiFi network.
PWM_FAN_PIN	Allows changing the pin number the fan is connected to.
DS18B20_PIN_NUM	Allows changing the pin number used to read data from the ds18b20 sensor.
REGULATOR_OPERATING_RANGE	Allows changing the regulator operating frequency/range.
PUBLISH_SEND_INTERVAL	Allows configuring the publish interval for the current_fan_speed_percentage/pepeunit and current_temp/pepeunit topics.
DUTY_MIN	Allows setting the minimum fan speed.
DUTY_MAX	Allows setting the maximum fan speed.
TEMP_MIN	Allows configuring the temperature from which the speed will be DUTY_MIN.
TEMP_MAX	Allows configuring the temperature from which the speed will be DUTY_MAX.

WARNING

Variables may change during development — this is absolutely normal. Add or remove variables in env_example.json and keep pepeunit.toml and readme.md up to date.

Pepeunit will show new variables to Users for input when they change the target version.

First commit

After you have filled in the minimum required files, it is time to commit them:

1. Open a terminal in your project directory.
2. Run git add . — add all files as candidates for a commit.
3. Run git commit -m "feat(init): initial files" — commit the changes.
4. Run git push — push the changes to your remote GitLab or GitHub hosting.

Creating a test Unit in Pepeunit

To continue developing the Unit, you need to interact with Pepeunit via MQTT and obtain env.json and schema.json. Choose a Pepeunit instance you trust and perform the following steps:

1. Create a RepositoryRegistry.
2. Create a Repo.
3. Create a Unit.
4. Configure the Unit for manual updates to strictly control the target version.
5. Fill in the Unit env.
6. Download the Archive containing env.json and schema.json.

The obtained env.json and schema.json files must be placed in the directory of your local Git repository. These files will contain the data required to connect to Pepeunit as well as the topics for publishing.

INFO

During development, you can open the test Unit and see:

• what data the Unit sends to the Output of the UnitNode through the DataPipe system
• how to create control actions for the Unit through the Input of the UnitNode

Filling the Unit with program logic

WARNING

There is no universal algorithm for software development. Develop in the way that is most convenient for you. However, we recommend trying to follow common code quality practices.

When your Unit in the local repository already has feedback from Pepeunit, try following this algorithm:

1. Test that the client libraries (Micropython, Golang, and Python) correctly send data and receive standard commands.
2. Retrieve data from your physical sensors, try printing values directly to the console without network complexity to ensure that the data really arrives.
3. Try sending your data to the output_topic specified in schema_example.json.
4. Receive commands from input_topic and handle them according to your Unit concept.
5. Integrate environment variables from env_example.json for remote configuration of your Unit.

After these steps, you will have a working Unit that needs to be tested in different operating modes.

WARNING

During development, you can make many commits with both working and non-working functionality, create branches, and use all the power of Git. However, at some point you will realize that everything works correctly and no further changes are required. At that moment, you can move on.

Creating pepeunit.toml and readme.md

INFO

Pepeunit relies on a machine-readable description of a Unit in the pepeunit.toml file.

To add a description for a Unit, you need to:

1. Create the pepeunit.toml file in the root of the Unit repository.
2. Generate readme.md based on pepeunit.toml.
3. Place the generated readme.md into the repository root. You do not need to write readme.md manually.

DANGER

Every Unit must have documentation so that Users can work with it.

Assigning a Tag

readme.md and pepeunit.toml are filled in, the functionality is ready, and everything works correctly. It is time to assign a Tag to the latest commit in the repository:

1. Open a terminal in your project directory.
2. Run git tag 1.0.0.
3. Run git push --tags to push tags to the remote repository.

Is there a restriction on the Tag format?

No, a Tag can have any structure.

INFO

For example, Pepeunit uses the major.minor.fix format everywhere.

DANGER

The Tag signals to Users that everything is ready for production use and has been tested by the Unit Developer.

Users will expect that by choosing the latest Tag they will get the most stable and up-to-date version of the Unit.