go-serial/CLAUDE.md

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交互和代码解释
• 文档和注释可以使用英文（保持与现有代码库风格一致）
• 技术术语遵循行业标准翻译

Git提交规范

• 提交信息必须包含中文说明：确保每个commit都有清晰的中文描述
• 提交信息格式：<类型>: <主题>，主题使用中文
• 提交信息应简洁明了，准确描述变更内容
• 类型可以是：feat(新功能)、fix(修复)、docs(文档)、style(样式)、refactor(重构)、test(测试)、chore(构建过程或辅助工具的变动)

代码库使用注意事项

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

代码库使用注意事项

• 本项目是一个开源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

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

// 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

// 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

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

Documentation

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

Generating Windows Syscall Bindings

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.