Compiled Blueprint

Compiled blueprint is made from uploaded blueprint with the following changes:

Lua scripts are amalgamated into a single file,
JSON schemas are integrated into the manifest.yml,
blueprint_spec is set to device_compiled/3.0,
enums are normalizd into two sections: enum and enum_with_metainfo,
telemetry enums are filled with colors,
alerts and alert_details are added to the telemetry,
not_configured alert is added to the alerts,
configuration, properties, telemetry and commands sections are filled with default access_level,
unit and auto_scale are normalized to full codes (see units guide),
implements and aliases are normalized to sequences,
fill implements in properties, telemetry and commands sections with names of implemented profiles,
fill aliases in properties, telemetry and commands sections with implemented profiles names,
fill units with all used units in manifest.

The manifest.yml file is must feet the scheme.

Manifest Fields

blueprint_specrequired#: The version of the blueprint specification. This reference describes version device_compiled/3.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.

implements#: The list of Enapter profiles which this blueprint implements. Available profiles are published on GitHub. See profiles usage guide for more details.

category#

The category of the device. It is used to group devices in the Cloud UI. The list of available categories:

hydrogen-storage
electrolysers
solar-generators
fuel-cells
water-treatment
battery-systems
power-meters
hvac
electric-vehicles
control
data-providers
sensors

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-).

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.

Runtime

Every device integration defined in the blueprint should be run something. Top-level runtime section describes how to run this device.

runtime:
  type: lua
  requirements:
    - lua_api_v3
    - modbus
  options:
    file: main.lua

typerequired#

The type of the runtime which is used to run the device integration.

lua — the device required a runtime to run Lua scripts.
embeded — the device is work bye themself, used by standalone devices and Enapter's hardware (UCM, electrolyser etc).

requirements#: A list of runtime requirements. Each item is a string which describes a requirement. See Lua development guide for the list of available requirements and its meanings.

options.fileconflicts: dir#: Lua script which will be uploaded to the runtime. The file must be placed into the same directory as a manifest.yml.

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
    access_level: readonly
  model:
    display_name: Device Model
    type: string
    access_level: readonly
    enum:
      - AnySen M12
      - AnySen MP20
    enum_with_metainfo:
      - value: AnySen M12
        display_name: AnySen M12
      - value: AnySen MP20
        description: AnySen M12

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. In this section enum is presented as a simple list of the values.

enum_with_metainfo#: Enumeration limits possible property values. In this section enum is presented as a list of objects with value, display_name, description and color fields. The value field is used to store the actual value of the property, while display_name and description are used to show the value in the UI. If color field is missed in original blueprint, it will be set to pseudo-random color (each enum values wih same name will have same color).

unit#: The unit of measurement in a full-code format which will be used to represent the value on the dashboards and the UI. Only applicable to the numeric types (integer and float). To learn more about available units and usage examples, see the units guide.

auto_scale#

Specifies the units to which the property value can be scaled within the UI.

unit: W
auto_scale: [W, kW, MW]

implements#

The list of Enapter profiles which this property implements. If property has same name as implmented profile, it is not necessary to specify it. See profiles usage guide for more details.

implements:
  - energy.inverter.nameplate.inverter_nameplate_capacity

aliases#: Extra names which can be used to refer to the same property. Aliases are useful for backward compatibility, when you want to keep the old name of the property but also want to use a new name.

access_level#

Defines the access level required to read the property value. The access level is a string which can be one of the following:

readonly
user
owner
installer
vendor
system

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: A
    access_level: readonly
  mode:
    display_name: Run Mode
    type: string
    access_level: readonly
    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.

json_schema#: JSON schema or path to file with it of telemetry attribute with json type.

enum#: Enumeration limits possible telemetry attribute values. In this section enum is presented as a simple list of the values.

enum_with_metainfo#: Enumeration limits possible telemetry attribute values. In this section enum is presented as a list of objects with value, display_name, description and color fields. The value field is used to store the actual value of the telemetry attribute, while display_name and description are used to show the value in the UI. If color field is missed in original blueprint, it will be set to pseudo-random color (each enum values wih same name will have same color).

unit#: The unit of measurement in a full-code format which will be used to represent the value on the dashboards and the UI. Only applicable to the numeric types (integer and float). To learn more about available units and usage examples, see the units guide.

auto_scale#

Specifies the units to which the telemetry attrubute value can be scaled within the UI.

unit: W
auto_scale: [W, kW, MW]

implements#

The list of Enapter profiles which this telemetry attribute implements. If the telemetry attribute has same name as implmented profile, it is not necessary to specify it. See profiles usage guide for more details.

implements:
  - energy.inverter.ac.1_phase.ac_l1_voltage

aliases#: Extra names which can be used to refer to the same telemetry attribute. Aliases are useful for backward compatibility, when you want to keep the old name but also want to use a new name.

access_level#

Defines the access level required to read the telemetry attribute value. The access level is a string which can be one of the following:

readonly
user
owner
installer
vendor
system

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.

Troubleshooting

alerts:
	WH_10:
    severity: warning
    display_name: Lost Modbus safety heartbeat communication
    description: Modbus communication between the Electrolyser and the Modbus master device has been lost. Please check that the Ethernet cable is properly installed, the connection is established, and the Modbus master is operational.
    component:
      - Ethernet
      - Modbus TCP
    condition:
      - Heartbeat packet was not received in time
    troubleshooting:
      - Please check that the Ethernet cable is properly installed, the connection is established, and the Modbus master is operational.

troubleshooting#: Troubleshooting steps to show in UIs.

telemetry#: Telemetry attributes that are related to the alert.

components#: Device components that are related to the alert.

conditions#: Conditions which may cause the alert raising.

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
    access_level: user
    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.

implements#

The list of Enapter profiles which this command implements. If command has same name as implmented profile, it is not necessary to specify it. See profiles usage guide for more details.

implements:
  - lib.device.power.power_on

aliases#: Extra names which can be used to refer to the same command. Aliases are useful for backward compatibility, when you want to keep the old name of the command but also want to use a new name.

access_level#

Defines the access level required to execute the command. The access level is a string which can be one of the following:

readonly
user
owner
installer
vendor
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.mobile_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
        enum_with_metainfo:
          - value: inverter
            display_name: Inverter
            description: Inverter mode, used for off-grid operation.
          - value: charger
            display_name: Charger
            description: Charger mode, used for grid-connected operation.
          - value: pass-through
            display_name: Pass-Through
            description: Pass-through mode, used for direct connection to the grid.
        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.

format#: Format of string command argument. It gets some hints to show more convenient UI instead of simple text field.

json_schema#: JSON schema or path to file with it of command argument with json type.

sensitive#: Sensitive command arguments will be hidden in command logs to protect sensitive data.

enum#

Enumeration limits possible argument values. In this section enum is presented as a simple list of the values.

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

enum_with_metainfo#: Enumeration limits possible argument values. In this section enum is presented as a list of objects with value, display_name and description fields. The value field is used to store the actual value of the argument, while display_name and description are used to show the value in the UI.

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.

Response

response key in the command definition is a map whose keys are response names, and values are success response definitions. This definition is a documentation and not validated by the Enapter Cloud.

commands:
    get_status:
        group: status
        display_name: Status
        response:
            live_sessions:
                required: true
                type: integer
            uptime:
                required: true
                type: string
                format: datetime

required#: Defines if the response value will be present in every success reponse.

typerequired#: Command response field type declaration, such as string, integer, etc. See the types chapter below for the details.

format#: Format of string command response field. It gets some hints about data representation.

json_schema#: JSON schema for json-type command response value. It can be filename or schema directly.

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.

The usage of this feature is similar to the configuration, but applies to commands. And commands can have a quick access from the mobile app without going through interfaces to massive settings for changing one simple setting.

commands:
  set_production_rate:
    # ...
    populate_values_command: read_production_rate

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 set_production_rate command which allows user to change the production rate. The read_production_rate command returns the current production rate value from the device.

commands:
  read_production_rate:
    display_name: Read Configuration
    group: config
  set_production_rate:
    display_name: Write Configuration
    group: config
    populate_values_command: read_production_rate
    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.

description#: A more detailed description of the command group.

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

Units

Units section describes all units are used in this manifest.

symbolrequired#: The unit symbol, which will be used to represent the value in the UI.

typerequired#

The unit type:

custom is for described in units section of original uploaded Blueprint
ucum is for UCUM units, it's got from properties and telemetry attributes

symbol#: The unit text representation.

Configuration

Top-level configuration section describes the configuration parameters which are required for the device to work properly. Configuration splits into buckets, which are used to group configuration parameters into logical groups.

configuration:
    network:
      display_name: Network
      description: Network settings for the device.
      access_level: user
      parameters:
        - name: uri
          display_name: Connection URI
          type: string
          required: true
          description: URI to connect to the device.
        - name: port
          display_name: Port
          type: integer
          default: 502

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

description#: The details about the configuration section.

access_level#

Defines the access level required to read/write the configuration. The access level is a string which can be one of the following:

readonly
user
owner
installer
vendor
system

ui.icon#: The icon will be shown next to the configuration bucket name in the UI. Must be one from the full list of available icons.

Configuration Parameters

parameters key in the configuration bucket is a list of configuration parameters. Each parameter is a map with the following keys.

display_namerequired#: Display name which will be shown in the UI.

required#: Defines if the parameter is required to device properly working.

typerequired#

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

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

format#: Format of string configuration parameter. It gets some hints to show more convenient UI instead of simple text field.

sensitive#: Sensitive configuration parameters will be hidden when get configuration to protect sensitive data.

default#: Defines default value of the parameter. It will be used in Lua script if parameter is not set.

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.

Manifest Fields​

blueprint_specrequired#

display_namerequired#

description#

implements#

category#

icon#

license#

author#

contributors#

support#

Runtime​

typerequired#

requirements#

options.fileconflicts: dir#

Properties​

display_namerequired#

description#

typerequired#

enum#

enum_with_metainfo#

unit#

auto_scale#

implements#

aliases#

access_level#

Telemetry​

display_namerequired#

description#

typerequired#

json_schema#

enum#

enum_with_metainfo#

unit#

auto_scale#

implements#

aliases#

access_level#

Alerts​

severityrequired#

code#

grace_period#

display_namerequired#

description#

Troubleshooting​

troubleshooting#

telemetry#

components#

conditions#

Commands​

display_namerequired#

description#

grouprequired#

implements#

aliases#

access_level#

ui.icon#

ui.mobile_quick_access#

Confirmation​

severityrequired#

titlerequired#

description#

Arguments​

display_namerequired#

description#

required#

typerequired#

format#

json_schema#

sensitive#

enum#

enum_with_metainfo#

default#

min, max#

Response​

required#

typerequired#

format#

json_schema#

Values Prepopulation​

Manifest Fields

`blueprint_spec`required#

`display_name`required#

`description`#

`implements`#

`category`#

`icon`#

`license`#

`author`#

`contributors`#

`support`#

Runtime

`type`required#

`requirements`#

`options.file`conflicts: dir#

Properties

`display_name`required#

`description`#

`type`required#

`enum`#

`enum_with_metainfo`#

`unit`#

`auto_scale`#

`implements`#

`aliases`#

`access_level`#

Telemetry

`display_name`required#

`description`#

`type`required#

`json_schema`#

`enum`#

`enum_with_metainfo`#

`unit`#

`auto_scale`#

`implements`#

`aliases`#

`access_level`#

Alerts

`severity`required#

`code`#

`grace_period`#

`display_name`required#

`description`#

Troubleshooting

`troubleshooting`#

`telemetry`#

`components`#

`conditions`#

Commands

`display_name`required#

`description`#

`group`required#

`implements`#

`aliases`#

`access_level`#

`ui.icon`#

`ui.mobile_quick_access`#

Confirmation

`severity`required#

`title`required#

`description`#

Arguments

`display_name`required#

`description`#

`required`#

`type`required#

`format`#

`json_schema`#

`sensitive`#

`enum`#

`enum_with_metainfo`#

`default`#

`min`, `max`#

Response

`required`#

`type`required#

`format`#

`json_schema`#

Values Prepopulation