feat(generics): support can

Author: kulti

README.md

@@ -69,3 +69,63 @@ power_relay:open() -- open contact
 power_relay:close() -- close contact
 local power_is_on = power_relay:is_closed() -- check contact status
 ```
+
+### CAN
+
+```lua
+local can_pkg = require('enapter.ucm.generics.can')
+
+local can = can_pkg.new() -- creates a new instance of client to generic CAN UCM
+local err = can:setup('AABBCC', subscriptions) -- setup to operate with UCM with hardware id AABBCC (about subscriptions see below)
+local payload, err = can:get('telemetry') -- get can messages for 'my_subscription' messages
+```
+
+#### CAN Subscriptions
+Subscriptions is a table:
+  - key is a name of subscritption
+  - value is an array of talbes describig CAN messages parsing rules
+
+The parsing rule contains:
+  - `name` or `names` of parsed values (one CAN message can contain more then one value).
+  - CAN message ID `msg_id`.
+  - `parser` function which received CAN message and return parsed value(s).
+  - `multi_msg` flag if parser function receives array of message.
+
+```lua
+subscriptoins = {
+  example = {
+    { name = 'fw_ver', msg_id = 0x318, parser = software_version },
+    {
+      name = 'dump_0x400',
+      msg_id = 0x400,
+      multi_msg = true,
+      parser = dump_0x400,
+    },
+  }
+}
+
+function dump_0x400(datas)
+  local str_0x400 = nil
+  for _, data in pairs(datas) do
+    str_0x400 = str_0x400 or ''
+    str_0x400 = str_0x400 .. ' ' .. data
+  end
+  return str_0x400
+end
+
+function software_version(data)
+  data = convert_input_data(data)
+  return string.format('%u.%u.%u', string.byte(data, 1), string.byte(data, 2), string.byte(data, 3))
+end
+
+--- Converts message from Generic CAN to bytes
+-- Generic CAN passes message as a 16-char string where every 2 char represent a byte in hex format.
+function convert_input_data(data)
+  local v = { string.unpack('c2c2c2c2c2c2c2c2', data) }
+  local vv = {}
+  for j = 1, 8 do
+    vv[j] = tonumber(v[j], 16)
+  end
+  return string.pack('BBBBBBBB', table.unpack(vv))
+end
+```

spec/generic_can_spec.lua

@@ -0,0 +1,167 @@
+local stubs = require('enapter.ucm.stubs')
+
+_G.inspect = require('inspect')
+
+describe('generic can', function()
+  local can, ucm_stubs, cursor
+
+  local function prepare_peer_stub()
+    local peer_stub = stubs.new_dummy_ucm_peer()
+    ucm_stubs.stubs = { peer_stub }
+    peer_stub.execute_command = function() return 'completed', { cursor = cursor } end
+    return peer_stub
+  end
+
+  before_each(function()
+    ucm_stubs = stubs.setup_enapter_ucm()
+
+    package.loaded['enapter.ucm.generics.can'] = false
+    can = require('enapter.ucm.generics.can').new()
+    can:setup('test_ucm_id', {})
+  end)
+
+  after_each(function()
+    stubs.teardown_generic_can()
+    stubs.teardown_enapter_ucm()
+  end)
+
+  it('shoud execute read command when setup', function()
+    local messages = {
+      { msg_id = 0x123 },
+      { msg_id = 0x789 },
+    }
+    local timeout = math.random(5000)
+
+    local peer_stub = prepare_peer_stub()
+    local s = spy.on(peer_stub, 'execute_command')
+    assert.is_nil(can:setup('', { test_cmd = messages }, timeout))
+    assert.spy(s).was_called(1)
+    assert
+      .spy(s)
+      .was_called_with(peer_stub, 'read', match.same({ msg_ids = { 0x123, 0x789 } }), { timeout = timeout })
+  end)
+
+  it('should store cursor', function()
+    cursor = math.random(100)
+    assert.is_nil(can:setup('', { test_cur = {} }))
+
+    local peer_stub = prepare_peer_stub()
+
+    local s = spy.on(peer_stub, 'execute_command')
+    local _, err = can:get('test_cur')
+    assert.is_nil(err)
+    assert.spy(s).was_called(1)
+    assert
+      .spy(s)
+      .was_called_with(peer_stub, 'read', match.same({ msg_ids = {} }), { timeout = 1000 })
+
+    peer_stub = prepare_peer_stub()
+    local s2 = spy.on(peer_stub, 'execute_command')
+    _, err = can:get('test_cur')
+    assert.is_nil(err)
+    assert.spy(s2).was_called(1)
+    assert
+      .spy(s2)
+      .was_called_with(peer_stub, 'read', match.same({ cursor = cursor, msg_ids = {} }), { timeout = 1000 })
+  end)
+
+  it('should not get for unknow subscription', function()
+    local _, err = can:get('unknown')
+    assert.is.equals("subscritpion with name 'unknown' is not exists", err)
+  end)
+
+  it('should handle error from generic can io', function()
+    assert.is_nil(can:setup('', { test_can_error = {} }))
+
+    local peer_stub = prepare_peer_stub()
+    peer_stub.execute_command = function() return 'completed', nil, 'can error' end
+
+    local _, err = can:get('test_can_error')
+    assert.is.equals('command failed: can error', err)
+  end)
+
+  it('should handle non-completed state from generic can io', function()
+    assert.is_nil(can:setup('', { test_non_completed = {} }))
+
+    local peer_stub = prepare_peer_stub()
+    peer_stub.execute_command = function() return 'non-completed', { errmsg = 'error msg' } end
+
+    local _, err = can:get('test_non_completed')
+    assert.is.equals('command failed: non-completed: {errmsg = "error msg"}', err)
+  end)
+
+  it('should get with name and names', function()
+    local messages = {
+      {
+        name = 't_name',
+        msg_id = 0x318,
+        parser = function() return 'test name' end,
+      },
+      {
+        names = { 'n_1', 'n_2' },
+        msg_id = 0x418,
+        parser = function() return { 1, 2 } end,
+      },
+    }
+
+    assert.is_nil(can:setup('', { test_names = messages }))
+
+    local peer_stub = prepare_peer_stub()
+    peer_stub.execute_command = function() return 'completed', { results = { { 'r1' }, { 'r2' } } } end
+
+    local ret, err = can:get('test_names')
+    assert.is_nil(err)
+
+    assert.is_same({ t_name = 'test name', n_1 = 1, n_2 = 2 }, ret)
+  end)
+
+  it('should differ pass data to multi_msg', function()
+    local test_data = { 'r1', 'r2' }
+    local messages = {
+      {
+        name = 't_multi',
+        msg_id = 0x318,
+        multi_msg = true,
+        parser = function(datas) return datas[1] .. datas[2] end,
+      },
+      {
+        name = 't_single',
+        msg_id = 0x418,
+        parser = function(data) return data end,
+      },
+    }
+
+    assert.is_nil(can:setup('', { test_multi = messages }))
+
+    local peer_stub = prepare_peer_stub()
+    peer_stub.execute_command = function()
+      return 'completed', { results = { test_data, test_data } }
+    end
+
+    local ret, err = can:get('test_multi')
+    assert.is_nil(err)
+
+    assert.is_same({ t_multi = 'r1r2', t_single = 'r2' }, ret)
+  end)
+
+  it('should handle errors from parser function', function()
+    local messages = {
+      {
+        name = 'fail',
+        msg_id = 0x404,
+        parser = function() error('not found') end,
+      },
+    }
+
+    assert.is_nil(can:setup('', { test_names = messages }))
+
+    local peer_stub = prepare_peer_stub()
+    peer_stub.execute_command = function() return 'completed', { results = { { 'any data' } } } end
+
+    local _, err = can:get('test_names')
+    assert.is_equals(
+      'data processing failed [msg_id=0x404 data={97 110 121 32 100 97 116 97 }]: <place>: not found',
+      err:gsub('spec/generic_can_spec.lua:%d+', '<place>')
+    )
+  end)
+end)

src/enapter/ucm/generics/can.lua

@@ -0,0 +1,92 @@
+local GENERAL_IO_CHANNEL = 'gio'
+local UCM_COMMAND_DEFAULT_TIMEOUT_MS = 1000
+
+local function extract_msg_ids(messages)
+  local msg_ids = {}
+  for _, msg in ipairs(messages) do
+    if msg.msg_id then table.insert(msg_ids, msg.msg_id) end
+  end
+  return msg_ids
+end
+
+local can_read = function(self, name)
+  local sub = self.subscriptions[name]
+  if not sub then return nil, nil, "subscritpion with name '" .. name .. "' is not exists" end
+
+  local peer = ucm.new(self.ucm_id, GENERAL_IO_CHANNEL)
+  local state, payload, err = peer:execute_command(
+    'read',
+    { cursor = sub.cursor, msg_ids = extract_msg_ids(sub.messages) },
+    { timeout = self.timeout }
+  )
+
+  if err then return nil, nil, 'command failed: ' .. err end
+
+  if state ~= 'completed' then
+    local payload_str = inspect(payload, { newline = '', indent = '' })
+    return nil, nil, 'command failed: ' .. tostring(state) .. ': ' .. payload_str
+  end
+
+  return sub, payload, nil
+end
+
+return {
+  new = function()
+    local can = { subscriptions = {} }
+
+    function can:setup(ucm_id, subscriptions, timeout)
+      self.ucm_id = ucm_id
+      self.timeout = timeout or UCM_COMMAND_DEFAULT_TIMEOUT_MS
+      self.subscriptions = {}
+
+      local sub_err
+      for name, messages in pairs(subscriptions) do
+        self.subscriptions[name] = { messages = messages }
+        local _, _, err = can_read(self, name)
+        sub_err = sub_err or err
+      end
+
+      return sub_err
+    end
+
+    function can:get(name)
+      local sub, payload, err = can_read(self, name)
+      if err then return nil, err end
+
+      sub.cursor = payload.cursor
+
+      local ret = {}
+      for i, h in ipairs(sub.messages) do
+        local data = payload.results[i]
+        if #data > 0 then
+          if not h.multi_msg then data = data[#data] end
+
+          local rr
+          local ok, err = pcall(function() rr = h.parser(data) end)
+          if not ok then
+            local data_arr = data:gsub('.', function(c) return string.byte(c) .. ' ' end)
+            return nil,
+              'data processing failed [msg_id='
+                .. string.format('0x%x', h.msg_id)
+                .. ' data={'
+                .. data_arr
+                .. '}]: '
+                .. err
+          end
+
+          if h.name ~= nil then
+            ret[h.name] = rr
+          else
+            for j, k in ipairs(h.names) do
+              ret[k] = rr[j]
+            end
+          end
+        end
+      end
+
+      return ret, nil
+    end
+
+    return can
+  end,
+}

src/enapter/ucm/stubs/generics_can.lua

@@ -0,0 +1,28 @@
+local function new_dummy_can()
+  return {
+    setup = function() end,
+    get = function() return {} end,
+  }
+end
+
+local function setup_generic_can()
+  local stub = { stubs = {} }
+  package.loaded['enapter.ucm.generics.can'] = false
+  package.preload['enapter.ucm.generics.can'] = function()
+    return {
+      new = function() return table.remove(stub.stubs, 1) or new_dummy_can() end,
+    }
+  end
+  return stub
+end
+
+local function teardown_generic_can()
+  package.loaded['enapter.ucm.generics.can'] = false
+  package.preload['enapter.ucm.generics.can'] = nil
+end
+
+return {
+  new_dummy_can = new_dummy_can,
+  setup_generic_can = setup_generic_can,
+  teardown_generic_can = teardown_generic_can,
+}

src/enapter/ucm/stubs/init.lua

@@ -3,6 +3,7 @@ local t = {}
 for _, pkg in ipairs({
   'enapter.ucm.stubs.enapter_ucm',
   'enapter.ucm.stubs.generics_rl6',
+  'enapter.ucm.stubs.generics_can',
 }) do
   for k, v in pairs(require(pkg)) do
     t[k] = v