feat(generics): support rl6

Author: kulti

Diff for: .luacheckrc

@@ -2,37 +2,53 @@
 
 -- Enapter Rule Engine API
 local enapter_api = {
+  'inspect',
   enapter = {
-    fields = {'log', 'device', 'register_command_handler'}
+    fields = { 'log', 'device', 'register_command_handler' },
+  },
+  ucm = {
+    fields = { 'new' },
   },
   storage = {
     fields = {
-      'read', 'write', 'remove', 'err_to_str',
-      'enable_error_mode', 'disable_error_mode',
-    }
+      'read',
+      'write',
+      'remove',
+      'err_to_str',
+      'enable_error_mode',
+      'disable_error_mode',
+    },
   },
   modbustcp = {
     fields = {
-      'new'
-    }
+      'new',
+    },
   },
   modbus = {
     fields = {
-      'read_coils', 'read_discrete_inputs', 'read_holdings', 'read_inputs',
-      'write_coil', 'write_holding', 'write_multiple_coils', 'write_multiple_holdings',
+      'read_coils',
+      'read_discrete_inputs',
+      'read_holdings',
+      'read_inputs',
+      'write_coil',
+      'write_holding',
+      'write_multiple_coils',
+      'write_multiple_holdings',
       'err_to_str',
-    }
-  }
+    },
+  },
 }
 
 stds.enapter = {
-  read_globals = enapter_api
+  read_globals = enapter_api,
 }
 
 std = 'lua53+enapter'
 
 ignore = {
   '212/self', -- allow unused `self`
-  '411/ok', '411/error', '411/err', -- allow to re-define some variables
+  '411/ok',
+  '411/error',
+  '411/err', -- allow to re-define some variables
   '421/err', -- allow to shadow some variables
 }

Diff for: README.md

@@ -52,3 +52,20 @@ config.init({
 ```
 
 After that commands to read/write config are registered and values can be get in Lua code via `config.read` and `config.read_all` methods.
+
+
+## Generics
+
+`enapter.ucm.generics` provides helpers to communicate with [Enapter Generic-IO](https://marketplace.enapter.com/blueprints/generic_io).
+
+### RL6
+
+```lua
+local rl6 = require('enapter.ucm.generics.rl6')
+
+local power_relay = rl6.new() -- creates a new instance of relay contact
+power_relay:setup('AABBCC', 5) -- setup to operate on contact 5 of generic RL-6 UCM with hardware id AABBCC
+power_relay:open() -- open contact
+power_relay:close() -- close contact
+local power_is_on = power_relay:is_closed() -- check contact status
+```

Diff for: spec/generic_rl6_spec.lua

@@ -0,0 +1,98 @@
+_G.inspect = require('inspect')
+local stubs = require('enapter.ucm.stubs')
+
+describe('generic rl6', function()
+  local rl6, peer_stub
+
+  before_each(function()
+    local ucm_stubs = stubs.setup_enapter_ucm()
+    peer_stub = stubs.new_dummy_ucm_peer()
+    ucm_stubs.stubs = { peer_stub }
+
+    package.loaded['enapter.ucm.generics.rl6'] = false
+    rl6 = require('enapter.ucm.generics.rl6').new()
+  end)
+
+  after_each(function()
+    stubs.teardown_generic_rl6()
+    stubs.teardown_enapter_ucm()
+  end)
+
+  it('should open', function()
+    rl6:setup('test_open_id', 57, 123)
+
+    local s = spy.on(peer_stub, 'execute_command')
+    assert.is_nil(rl6:open())
+    assert.spy(s).was_called(1)
+    assert.spy(s).was_called_with(peer_stub, 'open_channel', { channel = 57 }, { timeout = 123 })
+  end)
+
+  it('should close', function()
+    rl6:setup('test_close_id', 31)
+
+    local s = spy.on(peer_stub, 'execute_command')
+    assert.is_nil(rl6:close())
+    assert.spy(s).was_called(1)
+    assert.spy(s).was_called_with(peer_stub, 'close_channel', { channel = 31 }, { timeout = 1000 })
+  end)
+
+  it('should report state', function()
+    rl6:setup('test_state_id', 25)
+
+    peer_stub.execute_command = function() return 'completed', { closed = true } end
+    local closed, err = rl6:is_closed()
+    assert.is_nil(err)
+    assert.is_true(closed)
+  end)
+
+  it('should return error if state is missed', function()
+    rl6:setup('test_err_id', 25)
+
+    peer_stub.execute_command = function() return 'completed', { is_closed = true } end
+    local _, err = rl6:is_closed()
+    assert.is_same('unexpected response from io: {is_closed = true}', err)
+  end)
+
+  it('should return error if state is not boolean', function()
+    rl6:setup('test_err_id', 25)
+
+    peer_stub.execute_command = function() return 'completed', { closed = 'yes' } end
+    local _, err = rl6:is_closed()
+    assert.is_same('unexpected response from io: {closed = "yes"}', err)
+  end)
+
+  it('should return execution error (open)', function()
+    rl6:setup()
+    peer_stub.execute_command = function() return nil, nil, 'test exec err' end
+    assert.is_same('test exec err', rl6:open())
+  end)
+
+  it('should return execution error (close)', function()
+    rl6:setup()
+    peer_stub.execute_command = function() return nil, nil, 'test exec err' end
+    assert.is_same('test exec err', rl6:close())
+  end)
+
+  it('should return non-completed error (open)', function()
+    rl6:setup()
+    peer_stub.execute_command = function()
+      return 'non-completed', { errcode = 117, errmsg = 'test open error' }, nil
+    end
+    assert.is_same(
+      'relay module command failed: non-completed: {errcode = 117,errmsg = "test open error"}',
+      rl6:open()
+    )
+  end)
+
+  it('should return non-completed error', function()
+    rl6:setup()
+
+    peer_stub.execute_command = function()
+      return 'non-completed', { errcode = 428, errmsg = 'test close error' }, nil
+    end
+    assert.is_same(
+      'relay module command failed: non-completed: {errcode = 428,errmsg = "test close error"}',
+      rl6:close()
+    )
+  end)
+end)

Diff for: src/enapter/ucm/generics/rl6.lua

@@ -0,0 +1,55 @@
+local GENERAL_IO_CHANNEL = 'gio'
+local UCM_COMMAND_DEFAULT_TIMEOUT_MS = 1000
+
+local function do_cmd(self, cmd_name)
+  local peer = ucm.new(self.ucm_id, GENERAL_IO_CHANNEL)
+  local state, payload, err = peer:execute_command(
+    cmd_name,
+    { channel = self.channel_id },
+    { timeout = self.timeout }
+  )
+  if err then return nil, err end
+  if state ~= 'completed' then
+    return nil,
+      'relay module command failed: ' .. state .. ': ' .. inspect(
+        payload,
+        { newline = '', indent = '' }
+      )
+  end
+
+  return payload
+end
+
+return {
+  new = function()
+    local rl6 = {}
+
+    function rl6:setup(ucm_id, channel_id, timeout)
+      self.ucm_id = ucm_id
+      self.channel_id = math.tointeger(channel_id)
+      self.timeout = timeout or UCM_COMMAND_DEFAULT_TIMEOUT_MS
+    end
+
+    function rl6:open()
+      local _, err = do_cmd(self, 'open_channel')
+      return err
+    end
+
+    function rl6:close()
+      local _, err = do_cmd(self, 'close_channel')
+      return err
+    end
+
+    function rl6:is_closed()
+      local payload, err = do_cmd(self, 'is_channel_closed')
+      if err then return nil, err end
+      if payload.closed == nil or type(payload.closed) ~= 'boolean' then
+        return nil,
+          'unexpected response from io: ' .. inspect(payload, { newline = '', indent = '' })
+      end
+      return payload.closed
+    end
+
+    return rl6
+  end,
+}

Diff for: src/enapter/ucm/stubs/enapter_ucm.lua

@@ -0,0 +1,21 @@
+local function new_dummy_ucm_peer()
+  return {
+    execute_command = function() return 'completed', {} end,
+  }
+end
+
+local function setup_enapter_ucm()
+  local stub = { stubs = {} }
+  _G.ucm = {
+    new = function() return table.remove(stub.stubs, 1) or new_dummy_ucm_peer() end,
+  }
+  return stub
+end
+
+local function teardown_enapter_ucm() _G.ucm = nil end
+
+return {
+  new_dummy_ucm_peer = new_dummy_ucm_peer,
+  setup_enapter_ucm = setup_enapter_ucm,
+  teardown_enapter_ucm = teardown_enapter_ucm,
+}

Diff for: src/enapter/ucm/stubs/generics_rl6.lua

@@ -0,0 +1,28 @@
+local function new_dummy_rl6()
+  return {
+    setup = function() end,
+    is_closed = function() return false end,
+  }
+end
+
+local function setup_generic_rl6()
+  local stub = { stubs = {} }
+  package.loaded['enapter.ucm.generics.rl6'] = false
+  package.preload['enapter.ucm.generics.rl6'] = function()
+    return {
+      new = function() return table.remove(stub.stubs, 1) or new_dummy_rl6() end,
+    }
+  end
+  return stub
+end
+
+local function teardown_generic_rl6()
+  package.loaded['enapter.ucm.generics.rl6'] = false
+  package.preload['enapter.ucm.generics.rl6'] = nil
+end
+
+return {
+  new_dummy_rl6 = new_dummy_rl6,
+  setup_generic_rl6 = setup_generic_rl6,
+  teardown_generic_rl6 = teardown_generic_rl6,
+}

Diff for: src/enapter/ucm/stubs/init.lua

@@ -0,0 +1,12 @@
+local t = {}
+
+for _, pkg in ipairs({
+  'enapter.ucm.stubs.enapter_ucm',
+  'enapter.ucm.stubs.generics_rl6',
+}) do
+  for k, v in pairs(require(pkg)) do
+    t[k] = v
+  end
+end
+
+return t