3.11 JoggingControl 示教运动

概述

Arm::joggingControl 用于手动控制机器人做步进示教和连续点动。 对调用方来说，它最重要的并发语义是：

• StepMove() 是同步调用
• ContinuousMove() / MultiMove() 会注册周期性点动任务
• Stop() 负责取消该任务
• 这些动作复用同一个 Arm 会话的专用网络线程

3.11.1 公开方法

StepMove(int32_t ajNum, Float64 stepLength = 0.0, Float64 stepAngle = 0.0) -> STATUS_CODE
ContinuousMove(int32_t ajNum) -> STATUS_CODE
MultiMove(const std::vector<int32_t>& ajNumList) -> STATUS_CODE
Stop() -> void

方法	说明	返回
StepMove	单次步进示教	STATUS_CODE
ContinuousMove	启动单轴连续点动	STATUS_CODE
MultiMove	启动多轴连续点动	STATUS_CODE
Stop	停止持续点动任务	void

3.11.2 参数约束

项	规则
ajNum	不能为 0 ，且绝对值不能超过 9
ajNumList	不能为空；任一元素非法即返回 INVALID_PARAMETER
轴语义	1~9 的具体轴含义由控制器当前坐标系决定
正负方向	正值表示正方向，负值表示负方向

3.11.3 StepMove 语义

• stepAngle > 0 时，本次步进会使用传入的角度步长。
• stepLength > 0 时，本次步进会使用传入的直线步长。
• 两个步长都为 0 时，仍会发起一次步进动作，实际行为由控制器当前示教配置决定。
• 任一步骤失败立即返回错误码，不继续后续动作。

3.11.4 ContinuousMove / MultiMove 语义

• SDK 会在 Arm 专用网络线程上注册一个 50ms 的定时任务， 周期性下发连续点动命令。
• 重复启动时会先执行一次 Stop() ，再注册新的持续点动任务
• Stop() 负责取消 SDK 侧的持续下发
• 若某次持续点动请求返回非 OK ，该定时任务会自动取消

3.11.5 生命周期约束

• StepMove() 、 ContinuousMove() 、 MultiMove() 都依赖当前 Arm 已连接
• 持续点动不额外暴露独立业务线程，具体线程模型见 1.3-thread-model
• Arm::Disconnect() 与 Arm::~Arm() 会隐式执行 jogging.Stop() ， 调用方无需手动先停

3.11.6 最小调用示例

#include <chrono>  // 引入时间工具，用于构造点动持续时间
#include <thread>  // 引入线程休眠工具，用于短暂保持连续点动
#include "arm_api.h"  // 引入 Arm 主入口，连接后通过 arm.joggingControl 访问点动接口
#include "status_code.h"  // 引入 STATUS_CODE，用于检查 SDK 调用结果
int main()  // 示例程序入口
{  // 进入示例主函数
    Arm arm;  // 创建机器人会话对象
    STATUS_CODE connectRet = arm.Connect("192.168.110.2", "");  // 连接控制器，示教器地址留空表示使用默认规则
    if (connectRet != STATUS_CODE::OK) {  // 判断连接是否失败
        return 1;  // 连接失败时直接退出
    }  // 结束连接结果判断
    STATUS_CODE stepRet = arm.joggingControl.StepMove(1, 0.0, 5.0);  // 让 1 号轴按 5 度步长执行一次步进示教
    if (stepRet != STATUS_CODE::OK) {  // 判断步进示教是否失败
        return 1;  // 步进失败时返回错误码
    }  // 结束步进结果判断
    STATUS_CODE moveRet = arm.joggingControl.ContinuousMove(1);  // 启动 1 号轴正方向连续点动
    if (moveRet != STATUS_CODE::OK) {  // 判断连续点动启动是否失败
        return 1;  // 启动失败时返回错误码
    }  // 结束连续点动启动判断
    std::this_thread::sleep_for(std::chrono::milliseconds(120));  // 保持连续点动约 120 毫秒
    arm.joggingControl.Stop();  // 停止持续点动任务
    return 0;  // 示例正常结束
}  // 结束示例主函数

场景化示例

下面几组片段按 “单步、连续点动、多轴点动、停止” 交叉覆盖本页 API。片段默认承接最小调用示例里已经连接成功的 arm 对象；点动会驱动机器人运动，确认安全后再执行。

单步点动

// STATUS_CODE stepRet = arm.joggingControl.StepMove(1, 0.0, 5.0);  // 单次步进会驱动指定轴运动，确认安全后再执行

单轴连续点动

// STATUS_CODE continuousRet = arm.joggingControl.ContinuousMove(1);  // 单轴连续点动会持续驱动机器人，确认安全后再执行
// std::this_thread::sleep_for(std::chrono::milliseconds(120));  // 连续点动启动后短暂等待一段时间
arm.joggingControl.Stop();  // 停止当前持续点动任务

多轴连续点动

// STATUS_CODE multiRet = arm.joggingControl.MultiMove(std::vector<int32_t>{1, -2});  // 多轴连续点动会持续驱动多个轴，确认安全后再执行
// std::this_thread::sleep_for(std::chrono::milliseconds(120));  // 多轴点动启动后短暂等待一段时间
arm.joggingControl.Stop();  // 再次调用 Stop，确保持续点动任务被取消

示例代码

cpp17/jogging_basic/src/main.cpp

#include "step_move/run.h"
#include "continuous_move/run.h"
#include "multi_move/run.h"

int main(void)
{
    // [ZH] 默认只调用一个门面方法；如需体验其他接口，请把下一行替换成下面任意一行。
    // [EN] The main function calls only one facade by default. Replace the next line with any line below to try other APIs.
    return RunJoggingBasicStepMove();
    // return RunJoggingBasicContinuousMove();
    // return RunJoggingBasicMultiMove();
}

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;
}