-- require libmgmt_protocol
local libmgmt_protocol = require 'libmgmt_protocol'

-- Each component defines the access protocol configuration file for the hardware to which it belongs.
local config_obj = require 'path.to.config.obj'

-- Create an accessible object based on the file
-- An exception will be thrown if the configuration is incorrect.
local obj = libmgmt_protocol.device_spec_parser(config_obj)

-- Obtain the hardware property value based on the specific value in the configuration file.
-- For on_demand_property, call :value() to obtain the specific value.
-- If the property does not exist or the property value cannot be obtained, :value() returns nil.
-- The input parameter serves as a supplement to the configuration request data. If a conflict occurs, it will not override the request data in the configuration.
local on_demand_property = obj:OnDemandProperty({data = 'some data'}):value()

-- For on_schedule_property, a scheduler object is returned.
-- No data needs to be input if the input parameter remains unchanged.
local on_schedule_property_scheduler = obj:OnScheduleProperty()
-- scheduler does not start automatically. You need to manually call :start() to start it, at which point it will return the data obtained for the first time.
local on_schedule_property = on_schedule_property_scheduler:start()
-- scheduler supports listening to data change signals. When the obtained data is different from the data cached by scheduler, scheduler sends
-- the on_data_change signal with the new data.
on_schedule_property_scheduler.on_data_change:on(function(data)
  print('new data received!')
end)
-- scheduler supports listening to error signals. When data fails to be obtained (nil) during each polling, the on_error signal is sent.
on_schedule_property_scheduler.on_error:on(function()
  error('unable to read data from hardware!')
end)
-- scheduler supports changing input parameters. After the corresponding function is called, the new parameters are used in the next polling.
on_schedule_property_scheduler:update_params({
  name = 'another_property_name', --: New property name
  protocol ='new protocol', --: New protocol name (Currently, protocols that have not been used cannot be loaded.)
  request = {...}, -- Input parameters required by the protocol
})
-- scheduler supports changing the polling period. After the corresponding function is called, the new parameter is used in the next polling.
on_schedule_property_scheduler:set_period(10) -- Poll data every 10 seconds.

-- scheduler keeps accessing data based on the configured polling period. To stop the polling, you need to call :deconstruct().
on_schedule_property_scheduler:deconstruct()

--For a non-existent property, calling any function of the scheduler takes no effect. This is used when you are unsure whether a property exists.
local not_exist_property = obj:NotExistProperty()
not_exist_property:start()                    -- no op
not_exist_property.on_data_change:on(function()
  assert ('never reach here')                  -- This line should never be reached.
end)
not_exist_property.on_error:on(function()
  assert ('never reach here')                  -- This line should never be reached
end)
not_exist_property:deconstruct()              -- no op

local a_network_adapter = {
  protocol_dependencies = {
    smbus = {           -- The ref_chip object must be input for all I2C protocols.
      ref_chip = nil,   -- The hardware is accessed through the hwproxy.
      buffer_len = 64,  -- Maximum number of bytes supported by the protocol
    },
    ncsi_huawei = {     -- The endpoint object needs to be input for all MCTP protocols.
      endpoint = nil    -- The hardware is accessed through the mctpd.
    }
  },
  properties = {
    ...
  }
}

return a_network_adapter

properties = {
  ChipTemp = {        -- Property name, also the property access interface, e.g. obj:ChipTemp ()
    protocol = 'smbus',   -- Protocol name, which must be a supported protocol.
    action = 'on_schedule',   -- Single access or polling access
    period_in_sec = 2,      -- Period of polling access, in seconds.
    request = {             -- Request data required by the protocol. The specific format is checked by each protocol.
      opcode = 0x3,         -- opcode required by the SMBus protocol
      expect_data_len = 2   -- Return data length required by the SMBus protocol
    },
    response = function(data) -- Parsing function for the return data. It removes the protocol header, leaving only the actual business data.
      -- This function is called only when the hardware returns a response normally. It is not called when an error occurs.
      local r = bs.new([[<<temp:16>>]]):unpack(data, true) -- Support for unpacking binary data using bitstring
      return r.temp -- Return value of obj:ChipTemp ()
    end
  },
  MacAddressNCSI = {
    protocol = 'ncsi_huawei',
    action = 'on_demand',       -- Single access, which does not require period_in_sec.
    request = {
      huawei_cmd_id = 0x1,
      sub_cmd_id = 0x0
    },
    response = function(data)
      local r = bs.new([[<<
        _:8,
        mac_address_count:16/big,
        _:16,                     # libmgmt_protocol provides some common bitstring formats, for example, MAC_Address.
        mac_addrs:8/MAC_ADDRESS    
      >>]], libmgmt_protocol.common_bs_helper):unpack(data, true) -- Directly pass the corresponding input parameter when creating bs.
      return r.mac_addrs[1].mac_address
    end
  }
}

-- @function Constructor
-- @param    request:table
function protocol:ctor(params)
  -- params: protocol_dependencies in the protocol configuration file, which is defined by the component using the protocol.
  -- For example, endpoint needs to be input for the MCTP protocol, and ref_chip and buffer_len need to be input for the SMBus protocol.
  --   
end

-- @function Transmission request function
-- @param    request:table
-- @return   binary|boolean|nil
function protocol:send_request(request)
  -- request: request struct of each property in the protocol configuration file, containing the variables at runtime and the static configurations.
  -- The specific data of the response body is returned. If the response parsing function is configured in the configuration file, the input parameter of the response parsing function is returned.
  -- If the request fails, nil is returned.
  -- If the response parsing function does not need to be called, true is returned, indicating that the request is sent successfully.
end

-- @function Transmission request function
-- @param    request:table
-- @return   binary
function protocol:validate_request_params(request)
  -- request: request struct of each property in the protocol configuration file.
  -- It will be called once for parsing the configuration file. The input parameter is the static data in the configuration file.
  -- It will be called once again at runtime. The input parameter is the dynamic data passed in at runtime. If the value is nil, the function will not be called.
  -- The transmission can proceed only when true is returned. If false is returned, the transmission will not be performed.
end

-- The ncsi_standard assembling function  assembles only the part of the standard NC-SI protocol.
function ncsi_standard:construct_request_data(ctx, request)
  return req_ctx, req_bin
end

-- The ncsi_standard parsing function parses only the part of the standard NC-SI protocol.
function ncsi_standard:unpack_response_data(ctx, rsp_data_bin)
  return ...  
end

-- Split protocol assembling and unpacking into independent functions.
function ncsi_standard:send_request(request)
  local req_ctx, req_bin = self:construct_request_data(ctx, request)
  local ok, rsp_data_bin = pcall(self.endpoint.Request, self.endpoint, req_ctx, req_bin, 0)
  return self:unpack_response_data(ctx, rsp_data_bin)
end

local ncsi_huawei = class(ncsi_standard)

-- ncsi_huawei overrides the base encapsulation function to add its own implementation, and then calls the base encapsulation function.
function ncsi_huawei::construct_request_data(ctx, request)
  local request_with_ncsi_huawei_info = ...
  return ncsi_huawei.super.construct_request_data(ctx, request_with_ncsi_huawei_info)
end

-- ncsi_huawei overrides the base parsing function to return its own parsed data instead of using the base implementation.
function ncsi_standard:unpack_response_data(ctx, rsp_data_bin)
  return data
end

-- std_smbus uses the WriteRead function of hwproxy for hardware access.
function std_smbus:send_and_receive(data, len)
  return pcall(function()
    return self.ref_chip:WriteRead(ctx:new(), data, len)
  end)
end

-- Split hardware access into an independent function.
function std_smbus:send_request(request)
  ...
  local ok, rsp_bin = self:send_and_receive(data, len)
  ...
end

local smbus_5902 = class(std_smbus)

-- smbus_5902 requires checking whether the hardware can be accessed before transmission. Therefore, Write and Read must be sent separately.
-- You can add the required steps by overriding the base hardware access function.
function smbus_5902:send_and_receive(data, len)
  if self:check_idle() then
    self:send(data)
    if self:check_idle() then
      return self:receive(len)
    end
  end
end

-- std_smbus can accept the arg and data parameters.
local request_params_template<const> = {
  opcode = true,
  expect_data_len = true,
  arg = true,
  data = true
}

-- Store request_params_template when constructing the function.
function std_smbus:ctor()
  self.request_params_template = request_params_template
end

-- Separate out request_params_template.
function std_smbus:validate_request_params(request)
  for key in pairs(req) do
    if not self.request_params_template[key] then
      return false
    end
  end
  return true
end

local smbus = class(std_smbus)

local request_params_template<const> = {
  opcode = true,
  expect_data_len = true
}

-- Because of class inheritance, request_params_template will be replaced.
-- The local request_params_template will be used in validate_request_params.
function smbus:ctor()
  self.request_params_template = request_params_template
end