# EZRobot **Repository Path**: openez/ezrobot ## Basic Information - **Project Name**: EZRobot - **Description**: 机械手关节底层库, 基于igH+Ruckig + KDL / DLS / TRAC-IK构建, 支持tcp远程控制, 提供web仿真, 提供python版sdk - **Primary Language**: Unknown - **License**: GPL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-31 - **Last Updated**: 2026-09-03 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # EZRobot 一个面向 **单/多轴机械臂** 的实时运动控制运行时：以 C 为核心，桥接成熟的 C++ 运动学/轨迹规划开源库，提供 REST / TCP / WebSocket 网络接口与 Python SDK，并自带一个原生 JS 的 Web 控制台与离线仿真前端。 > 版本：v0.1.0 ｜ 语言规范：**C 优先**，仅 KDL / Ruckig / urdfdom / TRAC-IK 经 C++ 桥接（对外暴露纯 C ABI）。 --- ## 1. 它能做什么 - **运动控制**：`move_joint`（关节空间）、`move_pose`（笛卡尔空间，IK 求解）、`home`、`run_gcode`、`program` 程序执行。 - **运动学**：urdfdom 解析 → KDL 链；FK / 双求解器竞速 IK（KDL + TRAC-IK），欠自由度链自动走 TRAC-IK；FK 复核 + 广义可操作度（奇点检测）。 - **轨迹规划**：Ruckig 时间最优 / jerk 受限 OTG，多段轨迹队列无缝拼接。 - **EtherCAT 后端抽象**：`sim` 后端（完整仿真，默认开）；`igh` 后端（IgH EtherCAT Master，条件编译，仅当环境有 `ecrt.h` 时编入）。CiA 402 状态机、PDO 映射、DC 同步。 - **网络接口**：REST（llhttp + cJSON）、TCP 命令流（cJSON）、WebSocket 状态推送（RFC6455 自实现帧，20 Hz），统一进 core 指令队列。 - **安全机制**：Token 鉴权、TCP 心跳保活/超时踢除、输入严格校验、急停（CiA402 quick stop）、限位/伺服故障归因。 - **Python SDK**：本地（pybind11）/ TCP / HTTP / Async 四模式，自动重连（运动命令不重放）。 - **Web 控制台**：远程操作 + 鉴权 + 两个离线仿真演示页（`sim/6axis/`、`sim/scara/`）入口。 --- ## 2. 架构概览 ``` ┌────────────────────────────────────────────────────────────┐ │ ez_app（main, src/app）：线程编排 / 绑核 / 配置装载 / 生命周期 │ ├────────────────────────────────────────────────────────────┤ │ ez_net（libuv） ez_webui(web/ 静态) │ │ REST / TCP / WS 状态推送 │ ├────────────────────────────────────────────────────────────┤ │ ez_core（C） 控制状态机 / 指令队列 / G-code 执行器 / 安全联锁 │ ├────────────────────────────────────────────────────────────┤ │ ez_kin（C ABI + C++ 桥） ez_traj（C ABI + C++ 桥） │ │ urdfdom→KDL / FK / 竞速 IK / 奇点 Ruckig OTG / 轨迹队列 │ ├────────────────────────────────────────────────────────────┤ │ ez_ecat（C） 后端 vtable：sim（完整）｜igh（EZ_HAVE_IGH） │ │ CiA 402 状态机 / PDO / DC 同步抽象 │ ├────────────────────────────────────────────────────────────┤ │ ez_rt（SPSC 队列 / 线程亲和 / 时钟） │ │ ez_cfg（json-c 配置） ez_log（zlog 薄封装） ez_err（错误码） │ └────────────────────────────────────────────────────────────┘ └── python/（CPython SDK）：pybind11 本地 + 纯 Python 远程客户端 ``` **线程模型**（实时性关键）： | 线程 | 优先级 | 默认亲和 | 职责 | |------|--------|----------|------| | rt_cycle | SCHED_FIFO 95 | CPU2 | 1 kHz：取指令 → 插补 → 后端写目标 → 读反馈 → 联锁 → 发布状态 | | ik_a / ik_b | 50 | CPU1 / CPU1 | 双求解器竞速（原子标志仲裁 + 超时） | | core | 40 | CPU3 | 状态机、G-code → 指令流、IK 请求 | | net | 30 | CPU3 | REST / TCP / WS | 实时路径内禁止：malloc、文件 I/O、mutex、系统调用（除时钟）；跨层通信一律走 `ez_rt` SPSC 环形队列，rt 线程 `mlockall` 锁定内存。 --- ## 3. 目录结构 ``` EZRobot/ ├── CMakeLists.txt # 顶层构建（所有模块定义集中于此） ├── conf/ezrobot/ # 运行配置（robot.json / robot-4axis.json / robot-igh.json + .urdf） ├── include/ez/ # 公共 C 头文件（对外 ABI） ├── src/ │ ├── rt/ log/ cfg/ err/ # 基础设施 │ ├── ecat/ # EtherCAT 后端抽象（sim + igh） │ ├── kin/ traj/ # 运动学（C++ 桥）/ 轨迹规划 │ ├── gcode/ # G-code 解析器（纯 C） │ ├── core/ # 应用控制层（状态机 / 联锁 / 执行器） │ └── net/ app/ # 网络服务层 / 集成可执行 ezrobot ├── third_party/ # vendored：ruckig、trac_ik ├── python/ezrobot/ # SDK（pybind11 桥 + 纯 Python 客户端） ├── web/ # 静态前端（原生 JS）+ sim/ 仿真演示页 ├── tests/ # cmocka 单测 + 集成冒烟（net_api_smoke / sdk_smoke） ├── scripts/ # rt_tune.sh / check_ethercat.sh / 标定工具 ├── packaging/ # systemd 单元（ezrobot.service / ezrobot-rt-tune.service） └── docs/ # 设计 / 任务 / 失败记录 / 未完成 / 实时部署 ``` --- ## 4. 构建 环境要求：Linux + PREEMPT_RT 内核（实时场景）；gcc/clang；CMake ≥ 3.16；以下 apt 依赖： ``` libuv-dev libllhttp-dev libcjson-dev libjson-c-dev libzlog-dev \ liborocos-kdl-dev libnlopt-cxx-dev liburdfdom-dev libcmocka-dev \ pybind11-dev ``` ```bash cmake -B build # 默认：sim ON / ECAT OFF / tests ON / python ON cmake --build build -j ctest --test-dir build --output-on-failure # 全部单测 + 集成冒烟 ``` 构建矩阵： | 配置 | 选项 | 目标 | |------|------|------| | 本机仿真 | `-DEZ_ENABLE_SIM=ON`（默认） | 开发/测试全链路 | | 真机 | `-DEZ_ENABLE_ECAT=ON` + IgH 头文件/库 | ARM/实时部署 | | SDK | `-DEZ_BUILD_PYTHON=ON`（默认） | python/ezrobot | | 测试 | `-DEZ_BUILD_TESTS=ON`（默认） | ctest | --- ## 5. 快速开始（仿真） ```bash # 1) 启动运行时（sim 后端，6 轴） ./build/ezrobot conf/ezrobot/robot.ini # 2) 健康检查 curl -s localhost:8080/api/health # 3) Python SDK（本地模式） PYTHONPATH=build/python python3 -c " import ezrobot r = ezrobot.Robot('conf/ezrobot/robot.ini') r.enable(); r.home(); r.move_joint([0.1, 0.0, 0.0, 0.0, 0.0, 0.0]) print(r.get_status()) " # 4) Web 控制台：浏览器打开 web/ezrobot/index.html（或 http://localhost:8080/） # 含两个离线仿真演示页 web/ezrobot/sim/6axis/ 与 web/ezrobot/sim/scara/ ``` 4 轴仿真示例：`conf/ezrobot/robot-4axis.ini`（无需硬件即可回归 4 轴链运动学）。 --- ## 6. 主要 API 速览 网络层（REST 8080 / TCP 5000）： - `GET /api/health`、`GET /api/status` — 健康/状态快照 - `POST /api/control/enable|disable|reset|estop|pause|resume` - `POST /api/move/joint`、`POST /api/move/pose`、`POST /api/home` - `POST /api/gcode`（G0/1/2/3/4/20/21/90/91/F/M）、`POST /api/program[/:id]` - `GET /POST /api/params`、`POST /api/kin/inverse`、`GET /api/logs`、`GET /api/openapi.json` - WebSocket `/ws`（或 `/`）20 Hz 状态推送，支持 `subscribe`/`unsubscribe` SDK：`Robot`（本地）/ `RobotClient.connect`（TCP）/ `connect_http`（REST）/ `AsyncRobotClient`，统一 `EzRobotError(code, message)`、`wait_state` 轮询、上下文管理器。 --- ## 7. 当前状态（已完成 / 未完成） **已完成**（详见 `docs/TASKS.md`、`docs/失败记录.md`）： 全部核心模块（T01–T13）已收官——RT 实时链路、sim/igh 双后端、运动学与轨迹规划、G-code、core 控制状态机与安全联锁、REST/TCP/WS 网络、Python SDK 四模式 + 重连、运行环境（systemd / 标定脚本）、仿真参数可配置、G-code 关节坐标 + M 代码动作、mlockall、net/ik SCHED_FIFO 等均已落地并回归 `ctest 7/7`、`net_api_smoke 110`、`sdk_smoke 46`。 **未完成 / 现场阻塞**（详见 `docs/未完成.md`）： - **F8 Web 可视化编程**：拖拽式动作编程、G-code 语法高亮、参数面板、实时曲线、3D 预览未实现（控制台仅遥控 + 鉴权）。 - **真机联调（M9，4 轴 Leadshine 2CL3-EC507）**：j4 位置环增益（0x608F）整定（当前掉轴 ≈0.39 rad，首要阻塞）、60FD 限位/急停接线位号、回差标定、DC 相位 PLL 微调。 - **技术债务**：net.c 非实时线程 malloc/free（可接受）；IK 不可达目标多轮竞速重试时延。 - **ARM 交叉构建**：仓库已移除专用工具链要求，改为仅主机原生构建；aarch64 构建从未实测。 --- ## 8. 文档索引 | 文档 | 内容 | |------|------| | `docs/DEVELOPMENT.md` | 完整设计规范（分层、线程、API、部署） | | `docs/TASKS.md` | 任务分解与进度记录 | | `docs/失败记录.md` | 验收缺口 / 测试缺口 / 现场阻塞 / 明确不做的决策 | | `docs/未完成.md` | 仅未完成项清单（最新裁剪版） | | `docs/CALIBRATION.md` | 标定方法 | | `docs/RT_DEPLOY.md` | 实时部署：绑核 / 优先级 / GRUB / cyclictest 验收 | --- ## 9. License 见 `LICENSE`。