ezgo 0.0.1

宇树Go2机器狗Python控制库

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

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

功能特性

• 🤖 运动控制: 支持前进、后退、转向、舞蹈等多种动作
• 📹 视频流: 实时获取机器狗摄像头画面
• 🎮 状态管理: 智能状态检测和动作切换
• 🖥️ UI界面: 提供简单的图形界面用于显示和控制
• 🔧 易于集成: 简洁的API设计，便于快速开发

安装

使用pip安装

pip install ezgo

从源码安装

git clone https://github.com/your-username/ezgo.git
cd ezgo
pip install -e .

系统要求

在安装 ezgo 之前，请确保您的系统已安装以下依赖：

# Ubuntu/Debian
sudo apt update
sudo apt install python3-opencv python3-numpy python3-pil

# CentOS/RHEL
sudo yum install opencv-python numpy Pillow

# macOS
brew install opencv

# Windows
# 请使用 pip 安装或下载预编译的二进制包
pip install opencv-python numpy Pillow

注意: ezgo 不会自动安装这些依赖，因为它们可能需要系统级安装或特定配置。

快速开始

基本使用

from ezgo import Go2

# 初始化Go2控制器
go2 = Go2(interface="enx00e0986113a6")  # 替换为你的网卡接口

# 初始化连接
if go2.init():
    print("连接成功！")
    
    # 基本动作
    go2.StandUp()        # 站立
    go2.Forward(0.3, 2)  # 向前移动2秒
    go2.TurnLeft(0.5, 1) # 左转1秒
    go2.Hello()          # 打招呼
    go2.Damp()           # 进入阻尼状态
else:
    print("连接失败！")

视频流使用

import cv2
from ezgo import Go2

# 初始化
go2 = Go2()
if go2.init():
    print("开始获取视频流...")
    
    while True:
        frame = go2.read_image()
        if frame is not None:
            cv2.imshow('Go2 Camera', frame)
            
        if cv2.waitKey(1) & 0xFF == ord('q'):
            break
    
    cv2.destroyAllWindows()

UI界面使用

from ezgo.ui import APP
from ezgo.camera import Camera
import time

# 创建UI应用
app = APP(title="Go2控制面板", width=480, height=800)

# 创建摄像头
camera = Camera(index=0)
camera.open_camera()

# 更新界面
while app.is_running:
    try:
        # 获取摄像头图像
        frame = camera.read_cv2_image()
        image_tk = camera.cv2_to_tk(frame)
        app.set_image(image_tk)
        app.set_text("系统运行正常")
        
        app.update()
        time.sleep(0.03)  # 约30FPS
    except Exception as e:
        print(f"更新界面出错: {e}")
        break

app.mainloop()

API 文档

Go2 类

主要的机器狗控制类，提供以下方法：

运动控制

• StandUp() - 站立
• StandDown() - 蹲下
• Sit() - 坐下
• Damp() - 进入阻尼状态
• BalanceStand() - 平衡站立
• StopMove() - 停止移动

移动控制

• Move(vx, vy, vyaw) - 移动控制
• Forward(speed, duration) - 向前移动
• Backward(speed, duration) - 向后移动
• Left(speed, duration) - 向左移动
• Right(speed, duration) - 向右移动
• TurnLeft(speed, duration) - 左转
• TurnRight(speed, duration) - 右转

动作控制

• Hello() - 打招呼
• Stretch() - 伸懒腰
• Content() - 开心
• Heart() - 比心
• Scrape() - 拜年作揖
• Dance1() - 舞蹈1
• Dance2() - 舞蹈2
• FrontJump() - 前跳
• FrontPounce() - 向前扑人

视频控制

• read_image() - 获取一帧图像
• open_video(width, height) - 打开视频流

Camera 类

摄像头控制类，提供以下方法：

• open_camera() - 打开摄像头
• read_cv2_image() - 读取OpenCV格式图像
• read_pil_image() - 读取PIL格式图像
• cv2_to_tk(frame) - 转换为Tkinter格式
• resize(frame, size) - 调整图像尺寸
• crop_to_square(frame) - 裁剪为正方形

APP 类

UI界面类，基于Tkinter：

• set_image(image) - 设置显示图像
• set_text(text) - 设置显示文字

项目结构

ezgo/
├── src/
│   ├── __init__.py      # 包初始化文件
│   ├── go2.py          # Go2机器狗控制类
│   ├── camera.py       # 摄像头控制类
│   └── ui.py           # UI界面类
├── pyproject.toml      # 现代Python项目配置
├── README.md          # 项目文档
├── LICENSE            # 开源协议
├── quick_update.py    # 快速更新脚本
└── .pypirc           # PyPI配置文件

开发指南

本地开发

# 克隆仓库
git clone https://github.com/your-username/ezgo.git
cd ezgo

# 安装开发依赖
pip install -e .

# 运行测试
python -m pytest tests/

发布新版本

# 更新补丁版本
python quick_update.py patch

# 更新次版本
python quick_update.py minor

# 更新主版本
python quick_update.py major

# 发布到PyPI
python quick_update.py publish

常见问题

Q: 连接机器狗失败怎么办？

A: 请检查网络连接，确保机器狗IP (192.168.123.161) 可以ping通，并确认网卡接口名称正确。

Q: 视频流无法打开？

A: 请检查GStreamer是否正确安装，以及网卡多播配置是否正确。

Q: 某些动作无法执行？

A: 请检查机器狗当前状态，某些动作需要在特定状态下才能执行。

贡献

欢迎提交 Issue 和 Pull Request！

许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

更新日志

v0.0.1 (2024-01-01)

• 初始版本发布
• 基本运动控制功能
• 视频流获取功能
• UI界面功能