Standard Pepeunit MQTT commands

WARNING

Commands supported by a Unit must be listed in schema_example.json under input_base_topic.

The Unit must subscribe to these topics. When it receives a message, the Unit must follow the unified behavior pattern described in this section.

There are four command topics in Pepeunit:

1. UPDATE – update/pepeunit
2. SCHEMA_UPDATE – schema_update/pepeunit
3. ENV_UPDATE – env_update/pepeunit
4. LOG_SYNC – log_sync/pepeunit

UPDATE - update/pepeunit

When is this command sent?

1. When a Unit is updated manually.
2. When a Unit is updated automatically.
3. When the command is triggered via the dedicated button in the Unit UI.
4. When the command is triggered via REST or GQL.

This command tells the Unit to perform an update. The Unit must then execute a specific sequence of actions that results in switching the program code to a new version.

Message format for the update/pepeunit topic

DANGER

The message format differs for Compilable and Interpretable Repos:

Compilable:

{
    "COMMAND": "Update",
    "PU_COMMIT_VERSION": "ad1ddee1e559153f6ea4ae33790f5980e32d61cf",
    "COMPILED_FIRMWARE_LINK": "https://git.pepemoss.com/api/v4/projects/281/packages/generic/release/0.0.2/picker-linux-amd64"
}

Interpretable:

{
    "COMMAND": "Update",
    "PU_COMMIT_VERSION": "ad1ddee1e559153f6ea4ae33790f5980e32d61cf"
}

Unit behavior algorithm

DANGER

The Unit algorithm differs for Compilable and Interpretable Repos.

Compilable:

1. Compare the PU_COMMIT_VERSION from the message with the current PU_COMMIT_VERSION from env.json.
   • If they match, abort the update.
   • If they differ, start the update process.
2. Compute the Unit uuid from the PU_AUTH_TOKEN JWT in env.json.
3. Download a tgz, tar, or zip archive with env.json and schema.json via REST. The PU_HTTP_TYPE and PU_DOMAIN variables are available in env.json:
   • PU_HTTP_TYPE://PU_DOMAIN/pepeunit/api/v1/units/firmware/tgz/{Unit.uuid}?wbits=9&level=9
     • allowed wbits: (from -15 to -8) (from 9 to 16) (from 25 to 32)
     • allowed level: (from -1 to 10)
   • PU_HTTP_TYPE://PU_DOMAIN/pepeunit/api/v1/units/firmware/tar/{Unit.uuid}
   • PU_HTTP_TYPE://PU_DOMAIN/pepeunit/api/v1/units/firmware/zip/{Unit.uuid}
4. Extract env.json and schema.json from the archive.
5. Download the new compiled binary from COMPILED_FIRMWARE_LINK. See precompiled releases for details.
6. Run the new compiled binary and stop the old one.

Interpretable:

1. Compare the PU_COMMIT_VERSION from the message with the current PU_COMMIT_VERSION from env.json.
   • If they match, abort the update.
   • If they differ, start the update process.
2. Compute the Unit uuid from the PU_AUTH_TOKEN JWT in env.json.
3. Download a tgz, tar, or zip update archive via REST. The PU_HTTP_TYPE and PU_DOMAIN variables are available in env.json:
   • PU_HTTP_TYPE://PU_DOMAIN/pepeunit/api/v1/units/firmware/tgz/{Unit.uuid}?wbits=9&level=9
     • allowed wbits: (from -15 to -8) (from 9 to 16) (from 25 to 32)
     • allowed level: (from -1 to 10)
   • PU_HTTP_TYPE://PU_DOMAIN/pepeunit/api/v1/units/firmware/tar/{Unit.uuid}
   • PU_HTTP_TYPE://PU_DOMAIN/pepeunit/api/v1/units/firmware/zip/{Unit.uuid}
4. Extract all files from the archive into a separate directory or memory area.
5. Replace the current program files with the files from the new directory or memory area.
6. Restart the Unit.

ENV_UPDATE - env_update/pepeunit

When is this command sent?

1. When the command is triggered via the dedicated button in the Unit UI.
2. When the command is triggered via REST or GQL.

This command tells the Unit to update schema.json. The Unit must then execute a sequence of actions that results in replacing the current schema.json with a new one.

Message format for the schema_update/pepeunit topic

{
    "COMMAND": "SchemaUpdate"
}

Unit behavior algorithm

1. Download the new schema.json via REST. The PU_HTTP_TYPE and PU_DOMAIN variables are available in env.json:
   • PU_HTTP_TYPE://PU_DOMAIN/pepeunit/api/v1/units/get_current_schema/{Unit.uuid}
2. Replace the current schema.json state in the Unit with the new version.

ENV_UPDATE – env_update/pepeunit

When is this command sent?

1. When the command is triggered via the dedicated button in the Unit UI.
2. When the command is triggered via REST or GQL.

This command tells the Unit to update env.json. The Unit must then execute a sequence of actions that results in replacing the current env.json with a new one.

Message format for the env_update/pepeunit topic

{
    "COMMAND": "EnvUpdate"
}

Unit behavior algorithm

1. Download the new env.json via REST. The PU_HTTP_TYPE and PU_DOMAIN variables are available in the current env.json:
   • PU_HTTP_TYPE://PU_DOMAIN/pepeunit/api/v1/units/env/{Unit.uuid}
2. Replace the current env.json state in the Unit with the new version.

LOG_SYNC - log_sync/pepeunit

When is this command sent?

1. When the command is triggered via the dedicated button in the Unit UI.
2. When the command is triggered via REST or GQL.

This command tells the Unit to synchronize all logs it currently has locally. At the same time, Pepeunit forcibly deletes all logs for this Unit from ClickHouse. In response, the Unit must collect all existing logs and send them via MQTT back to Pepeunit.

Message format for the log_sync/pepeunit topic

{
    "COMMAND": "LogSync"
}

Unit behavior algorithm

1. Prepare logs in the required format (see the log/pepeunit topic section for details).
2. Send the prepared logs to the log/pepeunit topic from the output_base_topic section.

INFO

This command exists to simplify debugging and monitoring of Units. Not every error can be seen in real time via MQTT at the moment it occurs.