4.4 C99 Motion APIs

Overview

The C99 Motion APIs cover global velocity and acceleration, current TF/UF/TCS selection, pose queries and conversion, DH parameters, basic motion, position control, drag teaching, soft limits, UDP feedback, and payload management.

Header files:

• include/c_arm_motion.h
• include/c_arm_types.h

Prerequisites and Scope of Effect

Category	Description
Session requirement	Every API requires a valid ArmHandle* . Except for create, connect, and disconnect APIs, call Arm_Connect() successfully before service calls.
Output parameters	double* , int* , structure pointers, and array outputs are allocated by the caller. Read output contents only when the return value is 0 .
Parameter writes	SetOVC , SetOAC , SetTF , SetUF , and SetTCS change current controller motion parameters or coordinate-system selection.
Motion execution	MoveJoint , MoveLine , MoveCircle , position control, trajectory dragging, and payload-identification APIs change the on-site robot state.
Array capacity	GetDHParam , GetUserSoftLimit , and Payload_GetAll use outArray + maxCount + outCount ; insufficient maxCount is reported through the status code.

API Signatures

Arm_Motion_GetOVC

int Arm_Motion_GetOVC(ArmHandle* h, double* outValue);

Item	Description
Description	Reads the global velocity override OVC.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first outValue : double* , output velocity ratio, in the range 0~1
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_SetOVC

int Arm_Motion_SetOVC(ArmHandle* h, double value);

Item	Description
Description	Sets the global velocity override OVC.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first value : double , velocity ratio, in the range 0~1 and greater than 0
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_GetOAC

int Arm_Motion_GetOAC(ArmHandle* h, double* outValue);

Item	Description
Description	Reads the global acceleration override OAC.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first outValue : double* , output acceleration ratio, in the range 0~1.2
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_SetOAC

int Arm_Motion_SetOAC(ArmHandle* h, double value);

Item	Description
Description	Sets the global acceleration override OAC.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first value : double , acceleration ratio, in the range 0.01~1.2
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_GetTF

int Arm_Motion_GetTF(ArmHandle* h, int* outIndex);

Item	Description
Description	Reads the current tool frame TF number.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first outIndex : int* , output tool-frame number, in the range 0~50
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_SetTF

int Arm_Motion_SetTF(ArmHandle* h, int index);

Item	Description
Description	Sets the current tool frame TF number.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first index : int , tool-frame number, in the range 0~50
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_GetUF

int Arm_Motion_GetUF(ArmHandle* h, int* outIndex);

Item	Description
Description	Reads the current user frame UF number.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first outIndex : int* , output user-frame number, in the range 0~50
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_SetUF

int Arm_Motion_SetUF(ArmHandle* h, int index);

Item	Description
Description	Sets the current user frame UF number.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first index : int , user-frame number, in the range 0~50
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_GetTCS

int Arm_Motion_GetTCS(ArmHandle* h, int* outType);

Item	Description
Description	Reads the current teaching coordinate-system type.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first outType : int* , output teaching coordinate-system type; see ArmTcsType for values
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_SetTCS

int Arm_Motion_SetTCS(ArmHandle* h, int tcsType);

Item	Description
Description	Sets the current teaching coordinate-system type.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first tcsType : int , teaching coordinate-system type; see ArmTcsType for values
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_GetCurrentPose

int Arm_Motion_GetCurrentPose(ArmHandle* h, int poseType, ArmMotionPose* outPose);

Item	Description
Description	Reads the current robot pose. Joint and Cartesian poses are supported.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first poseType : int , pose type, either ARM_POSE_TYPE_JOINT or ARM_POSE_TYPE_CART outPose : ArmMotionPose* , pose output-structure pointer
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_ConvertJointToCart

int Arm_Motion_ConvertJointToCart(ArmHandle* h, const ArmMotionPose* inPose, int ufIndex, int tfIndex, ArmMotionPose* outPose);

Item	Description
Description	Converts a joint pose to a Cartesian pose.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first inPose : const ArmMotionPose* , input pose or point-structure pointer ufIndex : int , user-frame number tfIndex : int , tool-frame number outPose : ArmMotionPose* , pose output-structure pointer
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_ConvertCartToJoint

int Arm_Motion_ConvertCartToJoint(ArmHandle* h, const ArmMotionPose* inPose, int ufIndex, int tfIndex, ArmMotionPose* outPose);

Item	Description
Description	Converts a Cartesian pose to a joint pose. When inPose->hasPosture is non-zero, posture participates in the solution.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first inPose : const ArmMotionPose* , input pose or point-structure pointer ufIndex : int , user-frame number tfIndex : int , tool-frame number outPose : ArmMotionPose* , pose output-structure pointer
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_ConvertCartToJointSimple

int Arm_Motion_ConvertCartToJointSimple(ArmHandle* h, const ArmMotionPose* inPose, int ufIndex, int tfIndex, ArmMotionPose* outPose);

Item	Description
Description	Converts a Cartesian pose to a joint pose. This API always ignores posture and hasPosture , and solves only from the 6D Cartesian position.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first inPose : const ArmMotionPose* , input pose or point-structure pointer ufIndex : int , user-frame number tfIndex : int , tool-frame number outPose : ArmMotionPose* , pose output-structure pointer
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_GetDHParam

int Arm_Motion_GetDHParam(ArmHandle* h, ArmDhParam* outDhArray, size_t maxCount, size_t* outCount);

Item	Description
Description	Reads the DH parameter list.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first outDhArray : ArmDhParam* , DH parameter output array maxCount : size_t , output array capacity, expressed as the maximum number of elements the caller can receive outCount : size_t* , output-count pointer; on success, receives the actual number of elements
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_SetDHParam

int Arm_Motion_SetDHParam(ArmHandle* h, const ArmDhParam* dhArray, size_t count);

Item	Description
Description	Writes the DH parameter list.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first dhArray : const ArmDhParam* , DH parameter input array count : size_t , number of array elements
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_MoveJoint

int Arm_Motion_MoveJoint(ArmHandle* h, const ArmMotionPose* pose, double vel, double acc);

Item	Description
Description	Moves the robot TCP to the target point along a joint-space path.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first pose : const ArmMotionPose* , target point, either a joint pose or a Cartesian pose vel : double , velocity ratio, in the range 0~1 acc : double , acceleration ratio, in the range 0~1.2
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_MoveLine

int Arm_Motion_MoveLine(ArmHandle* h, const ArmMotionPose* pose, double vel, double acc);

Item	Description
Description	Moves the robot TCP to the target point along a straight line.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first pose : const ArmMotionPose* , target point, either a joint pose or a Cartesian pose vel : double , TCP velocity, in the range 1~4000 mm/s acc : double , acceleration ratio, in the range 0~1.2
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_MoveCircle

int Arm_Motion_MoveCircle(ArmHandle* h, const ArmMotionPose* viaPose, const ArmMotionPose* endPose, double vel, double acc);

Item	Description
Description	Moves the robot TCP along an arc defined by a via point and an end point.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first viaPose : const ArmMotionPose* , arc via-point pose endPose : const ArmMotionPose* , arc end-point pose vel : double , TCP velocity, in the range 1~4000 mm/s acc : double , acceleration ratio, in the range 0~1.2
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_EnterPositionControl

int Arm_Motion_EnterPositionControl(ArmHandle* h);

Item	Description
Description	Requests the controller to enter position control mode.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions
Notes	Uses controller axis group 1 fixed.

Arm_Motion_SetPositionTrajectoryParams

int Arm_Motion_SetPositionTrajectoryParams(ArmHandle* h, int maxTimeoutCount, int timeout, int filterLayer, double wristElbowThreshold, double shoulderThreshold);

Item	Description
Description	Sets trajectory parameters for position control mode.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first maxTimeoutCount : int , maximum timeout count, range [1, 100] timeout : int , timeout or send interval, range [1, 100] , in ms filterLayer : int , filter level, range [1, 100] wristElbowThreshold : double , wrist/elbow near-singularity threshold, range [10, 100] shoulderThreshold : double , shoulder near-singularity threshold, range [100, 300]
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions
Notes	If a parameter is outside its valid range, the SDK returns INVALID_PARAMETER before sending the request.

Arm_Motion_ExitPositionControl

int Arm_Motion_ExitPositionControl(ArmHandle* h);

Item	Description
Description	Requests the controller to exit position control mode.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions
Notes	Uses controller axis group 1 fixed.

Arm_Motion_EnableDrag

int Arm_Motion_EnableDrag(ArmHandle* h, int dragState);

Item	Description
Description	Enables or disables drag teaching.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first dragState : int , 1 enters drag state, and 0 exits drag state
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_GetDragSet

int Arm_Motion_GetDragSet(ArmHandle* h, ArmDragStatus* outStatus);

Item	Description
Description	Reads drag-teaching axis-lock status. Axis lock applies only to teaching motion.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first outStatus : ArmDragStatus* , status output pointer
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_SetDragStatus

int Arm_Motion_SetDragStatus(ArmHandle* h, const ArmDragStatus* dragStatus);

Item	Description
Description	Writes drag-teaching axis-lock status. Axis lock applies only to teaching motion.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first dragStatus : const ArmDragStatus* , drag-teaching configuration-structure pointer
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_GetUserSoftLimit

int Arm_Motion_GetUserSoftLimit(ArmHandle* h, ArmSoftLimit* outArray, size_t maxCount, size_t* outCount);

Item	Description
Description	Reads robot user soft limits, returning the lower and upper limit for each axis.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first outArray : ArmSoftLimit* , output array allocated by the caller maxCount : size_t , output array capacity, expressed as the maximum number of elements the caller can receive outCount : size_t* , output-count pointer; on success, receives the actual number of elements
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions
Notes	The array output is allocated by the caller. maxCount is the capacity, and outCount returns the actual count.

Arm_Motion_SetUdpFeedbackParams

int Arm_Motion_SetUdpFeedbackParams(ArmHandle* h, int flag, const char* ip, int interval, int feedbackType, const int* doList, size_t doCount);

Item	Description
Description	Configures UDP feedback parameters so the robot pushes data to the specified IP address.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first flag : int , whether to enable UDP data push, 1 enables it and 0 disables it ip : const char* , receiver IP address string interval : int , send interval in milliseconds feedbackType : int , feedback data format: 0 for XML, 1 for JSON, 2 for PROTO doList : const int* , DO signal list; may be NULL doCount : size_t , number of DO signals, at most 10
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions
Notes	Parameter settings take effect only when UDP data push is enabled.

Payload APIs

Arm_Motion_Payload_GetCurrentId

int Arm_Motion_Payload_GetCurrentId(ArmHandle* h, int* outPayloadId);

Item	Description
Description	Reads the currently active payload ID.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first outPayloadId : int* , output pointer for the current payload ID
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_Payload_GetById

int Arm_Motion_Payload_GetById(ArmHandle* h, int payloadId, ArmPayloadInfo* outPayload);

Item	Description
Description	Reads payload details by ID.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first payloadId : int , payload ID outPayload : ArmPayloadInfo* , payload-info output-structure pointer
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_Payload_SetCurrentId

int Arm_Motion_Payload_SetCurrentId(ArmHandle* h, int payloadId);

Item	Description
Description	Activates the specified payload ID.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first payloadId : int , payload ID
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_Payload_Add

int Arm_Motion_Payload_Add(ArmHandle* h, const ArmPayloadInfo* payloadInfo);

Item	Description
Description	Adds a user-defined payload configuration to the controller.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first payloadInfo : const ArmPayloadInfo* , payload-info structure pointer
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_Payload_Delete

int Arm_Motion_Payload_Delete(ArmHandle* h, int payloadId);

Item	Description
Description	Deletes the user-defined payload configuration with the specified ID from the controller.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first payloadId : int , payload ID
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions
Notes	The currently active payload cannot be deleted directly. To delete it, activate another payload first.

Arm_Motion_Payload_Update

int Arm_Motion_Payload_Update(ArmHandle* h, const ArmPayloadInfo* payload);

Item	Description
Description	Updates an existing user-defined payload configuration on the controller.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first payload : const ArmPayloadInfo* , payload-info structure pointer
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_Payload_GetAll

int Arm_Motion_Payload_GetAll(ArmHandle* h, ArmPayloadSummary* outArray, size_t maxCount, size_t* outCount);

Item	Description
Description	Reads the payload summary list. Each summary contains id and comment .
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first outArray : ArmPayloadSummary* , output array allocated by the caller maxCount : size_t , output array capacity, expressed as the maximum number of elements the caller can receive outCount : size_t* , output-count pointer; on success, receives the actual number of elements
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions
Notes	The array output is allocated by the caller. maxCount is the capacity, and outCount returns the actual count.

Arm_Motion_Payload_CheckAxisThreeHorizontal

int Arm_Motion_Payload_CheckAxisThreeHorizontal(ArmHandle* h, double* outValue);

Item	Description
Description	Checks the robot axis-3 horizontal angle, in degrees.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first outValue : double* , output-value pointer
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions
Notes	The horizontal angle must be between -1~1 degrees before payload identification can be performed.

Arm_Motion_Payload_InterferenceCheck

int Arm_Motion_Payload_InterferenceCheck(ArmHandle* h, double weight, double angle);

Item	Description
Description	Starts the interference check for payload identification.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first weight : double , payload weight angle : double , axis-6 rotation angle, in the range 30~90 degrees
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_Payload_IdentifyStart

int Arm_Motion_Payload_IdentifyStart(ArmHandle* h);

Item	Description
Description	Enters payload-identification preparation state.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_Payload_StartIdentify

int Arm_Motion_Payload_StartIdentify(ArmHandle* h, double weight, double angle);

Item	Description
Description	Starts the payload-identification process.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first weight : double , payload weight; pass -1 when unknown angle : double , allowed axis-6 rotation angle, in the range 30~90 degrees
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions
Notes	The controller must enter payload-identification preparation state before payload identification starts.

Arm_Motion_Payload_GetIdentifyState

int Arm_Motion_Payload_GetIdentifyState(ArmHandle* h, int* outState);

Item	Description
Description	Queries payload-identification state.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first outState : int* , status output pointer
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_Payload_GetIdentifyResult

int Arm_Motion_Payload_GetIdentifyResult(ArmHandle* h, ArmPayloadInfo* outPayload);

Item	Description
Description	Reads the payload-identification result.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first outPayload : ArmPayloadInfo* , payload-info output-structure pointer
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_Payload_IdentifyDone

int Arm_Motion_Payload_IdentifyDone(ArmHandle* h);

Item	Description
Description	Leaves payload-identification preparation state.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions

Arm_Motion_Payload_Identify

int Arm_Motion_Payload_Identify(ArmHandle* h, double weight, double angle, ArmPayloadInfo* outPayload);

Item	Description
Description	Runs one complete payload-identification flow and outputs the result.
Request parameters	h : ArmHandle* , C99 session handle, usually created by Arm_Create() ; service APIs require a successful connection first weight : double , payload weight; pass -1 when unknown angle : double , axis-6 rotation angle, in the range 30~90 degrees outPayload : ArmPayloadInfo* , payload-info output-structure pointer
Return value	Integer STATUS_CODE ; 0 means success, and other values should be handled according to the status-code definitions
Notes	The output payload result can be used to add a payload or update an existing payload configuration on the controller.

Types and Rules

Type	Description
ArmMotionPose	C99 pose structure; poseType determines whether joint or cartesian is used
ArmPoseType	ARM_POSE_TYPE_JOINT means joint pose, and ARM_POSE_TYPE_CART means Cartesian pose
ArmTcsType	Teaching coordinate-system type, used by Arm_Motion_SetTCS()
ArmDragStatus	Drag-teaching axis-lock state
ArmSoftLimit	User soft limit for a single axis
ArmPayloadInfo	Complete payload information
ArmPayloadSummary	Payload-list summary
ArmPayloadIdentifyState	Payload-identification state

Category	Rule
Global parameters	OVC is the velocity ratio. Read range is 0~1 ; write range is 0~1 and greater than 0 . OAC is the acceleration ratio. Read range is 0~1.2 ; write range is 0.01~1.2 .
Coordinate-system numbers	TF and UF numbers are in the range 0~50 ; switching coordinate systems affects later pose conversion and motion execution.
Pose structure	ArmMotionPose.poseType indicates whether joint or cartesian is used; jointSize and cartesianSize indicate the valid lengths of the corresponding arrays.
Pose conversion	Input and output pose structures are both allocated by the caller; pass 0 when no specific user/tool frame is required.
Drag state	ArmDragStatus.cartStatus[6] and jointStatus[9] represent Cartesian-axis and joint-axis teaching states, and isContinuousDrag indicates whether continuous drag is enabled.
Array outputs	GetDHParam , GetUserSoftLimit , and Payload_GetAll use outArray + maxCount + outCount ; prepare sufficient capacity for the expected business case.
Action APIs	MoveJoint , MoveLine , MoveCircle , position control, drag, and payload identification change the on-site state.
UDP feedback	doList is an optional DO list, and doCount is the number of elements, at most 10 .

Compatibility

Feature	Collaborative robot	Industrial robot
Global parameters, coordinate systems, pose conversion, basic motion	v7.5.0.0+	v7.5.0.0+
DH parameters	v7.5.0.0+	Not supported
Drag teaching	v7.5.0.0+	Not supported
User soft limits	v7.5.0.0+	v7.5.0.0+
UDP feedback parameters	v7.5.2.0+	Not supported
Payload query and configuration	v7.5.0.0+	v7.5.0.0+
Payload identification	v7.5.2.0+	Not supported

Payload Identification Flow

Step	C99 API	Description
1	Arm_Motion_Payload_CheckAxisThreeHorizontal	Checks the axis-3 horizontal angle, and continues after the horizontal condition is satisfied.
2	Arm_Motion_Payload_IdentifyStart	Enters payload-identification preparation state.
3	Arm_Motion_Payload_StartIdentify	Passes the payload weight and axis-6 rotation angle to start identification.
4	Arm_Motion_Payload_GetIdentifyState	Queries identification state.
5	Arm_Motion_Payload_GetIdentifyResult	Reads the identification result.
6	Arm_Motion_Payload_IdentifyDone	Leaves payload-identification preparation state.
One-step flow	Arm_Motion_Payload_Identify	Runs the full flow and outputs ArmPayloadInfo .

Minimal Example

#include <stdio.h>  // Provides printf for printing the velocity ratio.
#include "c_arm_api.h"  // Includes the aggregate C99 SDK header.
int main(void)  // Example program entry point.
{  // Enters the example main function.
    ArmHandle* h = Arm_Create();  // Creates a C99 session handle.
    double ovc = 0.0;  // Prepares the OVC output variable.
    if (h == NULL) {  // Checks whether handle creation failed.
        return 1;  // Exits when creation fails.
    }  // Ends the handle check.
    if (Arm_Connect(h, "10.27.1.2", "10.27.1.102") != 0) {  // Connects to the controller.
        Arm_Destroy(h);  // Releases the handle after connection failure.
        return 1;  // Returns an error.
    }  // Ends the connection check.
    int ret = Arm_Motion_GetOVC(h, &ovc);  // Reads the global velocity ratio.
    printf("ovc=%f\n", ovc);  // Prints the global velocity ratio.
    Arm_Disconnect(h);  // Disconnects from the controller.
    Arm_Destroy(h);  // Destroys the handle.
    return ret == 0 ? 0 : 1;  // Returns according to the read result.
}  // Ends the example main function.

Scenario Examples

Read and Set Motion Parameters

double ovc = 0.0;  // Prepares the velocity-ratio output.
double oac = 0.0;  // Prepares the acceleration-ratio output.
int tf = 0;  // Prepares the tool-frame number output.
int uf = 0;  // Prepares the user-frame number output.
int tcs = 0;  // Prepares the teaching coordinate-system output.
int ovcRet = Arm_Motion_GetOVC(h, &ovc);  // Reads OVC.
int oacRet = Arm_Motion_GetOAC(h, &oac);  // Reads OAC.
int tfRet = Arm_Motion_GetTF(h, &tf);  // Reads the current TF.
int ufRet = Arm_Motion_GetUF(h, &uf);  // Reads the current UF.
int tcsRet = Arm_Motion_GetTCS(h, &tcs);  // Reads the current TCS.
/* int setOvcRet = Arm_Motion_SetOVC(h, ovc); */  // Writing the velocity ratio changes motion parameters; execute only after confirmation.
/* int setOacRet = Arm_Motion_SetOAC(h, oac); */  // Writing the acceleration ratio changes motion parameters; execute only after confirmation.
/* int setTfRet = Arm_Motion_SetTF(h, tf); */  // Writing TF changes the current tool frame; execute only after confirmation.
/* int setUfRet = Arm_Motion_SetUF(h, uf); */  // Writing UF changes the current user frame; execute only after confirmation.
/* int setTcsRet = Arm_Motion_SetTCS(h, tcs); */  // Writing TCS changes the teaching coordinate system; execute only after confirmation.
(void)ovcRet;  // Keeps the status code in this example.
(void)oacRet;  // Keeps the status code in this example.
(void)tfRet;  // Keeps the status code in this example.
(void)ufRet;  // Keeps the status code in this example.
(void)tcsRet;  // Keeps the status code in this example.

Pose and Conversion

ArmMotionPose jointPose = {0};  // Prepares the joint pose.
ArmMotionPose cartPose = {0};  // Prepares the Cartesian pose.
int poseRet = Arm_Motion_GetCurrentPose(h, ARM_POSE_TYPE_JOINT, &jointPose);  // Gets the current joint pose.
int jointToCartRet = Arm_Motion_ConvertJointToCart(h, &jointPose, 0, 0, &cartPose);  // Converts joint to Cartesian.
int cartToJointRet = Arm_Motion_ConvertCartToJoint(h, &cartPose, 0, 0, &jointPose);  // Converts Cartesian to joint.
int simpleRet = Arm_Motion_ConvertCartToJointSimple(h, &cartPose, 0, 0, &jointPose);  // Performs simplified Cartesian-to-joint conversion.
(void)poseRet;  // Keeps the status code in this example.
(void)jointToCartRet;  // Keeps the status code in this example.
(void)cartToJointRet;  // Keeps the status code in this example.
(void)simpleRet;  // Keeps the status code in this example.

Motion, DH, Position Control, Drag, and Payload

ArmDhParam dh[9] = {0};  // Prepares the DH parameter array.
size_t dhCount = 0U;  // Prepares the DH count output.
ArmSoftLimit limits[9] = {0};  // Prepares the soft-limit array.
size_t limitCount = 0U;  // Prepares the soft-limit count output.
ArmDragStatus drag = {0};  // Prepares the drag-status structure.
ArmPayloadSummary payloads[16] = {0};  // Prepares the payload-summary array.
size_t payloadCount = 0U;  // Prepares the payload count output.
int dhRet = Arm_Motion_GetDHParam(h, dh, 9, &dhCount);  // Reads DH parameters.
int limitRet = Arm_Motion_GetUserSoftLimit(h, limits, 9, &limitCount);  // Reads user soft limits.
int dragRet = Arm_Motion_GetDragSet(h, &drag);  // Reads drag status.
int payloadRet = Arm_Motion_Payload_GetAll(h, payloads, 16, &payloadCount);  // Queries the payload list.
/* int moveJRet = Arm_Motion_MoveJoint(h, &jointPose, 20.0, 20.0); */  // Joint motion moves the robot; execute only after confirmation.
/* int moveLRet = Arm_Motion_MoveLine(h, &cartPose, 20.0, 20.0); */  // Linear motion moves the robot; execute only after confirmation.
/* int moveCRet = Arm_Motion_MoveCircle(h, &cartPose, &cartPose, 20.0, 20.0); */  // Arc motion moves the robot; execute only after confirmation.
/* int enterPositionRet = Arm_Motion_EnterPositionControl(h); */  // Entering position control changes the control mode; execute only after confirmation.
/* int setPositionParamRet = Arm_Motion_SetPositionTrajectoryParams(h, 10, 10, 5, 20.0, 120.0); */  // Writing position-control parameters changes trajectory parameters; execute only after confirmation.
/* int exitPositionRet = Arm_Motion_ExitPositionControl(h); */  // Exiting position control changes the control mode; execute only after confirmation.
/* int setDhRet = Arm_Motion_SetDHParam(h, dh, dhCount); */  // Writing DH parameters changes kinematic parameters; execute only after confirmation.
/* int enableDragRet = Arm_Motion_EnableDrag(h, 1); */  // Enabling drag changes the control mode; execute only after confirmation.
/* int setDragRet = Arm_Motion_SetDragStatus(h, &drag); */  // Writing drag status changes drag settings; execute only after confirmation.
(void)dhRet;  // Keeps the status code in this example.
(void)limitRet;  // Keeps the status code in this example.
(void)dragRet;  // Keeps the status code in this example.
(void)payloadRet;  // Keeps the status code in this example.

Sample code

c99/motion_basic/src/main.cpp

#include <stdio.h>
#include <string.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_motion] 创建句柄失败 / 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_motion] 连接失败 / Connect failed, 状态码 / Status code: %d\n", ret);
        Arm_Destroy(handle);
        return 1;
    }
    printf("[c99_motion] 机器人连接成功 / Robot connected successfully\n");

    // [ZH] 准备兜底位姿、DH 参数和负载数据，保证全部接口都能直接调用。
    // [EN] Prepare fallback poses, DH params, and payload data so every API can be called directly.
    ArmMotionPose jointPose = {0};
    ArmMotionPose cartPose = {0};
    ArmMotionPose convertedPose = {0};
    ArmDhParam dhList[16] = {0};
    ArmSoftLimit softLimits[16] = {0};
    ArmDragStatus dragStatus = {0};
    ArmPayloadInfo payload = {0};
    ArmPayloadInfo identifyPayload = {0};
    ArmPayloadSummary payloadList[16] = {0};
    size_t dhCount = 0U;
    size_t softLimitCount = 0U;
    size_t payloadCount = 0U;
    int payloadId = 1;
    int identifyState = 0;
    double ovc = 0.0;
    double oac = 0.0;
    int tf = 0;
    int uf = 0;
    int tcs = ARM_TCS_JOINT;
    int doList[2] = {1, 2};
    jointPose.poseType = ARM_POSE_TYPE_JOINT;
    jointPose.jointSize = 6;
    cartPose.poseType = ARM_POSE_TYPE_CART;
    cartPose.cartesianSize = 6;
    payload.id = 1;
    payload.weight = 1.0;
    payload.massCenter[0] = 0.1;
    payload.massCenter[1] = 0.0;
    payload.massCenter[2] = 0.0;
    snprintf(payload.comment, sizeof(payload.comment), "sdk example");
    dhList[0].id = 1;
    dhCount = 1U;

    // [ZH] 顺序执行运动查询与设置接口。
    // [EN] Execute motion query APIs and setter APIs in sequence.
    ret = Arm_Motion_GetOVC(handle, &ovc);
    printf("[c99_motion] GetOVC 状态码 / GetOVC status code: %d, OVC=%.6f\n", ret, ovc);
    ret = Arm_Motion_SetOVC(handle, ovc);
    printf("[c99_motion] SetOVC 状态码 / SetOVC status code: %d\n", ret);
    ret = Arm_Motion_GetOAC(handle, &oac);
    printf("[c99_motion] GetOAC 状态码 / GetOAC status code: %d, OAC=%.6f\n", ret, oac);
    ret = Arm_Motion_SetOAC(handle, oac);
    printf("[c99_motion] SetOAC 状态码 / SetOAC status code: %d\n", ret);
    ret = Arm_Motion_GetTF(handle, &tf);
    printf("[c99_motion] GetTF 状态码 / GetTF status code: %d, TF=%d\n", ret, tf);
    ret = Arm_Motion_SetTF(handle, tf);
    printf("[c99_motion] SetTF 状态码 / SetTF status code: %d\n", ret);
    ret = Arm_Motion_GetUF(handle, &uf);
    printf("[c99_motion] GetUF 状态码 / GetUF status code: %d, UF=%d\n", ret, uf);
    ret = Arm_Motion_SetUF(handle, uf);
    printf("[c99_motion] SetUF 状态码 / SetUF status code: %d\n", ret);
    ret = Arm_Motion_GetTCS(handle, &tcs);
    printf("[c99_motion] GetTCS 状态码 / GetTCS status code: %d, TCS=%d\n", ret, tcs);
    ret = Arm_Motion_SetTCS(handle, tcs);
    printf("[c99_motion] SetTCS 状态码 / SetTCS status code: %d\n", ret);

    // [ZH] 读取当前关节位姿和笛卡尔位姿，并调用全部位姿转换接口。
    // C API 对外笛卡尔顺序统一为 X/Y/Z/A/B/C。
    // [EN] Read the current joint and Cartesian poses, then call all pose conversion APIs.
    // The C API exposes Cartesian order as X/Y/Z/A/B/C.
    ret = Arm_Motion_GetCurrentPose(handle, ARM_POSE_TYPE_JOINT, &jointPose);
    printf("[c99_motion] GetCurrentPose(JOINT) 状态码 / GetCurrentPose(JOINT) status code: %d, 关节维度 / Joint size: %d\n", ret, jointPose.jointSize);
    ret = Arm_Motion_GetCurrentPose(handle, ARM_POSE_TYPE_CART, &cartPose);
    printf("[c99_motion] GetCurrentPose(CART) 状态码 / GetCurrentPose(CART) status code: %d, 笛卡尔维度 / Cartesian size: %d\n", ret, cartPose.cartesianSize);
    ret = Arm_Motion_ConvertJointToCart(handle, &jointPose, uf, tf, &convertedPose);
    printf("[c99_motion] ConvertJointToCart 状态码 / ConvertJointToCart status code: %d\n", ret);
    ret = Arm_Motion_ConvertCartToJoint(handle, &cartPose, uf, tf, &convertedPose);
    printf("[c99_motion] ConvertCartToJoint 状态码 / ConvertCartToJoint status code: %d\n", ret);
    ret = Arm_Motion_ConvertCartToJointSimple(handle, &cartPose, uf, tf, &convertedPose);
    printf("[c99_motion] ConvertCartToJointSimple 状态码 / ConvertCartToJointSimple status code: %d\n", ret);

    // [ZH] 读取并写回 DH 参数、软限位和 UDP 反馈参数。
    // [EN] Read and write back the DH params, soft limits, and UDP feedback params.
    ret = Arm_Motion_GetDHParam(handle, dhList, 16U, &dhCount);
    printf("[c99_motion] GetDHParam 状态码 / GetDHParam status code: %d, 数量 / Count: %zu\n", ret, dhCount);
    ret = Arm_Motion_SetDHParam(handle, dhList, dhCount > 0U ? dhCount : 1U);
    printf("[c99_motion] SetDHParam 状态码 / SetDHParam status code: %d\n", ret);
    ret = Arm_Motion_GetUserSoftLimit(handle, softLimits, 16U, &softLimitCount);
    printf("[c99_motion] GetUserSoftLimit 状态码 / GetUserSoftLimit status code: %d, 数量 / Count: %zu\n", ret, softLimitCount);
    ret = Arm_Motion_SetUdpFeedbackParams(handle, 0, "127.0.0.1", 20, 1, doList, 2U);
    printf("[c99_motion] SetUdpFeedbackParams 状态码 / SetUdpFeedbackParams status code: %d\n", ret);
    ret = Arm_Motion_EnterPositionControl(handle);
    printf("[c99_motion] EnterPositionControl 状态码 / EnterPositionControl status code: %d\n", ret);
    ret = Arm_Motion_SetPositionTrajectoryParams(handle, 3, 20, 2, 30.0, 150.0);
    printf("[c99_motion] SetPositionTrajectoryParams 状态码 / SetPositionTrajectoryParams status code: %d\n", ret);
    ret = Arm_Motion_ExitPositionControl(handle);
    printf("[c99_motion] ExitPositionControl 状态码 / ExitPositionControl status code: %d\n", ret);

    // [ZH] 直接执行全部运动接口。
    // [EN] Execute all motion APIs directly.
    ret = Arm_Motion_MoveJoint(handle, &jointPose, 10.0, 10.0);
    printf("[c99_motion] MoveJoint 状态码 / MoveJoint status code: %d\n", ret);
    ret = Arm_Motion_MoveLine(handle, &cartPose, 50.0, 10.0);
    printf("[c99_motion] MoveLine 状态码 / MoveLine status code: %d\n", ret);
    ret = Arm_Motion_MoveCircle(handle, &cartPose, &cartPose, 50.0, 10.0);
    printf("[c99_motion] MoveCircle 状态码 / MoveCircle status code: %d\n", ret);

    // [ZH] 顺序执行全部拖动示教接口。
    // [EN] Execute all drag-teaching APIs in sequence.
    ret = Arm_Motion_GetDragSet(handle, &dragStatus);
    printf("[c99_motion] GetDragSet 状态码 / GetDragSet status code: %d, 连续拖动 / Continuous drag: %d\n", ret, dragStatus.isContinuousDrag);
    ret = Arm_Motion_EnableDrag(handle, dragStatus.isContinuousDrag);
    printf("[c99_motion] EnableDrag 状态码 / EnableDrag status code: %d\n", ret);
    ret = Arm_Motion_SetDragStatus(handle, &dragStatus);
    printf("[c99_motion] SetDragStatus 状态码 / SetDragStatus status code: %d\n", ret);

    // [ZH] 顺序执行全部负载接口。
    // [EN] Execute all payload APIs in sequence.
    ret = Arm_Motion_Payload_GetCurrentId(handle, &payloadId);
    printf("[c99_motion] Payload_GetCurrentId 状态码 / Payload_GetCurrentId status code: %d, 当前负载 / Current payload id: %d\n", ret, payloadId);
    ret = Arm_Motion_Payload_GetById(handle, payloadId, &payload);
    printf("[c99_motion] Payload_GetById 状态码 / Payload_GetById status code: %d, comment=%s\n", ret, payload.comment);
    ret = Arm_Motion_Payload_SetCurrentId(handle, payloadId);
    printf("[c99_motion] Payload_SetCurrentId 状态码 / Payload_SetCurrentId status code: %d\n", ret);
    ret = Arm_Motion_Payload_Add(handle, &payload);
    printf("[c99_motion] Payload_Add 状态码 / Payload_Add status code: %d\n", ret);
    ret = Arm_Motion_Payload_Update(handle, &payload);
    printf("[c99_motion] Payload_Update 状态码 / Payload_Update status code: %d\n", ret);
    ret = Arm_Motion_Payload_Delete(handle, payload.id);
    printf("[c99_motion] Payload_Delete 状态码 / Payload_Delete status code: %d\n", ret);
    ret = Arm_Motion_Payload_GetAll(handle, payloadList, 16U, &payloadCount);
    printf("[c99_motion] Payload_GetAll 状态码 / Payload_GetAll status code: %d, 数量 / Count: %zu\n", ret, payloadCount);
    double axisThree = 0.0;
    ret = Arm_Motion_Payload_CheckAxisThreeHorizontal(handle, &axisThree);
    printf("[c99_motion] Payload_CheckAxisThreeHorizontal 状态码 / Payload_CheckAxisThreeHorizontal status code: %d, 值 / Value: %.6f\n", ret, axisThree);
    ret = Arm_Motion_Payload_InterferenceCheck(handle, payload.weight, 0.0);
    printf("[c99_motion] Payload_InterferenceCheck 状态码 / Payload_InterferenceCheck status code: %d\n", ret);
    ret = Arm_Motion_Payload_IdentifyStart(handle);
    printf("[c99_motion] Payload_IdentifyStart 状态码 / Payload_IdentifyStart status code: %d\n", ret);
    ret = Arm_Motion_Payload_StartIdentify(handle, payload.weight, 0.0);
    printf("[c99_motion] Payload_StartIdentify 状态码 / Payload_StartIdentify status code: %d\n", ret);
    ret = Arm_Motion_Payload_GetIdentifyState(handle, &identifyState);
    printf("[c99_motion] Payload_GetIdentifyState 状态码 / Payload_GetIdentifyState status code: %d, 状态 / State: %d\n", ret, identifyState);
    ret = Arm_Motion_Payload_GetIdentifyResult(handle, &identifyPayload);
    printf("[c99_motion] Payload_GetIdentifyResult 状态码 / Payload_GetIdentifyResult status code: %d, weight=%.6f\n", ret, identifyPayload.weight);
    ret = Arm_Motion_Payload_IdentifyDone(handle);
    printf("[c99_motion] Payload_IdentifyDone 状态码 / Payload_IdentifyDone status code: %d\n", ret);
    ret = Arm_Motion_Payload_Identify(handle, payload.weight, 0.0, &identifyPayload);
    printf("[c99_motion] Payload_Identify 状态码 / Payload_Identify status code: %d, weight=%.6f\n", ret, identifyPayload.weight);

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