Devices

enapter.devices

note

This function is available since Gateway version 2.1.1.

-- @return table, error
function enapter.devices()
end

Returns a list of devices that are available on a Gateway. Each object in the list is a device object described below.

Example

local devices = enapter.devices()

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

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 string ID.

• For enapter.devices it equals to device ID.
• For enapter.device it is the same as was used to find the device.

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 name 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 name 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 duration format.

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

telemetry.last

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

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

commands.execute

-- @param name string command 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

Duration Format

Duration 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.