Enapter EMS

The enapter library implements an interface to Enapter EMS.

The enapter library is available for all UCMs, both hardware and software.

Sending Data

enapter.send_properties

-- @param data table
-- @return string|nil
function enapter.send_properties(data)
end

Sends properties data to Enapter Cloud. data is Lua table where keys are property reference names (as declared in the blueprint manifest) and values are actual property values. Properties with reference names that are not declared in the manifest will be ignored, see the properties section in the manifest.yml reference.

Returns nil if data was sent successfully, otherwise returns an error string.

Example

function send_properties()
  local err = enapter.send_properties({ serial_num = read_serial_num() })
  if err ~= nil then
    -- Properties was not sent usually because of connectivity problem.
    -- Add any logic to handle this if needed. Or just ignore, scheduler
    -- (see below) will run the function again in 30 seconds.
  end
end

-- Periodically send properties to EMS Server
scheduler.add(1000, send_properties)

enapter.send_telemetry

-- @param data table
-- @return string|nil
function enapter.send_telemetry(data)
end

Sends telemetry data to Enapter Cloud. data is Lua table where keys are telemetry attribute reference names (as declared in the blueprint manifest) and values are actual telemetry values. Telemetry attributes with reference names that are not declared in the manifest will be ignored, see the telemetry section in the manifest.yml reference.

Returns nil if data was sent successfully, otherwise returns error string.

Example

function send_telemetry()
  local err = enapter.send_telemetry({ temperature = read_temperature() })
  if err ~= nil then
    -- Telemetry was not sent usually because of connectivity problem.
    -- You can ignore it since the scheduler (see below) will run
    -- the function again in 1 second.
  end
end

-- Periodically send telemetry to Cloud
scheduler.add(1000, send_telemetry)

enapter.log

-- @param text string
-- @param severity string Log severity: debug, info, warning, error. Default: info.
-- @param persist boolean If the log entry should be persisted in Cloud. Default: false.
function enapter.log(text, severity, persist)
end

Sends one log entry to Enapter Cloud.

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

In some cases, especially for errors, you may want to persist log entries to check it later. Set persist argument to true in that case. Otherwise log entry will be removed after a short period of time. The number of log entries stored per one UCM is limited, so it's better to store only important ones.

Example

-- Send temporary log with info severity
enapter.log("Modbus connection established")
-- Send temporary log with debug severity
enapter.log("Received CAN data: "..data, "debug")
-- Send persisted log with error severiry
enapter.log("Cannot create CAN connection: "..err, "error", true)

Working With Commands

enapter.register_command_handler

-- @param name string
-- @param command_handler function
function enapter.register_command_handler(name, command_handler)
end

-- @param ctx table Execution context
-- @param args table Execution arguments as key-value table
function command_handler(ctx, args)
end

Registers function that will be called when UCM receives a command named name. The command must be declared in the blueprint manifest under the same reference name, see the commands section in the manifest.yml reference.

handler function must receive two arguments:

• ctx — command execution context,
• args — Lua table with argument values used for command execution.

The handler function provides three distinct return options:

• ctx.error(payload) terminates function execution. Command execution result will be an error with payload (Lua table or string).
• Explicit return from Lua function with return payload. Command result will be a success with payload (Lua table or string).
• Implicit return from Lua function when no ctx.error or return statement was called. Command result will be a success without any payload.

Example

function update_config_command(ctx, args)
  if args["voltage"] == nil then
    -- This function execution will be terminated, command execution will be failed.
    ctx.error("no voltage argument provided")
  end
  ctx.log("Updating voltage to " .. args["voltage"])
  -- No return called. Command execution will be succeeded without a payload.
end

function read_config_command(ctx, args)
  local config = { voltage = read_voltage() }
  -- Explicit return call. Command execution will be succeeded with the `config` payload.
  return config
end

ctx.log

-- @param text string
-- @param severity string
function ctx.log(text, severity)
end

Sends command log entry to Enapter Cloud.

Use severity argument to distinguish log entry between debug, info, warning, error. Default severity is info.

Command logs are always persisted and can be retrieved after the command execution.

Example

ctx.log("Cannot write configuration option: "..code, "warning")

ctx.error

-- @param text string
function ctx.error(text)
end

Sends command execution error to Enapter Cloud.

Calling ctx.error terminates handler function execution and fails the command.

Example

ctx.error("Cannot write configuration: "..error_code)

Connection Status

enapter.on_connection_status_changed

-- @param handler function
function enapter.on_connection_status_changed(status_hadler)
end

-- @param status boolean New status: `true` if connected, `false` if disconnected.
function status_hadler(status)
end

Registers function that will be called if the connection state to Enapter EMS Server changed.

This is useful for connectivity-critical scenarios when the UCM must perform some logic when the connection fails, for example, when a connected device must stop operation if external monitoring is not available.

handler function must receive one parameter status, the values are:

• true if UCM got connected,
• false if UCM got disconnected.

Example

function connection_status_handler(status)
  if status then
    ensure_device_operational()
  else
    gracefully_stop_device_operation()
  end
end

enapter.on_connection_status_changed(connection_status_handler)

enapter.get_connection_status

-- @return boolean
function enapter.get_connection_status()
end

Function for check current connection status. Returns true if connected, and false if disconnected.