import ctypes

# ═══════════════════════════════════════════
# 第一步：加载 DLL
# ═══════════════════════════════════════════
dll = ctypes.WinDLL(r"C:\path\to\CH347DLLA64.dll")

# ═══════════════════════════════════════════
# 第二步：声明函数签名（参数类型 + 返回类型）
# ═══════════════════════════════════════════
# 告诉 ctypes：这个函数接收什么参数、返回什么
dll.CH347OpenDevice.argtypes = [ctypes.c_ulong]   # 参数：ULONG DevIndex
dll.CH347OpenDevice.restype = ctypes.c_int         # 返回：BOOL (用c_int映射)

# ═══════════════════════════════════════════
# 第三步：调用函数
# ═══════════════════════════════════════════
handle = dll.CH347OpenDevice(0)  # 打开第 0 号设备
if handle:
    print(f"设备已打开，句柄: {handle}")
else:
    print("设备打开失败")

// ====== 设备管理 ======

// 打开设备，返回设备句柄（0表示失败）
HANDLE WINAPI CH347OpenDevice(ULONG DevIndex);

// 关闭设备
BOOL WINAPI CH347CloseDevice(ULONG DevIndex);

// 获取设备信息
BOOL WINAPI CH347GetDeviceInfor(ULONG DevIndex, mDeviceInforS* DevInformation);

// ====== SPI 接口 ======

// 设置 SPI 参数
BOOL WINAPI CH347SPI_Init(ULONG DevIndex, mSpiCfgS* SpiCfg);

// SPI 读写数据（Stream 模式）
BOOL WINAPI CH347SPI_Stream(ULONG DevIndex, ULONG WriteStep, ULONG WriteSize,
                            PUCHAR WriteBuffer, ULONG* ReadStep,
                            ULONG* ReadSize, PUCHAR ReadBuffer);

// ====== I2C 接口 ======

// 设置 I2C 时钟频率
BOOL WINAPI CH347I2C_Set(ULONG DevIndex, ULONG iMode);

// I2C 读写数据
BOOL WINAPI CH347I2C_WriteRead(ULONG DevIndex, ULONG WriteLength,
                               PUCHAR WriteBuffer, ULONG* ReadLength,
                               PUCHAR ReadBuffer);

import ctypes
from ctypes import wintypes
import os

class CH347DLL:
    """CH347 DLL 的原始接口映射层（薄封装）"""

    def __init__(self, dll_path: str | None = None):
        """
        加载 CH347 DLL。

        Args:
            dll_path: DLL文件路径。为 None 时自动搜索。
        """
        if dll_path is None:
            # 默认在脚本同目录下查找
            dll_path = os.path.join(os.path.dirname(__file__), "CH347DLLA64.dll")

        if not os.path.exists(dll_path):
            raise FileNotFoundError(
                f"找不到 CH347 DLL: {dll_path}\n"
                f"请确保 DLL 文件存在，且 Python 位数（32/64）与 DLL 一致。"
            )

        # 根据调用约定选择加载方式
        self._dll = ctypes.WinDLL(dll_path)

        # ── 声明函数签名 ──
        self._declare_functions()

    def _declare_functions(self):
        """声明所有需要调用的 DLL 函数签名"""
        dll = self._dll

        # --- 设备管理 ---
        dll.CH347OpenDevice.argtypes = [ctypes.c_ulong]
        dll.CH347OpenDevice.restype = ctypes.c_void_p  # HANDLE

        dll.CH347CloseDevice.argtypes = [ctypes.c_ulong]
        dll.CH347CloseDevice.restype = ctypes.c_int  # BOOL

        dll.CH347GetDeviceInfor.argtypes = [
            ctypes.c_ulong,
            ctypes.POINTER(mDeviceInforS),
        ]
        dll.CH347GetDeviceInfor.restype = ctypes.c_int

        # --- SPI 接口 ---
        dll.CH347SPI_Init.argtypes = [
            ctypes.c_ulong,
            ctypes.c_void_p,  # mSpiCfgS* （后续细化）
        ]
        dll.CH347SPI_Init.restype = ctypes.c_int

        dll.CH347SPI_Stream.argtypes = [
            ctypes.c_ulong,           # DevIndex
            ctypes.c_ulong,           # WriteStep
            ctypes.c_ulong,           # WriteSize
            ctypes.POINTER(ctypes.c_ubyte),  # WriteBuffer
            ctypes.POINTER(ctypes.c_ulong),  # ReadStep (输出)
            ctypes.POINTER(ctypes.c_ulong),  # ReadSize (输出)
            ctypes.POINTER(ctypes.c_ubyte),  # ReadBuffer
        ]
        dll.CH347SPI_Stream.restype = ctypes.c_int

        # --- I2C 接口 ---
        dll.CH347I2C_Set.argtypes = [ctypes.c_ulong, ctypes.c_ulong]
        dll.CH347I2C_Set.restype = ctypes.c_int

import ctypes
from ctypes import wintypes
from typing import Optional
import logging

logger = logging.getLogger(__name__)


class CH347Error(Exception):
    """CH347 操作异常"""
    pass


class CH347:
    """
    CH347 USB 转 SPI/I2C/GPIO 设备的高层 Python 封装。

    使用方式（上下文管理器，推荐）：
        with CH347(dev_index=0) as dev:
            dev.spi_init(clock_mhz=10)
            data = dev.spi_read(0x9F, read_len=3)  # 读取 Flash JEDEC ID
            print(f"厂商ID: 0x{data[0]:02X}")

    使用方式（手动管理，不推荐）：
        dev = CH347(dev_index=0)
        dev.open()
        try:
            dev.spi_init()
            # ...
        finally:
            dev.close()
    """

    def __init__(self, dev_index: int = 0, dll_path: str | None = None):
        """
        初始化 CH347 设备。

        Args:
            dev_index: 设备索引号（0 表示第一个设备）
            dll_path: DLL 文件路径，None 表示自动搜索
        """
        self._dev_index = dev_index
        self._dll_wrapper = CH347DLL(dll_path)
        self._is_open = False

    def open(self) -> None:
        """打开设备"""
        if self._is_open:
            logger.warning(f"设备 {self._dev_index} 已经打开")
            return

        handle = self._dll_wrapper._dll.CH347OpenDevice(self._dev_index)
        if not handle:
            raise CH347Error(
                f"无法打开 CH347 设备 (索引: {self._dev_index})。\n"
                f"请检查：\n"
                f"  1. 设备是否已连接\n"
                f"  2. 驱动是否已安装\n"
                f"  3. Python 位数是否与 DLL 匹配"
            )

        self._is_open = True
        logger.info(f"CH347 设备 {self._dev_index} 已打开")

    def close(self) -> None:
        """关闭设备"""
        if not self._is_open:
            return

        result = self._dll_wrapper._dll.CH347CloseDevice(self._dev_index)
        self._is_open = False
        if not result:
            logger.warning(f"关闭设备 {self._dev_index} 时返回异常")
        else:
            logger.info(f"CH347 设备 {self._dev_index} 已关闭")

    def get_device_info(self) -> dict:
        """获取设备信息"""
        self._ensure_open()

        info = mDeviceInforS()
        result = self._dll_wrapper._dll.CH347GetDeviceInfor(
            self._dev_index, ctypes.byref(info)
        )
        if not result:
            raise CH347Error("获取设备信息失败")

        return {
            "device_type": info.iDeviceType,
            "chip_type": info.iChipType,
            "usb_vendor_id": f"0x{info.dwUSBVendor:04X}",
            "usb_product_id": f"0x{info.dwUSBProduct:04X}",
            "description": bytes(info.DeviceDescr).split(b"\x00")[0].decode("utf-8", errors="replace"),
        }

    # ── SPI 接口封装 ──

    def spi_stream(
        self,
        write_data: bytes,
        read_length: int = 0,
    ) -> bytes:
        """
        SPI Stream 模式读写。

        Args:
            write_data: 要发送的字节数据（如命令 + 地址）
            read_length: 需要读取的字节数

        Returns:
            读取到的字节数据
        """
        self._ensure_open()

        write_len = len(write_data)
        # 创建写入缓冲区
        WriteBuffer = (ctypes.c_ubyte * write_len)(*write_data)

        # 创建读取缓冲区
        total_read = write_len + read_length
        ReadBuffer = (ctypes.c_ubyte * total_read)()
        read_step = ctypes.c_ulong(0)
        read_size = ctypes.c_ulong(total_read)

        result = self._dll_wrapper._dll.CH347SPI_Stream(
            self._dev_index,
            write_len,                    # WriteStep
            write_len,                    # WriteSize
            WriteBuffer,                  # WriteBuffer
            ctypes.byref(read_step),      # ReadStep
            ctypes.byref(read_size),      # ReadSize
            ReadBuffer,                   # ReadBuffer
        )

        if not result:
            raise CH347Error("SPI Stream 操作失败")

        # 将 C 数组转换为 Python bytes
        return bytes(ReadBuffer[:read_size.value])

    def spi_read_flash_id(self) -> bytes:
        """
        读取 SPI Flash 的 JEDEC ID（3字节）。

        这是一个实用示例：发送 0x9F 命令，读取 3 字节返回数据。
        返回值格式：[厂商ID, 存储器类型, 容量标识]
        """
        # 0x9F 是 SPI Flash 的 RDID（Read Identification）命令
        result = self.spi_stream(write_data=b"\x9F", read_length=3)
        # 返回数据中，前 write_len 个字节是 MISO 线上的回显（通常为 0xFF）
        # 后 read_length 个字节才是有效数据
        return result[-3:] if len(result) >= 3 else result

    # ── 内部辅助方法 ──

    def _ensure_open(self) -> None:
        """确保设备已打开"""
        if not self._is_open:
            raise CH347Error("设备未打开，请先调用 open() 或使用 with 语句")

    # ── 上下文管理器 ──

    def __enter__(self):
        self.open()
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        self.close()
        return False  # 不吞掉异常

import logging

# 配置日志
logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")

# 使用上下文管理器（推荐：自动关闭设备，即使出错也能正确释放资源）
with CH347(dev_index=0) as dev:
    # 查看设备信息
    info = dev.get_device_info()
    print(f"设备: {info['description']}")
    print(f"USB VID:PID = {info['usb_vendor_id']}:{info['usb_product_id']}")

    # 读取 SPI Flash 的 JEDEC ID
    flash_id = dev.spi_read_flash_id()
    print(f"Flash JEDEC ID: {flash_id.hex(' ').upper()}")

    # 常见厂商 ID 对照：
    # EF → 华邦(Winbond)
    # C8 → 兆易创新(GigaDevice)
    # 01 → 赛普拉斯(Cypress/Infineon)
    # 20 → 美光(Micron)

# 退出 with 块时，设备自动关闭

import ctypes
from ctypes import wintypes
import logging

logger = logging.getLogger(__name__)

# ═══════════════════════════════════════════
# 第一步：定义回调函数类型
# ═══════════════════════════════════════════
# WINFUNCTYPE 对应 __stdcall 回调（如果 C 端用的是 CALLBACK / WINAPI）
# CFUNCTYPE 对应 __cdecl 回调
#
# 参数顺序：返回类型, 参数1类型, 参数2类型, ...
DataReceiveCallback = ctypes.WINFUNCTYPE(
    None,                   # 返回类型：void
    ctypes.c_ulong,         # DevIndex
    ctypes.POINTER(ctypes.c_ubyte),  # pData
    ctypes.c_ulong,         # DataLength
)


class CH347WithCallback:
    """带回调数据接收的 CH347 封装"""

    def __init__(self, dev_index: int = 0):
        self._dev_index = dev_index
        self._dll = ctypes.WinDLL("CH347DLLA64.dll")
        self._callback_ref = None  # ⚠️ 必须保存引用！

        # 声明注册回调的函数签名
        self._dll.CH347SetDataReceiveCallback.argtypes = [
            ctypes.c_ulong,
            DataReceiveCallback,
        ]
        self._dll.CH347SetDataReceiveCallback.restype = ctypes.c_int

    def register_callback(self, handler):
        """
        注册数据接收回调。

        Args:
            handler: Python 回调函数，签名为 handler(dev_index, data_bytes)
        """
        # 定义内部 C 回调函数，将 C 数据转换为 Python 数据后调用 handler
        @DataReceiveCallback
        def _c_callback(dev_index, p_data, data_length):
            try:
                # 将 C 指针指向的内存复制为 Python bytes
                data = bytes(p_data[:data_length])
                logger.info(f"收到数据: {len(data)} 字节 → {data.hex(' ')}")
                handler(dev_index, data)
            except Exception as e:
                logger.error(f"回调函数异常: {e}")

        # ⚠️⚠️⚠️ 关键：必须保存回调函数的引用！
        # 如果不保存，Python 的垃圾回收器会回收这个函数对象，
        # 当 DLL 试图调用它时，函数已经不存在了 → 程序崩溃！
        self._callback_ref = _c_callback

        # 注册到 DLL
        result = self._dll.CH347SetDataReceiveCallback(
            self._dev_index, self._callback_ref
        )
        if not result:
            raise CH347Error("注册回调函数失败")

        logger.info("数据接收回调已注册")

# 定义你的数据处理函数
def on_data_received(dev_index: int, data: bytes):
    """处理从设备收到的数据"""
    print(f"[设备 {dev_index}] 收到 {len(data)} 字节: {data.hex(' ')}")
    # 在这里做协议解析、数据存储等

# 注册回调
dev = CH347WithCallback(dev_index=0)
dev.register_callback(handler=on_data_received)

# 之后 DLL 有数据时会自动调用 on_data_received
# 注意：保持程序运行，不要让主线程退出
import time
try:
    while True:
        time.sleep(0.1)
except KeyboardInterrupt:
    print("退出")

class CH347MultiDevice:
    """管理多个 CH347 设备实例"""

    def __init__(self, device_count: int = 1, dll_path: str | None = None):
        """
        Args:
            device_count: 需要管理的设备数量
            dll_path: DLL 路径
        """
        self._devices: dict[int, CH347] = {}
        for i in range(device_count):
            self._devices[i] = CH347(dev_index=i, dll_path=dll_path)

    def open_all(self) -> list[int]:
        """打开所有设备，返回成功打开的设备索引列表"""
        opened = []
        for idx, dev in self._devices.items():
            try:
                dev.open()
                opened.append(idx)
            except CH347Error as e:
                logger.warning(f"设备 {idx} 打开失败: {e}")
        return opened

    def close_all(self) -> None:
        """关闭所有设备"""
        for idx, dev in self._devices.items():
            try:
                dev.close()
            except Exception as e:
                logger.warning(f"设备 {idx} 关闭异常: {e}")

    def get_device(self, index: int) -> CH347:
        """获取指定索引的设备实例"""
        if index not in self._devices:
            raise KeyError(f"设备索引 {index} 不存在")
        return self._devices[index]

    def __enter__(self):
        self.open_all()
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        self.close_all()
        return False


# 使用示例：同时管理 4 个设备
with CH347MultiDevice(device_count=4) as multi:
    for i in range(4):
        dev = multi.get_device(i)
        flash_id = dev.spi_read_flash_id()
        print(f"设备 {i}: Flash ID = {flash_id.hex(' ')}")

### 3.5.3 审查要点清单（AI 生成代码的"验货指南"）

AI 生成代码后，你必须逐条检查以下要点：

#### ✅ 检查点 1：结构体字段顺序

```python
# ❌ AI 可能犯的错误：调整了字段顺序（AI 有时喜欢"优化"排列）
_fields_ = [
    ("dwUSBVendor", ctypes.c_ulong),   # 被 AI 移到了前面
    ("iDeviceType", ctypes.c_ubyte),
    # ...
]

# ✅ 正确：严格按照 .h 文件中的定义顺序
_fields_ = [
    ("iDeviceType", ctypes.c_ubyte),    # 第一个字段
    ("iChipType", ctypes.c_ubyte),      # 第二个字段
    ("dwUSBVendor", ctypes.c_ulong),    # 第三个字段
    # ...
]

# 如果 C 头文件中有 #pragma pack(1) 或 __attribute__((packed))
# 说明这个结构体是 1 字节对齐（无填充），需要设置 _pack_ = 1
class PackedStruct(ctypes.Structure):
    _pack_ = 1  # ← 关键：1字节对齐
    _fields_ = [
        ("flag", ctypes.c_ubyte),     # 偏移 0，占 1 字节
        ("value", ctypes.c_ulong),    # 偏移 1，占 4 字节（无填充）
    ]

# 如果没有 #pragma pack，使用默认对齐（通常不需要设置 _pack_）
class NormalStruct(ctypes.Structure):
    _fields_ = [
        ("flag", ctypes.c_ubyte),     # 偏移 0，占 1 字节
        # ← 编译器可能在这里填充 3 字节
        ("value", ctypes.c_ulong),    # 偏移 4，占 4 字节
    ]

┌──────────────────────────────────────────────────┐
│ Step 1: 复制 .h 文件中的关键内容                    │
│   → 只复制你需要用的函数和结构体，不需要全部         │
│   → 去掉 #ifdef、#include 等预处理指令              │
└──────────────────────┬───────────────────────────┘
                       ↓
┌──────────────────────────────────────────────────┐
│ Step 2: 喂给 AI，使用上方 Prompt 模板              │
│   → AI 生成 ctypes 映射代码                       │
│   → AI 标注可能的坑                               │
└──────────────────────┬───────────────────────────┘
                       ↓
┌──────────────────────────────────────────────────┐
│ Step 3: 逐条审查（对照 7 个检查点）                │
│   → 特别关注：结构体顺序、对齐、BOOL 类型、指针    │
└──────────────────────┬───────────────────────────┘
                       ↓
┌──────────────────────────────────────────────────┐
│ Step 4: 编写最简单的验证脚本                       │
│   → 调用一个最简单的函数（如 OpenDevice）          │
│   → 确认 DLL 能正确加载、函数能正确返回            │
└──────────────────────┬───────────────────────────┘
                       ↓
┌──────────────────────────────────────────────────┐
│ Step 5: 封装为 Pythonic 类                         │
│   → 可以再次让 AI 帮你封装（给出封装要求）          │
│   → 添加异常处理、日志、上下文管理器               │
└──────────────────────┬───────────────────────────┘
                       ↓
┌──────────────────────────────────────────────────┐
│ Step 6: 编写 pytest 测试（第10章详解）              │
│   → 对每个函数编写正常和异常路径的测试              │
│   → 用 Mock 模拟 DLL，让测试不依赖硬件             │
└──────────────────────────────────────────────────┘