API 参考手册

完整的指令与 API 文档

1. GCode 指令

1.1 运动指令

1.2 M 指令（辅助功能）

1.3 参数单位

• X, Y, Z：毫米（mm）

• F：速度，mm/s（默认按距离自动计算）

• S：暂停时间，秒（s）

2. Python API

2.1 串口通信类

from serial import Serial
import time

class DeltaRobot:
    def __init__(self, port='COM3', baudrate=115200):
        """初始化串口连接"""
        self.ser = Serial(port, baudrate, timeout=1)
        time.sleep(2)  # 等待连接

    def send(self, gcode):
        """发送 GCode 指令"""
        self.ser.write((gcode + '\n').encode())
        response = self.ser.readline().decode().strip()
        return response

    def home(self):
        """回零"""
        return self.send("G28")

    def moveto(self, x, y, z, speed=1000):
        """移动到指定位置"""
        cmd = f"G0 X{x} Y{y} Z{z} F{speed}"
        return self.send(cmd)

    def pick(self):
        """吸取（开泵 + 关阀形成真空）"""
        self.send("M121")
        self.send("M2")

    def release(self):
        """释放（开阀泄气 + 关泵）"""
        self.send("M1")
        self.send("M122")

    def close(self):
        """关闭串口"""
        self.ser.close()

# 使用示例
robot = DeltaRobot('COM3')
robot.home()
robot.moveto(10, 20, -200)
robot.close()

2.2 视觉处理 API

from ultralytics import YOLO
import cv2

class VisionDetector:
    def __init__(self, model_path='yolov8n.pt'):
        """初始化 YOLOv8 模型"""
        self.model = YOLO(model_path)

    def detect(self, frame, conf=0.5):
        """
        目标检测

        参数：
            frame: 输入图像（numpy 数组）
            conf: 置信度阈值（0.0-1.0）

        返回：
            detections: List[(x, y, w, h, class_id, confidence)]
        """
        results = self.model(frame, conf=conf)
        detections = []

        for r in results:
            boxes = r.boxes
            for box in boxes:
                x1, y1, x2, y2 = box.xyxy[0].tolist()
                w, h = x2 - x1, y2 - y1
                cx, cy = (x1 + x2) / 2, (y1 + y2) / 2
                cls = int(box.cls[0])
                conf = float(box.conf[0])

                detections.append((cx, cy, w, h, cls, conf))

        return detections

# 使用示例
detector = VisionDetector()
cap = cv2.VideoCapture(0)

ret, frame = cap.read()
detections = detector.detect(frame)

for cx, cy, w, h, cls, conf in detections:
    print(f"Object at ({cx:.0f}, {cy:.0f}), class={cls}, conf={conf:.2f}")

3. 固件 API

3.1 运动学函数

// 文件：esp32/robotGeometry.cpp

/**
 * 逆运动学：由末端执行器位置计算电机角度
 *
 * @param x0, y0, z0 末端执行器坐标（mm）
 * @param theta1, theta2, theta3 输出的电机角度（度）
 * @return 0：成功，-1：超出范围
 */
int delta_calcInverse(float x0, float y0, float z0,
                      float &theta1, float &theta2, float &theta3);

/**
 * 正运动学：由电机角度计算末端执行器位置
 *
 * @param theta1, theta2, theta3 电机角度（度）
 * @param x0, y0, z0 输出的末端执行器坐标（mm）
 * @return 0：成功，-1：无解
 */
int delta_calcForward(float theta1, float theta2, float theta3,
                      float &x0, float &y0, float &z0);

3.2 插补函数

// 文件：esp32/interpolation.cpp

class Interpolation {
public:
    // 设置插补参数
    void setInterpolation(
        float start_x, float start_y, float start_z,
        float end_x, float end_y, float end_z,
        float duration_ms
    );

    // 获取当前位置（在循环中调用）
    void getInterpolation(float &x, float &y, float &z);

    // 判断插补是否完成
    bool isFinished();
};

4. 配置文件

4.1 ESP32 配置（config.h）

// 串口通信
#define BAUD 115200

// 臂长参数（mm）
#define LOW_SHANK_LENGTH 140.0    // 未使用（见 robotGeometry.cpp）
#define HIGH_SHANK_LENGTH 281.0   // 未使用（见 robotGeometry.cpp）
#define END_EFFECTOR_OFFSET 50.0  // 末端执行器偏移

// 电机参数
#define MICROSTEPS 16             // 细分数
#define STEPS_PER_REV 200         // 每圈步数
#define MAIN_GEAR_TEETH 4.5       // 减速比

// 指令队列
#define QUEUE_SIZE 10             // 最大排队指令数

// 插补模式
#define SPEED_PROFILE 2           // 0：匀速，1：反正切，2：余弦

// 工作空间范围（mm）
#define Z_MIN -320.0              // 最低 Z
#define Z_MAX -140.0              // 最高 Z

4.2 实际臂长（robotGeometry.cpp）

⚠️ 重要： 实际臂长硬编码在 robotGeometry.cpp（第 10–11 行），不在 config.h 中。

// 文件：esp32/robotGeometry.cpp（约第 10 行）
float L = 150.0;  // 上臂长度（mm）—— 改这里
float l = 281.0;  // 下臂长度（mm）—— 改这里

4.3 Python 配置（CameraDetect.py）

# 串口设置
SERIAL_PORT = 'COM3'
BAUD_RATE = 115200

# 摄像头设置
CAMERA_ID = 0                    # 摄像头设备 ID
FRAME_WIDTH = 640               # 分辨率宽
FRAME_HEIGHT = 480              # 分辨率高

# YOLO 设置
MODEL_PATH = 'yolov8n.pt'       # 模型文件路径
CONFIDENCE_THRESHOLD = 0.5      # 检测置信度阈值

# 坐标变换
HOMOGRAPHY_MATRIX = 'homography_matrix.npy'  # 变换矩阵文件

完整 API 文档

更详细的 API 说明请查看源码注释：

• ESP32 固件（C++）—— 随硬件提供

• PC 软件（Python）—— 随硬件提供