Skip to main content

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: shield-alert-outline
blueprint_specrequired#

The version of the blueprint specification. So far we have only one version of device blueprint specification which is 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 will be used for the device in the UI. Must be one from the full list of available icons.

Communication Module#

Every device integration defined in the blueprint is backend by one of Enapter UCMs. Top-level communication_module section contains an 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_file#

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

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

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 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 frist, then pre-populate it into the form fields, and allow 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#

There are several declarations in the manifest which require a type information: property, telemetry attribute, command argument. The declaration consists 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.

Emunerations 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"
Hardware diversity is welcome. Integrate any device into a unified energy network.
© 2021 Enapter
Developer toolkit
DocumentationReference
Community
GithubTindie