Skip to main content

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 that reference names 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()
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
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 that reference names 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()
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
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")
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.

There are three options to return from the handler function;

  • 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 param 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.

Hardware diversity is welcome. Integrate any device into a unified energy network.
© 2021 Enapter
Developer toolkit
DocumentationReference
Community
GithubTindie