# ezgo - 宇树Go2机器狗Python控制库

[![PyPI version](https://badge.fury.io/py/ezgo.svg)](https://badge.fury.io/py/ezgo)
[![Python versions](https://img.shields.io/pypi/pyversions/ezgo.svg)](https://pypi.org/project/ezgo/)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

这是一个用于控制宇树Go2机器狗的Python库，提供了简单易用的API接口。支持运动控制、视频流获取、声光控制等功能。

## 功能特性

- 🚶 **运动控制**: 支持行走、跑步、跳跃等多种运动模式
- 📷 **摄像头控制**: 支持图片获取和视频流处理
- 🔊 **声光控制**: 支持LED灯光和音量控制
- 🎮 **UI界面**: 提供图形化控制界面
- 🔧 **易于使用**: 简洁的API设计，支持懒加载
- 📦 **可选依赖**: 核心功能轻量，按需安装依赖

## 安装

### 基础安装（仅核心库，无强制依赖）
```bash
pip install ezgo
```

### 完整功能安装（包含所有可选依赖）
```bash
pip install ezgo[full]
n```

### 仅基础功能（图像处理相关依赖）
```bash
pip install ezgo[basic]
```

> **注意**: `ezgo` 核心库本身没有任何强制依赖。所有依赖都是可选的，您可以根据需要手动安装：
> - `unitree-sdk2py`: 机器人通信必需
> - `opencv-python`: 摄像头功能必需  
> - `numpy`: 数值计算支持
> - `Pillow`: 图像处理支持
> - `netifaces`: �络接口检测

## 快速开始

### 基本运动控制

```python
import ezgo

# 创建Go2控制对象
robot = ezgo.Go2()

# 初始化连接
if robot.init():
    print("连接成功!")
    
    # 基本动作
    robot.Damp()          # 进入阻尼状态
    robot.BalanceStand()   # 平衡站立
    robot.StopMove()       # 停止移动
```

### 摄像头控制

```python
import ezgo

# 方法1: 通过Go2对象获取摄像头
robot = ezgo.Go2()
camera = robot.get_camera()

# 方法2: 直接使用摄像头类
camera = ezgo.Go2Camera()

# 初始化摄像头
if camera.init():
    # 获取单张图片
    image = camera.capture_image("photo.jpg")
    
    # 打开视频流
    if camera.open_video_stream():
        frame = camera.read_frame()
```

### 声光控制

```python
import ezgo

# 方法1: 通过Go2对象获取VUI控制
robot = ezgo.Go2()
vui = robot.get_vui()

# 方法2: 直接使用VUI类
vui = ezgo.Go2VUI()

# 初始化VUI
if vui.init():
    # 设置LED亮度 (0-10)
    vui.set_brightness(5)
    
    # 获取当前亮度
    success, brightness = vui.get_brightness()
    
    # 设置音量 (0-10)
    vui.set_volume(3)
```

## API 参考

### Go2 类

主要的机器狗控制类，提供运动控制和状态管理功能。

#### 主要方法

- `init()`: 初始化与Go2的连接
- `Damp()`: 进入阻尼状态
- `BalanceStand()`: 平衡站立
- `StopMove()`: 停止所有移动动作
- `get_camera()`: 获取摄像头控制对象
- `get_vui()`: 获取声光控制对象

### Go2Camera 类

摄像头控制类，提供图片获取和视频流功能。

#### 主要方法

- `init()`: 初始化摄像头连接
- `capture_image(save_path=None)`: 获取单张图片
- `open_video_stream(width=480, height=320)`: 打开视频流
- `read_frame()`: 从视频流读取一帧
- `start_stream(width=480, height=320)`: 开始后台视频流

### Go2VUI 类

声光控制类，提供LED灯光和音量控制功能。

#### 主要方法

- `init()`: 初始化VUI客户端
- `set_brightness(level)`: 设置LED亮度 (0-10)
- `get_brightness()`: 获取当前LED亮度
- `set_volume(level)`: 设置音量 (0-10)
- `get_volume()`: 获取当前音量

## 依赖要求

### 核心依赖
- Python >= 3.7

### 可选依赖

**基础功能**:
- opencv-python >= 4.5.0
- numpy >= 1.19.0
- Pillow >= 8.0.0

**完整功能**:
- netifaces >= 0.10.0
- unitree-sdk2py (需要从官方源安装)

## 注意事项

1. **网络连接**: 确保计算机与Go2机器狗在同一网络中
2. **权限要求**: 某些功能可能需要管理员权限
3. **依赖安装**: `unitree-sdk2py` 需要从宇树官方源安装
4. **接口检测**: 库会自动检测网络接口，也可手动指定

## 故障排除

### 常见问题

1. **导入错误**: 确保已安装所有必需的依赖包
2. **连接失败**: 检查网络连接和防火墙设置
3. **摄像头问题**: 确保GStreamer正确安装
4. **权限问题**: 在某些系统上可能需要管理员权限

### 依赖安装

```bash
# 安装基础依赖
pip install opencv-python numpy Pillow netifaces

# unitree-sdk2py 需要从官方源安装
# 请参考宇树官方文档
```

## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 更新日志

### v0.0.2
- 添加了 Go2Camera 摄像头控制类
- 添加了 Go2VUI 声光控制类
- 优化了导入和错误处理
- 改进了文档和示例

### v0.0.1
- 初始版本发布
- 基本运动控制功能
- UI界面支持

## 链接

- [PyPI 项目页面](https://pypi.org/project/ezgo/)
- [GitHub 仓库](https://github.com/your-username/ezgo)
- [问题反馈](https://github.com/your-username/ezgo/issues)