LuatOS/script/libs/exmodbus.lua

--[[
@module exmodbus
@summary exmodbus 控制Modbus RTU/ASCII/TCP主站/从站通信
@version 1.0
@date    2025.
@author  马梦阳
@usage
本文件的对外接口有 5 个：
1、exmodbus.create(config)：创建 modbus 主站/从站，支持 RTU、ASCII、TCP 三种通信模式
2、modbus:read(config)：主站向从站发起读取请求（仅适用于 RTU、ASCII、TCP 主站模式）
3、modbus:write(config)：主站向从站发起写入请求（仅适用于 RTU、ASCII、TCP 主站模式）
4、modbus:destroy()：销毁 modbus 主站/从站实例对象
5、modbus:on(callback)：从站注册回调接口，用于处理主站发起的请求（仅适用于 RTU、ASCII、TCP 从站模式）
]]
local exmodbus = {}

-- 定义通信模式常量
exmodbus.RTU_MASTER = 0   -- RTU 主站模式
exmodbus.RTU_SLAVE = 1    -- RTU 从站模式
exmodbus.ASCII_MASTER = 2 -- ASCII 主站模式
exmodbus.ASCII_SLAVE = 3  -- ASCII 从站模式
exmodbus.TCP_MASTER = 4   -- TCP 主站模式
exmodbus.TCP_SLAVE = 5    -- TCP 从站模式

-- 定义数据类型常量
exmodbus.COIL_STATUS = 0      -- 线圈状态
exmodbus.INPUT_STATUS = 1     -- 离散输入状态
exmodbus.HOLDING_REGISTER = 4 -- 保持寄存器
exmodbus.INPUT_REGISTER = 3   -- 输入寄存器

-- 定义操作类型常量
exmodbus.READ_COILS = 0x01                       -- 读线圈状态
exmodbus.READ_DISCRETE_INPUTS = 0x02             -- 读离散输入状态
exmodbus.READ_HOLDING_REGISTERS = 0x03           -- 读保持寄存器
exmodbus.READ_INPUT_REGISTERS = 0x04             -- 读输入寄存器
exmodbus.WRITE_SINGLE_COIL = 0x05                -- 写单个线圈状态
exmodbus.WRITE_SINGLE_HOLDING_REGISTER = 0x06    -- 写单个保持寄存器
exmodbus.WRITE_MULTIPLE_HOLDING_REGISTERS = 0x10 -- 写多个保持寄存器
exmodbus.WRITE_MULTIPLE_COILS = 0x0F             -- 写多个线圈状态

-- 定义响应结果常量
exmodbus.STATUS_SUCCESS = 0      -- 收到响应数据且数据有效
exmodbus.STATUS_DATA_INVALID = 1 -- 收到响应数据但数据损坏/校验失败
exmodbus.STATUS_EXCEPTION = 2    -- 收到标准异常响应码
exmodbus.STATUS_TIMEOUT = 3      -- 超时未收到响应

-- 异常响应码常量
exmodbus.ILLEGAL_FUNCTION = 0x01           -- 不支持请求的功能码
exmodbus.ILLEGAL_DATA_ADDRESS = 0x02       -- 请求的数据地址无效或超出范围
exmodbus.ILLEGAL_DATA_VALUE = 0x03         -- 请求的数据值无效
exmodbus.SLAVE_DEVICE_FAILURE = 0x04       -- 从站在执行操作时发生内部错误
exmodbus.ACKNOWLEDGE = 0x05                -- 请求已接受，但需要长时间处理
exmodbus.SLAVE_DEVICE_BUSY = 0x06          -- 从站正忙，无法处理请求
exmodbus.NEGATIVE_ACKNOWLEDGE = 0x07       -- 无法执行编程功能
exmodbus.MEMORY_PARITY_ERROR = 0x08        -- 内存奇偶校验错误
exmodbus.GATEWAY_PATH_UNAVAILABLE = 0x0A   -- 网关路径不可用
exmodbus.GATEWAY_TARGET_NO_RESPONSE = 0x0B -- 网关目标设备无响应

-- 全局队列与调度器；
local request_queue = {}
local next_request_id = 1
local scheduler_started = false

-- 生成唯一请求 ID；
local function gen_request_id()
    local id = next_request_id
    next_request_id = next_request_id + 1
    -- 确保请求 ID 在 32 位有符号整数范围内；
    if next_request_id == 0x7FFFFFFF then next_request_id = 1 end
    return id
end

-- 处理队列中的请求；
local function process_request_queue()
    while true do
        if #request_queue > 0 then
            local req = table.remove(request_queue, 1)
            local instance = req.instance
            local config = req.config
            local is_read = req.is_read
            local req_id = req.request_id

            local result
            if is_read then
                result = instance:read_internal(config)
            else
                result = instance:write_internal(config)
            end

            sys.publish("exmodbus/resp/" .. req_id, result)
        else
            sys.waitUntil("start_scheduler")
        end
    end
end

-- 启动调度器；
local function start_scheduler()
    if scheduler_started then return end
    scheduler_started = true
    sys.taskInit(process_request_queue)
end

-- 入队请求并等待响应；（内部使用）
function exmodbus.enqueue_request(instance, config, is_read)
    -- 生成唯一请求 ID；
    local req_id = gen_request_id()

    -- 检查队列是否为空；
    -- 如果为空，先入队，然后发布主题告知调度器开始处理；
    -- 如果不为空，则直接入队，不用告知调度器；
    if #request_queue == 0 then
        -- 入队请求；
        table.insert(request_queue, {
            instance = instance,
            config = config,
            is_read = is_read,
            request_id = req_id
        })

        sys.publish("start_scheduler")
    else
        -- 入队请求；
        table.insert(request_queue, {
            instance = instance,
            config = config,
            is_read = is_read,
            request_id = req_id
        })
    end

    -- 启动调度器；
    start_scheduler()
    local ok, result = sys.waitUntil("exmodbus/resp/" .. req_id)

    return result
end

--[[
创建一个新的实例；
@api exmodbus.create(config)
@param config table 配置参数表，包含以下字段：
    mode number 通信模式，必须是 exmodbus 模块定义的常量（如 exmodbus.RTU_MASTER）
    uart_id number 串口 ID，uart0 写 0，uart1 写 1，以此类推
    baud_rate number 波特率
    data_bits number 数据位
    stop_bits number 停止位
    parity_bits number 校验位
    byte_order number 字节顺序
    rs485_dir_gpio number RS485 方向转换 GPIO 引脚
    rs485_dir_rx_level number RS485 接收方向电平
    adapter number 网卡 ID
    ip_address string 服务器 IP 地址
    port number 服务器端口号
    is_udp boolean 是否使用 UDP 协议
    is_tls boolean 是否使用加密传输
    keep_idle number 连接空闲多长时间后，开始发送第一个 keepalive 探针报文，单位：秒
    keep_interval number 发送第一个探针后，如果没收到 ACK 回复，间隔多久再发送下一个探针，单位：秒
    keep_cnt number 总共发送多少次探针后，如果依然没有回复，则判断连接已断开
    server_cert string TCP 模式下的服务器 CA 证书数据，UDP 模式下的 PSK
    client_cert string TCP 模式下的客户端证书数据，UDP 模式下的 PSK-ID
    client_key string TCP 模式下的客户端私钥加密数据
    client_password string TCP 模式下的客户端私钥口令数据
@return table/nil 成功时返回实例对象，失败时返回 nil
@usage
RTU/ASCII 通信模式：
local config = {
    mode = exmodbus.RTU_MASTER, -- 通信模式：RTU 主站
    uart_id = 1,                -- 串口 ID：uart1
    baud_rate = 115200,         -- 波特率：115200
    data_bits = 8,              -- 数据位：8
    stop_bits = 1,              -- 停止位：1
    parity_bits = uart.None,    -- 校验位：无校验
    byte_order = uart.LSB,      -- 字节顺序：小端序
    rs485_dir_gpio = 23,        -- RS485 方向转换 GPIO 引脚
    rs485_dir_rx_level = 0      -- RS485 接收方向电平：0 为低电平，1 为高电平
}
local rtu_master = exmodbus.create(config)

TCP 通信模式：
local config = {
    mode = exmodbus.TCP_MASTER, -- 通信模式：TCP 主站
    adapter = socket.LWIP_ETH,  -- 网卡 ID：LwIP 协议栈的以太网卡
    ip_address = "192.168.1.100", -- 服务器 IP 地址：192.168.1.100（主站：服务器 IP；从站：本地 IP，从站可以不用填此参数）
    port = 502,                 -- 服务器端口号：502（主站：服务器端口；从站：本地端口）
    is_udp = false,             -- 是否使用 UDP 协议：不使用 UDP 协议，false/nil 表示使用 TCP 协议
    is_tls = false,             -- 是否使用加密传输：不使用加密传输，false/nil 表示不使用加密
    keep_idle = 300,            -- 连接空闲多长时间后，开始发送第一个 keepalive 探针报文：300 秒
    keep_interval = 10,         -- 发送第一个探针后，如果没收到 ACK 回复，间隔多久再发送下一个探针：10 秒
    keep_cnt = 3,               -- 总共发送多少次探针后，如果依然没有回复，则判断连接已断开：3 次
    server_cert = nil,          -- TCP 模式下的服务器 CA 证书数据，UDP 模式下的 PSK：如果客户端不需要验证服务器证书，则设为 nil 或空着
    client_cert = nil,          -- TCP 模式下的客户端证书数据，UDP 模式下的 PSK-ID：如果服务器不需要验证客户端证书，则设为 nil 或空着
    client_key = nil,           -- TCP 模式下的客户端私钥加密数据：如果服务器不需要验证客户端私钥，则设为 nil 或空着
    client_password = nil       -- TCP 模式下的客户端私钥口令数据：如果服务器不需要验证客户端私钥口令，则设为 nil 或空着
}
local tcp_master = exmodbus.create(config)
--]]
function exmodbus.create(config)
    -- 检查配置参数是否有效；
    if not config or type(config) ~= "table" then
        log.error("exmodbus", "配置必须是表格类型")
        return false
    end

    -- 根据通信模式加载对应的模块；
    if config.mode == exmodbus.RTU_MASTER or config.mode == exmodbus.RTU_SLAVE or
        config.mode == exmodbus.ASCII_MASTER or config.mode == exmodbus.ASCII_SLAVE then
        local result, mod = pcall(require, "exmodbus_rtu_ascii")
        if not result then
            log.error("exmodbus", "加载 RTU/ASCII 模块失败")
            return false
        end
        return mod.create(config, exmodbus, gen_request_id)
    elseif config.mode == exmodbus.TCP_MASTER or config.mode == exmodbus.TCP_SLAVE then
        local result, mod = pcall(require, "exmodbus_tcp")
        if not result then
            log.error("exmodbus", "加载 TCP 模块失败")
            return false
        end
        return mod.create(config, exmodbus, gen_request_id)
    else
        log.error("exmodbus", "通信模式不支持")
        return false
    end
end

--[[
主站向从站发送读取请求（仅适用于 RTU、ASCII、TCP 主站模式）
@api modbus:read(config)
@param config table 配置参数表，包含以下字段：
    slave_id number 从站 ID
    reg_type number 寄存器类型
    start_addr number 寄存器起始地址
    reg_count number 寄存器数量
    raw_request string 原始请求帧
    timeout number 超时时间，单位：毫秒
@return table 包含以下字段：
    status number 响应结果状态码，参考 exmodbus 模块定义的常量（如 exmodbus.STATUS_SUCCESS）
    execption_code number 异常码，仅在 status 为 exmodbus.STATUS_EXCEPTION 时有效
    data table 寄存器数值，仅在 status 为 exmodbus.STATUS_SUCCESS 时有效，包含以下字段
        [start_addr] number 寄存器数值，索引为寄存器地址，值为寄存器数值
        ...
    raw_response string 原始响应帧
@usage
用户在传入 config 参数时，有 原始帧 和 字段参数 两种方式
1. 原始帧方式
local read_config = {
    raw_request = "010300000002C40B", -- 原始请求帧：01 03 00 00 00 02 C4 0B（读取保持寄存器 0x0000 开始的 2 个寄存器）
    timeout = 1000                    -- 超时时间：1000 毫秒
}
local result = modbus:read(read_config)
if result.status == exmodbus.STATUS_SUCCESS then
    log.info("exmodbus_test", "读取成功，原始响应帧: ", table.concat(result.raw_response, ", "))
elseif result.status == exmodbus.STATUS_TIMEOUT then
    log.error("exmodbus_test", "读取请求超时")
else
    log.error("exmodbus_test", "读取失败")
end

2. 字段参数方式
local read_config = {
    slave_id = 1,                         -- 从站 ID：1
    reg_type = exmodbus.HOLDING_REGISTER, -- 寄存器类型：保持寄存器
    start_addr = 0x0000,                  -- 寄存器起始地址：0
    reg_count = 0x0002,                   -- 寄存器数量：2
    timeout = 1000                        -- 超时时间：1000 毫秒
}

local result = modbus:read(read_config)
-- 根据返回状态处理结果
if result.status == exmodbus.STATUS_SUCCESS then
    -- 数据解析：
    log.info("exmodbus_test", "成功读取到从站 1 保持寄存器 0-2 的值，寄存器 0 数值：", result.data[result.start_addr],
        "，寄存器 1 数值：", result.data[result.start_addr + 1])
elseif result.status == exmodbus.STATUS_DATA_INVALID then
    log.info("exmodbus_test", "收到从站 1 的响应数据但数据损坏/校验失败")
elseif result.status == exmodbus.STATUS_EXCEPTION then
    log.info("exmodbus_test", "收到从站 1 的 modbus 标准异常响应，异常码为", result.execption_code)
elseif result.status == exmodbus.STATUS_TIMEOUT then
    log.info("exmodbus_test", "未收到从站 1 的响应（超时）")
end
--]]
-- 该接口在各个子文件中，此处仅用作注释
-- function modbus:read(config) end


--[[
主站向从站发送写入请求（仅适用于 RTU、ASCII、TCP 主站模式）
@api modbus:write(config)
@param config table 配置参数表，包含以下字段：
    slave_id number 从站 ID
    reg_type number 寄存器类型
    start_addr number 寄存器起始地址
    reg_count number 寄存器数量
    data table 寄存器数值，包含以下字段：
        [start_addr] number 寄存器数值，索引为寄存器地址，值为寄存器数值
        ...
    force_multiple boolean 是否强制使用写多个功能码进行写入单个寄存器操作
    raw_request string 原始请求帧
    timeout number 超时时间，单位：毫秒
@return table 包含以下字段：
    status number 响应结果状态码，参考 exmodbus 模块定义的常量（如 exmodbus.STATUS_SUCCESS）
    execption_code number 异常码，仅在 status 为 exmodbus.STATUS_EXCEPTION 时有效
    raw_response string 原始响应帧
@usage
用户在传入 config 参数时，有 原始帧 和 字段参数 两种方式
1. 原始帧方式
local write_config = {
    raw_request = "011000000002007B01592471", -- 原始请求帧：01 10 00 00 00 02 00 7B 01 59 24 71（写入保持寄存器 0x0000 开始的 2 个寄存器，值为 0x007B 和 0x0159）
    timeout = 1000                            -- 超时时间：1000 毫秒
}
local result = modbus:write(write_config)
if result.status == exmodbus.STATUS_SUCCESS then
    log.info("exmodbus_test", "写入成功，原始响应帧: ", table.concat(result.raw_response, ", "))
elseif result.status == exmodbus.STATUS_TIMEOUT then
    log.error("exmodbus_test", "写入请求超时")
else
    log.error("exmodbus_test", "写入失败")
end

2. 字段参数方式
local write_config = {
    slave_id = 1,                         -- 从站 ID：1
    reg_type = exmodbus.HOLDING_REGISTER, -- 寄存器类型：保持寄存器
    start_addr = 0x0000,                  -- 寄存器起始地址：0
    reg_count = 0x0002,                   -- 寄存器数量：2
    data = {
        [0x0000] = 0x007B,                -- 寄存器 0 数值：0x007B
        [0x0001] = 0x0159,                -- 寄存器 1 数值：0x0159
    },
    timeout = 1000                        -- 超时时间：1000 毫秒
}

local result = modbus:write(write_config)
-- 根据返回状态处理结果
if result.status == exmodbus.STATUS_SUCCESS then
    log.info("exmodbus_test", "成功写入从站 1 保持寄存器 0-2 的值")
elseif result.status == exmodbus.STATUS_DATA_INVALID then
    log.info("exmodbus_test", "收到从站 1 的响应数据但数据损坏/校验失败")
elseif result.status == exmodbus.STATUS_EXCEPTION then
    log.info("exmodbus_test", "收到从站 1 的 modbus 标准异常响应，异常码为", result.execption_code)
elseif result.status == exmodbus.STATUS_TIMEOUT then
    log.info("exmodbus_test", "未收到从站 1 的响应（超时）")
end
--]]
-- 该接口在各个子文件中，此处仅用作注释
-- function modbus:write(config) end


--[[
销毁 modbus 主站/从站实例对象
@api modbus:destroy()
@return nil
@usage
modbus:destroy()
--]]
-- 该接口在各个子文件中，此处仅用作注释
-- function modbus:destroy() end


--[[
从站注册回调接口，用于处理主站发起的请求（仅适用于 RTU、ASCII、TCP 从站模式）
@api modbus:on(callback)
@param callback function 回调函数，格式为：
    function callback(request)
        -- 用户代码
    end
    该回调函数接收 requset 一个参数，该参数为 table 类型，包含以下字段：
        slave_id number 从站 ID
        func_code number 功能码
        reg_type number 寄存器类型
        start_addr number 寄存器起始地址
        reg_count number 寄存器数量
        data table 寄存器数值，包含以下字段：
            [start_addr] number 寄存器数值，索引为寄存器地址，值为寄存器数值
            ...
@return nil
@usage
function callback(request)
    -- 用户处理代码
end
--]]
-- 该接口在各个子文件中，此处仅用作注释
-- modbus:on(callback)

return exmodbus