Skip to main content

Enapter EMS

enapter library implements an interface to Enapter EMS.

enapter.log​

-- @param text string
-- @param severity string Log severity: debug, info, warning, error. Default: info.
function enapter.log(text, severity)
end

Sends one log entry to Enapter EMS. These log entries can be viewed in Enapter EMS UI or via public HTTP API.

Use severity argument to distinguish log entry between debug, info, warning, error. Different severities may be shown differently in the UI. Default severity is info.

Example​

local data, err = read_device_telemetry()
if err ~= nil then
  enapter.log("Reading data failed: "..err, "error")
end

enapter.device​

-- @param id string Device ID or slug
-- @return table, string|nil
function enapter.device(id)
end

Finds device by the given ID or slug. Returns device object. On failure (e.g. device is not found), it returns nil and an error message string.

Example​

local device, err = enapter.device("my-device")
if err ~= nil then
  enapter.log("Device not found: "..err)
end

enapter.devices​

-- @return table|nil, string|nil
function enapter.devices()
end

Returns a list of devices that are available on a site. On failure, it returns nil and an error message string.

Example​

local devices = enapter.devices()
for _, device in pairs(devices) do
  local model = device.property("model")
  if model == "EL40" then
    enapter.log("Enapter EL4.0: "..device.id)
  end
end

device object​

device.id​

device.id holds string ID.

device.online​

-- @return boolean, string|nil
function device.online()
end

Returns true if the device is online, false otherwise.

On failure, it returns false and an error message string.

Example​

local device, err = enapter.device("my-device")
if device then
  local online, err = device.online()
  if err ~= nil then
    enapter.log("cannot read device status: "..err)
  else
    enapter.log("device online: "..tostring(online))
  end
end

device.implements​

-- @return table, string|nil
function device.implements()
end

Returns a table containing list of profiles implemented by the device. The list is the same as the implements section in the device manifest.yml.

On failure, it returns nil and an error message string.

Example​

local device, err = enapter.device("my-device")
if device then
  local implements, err = device.implements()
  if err ~= nil then
    enapter.log("cannot read implements list: "..err)
  else
    enapter.log("device implements: "..table.concat(implements, ", "))
  end
end

device.property​

-- @param name string Property name
-- @return table, string|nil
function device.property(name)
end

Returns current property value. The property name must be declared in the properties section in the device manifest.yml. If the device has never sent this property, then the function returns nil.

On failure, it returns nil and an error message string.

Example​

local device, err = enapter.device("AABB")
if device then
  local model, err = device.property("model")
  if err ~= nil then
    enapter.log("cannot read device property: "..err)
  else
    enapter.log("device model: "..tostring(model))
  end
end

device.properties​

-- @return table, string|nil
function device.properties()
end

Returns a table containing current properties of the device. The properties must be declared in the properties section in the device manifest.yml.

On failure, it returns nil and an error message string.

device.telemetry.now​

-- @param name string telemetry attribute name
-- @return string|number|boolean|nil, string|nil
function device.telemetry.now(name)
end

Returns current telemetry attribute value. The attribute name must be declared in the telemetry section in the device manifest.yml. If the device is offline or is not transmitting this telemetry attribute value, then the function returns nil.

On failure, it returns nil and an error message string.

Example​

local device, err = enapter.device("AABB")
if err == nil then
  local voltage, err = device.telemetry.now("volt")
  if err ~= nil then
    enapter.log("cannot read device voltage, device may be offline: "..err)
  else
    enapter.log("device voltage="..tostring(voltage))
  end
end

device.telemetry.avg​

-- @param name string telemetry attribute name
-- @param interval string averaging interval
-- @return number|nil, string|nil
function device.telemetry.avg(name, interval)
end

Returns an average value of the telemetry attribute over a period of the given interval. The attribute name must be declared in the telemetry section in the device manifest.yml and be of numeric (integer or float) type. If the device is offline or is not transmitting this telemetry attribute value, then the function returns nil.

Interval must be provided in duration format.

This function is useful for making the logic less reactive to the fluctuations of the target telemetry value.

On failure, it returns nil and an error message string.

Example​

local device, err = enapter.device("AABB")
if device then
  local avg_volt, err = device.telemetry.avg("volt", "2m")
  if avg_volt then
    enapter.log("average voltage for the last 2 minutes is "..tostring(avg_volt).."V")
  else
    enapter.log("cannot read device voltage, device may be offline: "..err)
  end
end

device.telemtry.median​

-- @param name string telemetry attribute name
-- @param interval string averaging interval
-- @return number|nil, string|nil
function device.telemetry.median(name, interval)
end

Returns a median value of the telemetry attribute over a period of the given interval. The attribute name must be declared in the telemetry section in the device manifest.yml and be of numeric (integer or float) type. If the device is offline or is not transmitting this telemetry attribute value, then the function returns nil.

Interval must be provided in duration format.

This function is useful for making the logic less reactive to the fluctuations of the target telemetry value.

On failure, it returns nil and an error message string.

Example​

local device, err = enapter.device("AABB")
if device then
  local avg_volt, err = device.telemetry.median("volt", "2m")
  if avg_volt then
    enapter.log("median voltage for the last 2 minutes is "..tostring(avg_volt).."V")
  else
    enapter.log("cannot read device voltage, device may be offline: "..err)
  end
end

device.telemetry.last​

-- @param name string telemetry attribute name
-- @param interval string relevance interval
-- @return string|number|boolean|nil, string|nil
function device.telemetry.last(name, interval)
end

Returns the last value of the telemetry attribute over a period of the given interval or nil if nothing transmitted. The attribute name must be declared in the telemetry section in the device manifest.yml.

Interval must be provided in duration format.

On failure, it returns nil and an error message string.

Example​

local device, err = enapter.device("AABB")
if device then
  local last_volt, err = device.telemetry.last("volt", "2m")
  if last_volt then
    enapter.log("last voltage value for the last 2 minutes is "..last_volt.."V")
  else
    enapter.log("cannot read device voltage, device may be offline: "..err)
  end
end

device.commands.execute​

-- @param name string command name
-- @param args table command arguments
-- @return table|nil, string|nil
function device.commands.execute(name, args)
end

Executes device command with the given name and given command arguments. The attribute name must be declared in the telemetry section in the device manifest.yml. Returns command response payload. On failure, it returns nil and an error message string.

Rule execution blocks until command execution is completed.

Examples​

local device, err = enapter.device("AABB")
if device then
  local resp, err = device.commands.execute("set_production_rate", { rate = 100 })
  if err ~= nil then
    enapter.log("set_production_rate failed: "..err)
  else
    enapter.log("set_production_rate completed: "..inspect(resp))
  end
end

device.commands.start​

-- @param name string command name
-- @param args table command arguments
-- @return string|nil, string|nil
function device.commands.start(name, args)
end

Start execution of device command with the given name and given command arguments. The attribute name must be declared in the telemetry section in the device manifest.yml. Return command execution ID. On failure, it returns nil and an error message string.

Rule does not wait until command execution is completed. Use returned execution ID and device.command.response for reading command response.

device.commands.response​

-- @param execution_id string command execution ID
-- @return table|nil, string|nil
function device.commands.response(execution_id)
end

Returns command execution response by execution ID returned by device.command.start. On failure, it returns nil and an error message string. If command is not completed yet, function returns device.commands.err_not_completed.

Example​

local device, err = enapter.device("AABB")
if device then
  local executionID = device.commands.start("set_production_rate", { rate = 100 })
  local response, err = device.commands.response(executionID)
  if err ~= nil then
    if err == device.commands.err_not_completed then
      enapter.log("command stil not completed")
    else
      enapter.log("set_production_rate failed: "..err)
    end
  else
    enapter.log("set_production_rate completed")
  end
end

Duration Format​

A duration string is a sequence of decimal numbers, each with optional fraction and a unit suffix, such as 1s, 1.5m or 2h45m. Valid time units are ns (nanosecond), us (microsecond), ms (millisecond), s (second), m (minute), h (hour), d (day), y (year).

All Rights Reserved © 2025 Enapter AG.

Privacy Policy|Cookies Policy