Configuration Guide

Introduction

After some years of writing Enapter Blueprints we decided to stop forcing users to write the boilerplate code of configuration interface in Lua script and added a new feature to the manifest. All you have to do is just to declare configuration parameters in dedicated group(s).

Best Practices for Configuration

When defining configuration in your blueprint, follow these guidelines to keep things clean and maintainable:

1. Use configuration for long-term settings

   • Only include properties that don't need to be changed frequently. Use telemetry for dynamic or real-time data.

2. Set access_level thoughtfully

   • Choose the appropriate access level to control who can modify which settings. This helps prevent accidental or unauthorized changes.

3. Use default values sparingly

   • Defaults can be helpful, but avoid setting them unless the value makes sense for most users or devices.

4. Group related settings

   • You can define multiple configuration groups within a single manifest to organize settings logically and improve usability.

Configuration use cases

Connection parameters

Connection URI, device Modbus address or unit ID - any parameters required to connect to your device should be included in the configuration section.

configuration:
  connection:
    display_name: Connection
    description: Device connection parameters
    access_level: owner
    parameters:
      address:
        display_name: Modbus Address
        description: Device address in range 1-247
        type: integer
        required: true
      conn_str:
        display_name: Connection string
        description: Connection URI to the runtime device
        type: string
        format: connection_uri
        required: true

Device-specific information

Some device characteristics should be explicitly set by the user. For this purpose, the configuration is also well-suited.

Functional settings

configuration:
  device_info:
    display_name: Pressure sensor properties
    description: To set by user
    access_level: user
    parameters:
      calib_slope:
        display_name: Calibration Slope
        description: "`k` in calibration line equation `Pressure = k * Current + b`"
        type: float
        required: true
      calib_intercept:
        display_name: Calibration Intercept
        description: "`b` in calibration line equation `Pressure = k * Current + b`"
        type: float
        required: true

Hardware settings

configuration:
  relay:
    display_name: Relay settings
    description: Relay channels for power and start
    access_level: owner
    parameters:
      power_relay:
        display_name: Power Contact Channel
        description: The number of a relay channel to which an FC power contact is connected.
        type: integer
        required: true
      start_relay:
        display_name: Start Contact Channel
        description: The number of a relay channel to which an FC start contact is connected.
        type: integer
        required: true

Third-party API credentials

When setting any credentials, consider using the sensitive option to protect confidential data.

configuration:
  tasmota:
    display_name: Tasmota account settings
    description: Account credentials required to connect to Tasmota device
    access_level: owner
    parameters:
      username:
        display_name: Tasmota Username
        type: string
        required: true
      password:
        display_name: Tasmota Password
        type: string
        required: true
        sensitive: true