3.11 JoggingControl

Overview

Arm::jogging is used for manual step jogging and continuous jogging. For callers, the most important concurrency rules are:

• StepMove() is synchronous.
• ContinuousMove() / MultiMove() register periodic jogging tasks.
• Stop() cancels the registered task.
• These actions reuse the dedicated network thread of the same Arm session.

3.11.1 Public Methods

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

Method	Description	Return
StepMove	Executes one step-jog action	STATUS_CODE
ContinuousMove	Starts continuous jogging for one axis	STATUS_CODE
MultiMove	Starts continuous jogging for multiple axes	STATUS_CODE
Stop	Stops the continuous jogging task	void

3.11.2 Parameter Constraints

Item	Rule
ajNum	Must not be 0 , and its absolute value must not be greater than 9
ajNumList	Must not be empty. If any element is invalid, INVALID_PARAMETER is returned
Axis meaning	The meaning of 1~9 depends on the controller's current coordinate system
Direction	A positive value means the positive direction; a negative value means the negative direction

3.11.3 StepMove Semantics

• When stepAngle > 0 , this step uses the specified angular step size.
• When stepLength > 0 , this step uses the specified linear step size.
• When both step sizes are 0 , one step action is still issued; the actual behavior follows the controller's current jogging configuration.
• If any step fails, the function returns the error code immediately and does not continue with later actions.

3.11.4 ContinuousMove / MultiMove Semantics

• The SDK registers a 50ms timer task on the Arm dedicated network thread and periodically sends continuous jogging commands.
• Starting continuous jogging again first executes Stop() , then registers the new continuous jogging task.
• Stop() cancels SDK-side continuous command sending.
• If any continuous jogging request returns a non- OK status, the timer task is canceled automatically.

3.11.5 Lifecycle Constraints

• StepMove() , ContinuousMove() , and MultiMove() all require the current Arm to be connected.
• Continuous jogging does not expose an additional application thread. For the full threading model, see 1.3-thread-model .
• Arm::Disconnect() and Arm::~Arm() implicitly execute jogging.Stop() , so callers do not need to stop jogging manually before cleanup.

3.11.6 Minimal Call Example

#include <chrono>       // Time utilities for defining the jogging duration
#include <thread>       // Sleep utility for briefly keeping continuous jogging active
#include "arm_api.h"    // Arm entry point; after connection, jogging APIs are accessed through arm.joggingControl
#include "status_code.h" // STATUS_CODE for checking SDK call results

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);
    if (stepRet != STATUS_CODE::OK) {
        return 1;
    }

    STATUS_CODE moveRet = arm.joggingControl.ContinuousMove(1);
    if (moveRet != STATUS_CODE::OK) {
        return 1;
    }

    std::this_thread::sleep_for(std::chrono::milliseconds(120));
    arm.joggingControl.Stop();
    return 0;
}

Scenario Examples

The snippets below cover single-step jogging, continuous single-axis jogging, multi-axis jogging, and stop behavior. They assume the arm object from the minimal example is already connected. Jogging commands move the robot; run them only after the motion area is safe.

Single-Step Jogging

// STATUS_CODE stepRet = arm.joggingControl.StepMove(1, 0.0, 5.0);

Single-Axis Continuous Jogging

// STATUS_CODE continuousRet = arm.joggingControl.ContinuousMove(1);
// std::this_thread::sleep_for(std::chrono::milliseconds(120));
arm.joggingControl.Stop();

Multi-Axis Continuous Jogging

// STATUS_CODE multiRet = arm.joggingControl.MultiMove(std::vector<int32_t>{1, -2});
// std::this_thread::sleep_for(std::chrono::milliseconds(120));
arm.joggingControl.Stop();

Example code:

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