4.11 C99 Jogging Interface

Overview

C99 Jogging provides teaching motion capability. It does not expose object members; all entry points are flat functions named Arm_Jogging_* .

Interface Signatures

Arm_Jogging_StepMove

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

Item	Description
Description	Executes one step jogging motion
Request Parameters	h : ArmHandle* , C99 session handle, usually from Arm_Create() ; business APIs require connection first ajNum : int , jogging axis or direction number. The sign indicates direction. It must not be 0 , and its absolute value must not exceed 9 stepLength : double , step distance for a linear axis or Cartesian direction stepAngle : double , step angle for a joint direction
Return Value	STATUS_CODE integer value; 0 means success, other values should be handled as status codes
Notes	Triggers only one step motion. Confirm safe space around the robot before running

Arm_Jogging_ContinuousMove

int Arm_Jogging_ContinuousMove(ArmHandle* h, int ajNum);

Item	Description
Description	Starts single-axis continuous jogging
Request Parameters	h : ArmHandle* , C99 session handle, usually from Arm_Create() ; business APIs require connection first ajNum : int , jogging axis or direction number. The sign indicates direction. It must not be 0 , and its absolute value must not exceed 9
Return Value	STATUS_CODE integer value; 0 means success, other values should be handled as status codes
Notes	After this call, the robot keeps moving until Arm_Jogging_Stop() , disconnection, or handle destruction

Arm_Jogging_MultiMove

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

Item	Description
Description	Starts multi-axis continuous jogging
Request Parameters	h : ArmHandle* , C99 session handle, usually from Arm_Create() ; business APIs require connection first ajNumList : const int* , array of jogging axis or direction numbers. Each element follows the same rules as ajNum count : size_t , number of array elements. Must be greater than 0
Return Value	STATUS_CODE integer value; 0 means success, other values should be handled as status codes
Notes	Used for jogging multiple axes at the same time. The caller must keep the array valid for the duration of the call

Arm_Jogging_Stop

void Arm_Jogging_Stop(ArmHandle* h);

Item	Description
Description	Stops the continuous jogging task
Request Parameters	h : ArmHandle* , C99 session handle, usually from Arm_Create() ; business APIs require connection first
Return Value	No return value
Notes	Safe to call even when continuous jogging has not been started; useful for cleanup or safety stop

Parameters and Behavior

Item	Rule
h	Must not be null
ajNum	Must not be 0 ; absolute value must not exceed 9
stepLength	Step distance for a linear axis or Cartesian direction
stepAngle	Step angle for a joint direction
ajNumList	Must not be null when count > 0
count	Returns INVALID_PARAMETER when 0
Axis meaning	1~9 correspond to axis or direction IDs in the controller's current coordinate system and jogging mode
Direction	Positive values mean positive direction; negative values mean negative direction

Behavior conventions:

• When not connected, motion functions return OTHER_ERR .
• Arm_Jogging_Stop() can be called safely even when no continuous jogging task is running.
• Arm_Jogging_StepMove() is one synchronous step. When stepAngle > 0 , it uses the angular step; when stepLength > 0 , it uses the linear step.
• When both step values are 0 , one step motion is still issued, and the actual step follows the controller's current teaching configuration.
• ContinuousMove() / MultiMove() register a 50ms periodic task on the current session's dedicated network thread.
• Starting continuous jogging again stops the existing continuous jogging task first, then registers the new task.
• If a continuous jogging request returns a non- 0 value, the SDK cancels continuous sending.
• Arm_Disconnect() / Arm_Destroy() implicitly stop continuous jogging tasks.

Minimal Call Example

#include "c_arm_api.h" // C99 SDK umbrella header

int main(void)
{
    ArmHandle* h = Arm_Create();
    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);
    Arm_Jogging_Stop(h);
    Arm_Disconnect(h);
    Arm_Destroy(h);
    return ret == 0 ? 0 : 1;
}

Scenario Examples

The snippets below assume there is already a connected ArmHandle* h . Continuous jogging keeps the robot moving, so confirm site safety before running it.

Single-Axis Step

int ret = Arm_Jogging_StepMove(h, 1, 0.0, 5.0);
(void)ret;

Single-Axis Continuous Jogging

int ret = Arm_Jogging_ContinuousMove(h, 1);
Arm_Jogging_Stop(h);
(void)ret;

Multi-Axis Continuous Jogging

int axes[2] = {1, -2};
int ret = Arm_Jogging_MultiMove(h, axes, 2);
Arm_Jogging_Stop(h);
(void)ret;

Example code:

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