# EZScara_python

**Repository Path**: openez/ezscara_python

## Basic Information

- **Project Name**: EZScara_python
- **Description**: 使用EZGRobot驱动的立柱式焊接机械手示例, 通过libezrobot.so整合底层电机驱动, 兼容INFORM格式语言, 使用Python进行驱动
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EZScara — 4轴SCARA机械手控制系统（Python 后端版）

> 基于 EZRobot 共享库 `libezrobot.so` 进程内集成的开放式 4 轴 SCARA 水平多关节机械手 Web 控制系统。
> **本仓库后端已完全 Python 化**：移除全部 C 后端源码（src/、Makefile），
> 以纯 Python 标准库实现 Web/WS/REST 服务，并通过 **ctypes** 在进程内连接 `libezrobot.so`。

## 截图与演示

### 在线控制主页（已连接 EZRobot，模式 IDLE）

![在线控制主页](screenshots/02_home_online.png)

### P3 单步拾取程序执行中（x2 最高速度倍率）

![P3程序执行中](screenshots/03_P3_running.png)

### 离线仿真主页

![离线仿真主页](screenshots/01_home_offline.png)

### 程序执行完成态

![程序执行完成](screenshots/04_P3_done.png)

---

## 功能特性

- **在线/离线双模式**：离线纯本地 3D 仿真，在线联动真实电机（`libezrobot.so` 进程内集成）
- **4 轴控制**：J1 肩部旋转 / J2 肘部旋转 / J3 Z 轴升降 / J4 末端旋转，Jog / 回零 / 设零 / 速度倍率
- **运动程序**：P1~P5 内置程序（回零/联动/拾取/分拣/完整分拣），INFORM 语言编辑器，流式执行
- **真空末端**：真空吸嘴 DO 控制（M5 开 / M4 关，映射 `digital_outputs[0].bit0`），拾取/放置时序
- **3D 仿真**：Three.js 实时场景，SCARA 机械手 + 双工作台 + 元件/目标盘，视角预设与显示开关
- **安全联锁**：急停最高优先级，软限位 + 真空/运动联锁，库核心状态快照
- **开放集成**：REST API + WebSocket + Python SDK，支持多客户端并发监视与控制

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | **Python 3（纯标准库）**：单端口 HTTP + WebSocket + REST（线程模型） |
| 电机驱动 | **`libezrobot.so` 进程内集成（Python/ctypes 方式）**，`ezserver/ezrobot.py` 定义结构体与全部 API 绑定 |
| 配置/存储 | INI（`configparser`）+ SQLite（`sqlite3`），对应 `ezserver/config.py`、`ezserver/db.py` |
| 前端 | 原生 HTML/CSS/JS + Three.js（3D 仿真） |
| SDK | Python（REST + WebSocket 封装，`python/ezscara/`，纯标准库） |
| 运行 | `python3 run.py`（无需编译，无需第三方依赖） |

## 快速开始

```bash
# 进入项目根目录（libezrobot.so 配置文件为相对路径）
cd /root/src/EZScara_python

# 直接运行（默认 sim 仿真后端，4 轴配置，端口 8091）
python3 run.py

# 或使用重启脚本（自动释放 8091 并后台运行）
bash test/restart-ezscara.sh
```

打开浏览器：`http://<host>:8091`

### 切换真机

编辑 `conf/config.ini`：

```ini
[ezrobot]
lib_config = conf/ezrobot/robot-4axis-gcode.ini   ; sim 仿真
; lib_config = conf/ezrobot/robot-igh.ini            ; IgH EtherCAT 真机
```

并将对应配置文件中 `ecat.backend` 设为 `igh`。

## 项目结构

```
EZScara_python/
├── run.py                  # Python 后端入口（替代原 src/main.c）
├── ezserver/               # Python 后端包（替代原 src/ 全部 C 代码）
│   ├── __init__.py
│   ├── config.py           # INI 配置加载（替代 core/cfg.c）
│   ├── log.py              # 日志（替代 core/log.c）
│   ├── db.py               # SQLite 存储（替代 core/db.c）
│   ├── ezrobot.py          # libezrobot.so ctypes 驱动（替代 driver/ezrobot.c）★Python方式连接
│   ├── inform.py           # INFORM 程序解析/生成
│   ├── services.py         # 业务服务层：认证/程序/执行器/WS/REST（替代 router/services.c）
│   ├── wsproto.py          # WebSocket 服务端协议（RFC 6455）
│   └── server.py           # 单端口 HTTP+WS+REST 服务器（替代 router/router.c）
├── web/                    # 前端 (index.html + js/app.js)
├── lib/                    # libezrobot.so + include/ + examples/
├── conf/                   # config.ini + ezrobot/ 配置
├── programs/               # INFORM 程序文件 (P1~P5)
├── data/                   # SQLite 运行期数据
├── python/                 # Python SDK（远程客户端）
├── test/                   # 测试与重启脚本
├── screenshots/            # 截图与演示 GIF
└── docs/                   # 开发需求文档
```

> 原 C 后端（`src/`、`Makefile`）已移除，由 `ezserver/` + `run.py` 完全替代。
> 原始工程备份：`/root/EZScara_python_backup.tar.gz`。

## 电机驱动集成（Python/ctypes 方式）

EZScara 不再有任何 C 后端代码；Python 后端通过 `ctypes` 直接加载 `libezrobot.so`
并调用其 C ABI（`init/start/enable/move_joint/status/stop`），在进程内完成全部电机控制：

```
EZScara_python 进程 (python3 run.py)
├── Web/WS/REST (ezserver/server.py, 端口 8091)
├── services.py → ezrobot.cmd_sync() → ctypes 调用
└── libezrobot.so → libezrobot_init/start/enable/move_joint/status/stop
                          └── ez_ecat 后端: sim(仿真) | igh(IgH EtherCAT)
```

## 从 C 后端移植的说明

- 全部 C 源码功能点均已等价移植：认证（MD5 token）、控制权互斥、软限位、轴参数缓存、
  INFORM 解析/生成/流式执行器、WS/REST 全部端点、SQLite 落库、状态周期推送。
- 修正了原 C 端两处缺陷：
  1. INFORM 解析把 `'Jxxxx` 注释行误当作坐标行（导致 axes[0]=1.0）——现已正确读取 `J x,y,z,w` 行；
  2. `prog_load` 返回的程序名是未初始化内存垃圾——现返回正确程序名。
- `lib/`、`conf/`、`programs/`、`web/`、`python/` 等原样保留；`libezrobot.so` 仍由 ctypes 进程内加载。

## 许可证

GPL v2 — 详见 [LICENSE](LICENSE)。