Enapter Cloud

enapter library implements an interface to Enapter Cloud.

Sending Data

enapter.send_properties

-- @param data table
-- @return number
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 0 if data was sent successfully, otherwise returns error code (use enapter.err_to_str to convert it to string representation).

Example

function send_properties()
  local result = enapter.send_properties({ serial_num = read_serial_num() })
  if result ~= 0 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 Cloud
scheduler.add(30000, send_properties)

enapter.send_telemetry

-- @param data table
-- @return number
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 0 if data was sent successfully, otherwise returns error code (use enapter.err_to_str to convert it to string representation).

Example

function send_telemetry()
  local result = enapter.send_telemetry({ temperature = read_temperature() })
  if result ~= 0 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.

Log entries are not persisted in Enapter Cloud by default, so you can only see these logs in real-time in Enapter CLI using enapter devices logs or in Enapter Web IDE.

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. The number of log entries stored per one UCM is limited, so it's better to store only important ones.

Examples

enapter.log("Modbus connection established")

enapter.log("CAN data frame received: " .. table.concat(bytes), "debug")

local temperature = read_temperature()
if not temperature then
  enapter.log("Temperature sensor is not connected, returned value: " .. tostring(temperature), "warning")
end

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("Configuration updated successfully, " .. tostring(number) .. " bytes written.")

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(handler)
end

Registers function that will be called if the connection state to Enapter Cloud or Enapter Gateway (depends on your setup) 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

-- @param status boolean New status: `true` if connected, `false` if disconnected.
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.

enapter.err_to_str

-- @param error number
-- @return string
function enapter.err_to_str(error)
end

Returns string representation of enapter function return code.