4.11 C99 Jogging 点动接口

概述

C99 Jogging 提供示教运动能力。它不暴露对象成员，所有入口都是以 Arm_Jogging_* 命名的扁平函数。

接口签名

Arm_Jogging_StepMove

int Arm_Jogging_StepMove(ArmHandle* h, int ajNum, double stepLength, double stepAngle);

项	说明
描述	执行单次步进示教运动。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 ajNum : int ，点动轴或方向编号，正负号表示运动方向，不能为 0 ，绝对值不能超过 9 stepLength : double ，线性轴或笛卡尔方向的步进距离 stepAngle : double ，关节方向的步进角度
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理
备注	只触发一次步进运动；运行前需要确认机器人周围安全空间。

Arm_Jogging_ContinuousMove

int Arm_Jogging_ContinuousMove(ArmHandle* h, int ajNum);

项	说明
描述	启动单轴连续点动。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 ajNum : int ，点动轴或方向编号，正负号表示运动方向，不能为 0 ，绝对值不能超过 9
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理
备注	调用后机器人会持续运动，直到 Arm_Jogging_Stop() 、断开连接或销毁句柄。

Arm_Jogging_MultiMove

int Arm_Jogging_MultiMove(ArmHandle* h, const int* ajNumList, size_t count);

项	说明
描述	启动多轴连续点动。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 ajNumList : const int* ，点动轴或方向编号数组，每个元素规则同 ajNum count : size_t ，数组元素数量，必须大于 0
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理
备注	适合同时点动多轴；调用方需要保证数组在调用期间有效。

Arm_Jogging_Stop

void Arm_Jogging_Stop(ArmHandle* h);

项	说明
描述	停止持续点动任务。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
返回值	无返回值
备注	未启动持续点动时也可以调用，用于收尾或安全停动。

参数与行为

项	规则
h	不能为空
ajNum	不能为 0 ，绝对值不能超过 9
stepLength	线性轴或笛卡尔方向步进距离
stepAngle	关节方向步进角度
ajNumList	count > 0 时不能为空
count	为 0 时返回 INVALID_PARAMETER
轴语义	1~9 对应控制器当前坐标系和点动模式下的轴或方向编号
正负方向	正值表示正方向，负值表示负方向

行为约定：

• 未连接时，运动类函数返回 OTHER_ERR 。
• Arm_Jogging_Stop() 未启动时也可以安全调用。
• Arm_Jogging_StepMove() 是单次同步点动； stepAngle > 0 时使用角度步长， stepLength > 0 时使用直线步长。
• 两个步长都为 0 时仍会发起一次步进动作，实际步长由控制器当前示教配置决定。
• ContinuousMove() / MultiMove() 会在当前会话的专用网络线程上注册 50ms 周期任务。
• 重复启动持续点动时，会先停止已有持续点动任务，再注册新的持续点动任务。
• 持续点动过程中如果某次请求返回非 0 ，SDK 会取消持续下发。
• Arm_Disconnect() / Arm_Destroy() 会隐式停止持续点动任务。

最小调用示例

#include "c_arm_api.h"  // 引入 C99 SDK 总头文件
int main(void)  // 示例程序入口
{  // 进入示例主函数
    ArmHandle* h = Arm_Create();  // 创建 C99 会话句柄
    if (h == NULL) {  // 判断句柄是否创建失败
        return 1;  // 创建失败时退出
    }  // 结束句柄创建判断
    if (Arm_Connect(h, "10.27.1.254", NULL) != 0) {  // 连接控制器或路由地址
        Arm_Destroy(h);  // 连接失败时销毁句柄
        return 1;  // 返回错误码
    }  // 结束连接判断
    int ret = Arm_Jogging_StepMove(h, 1, 0.0, 5.0);  // 让 1 号轴按 5 度步进一次
    Arm_Jogging_Stop(h);  // 停止可能存在的持续点动任务
    Arm_Disconnect(h);  // 断开机器人连接
    Arm_Destroy(h);  // 销毁会话句柄
    return ret == 0 ? 0 : 1;  // 根据步进结果返回示例状态
}  // 结束示例主函数

场景化示例

下面片段默认已经有连接成功的 ArmHandle* h 。连续点动会让机器人持续运动，运行前需要确认现场安全。

单轴步进

int ret = Arm_Jogging_StepMove(h, 1, 0.0, 5.0);  // 1 号轴按角度步进一次
(void)ret;  // 示例中保留返回码，实际代码应检查是否为 0

单轴连续点动

int ret = Arm_Jogging_ContinuousMove(h, 1);  // 启动 1 号轴连续点动
Arm_Jogging_Stop(h);  // 停止连续点动
(void)ret;  // 示例中保留返回码，实际代码应检查是否为 0

多轴连续点动

int axes[2] = {1, -2};  // 准备两个点动方向，正负号表示运动方向
int ret = Arm_Jogging_MultiMove(h, axes, 2);  // 启动多轴连续点动
Arm_Jogging_Stop(h);  // 停止多轴连续点动
(void)ret;  // 示例中保留返回码，实际代码应检查是否为 0

示例代码

c99/jogging_basic/src/main.cpp

#include <stdio.h>

extern "C" {
#include "c_arm_api.h"
}

int main(void)
{
    // [ZH] 本示例直接在源码中写死连接地址，不解析命令行参数。
    // [EN] This example hard-codes the connection addresses in the source code and does not parse command-line arguments.
    // [ZH] 创建并连接 SDK 句柄。
    // [EN] Create the SDK handle and connect to the robot.
    ArmHandle* handle = Arm_Create();
    if (handle == NULL) {
        printf("[c99_jogging] 创建句柄失败 / Failed to create the handle\n");
        return 1;
    }
    int ret = Arm_Connect(handle, "10.27.1.2", "10.27.1.102");
    if (ret != 0) {
        printf("[c99_jogging] 连接失败 / Connect failed, 状态码 / Status code: %d\n", ret);
        Arm_Destroy(handle);
        return 1;
    }
    printf("[c99_jogging] 机器人连接成功 / Robot connected successfully\n");

    // [ZH] 顺序执行全部点动接口。
    // [EN] Execute all jogging APIs in sequence.
    int ajNumList[2] = {1, -2};
    ret = Arm_Jogging_StepMove(handle, 1, 0.0, 5.0);
    printf("[c99_jogging] StepMove 状态码 / StepMove status code: %d\n", ret);
    ret = Arm_Jogging_ContinuousMove(handle, 1);
    printf("[c99_jogging] ContinuousMove 状态码 / ContinuousMove status code: %d\n", ret);
    Arm_Jogging_Stop(handle);
    printf("[c99_jogging] Stop 已调用 / Stop called\n");
    ret = Arm_Jogging_MultiMove(handle, ajNumList, 2U);
    printf("[c99_jogging] MultiMove 状态码 / MultiMove status code: %d\n", ret);
    Arm_Jogging_Stop(handle);
    printf("[c99_jogging] Stop 再次调用 / Stop called again\n");

    // [ZH] 断开连接并销毁句柄。
    // [EN] Disconnect and destroy the handle.
    Arm_Disconnect(handle);
    Arm_Destroy(handle);
    printf("[c99_jogging] 示例结束 / Example finished\n");
    return 0;
}