manifest.yml

Manifest file is an essential part of any device blueprint. It describes the device in a few core concepts:

• properties – device metadata which does not change during normal device operation. "Firmware version", "Device model", and "Serial number" fit this well.
• telemetry – device sensors data and internal state which must be tracked during device operation. Examples are "Engine temperature" and "Connection status".
• alerts – alerts that the device can raise during operation. An example is "Engine overheating".
• commands – commands which can be performed on the device. An example is "Turn on engine".

The file is based on YAML standard. File name must be manifest.yml.

Blueprint Metadata

Every manifest has several lop-level fields which describe the blueprint itself.

blueprint_spec: device/1.0

display_name: H2 Sensor
description: Integrates H2 sensor over Modbus using ENP-RS485.
icon: enapter-gauge
vendor: sma

license: MIT
author: enapter
contributors:
  - anataty
  - nikitug
support:
  url: "https://enapter.com/support"
  email: "support@enapter.com"

blueprint_specrequired

The version of the blueprint specification. Currently, the device blueprint specification has only one version, device/1.0.

display_namerequired

The name of your blueprint. Usually it's equal to the name of the device which you are integrating.

description

The details about the device integration. May contain most important information about physical connections, device versions, etc. It will be shown next to the blueprint name on some screens in the UI.

icon

The icon to be used for the device in the UI. Must be either one from the community list of icons or Enapter icon set (prepend an icon name with enapter-).

vendor

The vendor of integrated device. Should be empty for generic blueprints.

Available vendors are presented in the marketplace GitHub repository. If you want to propose a new one, please create Pull Request or fill an issue.

license

The license type. You may use any license you want. MIT is usually a good choice.

author

The name of the blueprint author. Should be a valid GitHub username.

contributors

A list of developers who contributed to this blueprint. Items should be valid GitHub usernames.

support

The contact information. Contains a web address and an email of a responsible person or organisation able to provide help with this blueprint.

Communication Module

Every device integration defined in the blueprint is backend by one of Enapter UCMs. Top-level communication_module section contains information about that UCM.

communication_module:
  product: ENP-RS485
  lua_file: ucm.lua

productrequired

The product name of Enapter UCM, must equal to the name from the modules list, e.g. ENP-RS485, ENP-CAN etc.

lua_fileconflicts: lua

Lua script which will be uploaded to the UCM. The file must be placed into the same directory as a manifest.yml. Subdirectories are also supported:

lua_file: my_subdir/rs485.lua

luaconflicts: lua_file

Description of Lua script split into several files and/or with external dependencies. See available options and manifest examples below.

Single file with dependencies

communication_module:
  product: ENP-RS485
  lua:
    file: ucm.lua
    dependencies:
      - lua-string ~> 1.2

Multiple files with rockspec

communication_module:
  product: ENP-RS485
  lua:
    dir: fwdir
    rockspec: my-dev-1.rockspec

fileconflicts: dir

Lua script which will be uploaded to the UCM. The file must be placed into the same directory as a manifest.yml. Subdirectories are also supported.

dirconflicts: file

The directory with Lua scripts. It must contain main.lua file as an entrypoint for amalgamated Lua script.

dependenciesconflicts: rockspec

External dependencies list. Each row should be a Luarocks package. We strongly recommend to specify versions for your dependencies to avoid breaking changes. For example, lua-string ~> 1.2 means "get lua-string package with version >= 1.2 and < 1.3". See Rockspec dependencies format to learn more.

rockspecconflicts: dependencies

Rockspec file which will be used to resolve dependencies.

allow_dev_dependencies

If set to true it is allowed to use luarocks dev packages.

amalg_mode

Mode to use for amalgamation. The following modes are supported:

• isolate
• nodebug

Specify isolate mode if you want to disable smart dependency resolver and amalgamate all provided Lua modules (see troubleshooting section for complex Lua scripts):

amalg_mode: isolate

Specify nodebug mode if you want to exclude debug information from amalgamated file (see troubleshooting section for complex Lua scripts)

amalg_mode: nodebug

To specify more than one mode use yaml arrays syntax:

amalg_mode:
  - isolate
  - nodebug

Properties

Top-level properties section is a map whose keys are property names, and values are property definitions.

properties:
  serial_number:
    display_name: Serial Number
    description: "1XXXX" are produced in Italy, "2XXXX" – in China.
    type: integer
  model:
    display_name: Device Model
    type: string
    enum:
      - AnySen M12
      - AnySen MP20

display_namerequired

Display name which will be shown to the users in the UI.

description

The more detailed description about the property. It will be shown next to the property display name on some screens in the UI.

typerequired

Property type declaration, such as string, integer, etc. If a Lua script will send wrong type for the property, its value will be ignored. See the types chapter below for the details.

enum

Enumeration limits possible property values. If a Lua script sends some value which is not in the enumeration set, the value will be ignored. See the enums chapter below for the details.

Telemetry

Top-level telemetry section is a map whose keys are telemetry attribute names, and values are telemetry attribute definitions.

telemetry:
  voltage:
    display_name: Battery Amperage
    description: The value is read from a shunt.
    type: float
    unit: amp
  mode:
    display_name: Run Mode
    type: string
    enum:
      - stopped
      - running

display_namerequired

Display name which will be shown to the users in the UI.

description

The more detailed description about the telemetry attribute. It will be shown next to the attribute display name on some screens in the UI.

typerequired

Telemetry attribute type declaration, such as string, integer, etc. If a Lua script will send wrong type for the attribute, its value will be ignored. See the types chapter below for the details.

enum

Enumeration limits possible telemetry attribute values. If a Lua script sends some value which is not in the enumeration set, the value will be ignored. See the enums chapter below for the details.

unit

The unit of measurement which will be used to represent the value on the dashboards and the UI. Only applicable to the numeric types (integer and float).

Device Status

status attribute should only be used to indicate overall device status. This status will be shown next to the device name on some screens.

Device status indicator on devices list page

It must be string with declared enum values, otherwise manifest validation will fail. Let's take an example of car engine:

telemetry:
  status:
    display_name: Engine Status
    type: string
    enum:
      - warmingup
      - running
      - cooling
      - stopped

Alerts Attribute

alerts attribute is reserved for alerts integration and should not be declared in the manifest by the user, otherwise validation will fail. Instead alerts attribute is automatically added to every manifest as an array of strings.

Alerts

Top-level alerts section is a map whose keys are alert names, and values are alert definitions.

When any alert is active on a connected device, a Lua script running on the UCM passes that alert names in the alerts telemetry attribute. Enapter Cloud then takes alerts metadata (like name and description) from the manifest declaration.

If alert is sent by the UCM, but not declared in the manifest, then it will still be shown to the user with default severity error.

alerts:
  overcurrent:
    severity: warning
    code: W115
    display_name: High Current
    description: Current is very high, stop some loads to prevent overload shut-off.

severityrequired

Alert severity, one of: error, warning, info.

You can use your own meanings for different severity levels. As a general approach try to follow the convention:

• error – the device is not operational due to error,
• warning – the device is operational but requires user attention,
• info – the device may require user attention.

code

Vendor-specific alert code, which may be useful, for example, for checking in the device manual.

grace_period

Period in duration format (1m, 2m30s) when soft fail become hard fail. If empty grace period is equal zero and all alerts are raised as hard. This is useful for failures which are not critical in a short time, but become dangerous after a while.

display_namerequired

Display name which will be shown to the users in the UI.

description

The details about the alert. It may explain alert conditions or suggest a resolution instruction. It will be shown on the alert screen.

Commands

Top-level commands section is a map whose keys are command names, and values are command definitions.

Command handler must be declared in the UCM Lua script under the same name.

commands:
  beep:
    display_name: Beep
    group: checks
    ui:
      icon: alarm-light-outline
      quick_access: true

display_namerequired

Display name which will be shown to the users in the UI.

description

The details about the command. It will be shown on the command execution screen.

grouprequired

Group name, which references the group declared in the command_groups section.

Every command must be placed into a group. The grouping only affects the user interfaces, and does not affect the logic of the system.

ui.icon

The icon will be shown next to the command name in the UI. Must be one from the full list of available icons.

ui.quick_access

Places the command into a quick access list in the Enapter mobile app. Use the remote control button on the device screen to trigger the list.

Confirmation

confirmation key in the command definition enables a confirmation message upon command execution.

commands:
  configure:
    # ...
    confirmation:
      severity: warning
      title: Changing Configuration
      description: Make sure to reboot the device after configuration process is over.

severityrequired

Confirmation severity, one of: info, warning. Severity only affects the UI of the confirmation message.

titlerequired

The title of the confirmation message box.

description

The message body which will be shown to the user upon the command execution.

Arguments

arguments key in the command definition is a map whose keys are argument names, and values are argument definitions.

Command arguments are asked upon the command execution. The arguments form is generated automatically based on the argument types and expected values. Arguments are then passed to the command handler in the Lua script.

commands:
  switch_mode:
    # ...
    arguments:
      mode:
        display_name: Mode to Switch to
        description: Select device operation mode. "charger" mode requires grid connection.
        required: true
        type: string
        enum:
          - inverter
          - charger
          - pass-through
        default: inverter
      voltage:
        display_name: Target Voltage
        type: float
        min: 23.0
        max: 25.5

display_namerequired

Display name which will be shown in the arguments form.

description

A more detailed description of the argument. It will be shown next to the argument field in the arguments form.

required

Defines if the argument is required for command execution. If required field is not set, the argument is considered optional by default.

typerequired

Command argument type declaration, such as string, integer, etc. See the types chapter below for the details.

Type defines which input field will be used for the argument in the arguments form. For example, integer type will show numerical keyboard in the mobile application.

enum

Enumeration limits possible argument values. See the enums chapter below for the details.

The values are offered to the user in the arguments form as a select field.

default

Defines default value of the argument. It will be used in the arguments form as a default value of an input field.

min, max

Validates a passed argument value with minimum and maximum thresholds. It could only be applied to numerical argument types.

Validation happens on the UI side only upon the arguments form submission. If the validation is critical for the proper command functionality, additionally check the argument value in UCM Lua script.

Values Prepopulation

Prepopulation mechanism reads the values for the argument form from another command first, then pre-populates it into the form fields, and allows the user to change it before form submission.

commands:
  write_config:
    # ...
    populate_values_command: read_config

populate_values_command

The name of the command which should be used for reading the values for the arguments form pre-population. This "read" command should return a Lua table with the same keys as the arguments in the write command, see the example below.

Example

We are implementing the write_config command which allows user to change the voltage threshold configuration. The read_config command reads the threshold from the device.

commands:
  read_config:
    display_name: Read Configuration
    group: config
  write_config:
    display_name: Write Configuration
    group: config
    populate_values_command: read_config
    arguments:
      voltage_threshold:
        display_name: Voltage Threshold
        type: float

The read_config command on the UCM should return the corresponding voltage_threshold argument value.

function read_config_command(ctx, args)
  return {
    voltage_threshold = 12.5 -- read actual value
  }
end

enapter.register_command_handler("read_config", read_config_command)

Types

The types of the returned values from the Lua script should conform to the types of the arguments declared in the manifest.

Groups

Top-level command_groups key is a map whose keys are command group names, and values are group definitions.

command_groups:
  checks:
    display_name: Checks

display_namerequired

Display name which will be shown as a heading of the commands group on the commands screen.

Type Declarations

Several manifest declarations necessitate type information, including property, telemetry attribute, command argument. These declarations are composed of two keys.

typerequired

Can be integer, float, string, boolean.

enum

Enumeration limits possible values and must conform to the declared type. integer, float, string types support enum declaration.

Enumerations and YAML Types

YAML has numeric, string, and boolean built-in types.

When you use 1 as a value it's an integer, and when you use "1" – it's a string.

type: integer
enum:
  - 1
  - "2" # error: it's a string, but type must be integer

Type coercion between integers and floats is handled automatically.

type: float
enum:
  - 1.0
  - 2 # ok: integer will be coerced into float

Boolean types can be specified in YAML as true, false, yes, no values (note - without quotes), while, for example, "true" is a string.

type: string
enum:
  - 1 # error: it's an integer, but type must be string
  - no # error: it's a boolean equal to false, use "no" instead
  - "2"