codroid-robot-sdk 2.0.0

No project description provided

Codroid Robot Python SDK

Codroid 机器人 Python 软件开发工具包。支持 TCP 指令控制、实时数据 (CRI) 监控以及运动路径规划。

---

Table of Contents

• Codroid Robot Python SDK
  • Table of Contents
  • 🚀 快速开始
    • 1. 前置条件
    • 2. 获取代码与初始化
    • 3. 运行示例程序
  • Installation
  • Basic Usage
• 🛠️ Hatch 开发工作流
  • 进入开发 Shell
  • 构建项目
  • 文档预览
• 📂 目录结构说明
  • License

🚀 快速开始

1. 前置条件

• Python: 3.8 及以上版本。
• Hatch: 本项目使用 Hatch 作为项目管理工具。

安装 Hatch:

pipx install hatch
# 或者使用 pip (如果系统允许)
pip install hatch

2. 获取代码与初始化

git clone <your-repo-url>
cd CodroidPython

若系统仅有 python3 命令（常见于 Debian/Ubuntu），下文请将 python 换成 python3，或使用 hatch shell 后按 Hatch 环境内的解释器为准。

3. 运行示例程序

使用 Hatch 运行示例是最简单的方法，它会自动处理所有依赖和环境路径。

# 运行基础使用示例
hatch run python examples/01_basic_usage.py

Installation

pip install codroid-robot-sdk

Basic Usage

from codroid import CodroidControlInterface

# Initialize and connect automatically (CodroidSession + synchronous JsonStreamClient)
with CodroidControlInterface(host="192.168.1.136") as robot:
    robot.to_remote()
    robot.switch_on()

需要 后台收包、id 配对、Publish 按 ty 分发 时，请使用 CodroidClient（内部为 TransportClient）：

from codroid import CodroidClient

with CodroidClient(host="192.168.1.136") as robot:
    robot.to_remote()
    robot.switch_on()

🛠️ Hatch 开发工作流

本项目采用了现代 Python 的 src 布局，建议通过以下命令进行开发：

进入开发 Shell

如果你想在一个持久的虚拟环境中工作，可以进入 Hatch Shell：

hatch shell
# 进入 shell 后直接运行 python
python examples/01_basic_usage.py

构建项目

生成可分发的 .whl 和 .tar.gz 文件：

hatch build

文档预览

本项目配置了 mkdocs 文档环境：

# 启动本地文档服务器
hatch run docs:serve

📂 目录结构说明

源码布局与 C# SDK（CodroidSDK/*.cs）同名模块一一对应（Python 为 snake_case + .py）。详细演进见仓库根目录 plan.md。

src/codroid/
├── __init__.py              # 公开 API 聚合导出
├── __about__.py             # 版本号
├── Codroid.py               # CodroidSession；CodroidControlInterface 别名
├── client.py                # CodroidClient（TransportClient + 门面）
├── async_tcp_client.py      # JsonStreamClient、TransportClient / FutureTcpClient
├── define.py                # DTO / 常量（Define.cs）
├── types.py                 # DTO 再导出（便于与文档表述一致）
├── exceptions.py            # CodroidCommandException、网络/超时等
├── utils.py                 # 共用工具
├── console.py               # PrintBanner 等
├── publish.py               # CodroidPublish.cs
├── trajectory.py            # Trajectory.cs
├── cri_realtime_packet_parser.py   # CriRealtimePacketParser.cs（含 CriStreamHandler）
└── cri_realtime_dispatcher.py      # CriRealtimeDispatcher.cs

下列文件在 2.0 计划 中与 C# 对齐，业务将从 Codroid.py 拆出后落盘（当前可能尚未存在）：global_variables.py、io.py、register.py、robot_kinematics.py、robot_motion.py。

• examples/: 示例程序。
• pyproject.toml: Hatch / 构建配置。
• 契约与算法文档：AGENTS.md、SDK_API_AND_DESIGN.md、PROTOCOL_LINE_BY_LINE.md、TRAJECTORY_ALGORITHM.md。

License

codroid is distributed under the terms of the MIT license.