python-can-hirain-test 0.1.1__py3-none-any.whl

can_hirain/TestBaseVCI.py

@@ -0,0 +1,1084 @@
+import ctypes
+import platform
+import signal
+import atexit
+from typing import Tuple, Optional,Any, Dict, List
+from . import BasicStructure
+import threading
+
+
+def load_dll() -> ctypes.CDLL:
+    """
+    加载 himetal3api 动态库。
+
+    Returns:
+        ctypes.CDLL: 已加载的动态库对象。
+    """
+    if platform.system() == "Windows":
+        dll = ctypes.CDLL("himetal3api.dll")
+    else:
+        dll = ctypes.CDLL("libhimetal3api.so")
+    return dll
+
+dll = load_dll()
+
+
+def set_exit_callback(func: callable) -> None:
+    """注册程序退出时的回调函数（支持 Ctrl+C 和正常退出）"""
+    signal.signal(signal.SIGINT, func)
+    signal.signal(signal.SIGTERM, func)
+    atexit.register(func)
+
+
+def get_driver_config() -> List[Dict[str, Any]]:
+    """
+    获取驱动配置，并以标准 Python 数据结构返回所有可用通道的详细信息。
+    ...
+    """
+    driver_config = BasicStructure.H3DriverConfig()
+    # 第二个参数传空指针，表示忽略 IP 地址（与原版保持一致）
+    ip_config = ctypes.c_char_p()
+    ret = dll.H3GetDriverConfig(ctypes.byref(driver_config), ip_config)
+
+    if ret != 0:
+        print(f"driver 信息获取失败，错误码：{ret}")
+        return []
+
+    channels = []
+    for index in range(driver_config.nChannelCount):
+        ch = driver_config.h3Channels[index]
+        hw_name = ch.szHwName.decode('utf-8', errors='ignore').rstrip('\x00') if isinstance(ch.szHwName, bytes) else str(ch.szHwName)
+        hw_additional_info = ch.szHwAdditionalInfo.decode('utf-8', errors='ignore').rstrip('\x00') if isinstance(ch.szHwAdditionalInfo, bytes) else str(ch.szHwAdditionalInfo)
+
+        channel_dict = {
+            'channel_index': ch.ucChannelIndex,
+            'channel_mask': ch.unChannelMask,
+            'hw_name': hw_name,
+            'hw_type': ch.szHwType,
+            'hw_additional_info': hw_additional_info,
+            'hw_channel_no': ch.ucHwChannelNo,
+            'hw_trans_mode': ch.ucHwTransMode,
+            'bus_capabilities': ch.ucBusCapabilities,
+        }
+        channels.append(channel_dict)
+
+    return channels
+
+
+
+
+def channel_mask(channel: int) -> tuple[int, int]:
+    """
+    获取指定通道的掩码和通道索引。
+
+    Args:
+        channel (int): 通道在配置列表中的序号（从 0 开始）。
+
+    Returns:
+        tuple[int, int]: (通道掩码, 通道索引)，若获取失败则返回 (0, 0)。
+    """
+    driver_config = get_driver_config()
+    if not driver_config:
+        print("无法获取驱动配置，请检查硬件连接或驱动状态。")
+        return 0, 0
+
+    if channel < 0 or channel >= len(driver_config):
+        print(f"通道序号 {channel} 超出范围，当前可用通道数：{len(driver_config)}。")
+        return 0, 0
+
+    ch = driver_config[channel]
+    mask = ch['channel_mask']          # int
+    channel_index = ch['channel_index']  # int
+    return mask, channel_index
+
+
+def open_port(mask: int) -> int:
+    """
+    打开指定掩码的端口，获得端口句柄。
+
+    Args:
+        mask (int): 通道掩码，由 channel_mask() 返回。
+
+    Returns:
+        int: 端口句柄（正整数），若失败返回 0。
+    """
+    port_handle = ctypes.c_size_t()
+    ret = dll.H3OpenPort(ctypes.byref(port_handle), ctypes.c_uint64(mask))
+    if ret != 0:
+        print(f"端口打开失败！错误码: {ret}")
+        return 0
+    return port_handle.value
+
+
+def get_device_version(port_handle: int, mask: int) -> tuple:
+    """
+    获取设备版本信息。
+
+    Args:
+        port_handle (int): 端口句柄，由 open_port() 返回。
+        mask (int): 通道掩码（当前版本未使用，保留以兼容旧接口）。
+
+    Returns:
+        tuple: (版本信息字典, 错误码)。
+               成功时返回 ({"hw_version": (...), "bt_version": (...), "sw_version": (...)}, 0)；
+               失败时返回 (None, 错误码)，并自动打印错误信息。
+    """
+    dev_version = BasicStructure.DeviceVersion()
+    ret = dll.H3GetDeviceVersion(ctypes.c_size_t(port_handle), ctypes.byref(dev_version))
+    if ret != 0:
+        print(f"获取设备版本信息失败！错误码: {ret}")
+        return None, ret
+
+    version_info = {
+        "hw_version": (dev_version.hw_version_1, dev_version.hw_version_2),
+        "bt_version": (
+            dev_version.bt_version_1,
+            dev_version.bt_version_2,
+            dev_version.bt_version_3,
+        ),
+        "sw_version": (
+            dev_version.sw_version_1,
+            dev_version.sw_version_2,
+            dev_version.sw_version_3,
+        ),
+    }
+    return version_info, 0
+
+
+def active_can_channel(
+    port_handle: int,
+    channel_index: int,
+    listen_flag: int = 0,
+    baudrate: int = 500000,
+    sample_point: int = 0,
+) -> bool:
+    """
+    激活指定的 CAN 通道。
+
+    Args:
+        port_handle (int): 端口句柄，由 open_port() 返回。
+        channel_index (int): 通道索引，由 channel_mask() 返回。
+        listen_flag (int): 监听标志，0 表示正常模式。默认 0。
+        baudrate (int): CAN 波特率，单位 bps。默认 500000。
+        sample_point (int): 采样点位置，0 表示自动。默认 0。
+
+    Returns:
+        bool: 激活成功返回 True，失败返回 False 并在终端打印错误码。
+    """
+    channel_bus_params = BasicStructure.CHANNEL_BUS_PARAMS()
+    time_stamp = ctypes.create_string_buffer(10)
+
+    # 固定为 CAN 类型
+    channel_bus_params.ucBusType = 0x0
+    # 使用传入的参数配置 CAN 参数
+    channel_bus_params.busParam.can.ucListenFlag = listen_flag
+    channel_bus_params.busParam.can.ucBaudrate = baudrate
+    channel_bus_params.busParam.can.ucSamplePoint = sample_point
+
+    ret = dll.H3ActiveChannel(
+        ctypes.c_size_t(port_handle),
+        ctypes.c_ubyte(channel_index),
+        ctypes.byref(channel_bus_params),
+        time_stamp,
+    )
+    if ret != 0:
+        print(f"CAN 通道激活失败！错误码: {ret}")
+        return False
+    return True
+
+
+def active_canfd_channel(
+    port_handle: int,
+    channel_index: int,
+    listen_flag: int = 0,
+    abr_baudrate: int = 500_000,
+    dbr_baudrate: int = 2_000_000,
+    abr_sample_point: int = 0,
+    dbr_sample_point: int = 0,
+) -> int:
+    """
+    激活指定的 CAN FD 通道。
+
+    Args:
+        port_handle (int): 端口句柄，由 open_port() 返回。
+        channel_index (int): 通道索引，由 channel_mask() 返回。
+        listen_flag (int): 监听标志，0 表示正常模式。默认 0。
+        abr_baudrate (int): 仲裁段波特率（bps），默认 500_000。
+        dbr_baudrate (int): 数据段波特率（bps），默认 2_000_000。
+        abr_sample_point (int): 仲裁段采样点位置，0 为自动。默认 0。
+        dbr_sample_point (int): 数据段采样点位置，0 为自动。默认 0。
+
+    Returns:
+        int: 错误码。0 表示成功；非 0 表示失败，并会在终端打印具体错误码。
+    """
+    channel_bus_params = BasicStructure.CHANNEL_BUS_PARAMS()
+    time_stamp = ctypes.c_uint()
+
+    channel_bus_params.ucBusType = 3                     # CAN FD 类型
+    channel_bus_params.busParam.canFd.ucListenFlag = listen_flag
+    channel_bus_params.busParam.canFd.abrBaudrate = abr_baudrate
+    channel_bus_params.busParam.canFd.dbrBaudrate = dbr_baudrate
+    channel_bus_params.busParam.canFd.abrSamplePoint = abr_sample_point
+    channel_bus_params.busParam.canFd.dbrSamplePoint = dbr_sample_point
+
+    ret = dll.H3ActiveChannel(
+        ctypes.c_size_t(port_handle),
+        ctypes.c_ubyte(channel_index),
+        ctypes.byref(channel_bus_params),
+        ctypes.byref(time_stamp),
+    )
+    if ret != 0:
+        print(f"CAN FD 通道激活失败！错误码: {ret}")
+    return ret
+
+
+def active_lin_channel(
+    port_handle: int,
+    channel_index: int,
+    baudrate: int = 9600,
+    lin_version: int = 0,
+) -> int:
+    """
+    激活指定的 LIN 通道。
+
+    Args:
+        port_handle (int): 端口句柄，由 open_port() 返回。
+        channel_index (int): 通道索引，由 channel_mask() 返回。
+        baudrate (int): LIN 波特率 (bps)，默认 9600。
+        lin_version (int): LIN 协议版本号，0 表示自动/默认版本。默认 0。
+
+    Returns:
+        int: 错误码。0 表示成功；非 0 表示失败，并会在终端打印错误信息。
+    """
+    channel_bus_params = BasicStructure.CHANNEL_BUS_PARAMS()
+    time_stamp = ctypes.create_string_buffer(10)
+
+    channel_bus_params.ucBusType = 0x2               # LIN 类型
+    channel_bus_params.busParam.lin.unBaudrate = baudrate
+    channel_bus_params.busParam.lin.ucLinVersion = lin_version
+
+    ret = dll.H3ActiveChannel(
+        ctypes.c_size_t(port_handle),
+        ctypes.c_ubyte(channel_index),
+        ctypes.byref(channel_bus_params),
+        time_stamp,
+    )
+    if ret != 0:
+        print(f"LIN 通道激活失败！错误码: {ret}")
+    return ret
+
+
+def active_ethernet_channel(
+    port_handle: int,
+    channel_index: int
+) -> int:
+    """
+    激活指定的以太网通道。
+
+    Args:
+        port_handle (int): 端口句柄，由 open_port() 返回。
+        channel_index (int): 通道索引，由 channel_mask() 返回。
+
+    Returns:
+        int: 错误码。0 表示成功；非 0 表示失败，并会在终端打印错误信息。
+    """
+    channel_bus_param = BasicStructure.CHANNEL_BUS_PARAMS()
+    time_stamp = ctypes.c_uint()
+
+    channel_bus_param.ucBusType = 0x4
+    channel_bus_param.busParam.eth.szFilter = b''
+    channel_bus_param.busParam.eth.nMaxSize = 256
+    channel_bus_param.busParam.eth.nMaxPacks = 1024
+    channel_bus_param.busParam.eth.szDumpFileDir = br'C:\test_Ethernet'
+
+    ret = dll.H3ActiveChannel(
+        ctypes.c_size_t(port_handle),
+        ctypes.c_ubyte(channel_index),
+        channel_bus_param,
+        ctypes.byref(time_stamp),
+    )
+    if ret != 0:
+        print(f"以太网通道激活失败！错误码: {ret}")
+    return ret
+
+
+# ===================== CAN =====================
+def can_set_resistor(
+    port_handle: int,
+    channel_index: int,
+    value: bool,
+) -> int:
+    """
+    设置 CAN 终端电阻。
+
+    Args:
+        port_handle (int): 端口句柄。
+        channel_index (int): 通道索引。
+        value (bool): True 启用电阻，False 关闭电阻。
+
+    Returns:
+        int: 错误码。0 表示成功；非 0 表示失败，并打印错误信息。
+    """
+    ret = dll.H3CANSetResistor(port_handle, channel_index, value)
+    if ret != 0:
+        print(f"CAN 终端电阻操作失败！错误码: {ret}")
+    return ret
+
+
+# ===================== LIN =====================
+def lin_set_master_slave(
+    port_handle: int,
+    channel_index: int,
+    value: bool,
+) -> int:
+    """
+    设置 LIN 主从节点。
+
+    Args:
+        port_handle (int): 端口句柄。
+        channel_index (int): 通道索引。
+        value (bool): True 主节点，False 从节点。
+
+    Returns:
+        int: 错误码。0 表示成功；非 0 表示失败，并打印错误信息。
+    """
+    ret = dll.H3LINSetResistor(port_handle, channel_index, value)
+    if ret != 0:
+        print(f"LIN 终端电阻设置失败！错误码: {ret}")
+    return ret
+
+
+def set_lin_tx_msg(
+    port_handle: int,
+    channel_index: int,
+    tx_msg_count: int,
+    lin_msg,
+) -> int:
+    """
+    发送 LIN 响应报文。
+
+    Args:
+        port_handle (int): 端口句柄。
+        channel_index (int): 通道索引。
+        tx_msg_count (int): 发送报文数量。
+        lin_msg (ctypes.Structure): LIN 消息结构体（需与 DLL 定义匹配）。
+
+    Returns:
+        int: 错误码。0 表示成功；非 0 表示失败，并打印错误信息。
+    """
+    ret = dll.H3LINSetTxMsgs(port_handle, channel_index, tx_msg_count, ctypes.byref(lin_msg))
+    if ret != 0:
+        print(f"LIN 响应报文发送失败！错误码: {ret}")
+    return ret
+
+
+def set_lin_schedule(
+    port_handle: int,
+    channel_index: int,
+    lin_count: int,
+    node,
+) -> int:
+    """
+    发送 LIN 头部报文（调度表）。
+
+    Args:
+        port_handle (int): 端口句柄。
+        channel_index (int): 通道索引。
+        lin_count (int): 调度表条目数量。
+        node (ctypes.Structure): 调度表节点结构体（需与 DLL 定义匹配）。
+
+    Returns:
+        int: 错误码。0 表示成功；非 0 表示失败，并打印错误信息。
+    """
+    ret = dll.H3LINSetScheduleTable(port_handle, channel_index, lin_count, ctypes.byref(node))
+    if ret != 0:
+        print(f"LIN 首部报文发送失败！错误码: {ret}")
+    return ret
+
+
+def lin_clear(
+    port_handle: int,
+    channel_index: int,
+    value: int,
+) -> int:
+    """
+    清除 LIN 数据。
+
+    Args:
+        port_handle (int): 端口句柄。
+        channel_index (int): 通道索引。
+        value (int): 清除标志（具体含义参考硬件手册）。
+
+    Returns:
+        int: 错误码。0 表示成功；非 0 表示失败，并打印错误信息。
+    """
+    ret = dll.H3LINClear(port_handle, channel_index, value)
+    if ret != 0:
+        print(f"LIN 数据清除失败！错误码: {ret}")
+    return ret
+
+
+# def start_stop_trace(
+#     port_handle: int,
+#     channel_index: int,
+#     value: bool,
+# ) -> int:
+#     """
+#     启用/停止总线监控。
+#
+#     Args:
+#         port_handle (int): 端口句柄。
+#         channel_index (int): 通道索引。
+#         value (bool): True 启用监控，False 停止监控。
+#
+#     Returns:
+#         int: 错误码。0 表示成功；非 0 表示失败，并打印错误信息。
+#     """
+#     time_stamp = ctypes.c_void_p()
+#     ret = dll.H3StartStopBusTrace(port_handle, channel_index, value, ctypes.pointer(time_stamp))
+#     if ret != 0:
+#         print(f"启用/停止监控设置失败！错误码: {ret}")
+#     return ret
+def start_stop_trace(port_handle: int, channel_index: int, value: bool) -> int:
+    time_stamp = ctypes.c_longlong()  # 改为 64 位类型
+    ret = dll.H3StartStopBusTrace(port_handle, channel_index, value, ctypes.byref(time_stamp))
+    if ret != 0:
+        print(f"启用/停止监控设置失败！错误码: {ret}")
+    return ret
+
+def close_port(port_handle: int) -> int:
+    """
+    关闭端口。
+
+    Args:
+        port_handle (int): 端口句柄。
+
+    Returns:
+        int: 错误码。0 表示成功；非 0 表示失败，并打印错误信息。
+    """
+    ret = dll.H3ClosePort(port_handle)
+    if ret != 0:
+        print(f"关闭端口失败！错误码: {ret}")
+    return ret
+
+
+def deactive_channel(port_handle: int) -> int:
+    """
+    取消激活通道。
+
+    Args:
+        port_handle (int): 端口句柄。
+
+    Returns:
+        int: 错误码。0 表示成功；非 0 表示失败，并打印错误信息。
+    """
+    ret = dll.H3DeactiveChannel(port_handle)
+    if ret != 0:
+        print(f"通道取消失败！错误码: {ret}")
+    return ret
+
+
+def get_device_time_stamp(port_handle: int) -> int:
+    """
+    获取设备时间戳。
+
+    Args:
+        port_handle (int): 端口句柄。
+
+    Returns:
+        ctypes.c_longlong: 设备时间戳（若失败会打印错误信息，返回的时间戳可能无效）。
+    """
+    time_stamp = ctypes.c_longlong()
+    ret = dll.H3GetDeviceTimeStamp(port_handle, ctypes.pointer(time_stamp))
+    if ret != 0:
+        print(f"时间戳获取失败！错误码: {ret}")
+    return time_stamp.value
+
+
+def replay_send_packs(
+    port_handle: int,
+    msg_pack_count: int,
+    packs,
+) -> int:
+    """
+    发送回放报文。
+
+    Args:
+        port_handle (int): 端口句柄。
+        msg_pack_count (int): 报文包数量。
+        packs: 报文包结构体（需与 DLL 定义匹配）。
+
+    Returns:
+        int: 错误码。0 表示成功；非 0 表示失败，并打印错误信息。
+    """
+    ret = dll.H3ReplaySendPacks(port_handle, msg_pack_count, ctypes.byref(packs))
+    if ret != 0:
+        print(f"回放报文发送失败！错误码: {ret}")
+    return ret
+
+
+def can_set_periodic_tx_msgs(
+    port_handle: int,
+    channel_index: int,
+    can_id: int,
+    is_fd: bool = False,
+    dlc: int = 8,
+    brs: int = 0,
+    data = (1, 2, 3, 4, 5, 6, 7, 8),
+    period: int = 10,
+) -> int:
+    """
+    设置 CAN 周期发送报文。
+
+    Args:
+        port_handle (int): 端口句柄。
+        channel_index (int): 通道索引。
+        can_id (int): 发送方 CAN ID。
+        is_fd (bool): 是否为 CAN FD 帧，True 表示 FD 帧，False 为标准 CAN 帧。
+        dlc (int): 数据长度码 DLC（0~15），默认 8。
+        brs (int): 比特率开关（BRS），仅 CAN FD 有效，0 或 1，默认 0。
+        data: 发送数据，需与 ucData 字段兼容（长度不超过 CAN_MSG_LENGTH）。
+        period (int): 发送周期（单位与硬件相关）。
+
+    Returns:
+        int: 错误码。0 表示成功；非 0 表示失败，并在终端打印错误信息。
+    """
+    ptxinfo = BasicStructure.CanPeriodTxInfo()
+    can_msg = BasicStructure.GET_CAN_TRACE()
+
+    # 填充 CAN 消息结构体
+    can_msg.unCanId = can_id
+    can_msg.ucDLC = dlc
+    can_msg.ucEDL = 1 if is_fd else 0    # EDL=1 表示 CAN FD 帧
+    can_msg.ucBRS = brs                   # 比特率开关
+    can_msg.ucData = data
+    # ucTag 保持默认值 0（通常表示发送帧）
+
+    ptxinfo.canMsg = can_msg
+    ptxinfo.usPeriod = ctypes.c_ushort(period)
+
+    uc_tx_info_count = 1
+    time_stamp = ctypes.create_string_buffer(8)   # 时间戳缓冲区，长度按硬件要求
+    ret = dll.H3CANSetPeriodicTxMsgs(
+        port_handle,
+        channel_index,
+        uc_tx_info_count,
+        ctypes.byref(ptxinfo),
+        time_stamp,
+    )
+    if ret != 0:
+        print(f"CAN 周期报文发送失败！错误码: {ret}")
+    return ret
+
+
+def can_set_one_tx_msgs(
+    port_handle: int,
+    channel_index: int,
+    can_id: int,
+    tx_data,
+    is_fd: bool = False,
+    dlc: int = 8,
+    brs: int = 0,
+) -> int:
+    """
+    发送 CAN 单次报文（一帧）。
+
+    Args:
+        port_handle (int): 端口句柄。
+        channel_index (int): 通道索引。
+        can_id (int): CAN 标识符 ID。
+        tx_data: 发送数据，需与 ucData 字段兼容（长度不超过 CAN_MSG_LENGTH）。
+        is_fd (bool): 是否为 CAN FD 帧，True 表示 FD 帧，False 为标准 CAN 帧。
+        dlc (int): 数据长度码 DLC（0~15），默认 8。
+        brs (int): 比特率开关（BRS），仅 CAN FD 有效，0 或 1，默认 0。
+
+    Returns:
+        int: 错误码。0 表示成功；非 0 表示失败，并打印错误信息。
+    """
+    time_stamp = ctypes.create_string_buffer(8)
+    can_msg_arr = (BasicStructure.GET_CAN_TRACE * 1)()
+
+    # 填充要发送的 CAN 消息
+    can_msg_arr[0].unCanId = can_id
+    can_msg_arr[0].ucDLC = dlc
+    can_msg_arr[0].ucEDL = 1 if is_fd else 0    # EDL=1 表示 CAN FD 帧
+    can_msg_arr[0].ucBRS = brs                   # 比特率开关
+    can_msg_arr[0].ucData = tx_data
+    # ucTag 默认为 0（通常表示发送帧）
+
+    tx_msg_count = 1
+    ret = dll.H3CANSetOneTimeTxMsgs(
+        port_handle,
+        channel_index,
+        tx_msg_count,
+        ctypes.byref(can_msg_arr),
+        time_stamp,
+    )
+    if ret != 0:
+        print(f"CAN 单次报文发送失败！错误码: {ret}")
+    return ret
+
+
+def ethernet_set_one_time_tx_msg(
+    port_handle: int,
+    channel_index: int,
+    data,
+    data_len: int = 82,
+) -> int:
+    """
+    发送以太网单次报文（无应答）。
+
+    Args:
+        port_handle (int): 端口句柄。
+        channel_index (int): 通道索引。
+        data: 发送数据（需符合 ucData 格式）。
+        data_len (int): 数据长度，默认 82。
+
+    Returns:
+        int: 错误码。0 表示成功；非 0 表示失败，并打印错误信息。
+    """
+    ethernet_msg = BasicStructure.ETH_MSG()
+    ethernet_msg.unDataLength = data_len
+    ethernet_msg.ucData = data
+    ret = dll.H3EthernetSetOneTimeTxMsgNoResp(port_handle, channel_index, ethernet_msg)
+    if ret != 0:
+        print(f"以太网报文发送失败！错误码: {ret}")
+    return ret
+
+
+def can_set_param_15765_2(
+    port_handle: int,
+    channel_index: int,
+    Value: int,
+    Parameter: int = BasicStructure.N_Parameter.N_Bs,
+    MType: int = BasicStructure.CANMType.MTYPE_LOCAL,
+) -> int:
+    """
+    设置 ISO-15765 诊断参数。
+
+    Args:
+        port_handle (int): 端口句柄。
+        channel_index (int): 通道索引。
+        Value (int): 参数值。
+        Parameter (int): 要设置的参数类型，取值见 N_Parameter 枚举，默认 N_Bs。
+        MType (int): 诊断类型，MTYPE_LOCAL（1，本地）或 MTYPE_REMOTE（2，远程）。
+
+    Returns:
+        int: 错误码，0 表示成功，非 0 表示失败。
+    """
+    udsParameter = BasicStructure.CAN_PARAMS()
+    udsParameter.ucMType = MType
+    udsParameter.ucParameter = Parameter
+    udsParameter.unValue = Value
+    n_rst = dll.H3CANSetParam15765_2(port_handle, channel_index, udsParameter)
+    return n_rst
+
+
+def can_set_diagnostic_config(
+    port_handle: int,
+    channel_index: int,
+    ReqId: int,
+    FuncReqID: int,
+    RespId: int,
+    DataPadding: int = 0xCC,
+) -> int:
+    """
+    设置诊断配置（ECU 信息）。
+
+    Args:
+        port_handle (int): 端口句柄。
+        channel_index (int): 通道索引。
+        ReqId (int): 请求 ID（物理寻址）。
+        FuncReqID (int): 功能寻址请求 ID。
+        RespId (int): 响应 ID。
+        DataPadding (int): 数据填充字节，默认 0xCC。
+
+    Returns:
+        int: 错误码，0 表示成功，非 0 表示失败。
+    """
+    ecu_info = (BasicStructure.EcuInfo * 256)()
+    ecu_info[0].unReqID = ReqId
+    ecu_info[0].unUSDTRespID = RespId
+
+    diagnostic_config = BasicStructure.CAN_DIAGNOSTIC_CONFIG()
+    diagnostic_config.ucDataPadding = DataPadding
+    diagnostic_config.unFuncReqID = FuncReqID
+    diagnostic_config.ucEcuCount = 1
+    diagnostic_config.ecuInfo = ecu_info
+
+    n_rst = dll.H3CANSetDiagnosticConfig(
+        port_handle, channel_index, diagnostic_config
+    )
+    return n_rst
+
+response_event = threading.Event()
+current_response_data = None
+response_lock = threading.Lock()
+
+def can_forward_15765_2(
+        port_handle: int,
+        channel_index: int,
+        req_id: int,
+        is_fd: bool = False,
+        is_brs: bool = False,
+        dlc: int = 8,
+        m_type: int = BasicStructure.CANMType.MTYPE_LOCAL,
+        data_len: int = 2,
+        data: tuple = (0x10, 0x01),
+        wait_resp: bool = False,
+) -> Tuple[int, Optional[Any]]:
+    """
+    发送 ISO-15765 诊断请求（UDS）。
+
+    Args:
+        port_handle: 端口句柄。
+        channel_index: 通道索引。
+        req_id: 请求 ID。
+        is_fd: 是否使用 CAN FD 帧，默认 False。
+        is_brs: 是否使能比特率开关（BRS），仅 CAN FD 有效，默认 False。
+        dlc: 数据长度码 DLC，默认 8。
+        m_type: 诊断类型，MTYPE_LOCAL(1) 或 MTYPE_REMOTE(2)。
+        data_len: 实际数据长度（字节），默认 2。
+        data: 要发送的数据，格式为字节元组，默认 (0x10, 0x01)。
+        wait_resp: 是否等待并返回响应数据，默认 False。
+
+    Returns:
+        Tuple[int, Optional[Any]]:
+            - 错误码，0 表示成功，非 0 表示失败或超时。
+            - 响应数据，当 wait_resp=True 且成功时返回数据，否则为 None。
+    """
+
+    # 构建 CAN 请求结构体
+    can_request = BasicStructure.CanRequest()
+    can_request.unReqID = req_id
+
+    # 计算 MValue: [bit7=保留] [bit6=FD] [bit5=BRS] [bit4..1=DLC] [bit0=MType]
+    m_value = (is_fd << 6) | (is_brs << 5) | (dlc << 1) | m_type
+    can_request.ucMType = m_value
+
+    # 设置数据长度和数据内容
+    can_request.usDataLen = data_len
+    can_request.ucData = data
+
+    # 设置超时时间（单位：ms）
+    time_out = ctypes.c_ushort(6000)
+
+    # 发送请求
+    ret_code = dll.H3CANForward15765_2(
+        port_handle, channel_index, can_request, time_out
+    )
+
+    # 发送失败，直接返回错误码
+    if ret_code != 0:
+        return ret_code, None
+
+    # 发送成功，根据 wait_resp 决定是否等待响应
+    if not wait_resp:
+        return ret_code, None
+
+    # 等待响应（阻塞等待，超时时间 30 秒）
+    response_received = response_event.wait(timeout=30.0)
+
+    if not response_received:
+        # 超时返回特定错误码
+        return 0x2002, None
+
+    # 成功收到响应，返回响应数据
+    with response_lock:
+        return ret_code, current_response_data
+
+
+def dlc_to_len(dlc: int) -> int:
+    """
+    将 CAN FD 的 DLC 值转换为实际数据长度。
+
+    Args:
+        dlc: DLC 编码值（0~15）。
+
+    Returns:
+        int: 对应的实际数据长度（0~64 字节）。
+
+    映射关系：
+        0~8  -> 0~8 字节
+        9    -> 12 字节
+        10   -> 16 字节
+        11   -> 20 字节
+        12   -> 24 字节
+        13   -> 32 字节
+        14   -> 48 字节
+        15   -> 64 字节
+    """
+    # CAN FD DLC 到实际长度的映射表
+    dlc_length_map = {
+        9: 12,
+        10: 16,
+        11: 20,
+        12: 24,
+        13: 32,
+        14: 48,
+        15: 64,
+    }
+
+    if dlc <= 8:
+        return dlc
+
+    return dlc_length_map.get(dlc, 64)  # 默认返回最大值以容错
+
+
+# def rx_msg(
+#         port_handle: int,
+#         rx_services: BasicStructure.RX_SERVICE,
+#         count: int,
+#         response_lock: threading.Lock,
+#         response_event: threading.Event,
+#         current_response_data: dict,
+# ) -> int:
+#     """
+#     获取接收队列报文并解析诊断响应内容。
+#
+#     Args:
+#         port_handle: 端口句柄。
+#         rx_services: 写入报文信息的预分配结构体。
+#         count: 期望获取的报文数量。
+#         response_lock: 响应数据的线程锁。
+#         response_event: 响应事件，用于通知等待线程。
+#         current_response_data: 存储当前响应数据的字典（用于线程间共享）。
+#
+#     Returns:
+#         int:
+#             0 表示成功，
+#             非 0 表示错误码。
+#     """
+#     # 获取接收到的报文数量
+#     rx_count = ctypes.c_uint(count)
+#     ret = dll.H3GetRxService(
+#         port_handle,
+#         ctypes.pointer(rx_services),
+#         ctypes.pointer(rx_count)
+#     )
+#
+#     if ret != 0:
+#         print(f"接收报文获取失败！错误码: {ret}")
+#         return ret
+#
+#     # 遍历所有接收到的报文
+#     rx_count_value = rx_count.value
+#     for i in range(rx_count_value):
+#         rx_msg = rx_services[i]  # 假设可以通过索引访问
+#
+#         # 检查是否为诊断响应报文（nServiceType == 4）
+#         if rx_msg.nServiceType != 4:
+#             continue
+#
+#         # 提取 ISO-15765 诊断响应数据
+#         diag_msg = rx_msg.service.get15765_2_RespInd
+#
+#         # 构建响应数据字典
+#         response_data = {
+#             'data': diag_msg.ucData[:diag_msg.usLength],
+#             'data_len': diag_msg.usLength,
+#             'req_id': diag_msg.unEcuRespId,
+#         }
+#
+#         # 使用锁保护共享数据的写入
+#         with response_lock:
+#             current_response_data.update(response_data)
+#
+#             # 判断是否为"正在处理"响应（0x78 表示待处理响应）
+#             data_array = current_response_data['data']
+#             is_pending_response = (
+#                     len(data_array) >= 3 and
+#                     data_array[2] == 0x78
+#             )
+#
+#             if not is_pending_response:
+#                 # 收到最终响应，通知等待线程
+#                 response_event.set()
+#             else:
+#                 print("收到 0x78 待处理响应，继续等待...")
+#
+#     return 0
+def rx_msg(port_handle: int, count: int = 1, timeout_ms: int = 0) -> List[Dict]:
+    """
+    获取接收队列报文，返回原生 Python 字典列表。
+
+    Returns:
+        List[Dict]: 每个字典包含 nServiceType 及对应的解析后数据。
+                    CAN 帧示例：{'type': 8, 'channel':..., 'id':..., 'data':..., ...}
+                    Diag 帧示例：{'type': 4, 'data':..., 'data_len':..., 'req_id':...}
+    """
+    # 分配结构体（此操作必须保留，但对外不可见）
+    rx_array = (BasicStructure.RX_SERVICE * count)()
+    rx_count = ctypes.c_uint(count)
+    ret = dll.H3GetRxService(
+        ctypes.c_size_t(port_handle),
+        ctypes.pointer(rx_array),
+        ctypes.pointer(rx_count),
+    )
+    if ret != 0:
+        return []
+
+    results = []
+    for i in range(rx_count.value):
+        svc = rx_array[i]
+        st = svc.nServiceType
+        item = {'nServiceType': st, 'ucChannelIndex': svc.ucChannelIndex}
+        if st == 8:  # CAN/CANFD
+            t = svc.service.getCanTrace
+            item.update({
+                'can_id': t.unCanId,
+                'is_extended': bool((t.unCanId >> 31) & 1),
+                'is_fd': bool(t.ucEDL),
+                'brs': bool(t.ucBRS),
+                'dlc': t.ucDLC,
+                'data': bytes(t.ucData[:64]),  # 全部 64 字节，上层按 DLC 截断
+                'tag': t.ucTag,
+                'timestamp': t.unTimestamp,
+            })
+        elif st == 4:  # Diag response
+            d = svc.service.get15765_2_RespInd
+            item.update({
+                'data': d.ucData[:d.usLength],
+                'data_len': d.usLength,
+                'req_id': d.unEcuRespId,
+            })
+        elif st == 0:  # Error
+            e = svc.service.getBusError
+            item.update({
+                'error_type': e.ucErrType,
+                'timestamp': e.unTimestamp,
+            })
+        # 可继续扩展 LIN 等其他类型...
+        results.append(item)
+    return results
+
+
+def rx_msg_print_all(port_handle: int, count: int = 1000) -> int:
+    """
+    从端口获取接收报文并打印所有细节（CAN/CAN FD/LIN/Error/Ethernet等）。
+    本函数主要供调试和监控使用，会直接在终端输出报文信息。
+
+    Args:
+        port_handle (int): 端口句柄。
+        count (int): 每次请求最大报文数，默认 1000。
+
+    Returns:
+        int: 0 表示成功，非 0 表示错误码。
+    """
+    rx_services = (BasicStructure.RX_SERVICE * count)()
+    rx_count = ctypes.c_uint(count)
+
+    ret = dll.H3GetRxService(
+        ctypes.c_size_t(port_handle),
+        ctypes.pointer(rx_services),
+        ctypes.pointer(rx_count),
+    )
+    if ret != 0:
+        print(f"获取报文失败！错误码: {ret}")
+        return ret
+
+    rx_count_val = rx_count.value
+    for i in range(rx_count_val):
+        svc = rx_services[i]
+        st = svc.nServiceType
+
+        if st == 8:                     # CAN / CAN FD 报文
+            trace = svc.service.getCanTrace
+            msg_id = trace.unCanId
+            is_ext = (msg_id >> 31) & 1
+            can_id = msg_id & 0x7FFFFFFF
+            is_fd = trace.ucEDL & 1
+            brs = trace.ucBRS & 1
+            dlc = trace.ucDLC
+            data_len = dlc_to_len(dlc)
+            data_str = ','.join(f"{b:02X}" for b in trace.ucData[:data_len])
+            print(
+                f"[CAN{' FD' if is_fd else ''}] "
+                f"Ch={svc.ucChannelIndex} "
+                f"ID=0x{can_id:X}{' (Ext)' if is_ext else ''} "
+                f"Ts={trace.unTimestamp} "
+                f"DLC={dlc} "
+                f"BRS={brs} "
+                f"Dir={'RX' if trace.ucTag else 'TX'} "
+                f"Data=[{data_str}]"
+            )
+        elif st == 9:                   # LIN 报文
+            lin = svc.service.getLINMsg
+            print(
+                f"[LIN] Ch={svc.ucChannelIndex} "
+                f"PID=0x{lin.ucPID:02X} "
+                f"Dir={'Master' if lin.ucDir else 'Slave'} "
+                f"Ts={lin.unTimestamp} "
+                f"Data=[{','.join(f'{b:02X}' for b in lin.ucData[:lin.ucDLC])}] "
+                f"Checksum=0x{lin.ucChecksum:02X}"
+            )
+        elif st == 6 or st == 7:        # 错误帧/事件
+            err = svc.service.getErrorInfo
+            print(f"[ERROR] Ch={svc.ucChannelIndex} ErrorType={err.ucErrType} "
+                  f"Ts={err.unTimestamp}")
+        elif st == 10:                  # 以太网(示例)
+            eth = svc.service.getEthMsg
+            print(f"[ETH] Ch={svc.ucChannelIndex} Len={eth.unDataLength} "
+                  f"Ts={eth.unTimestamp}")
+        else:
+            # 其它未知类型可按需扩展
+            print(f"[TYPE={st}] Ch={svc.ucChannelIndex} (raw data omitted)")
+
+    return 0
+
+
+def fetch_rx_services(port_handle: int, count: int = 1):
+    """
+    从接收队列获取报文，返回 Python 原生字典列表。
+    该函数封装了 H3GetRxService 的 DLL 调用和 ctypes 结构体操作。
+    """
+    rx_array = (BasicStructure.RX_SERVICE * count)()
+    rx_count = ctypes.c_uint(count)
+
+    ret = dll.H3GetRxService(
+        ctypes.c_size_t(port_handle),
+        ctypes.pointer(rx_array),
+        ctypes.pointer(rx_count),
+    )
+    if ret != 0:
+        return []
+
+    results = []
+    for i in range(rx_count.value):
+        svc = rx_array[i]
+        st = svc.nServiceType
+        item = {
+            'nServiceType': st,
+            'ucChannelIndex': svc.ucChannelIndex,
+        }
+        if st == 8:  # CAN / CANFD
+            t = svc.service.getCanTrace
+            item.update({
+                'can_id': t.unCanId,
+                'is_extended': bool((t.unCanId >> 31) & 1),
+                'is_fd': bool(t.ucEDL),
+                'brs': bool(t.ucBRS),
+                'dlc': t.ucDLC,
+                'data': bytes(t.ucData[:64]),
+                'tag': t.ucTag,
+                'timestamp': t.unTimestamp,
+            })
+        elif st == 4:  # 15765 诊断响应
+            d = svc.service.get15765_2_RespInd
+            item.update({
+                'data': d.ucData[:d.usLength],
+                'data_len': d.usLength,
+                'req_id': d.unEcuRespId,
+            })
+        elif st == 0:  # 总线错误
+            e = svc.service.getBusError
+            item.update({
+                'error_type': e.ucErrType,
+                'timestamp': e.unTimestamp,
+            })
+        results.append(item)
+    return results
+
+
+if __name__ == '__main__':
+    driver = get_driver_config()