Skip to main content

Devices

enapter.device

-- @param id string
-- @return table, error
function enapter.device(id)
end

Finds device by the given ID. Returns device object referred as device below.

Example

local device, err = enapter.device("AABB")
if not device then
enapter.log("Device not found: "..err)
end

device Object

id

device.id holds the same string ID as was used to find the device using enapter.device function.

Example

local device, err = enapter.device("AABB")
if device then
local id = device.id
enapter.log("Device is found, ID="..id)
end

properties

device.properties holds a Lua table with the latest values of device properties defined in the device manifest.yml.

Example

local device, err = enapter.device("AABB")
if device then
local model = device.properties.model
enapter.log("device model="..model)
end

telemetry.now

-- @param id string telemetry attribute name
-- @return string|number, error
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.

Example

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

telemetry.avg

-- @param id string telemetry attribute name
-- @param interval string averaging interval
-- @return number, error
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. If the device is offline or is not transmitting this telemetry attribute value, then the function returns nil.

Interval must be provided in a Xu format, where X is an integer value and u is a string unit identifier. For example, 1m is 1 minute, 15s is 15 seconds, 2h is two hours. Supported units are:

  • s for seconds,
  • m for minutes,
  • h for hours.

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

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 "..avg_volt.."V")
else
enapter.log("cannot read device voltage, device may be offline: "..err)
end
end

commands.execute

-- @param id string telemetry attribute name
-- @param args table command arguments
-- @return error
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.

Command execution does not wait for device response, but rather gets scheduled for the execution right after the function call. This means that the command may fail on the target device, but the rule will not know that it failed. To work around this limitation one should design the logic the way that device telemetry will be used as an indication of the command success.

Examples

local device, err = enapter.device("AABB")
if device then
-- Execute command with arguments
device.commands.execute("set_production_rate", { rate = 100 })
end
-- Simple rule which cycles relay
local device, err = enapter.device("AABB")
if device then
local status, err = device.telemetry.now("relay_status")
if status == "opened" then
device.commands.execute("close_relay")
elseif status == "closed" then
device.commands.execute("open_relay")
end
end
Hardware diversity is welcome. Integrate any device into a unified energy network.
© 2022 Enapter
Developer toolkit
DocumentationReference