# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 开发者约束要求

### 语言与地区
- **主要交互语言**: 中文（简体）
- **开发者所在地**: 中国大陆
- **时区**: GMT+8（北京时间）

### AI Agent交互规范
- 使用中文进行所有AI Agent交互和代码解释
- 文档和注释可以使用英文（保持与现有代码库风格一致）
- 技术术语遵循行业标准翻译

### 代码库使用注意事项
- 本项目是一个开源Go库，主要用于跨平台串口通信
- 遵守BSD 3-clause开源许可证
- 保持代码的跨平台兼容性和简洁性
- 所有修改需要通过GitHub PR流程进行

## Project Overview

**go-serial** is a cross-platform serial port communication library for Go. It provides a simple and consistent API for accessing serial ports on Windows, macOS, Linux, and other Unix-like systems.

## Key Features

- Cross-platform support (Windows, macOS, Linux, FreeBSD, OpenBSD)
- Simple API for opening and configuring serial ports
- Support for modem control lines (RTS, DTR, CTS, DSR, etc.)
- USB device enumeration with VID/PID and serial number detection
- Read/write timeout support
- Parity, data bits, stop bits configuration
- Break signal support

## Package Structure

```
go-serial/
├── serial.go              # Core API definition (Port interface, Mode, errors)
├── serial_*.go            # Platform-specific implementations (windows, darwin, linux, bsd, wasm)
├── enumerator/            # USB serial port enumeration with detailed info
│   ├── enumerator.go      # Core enumerator API
│   └── usb_*.go          # Platform-specific USB enumeration
├── portlist/             # Simple port listing implementation
├── unixutils/            # Unix-specific utility functions
└── *.test.go             # Example and test files
```

## Core API

### Opening a Serial Port

```go
import "go.bug.st/serial"

mode := &serial.Mode{
    BaudRate: 115200,
    Parity: serial.EvenParity,
    DataBits: 7,
    StopBits: serial.OneStopBit,
}
port, err := serial.Open("/dev/ttyUSB0", mode)
if err != nil {
    log.Fatal(err)
}
defer port.Close()
```

### Reading and Writing

```go
// Write data
n, err := port.Write([]byte("Hello"))
if err != nil {
    log.Fatal(err)
}

// Read data with timeout
buff := make([]byte, 100)
port.SetReadTimeout(5 * time.Second)
n, err := port.Read(buff)
if err != nil {
    log.Fatal(err)
}
```

### Getting Port List

```go
// Simple port list
ports, err := serial.GetPortsList()

// Detailed port list with USB info
import "go.bug.st/serial/enumerator"
ports, err := enumerator.GetDetailedPortsList()
for _, port := range ports {
    if port.IsUSB {
        fmt.Printf("USB Port: %s (VID:%s PID:%s Serial:%s)\n",
            port.Name, port.VID, port.PID, port.SerialNumber)
    }
}
```

## Common Commands

### Testing

```bash
go test -v ./...              # Run all tests
go test -v ./enumerator       # Run enumerator tests specifically
```

### Documentation

```bash
go doc go.bug.st/serial       # Show package documentation
go doc go.bug.st/serial.Port  # Show Port interface documentation
```

### Generating Windows Syscall Bindings

```bash
cd go-serial
go generate
```

## Platform-Specific Notes

- **Windows**: Uses Windows API for serial communication, supports most USB-to-serial adapters
- **macOS**: Uses IOKit framework (requires cgo) for USB enumeration
- **Linux**: Supports standard serial ports and USB-to-serial devices via `/dev/tty*`
- **Unix-like systems**: Use termios API for configuration
- **Wasm**: Limited support (enumeration not implemented)

## Recent Changes

The repository has recent commits related to:
- Fixing serial port getter methods
- Making Windows internal constants private
- Fixing incorrect masks for modem status bits on Windows
- Renaming variables to match documentation
- Windows port enumeration improvements
- **Linux系统下串口Close方法深度优化**：
  - 优化了资源释放顺序，先释放独占访问权，再关闭实际的端口句柄
  - 添加了句柄有效性检查，避免对无效句柄进行操作
  - 确保所有资源都能正确清理，包括句柄和信号管道
  - 改进了错误处理机制，确保只返回第一个错误
  - 为所有方法添加了端口状态检查，确保在端口关闭后立即返回PortClosed错误
  - 统一了错误处理格式，使用PortError类型包装系统错误
  - 优化了Read方法的错误处理和超时逻辑
  - 为Write、Break、SetMode、SetDTR、SetRTS和GetModemStatusBits方法添加了端口状态检查

## License

BSD 3-clause license - see LICENSE file for details.