Write Blueprint

Example Device

Because Modbus is one of the most popular communication protocols, we use an example Hydrogen sensor over Modbus - a fictional H2 sensor that works over the RS-485 communication standard and supports Modbus RTU protocol. We use ENP-RS485 hardware UCM for this example. For details on working with other interfaces, see:

• CAN bus
• Relay

At this level we keep things simple — connection parameters are hardcoded in Lua script and errors are not handled in the best way. It will be improved on the Level 2.

Writing Manifest

YAML Format

The file is based on YAML standard which is sensitive to line indentation. We highly recommend using a text editor or an IDE with YAML support.

Open your favourite text editor or an IDE and create a manifest.yml file:

manifest.yml

# Blueprint specification version
blueprint_spec: device/3.0

display_name: H2 Sensor
description: Hydrogen sensor integration example.
icon: enapter-gauge

# Runtime describes how to run the device
runtime:
  type: lua
  requirements:
    - modbus
  options:
    file: main.lua

# Properties are metadata that does not change during device normal operation
properties:
  serial_number:
    type: string
    display_name: Serial Number

# Sensors data and internal device state, operational data
telemetry:
  h2_concentration:
    type: float
    unit: "%LEL"
    display_name: H2 Concentration

# Alerts which the device can raise during operation
alerts:
  h2_high:
    severity: error
    display_name: High H2 Concentration
    description: Hydrogen leakage is detected.

# Commands which can be performed on the device
commands:
  reset:
    display_name: Reset Sensor Alarm
    group: sensor
    ui:
      icon: bell-off-outline
      quick_access: true

# Commands can be grouped in the UI
command_groups:
  sensor:
    display_name: Sensor

Notice that these manifests do not contain a configuration section. At this level, all connection parameters will be hardcoded in the Lua script.

Please check the full manifest reference out to find out about all the capabilities.

Lua Script

The Lua script implements the device interface declared in the manifest. It uses the enapter.main() function as the entrypoint — this function is called automatically when the device starts.

Create a new main.lua file:

main.lua

-- Hardcoded connection URI for the Modbus device.
-- For hardware UCM (ENP-RS485): "port://rs485"
local CONNECTION_URI = "port://rs485"

-- Create Modbus client with hardcoded connection URI to read device serial number
local client, err = modbus.new(CONNECTION_URI)
if err then
  enapter.log('Cannot create Modbus connection: ' .. err, 'error')
  return
end

-- Hardcoded Modbus unit ID of the endpoint device
local UNIT_ID = 1

-- H2 concentration limit in %LEL
local H2_LIMIT = 4.0

-- The entrypoint to your code, called automatically
function enapter.main()
  -- Register periodic function, will send properties every 30 seconds
  scheduler.add(30000, send_properties)

  -- Register periodic function, will send telemetry every 1 second
  scheduler.add(1000, send_telemetry)

  -- Register "reset" command
  enapter.register_command_handler('reset', reset_command)
end

function send_properties()
  enapter.send_properties({
    serial_number = "AAACCB"
  })
end

function send_telemetry()
  -- Read H2 concentration from holding register 100
  local data, read_err = client:read_holdings(UNIT_ID, 100, 1, 1000)
  if read_err then
    enapter.log('Failed to read Modbus data: ' .. read_err, 'error')
    return
  end

  local h2_concentration = data[1] / 100.0

  -- Check H2 limit
  local alerts = {}
  if h2_concentration >= H2_LIMIT then
    alerts = {'h2_high'}
  end

  enapter.send_telemetry({
    h2_concentration = h2_concentration,
    alerts = alerts,
  })
end

-- "reset" command implementation
function reset_command(ctx)
  -- Write into holding register 420
  local err = client:write_holding(UNIT_ID, 420, 1, 1000)
  if err then
    ctx.error('Failed to write into Modbus register: ' .. err, 'error')
  end
  return 'Reset sensor alarm'
end

Key Points

• enapter.main() is the entrypoint called automatically when the device starts. Use it to register periodic functions and command handlers.
• scheduler.add(period, fn) schedules a function to be called periodically. The period is in milliseconds.
• modbus.new(connection_uri) creates a Modbus client. The connection URI specifies how and where to connect.

tip

Connection parameters (CONNECTION_URI, UNIT_ID, etc.) are hardcoded as Lua constants. This works well for a single installation, but if you need to reuse the blueprint with different devices or settings, consider adding a configuration section to make these parameters adjustable through the UI.

Please check the full Lua API reference out to find out about all the capabilities.

Next Steps

Now that the blueprint is ready:

1. Create a device to upload your blueprint and start running it.
2. Once you're comfortable, move to Level 2 to learn about configuration.