4.4 C99 Motion 运动接口

概述

C99 Motion 覆盖全局速度 / 加速度、当前 TF / UF / TCS、位姿查询与转换、DH、基础运动、位置控制、拖动示教、软限位、UDP 反馈和负载管理。

对应头文件：

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

使用前提与影响范围

类别	说明
会话要求	所有接口都需要传入有效的 ArmHandle* 。除创建、连接、断开类接口外，业务调用前应先完成 Arm_Connect() 。
输出参数	double* 、 int* 、结构体指针和数组输出都由调用方分配；返回值为 0 时才读取输出内容。
参数写入	SetOVC 、 SetOAC 、 SetTF 、 SetUF 、 SetTCS 会改变控制器当前运动参数或坐标系选择。
运动执行	MoveJoint 、 MoveLine 、 MoveCircle 、位置控制、轨迹拖动和负载测定相关接口会改变机器人现场状态。
数组容量	GetDHParam 、 GetUserSoftLimit 、 Payload_GetAll 使用 outArray + maxCount + outCount ； maxCount 不足时按状态码返回。

接口签名

Arm_Motion_GetOVC

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

项	说明
描述	读取全局速度比例 OVC。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 outValue : double* ，输出速度比例，范围为 0~1
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_SetOVC

int Arm_Motion_SetOVC(ArmHandle* h, double value);

项	说明
描述	设置全局速度比例 OVC。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 value : double ，速度比例，范围为 0~1 且大于 0
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_GetOAC

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

项	说明
描述	读取全局加速度比例 OAC。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 outValue : double* ，输出加速度比例，范围为 0~1.2
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_SetOAC

int Arm_Motion_SetOAC(ArmHandle* h, double value);

项	说明
描述	设置全局加速度比例 OAC。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 value : double ，加速度比例，范围为 0.01~1.2
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_GetTF

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

项	说明
描述	读取当前工具坐标系 TF 编号。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 outIndex : int* ，输出工具坐标系编号，范围为 0~50
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_SetTF

int Arm_Motion_SetTF(ArmHandle* h, int index);

项	说明
描述	设置当前工具坐标系 TF 编号。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 index : int ，工具坐标系编号，范围为 0~50
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_GetUF

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

项	说明
描述	读取当前用户坐标系 UF 编号。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 outIndex : int* ，输出用户坐标系编号，范围为 0~50
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_SetUF

int Arm_Motion_SetUF(ArmHandle* h, int index);

项	说明
描述	设置当前用户坐标系 UF 编号。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 index : int ，用户坐标系编号，范围为 0~50
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_GetTCS

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

项	说明
描述	读取当前示教坐标系类型。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 outType : int* ，输出示教坐标系类型，取值见 ArmTcsType
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_SetTCS

int Arm_Motion_SetTCS(ArmHandle* h, int tcsType);

项	说明
描述	设置当前示教坐标系类型。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 tcsType : int ，示教坐标系类型，取值见 ArmTcsType
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_GetCurrentPose

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

项	说明
描述	读取机器人当前位姿，支持关节位姿或笛卡尔位姿。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 poseType : int ，位姿类型， ARM_POSE_TYPE_JOINT 或 ARM_POSE_TYPE_CART outPose : ArmMotionPose* ，位姿输出结构体指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_ConvertJointToCart

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

项	说明
描述	将关节位姿转换为笛卡尔位姿。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 inPose : const ArmMotionPose* ，输入位姿或点位结构体指针 ufIndex : int ，用户坐标系编号 tfIndex : int ，工具坐标系编号 outPose : ArmMotionPose* ，位姿输出结构体指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_ConvertCartToJoint

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

项	说明
描述	将笛卡尔位姿转换为关节位姿； inPose->hasPosture 非零时使用 posture 参与求解。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 inPose : const ArmMotionPose* ，输入位姿或点位结构体指针 ufIndex : int ，用户坐标系编号 tfIndex : int ，工具坐标系编号 outPose : ArmMotionPose* ，位姿输出结构体指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_ConvertCartToJointSimple

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

项	说明
描述	将笛卡尔位姿转换为关节位姿；该接口始终忽略 posture 和 hasPosture ，只使用 6 维笛卡尔位置求解。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 inPose : const ArmMotionPose* ，输入位姿或点位结构体指针 ufIndex : int ，用户坐标系编号 tfIndex : int ，工具坐标系编号 outPose : ArmMotionPose* ，位姿输出结构体指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_GetDHParam

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

项	说明
描述	读取 DH 参数列表。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 outDhArray : ArmDhParam* ，DH 参数输出数组 maxCount : size_t ，输出数组容量，表示调用方最多可接收多少个元素 outCount : size_t* ，输出数量指针，成功时写入实际数量
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_SetDHParam

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

项	说明
描述	写入 DH 参数列表。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 dhArray : const ArmDhParam* ，DH 参数输入数组 count : size_t ，数组元素数量
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_MoveJoint

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

项	说明
描述	控制机器人末端沿关节空间路径移动到目标点位。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 pose : const ArmMotionPose* ，目标点位，可为关节位姿或笛卡尔位姿 vel : double ，速度比例，范围为 0~1 acc : double ，加速度比例，范围为 0~1.2
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_MoveLine

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

项	说明
描述	控制机器人末端沿直线移动到目标点位。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 pose : const ArmMotionPose* ，目标点位，可为关节位姿或笛卡尔位姿 vel : double ，末端速度，范围为 1~4000 mm/s acc : double ，加速度比例，范围为 0~1.2
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_MoveCircle

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

项	说明
描述	控制机器人末端沿圆弧运动，通过途经点和终点确定圆弧。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 viaPose : const ArmMotionPose* ，圆弧途经点位姿 endPose : const ArmMotionPose* ，圆弧终点位姿 vel : double ，末端速度，范围为 1~4000 mm/s acc : double ，加速度比例，范围为 0~1.2
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_EnterPositionControl

int Arm_Motion_EnterPositionControl(ArmHandle* h);

项	说明
描述	请求控制器进入位置控制模式。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理
备注	固定使用控制器轴组 1 。

Arm_Motion_SetPositionTrajectoryParams

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

项	说明
描述	设置位置控制模式下的轨迹参数。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 maxTimeoutCount : int ，最大超时次数，范围 [1, 100] timeout : int ，超时时间或发送间隔，范围 [1, 100] ，单位 ms filterLayer : int ，滤波层级，范围 [1, 100] wristElbowThreshold : double ，腕 / 肘部接近奇异点阈值，范围 [10, 100] shoulderThreshold : double ，肩部接近奇异点阈值，范围 [100, 300]
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理
备注	参数超出范围时，SDK 在发送请求前返回 INVALID_PARAMETER 。

Arm_Motion_ExitPositionControl

int Arm_Motion_ExitPositionControl(ArmHandle* h);

项	说明
描述	请求控制器退出位置控制模式。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理
备注	固定使用控制器轴组 1 。

Arm_Motion_EnableDrag

int Arm_Motion_EnableDrag(ArmHandle* h, int dragState);

项	说明
描述	开启或关闭拖动示教。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 dragState : int ， 1 进入拖动状态， 0 退出拖动状态
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_GetDragSet

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

项	说明
描述	读取拖动示教轴锁定状态；轴锁定仅针对示教运动。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 outStatus : ArmDragStatus* ，状态输出指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_SetDragStatus

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

项	说明
描述	写入拖动示教轴锁定状态；轴锁定仅针对示教运动。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 dragStatus : const ArmDragStatus* ，拖动示教配置结构体指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_GetUserSoftLimit

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

项	说明
描述	读取机器人用户软限位，返回各轴下限位和上限位。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 outArray : ArmSoftLimit* ，输出数组，由调用方分配 maxCount : size_t ，输出数组容量，表示调用方最多可接收多少个元素 outCount : size_t* ，输出数量指针，成功时写入实际数量
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理
备注	数组输出由调用方分配， maxCount 表示容量， outCount 返回实际数量。

Arm_Motion_SetUdpFeedbackParams

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

项	说明
描述	配置机器人向指定 IP 地址推送数据的 UDP 反馈参数。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 flag : int ，是否开启 UDP 数据推送， 1 开启， 0 关闭 ip : const char* ，接收端 IP 地址字符串 interval : int ，发送间隔，单位为毫秒 feedbackType : int ，反馈数据格式， 0 表示 XML， 1 表示 JSON， 2 表示 PROTO doList : const int* ，DO 信号列表，可为 NULL doCount : size_t ，DO 信号数量，最多 10 个
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理
备注	参数设置仅在 UDP 数据推送功能启用时有效。

负载接口

Arm_Motion_Payload_GetCurrentId

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

项	说明
描述	读取当前激活的负载 ID。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 outPayloadId : int* ，当前负载 ID 输出指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_Payload_GetById

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

项	说明
描述	按 ID 读取负载详情。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 payloadId : int ，负载 ID outPayload : ArmPayloadInfo* ，负载信息输出结构体指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_Payload_SetCurrentId

int Arm_Motion_Payload_SetCurrentId(ArmHandle* h, int payloadId);

项	说明
描述	激活指定负载 ID。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 payloadId : int ，负载 ID
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_Payload_Add

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

项	说明
描述	向控制器新增用户自定义负载配置。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 payloadInfo : const ArmPayloadInfo* ，负载信息结构体指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_Payload_Delete

int Arm_Motion_Payload_Delete(ArmHandle* h, int payloadId);

项	说明
描述	从控制器删除指定 ID 的用户自定义负载配置。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 payloadId : int ，负载 ID
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理
备注	当前激活的负载不能直接删除；如需删除，先激活其他负载。

Arm_Motion_Payload_Update

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

项	说明
描述	更新控制器中已存在的用户自定义负载配置。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 payload : const ArmPayloadInfo* ，负载信息结构体指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_Payload_GetAll

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

项	说明
描述	读取负载摘要列表；摘要包含 id 和 comment 。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 outArray : ArmPayloadSummary* ，输出数组，由调用方分配 maxCount : size_t ，输出数组容量，表示调用方最多可接收多少个元素 outCount : size_t* ，输出数量指针，成功时写入实际数量
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理
备注	数组输出由调用方分配， maxCount 表示容量， outCount 返回实际数量。

Arm_Motion_Payload_CheckAxisThreeHorizontal

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

项	说明
描述	检测机器人 3 轴水平角度，单位为度。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 outValue : double* ，输出值指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理
备注	水平角度必须在 -1~1 度之间才能进行负载测定。

Arm_Motion_Payload_InterferenceCheck

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

项	说明
描述	开始负载测定的干涉检查。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 weight : double ，负载重量 angle : double ，6 轴转动角度，范围为 30~90 度
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_Payload_IdentifyStart

int Arm_Motion_Payload_IdentifyStart(ArmHandle* h);

项	说明
描述	进入负载测定准备状态。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_Payload_StartIdentify

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

项	说明
描述	开始负载测定过程。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 weight : double ，负载重量；未知时传 -1 angle : double ，6 轴允许转动角度，范围为 30~90 度
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理
备注	开始负载测定前必须先进入负载测定准备状态。

Arm_Motion_Payload_GetIdentifyState

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

项	说明
描述	查询负载测定状态。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 outState : int* ，状态输出指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_Payload_GetIdentifyResult

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

项	说明
描述	读取负载测定结果。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 outPayload : ArmPayloadInfo* ，负载信息输出结构体指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_Payload_IdentifyDone

int Arm_Motion_Payload_IdentifyDone(ArmHandle* h);

项	说明
描述	结束负载测定准备状态。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Motion_Payload_Identify

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

项	说明
描述	执行一次完整负载测定流程并输出结果。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 weight : double ，负载重量；未知时传 -1 angle : double ，6 轴转动角度，范围为 30~90 度 outPayload : ArmPayloadInfo* ，负载信息输出结构体指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理
备注	输出的负载结果可用于新增负载，或写入控制器中已有负载配置。

类型与规则

类型	说明
ArmMotionPose	C99 位姿结构，按 poseType 决定使用 joint 或 cartesian
ArmPoseType	ARM_POSE_TYPE_JOINT 表示关节位姿， ARM_POSE_TYPE_CART 表示笛卡尔位姿
ArmTcsType	示教坐标系类型，用于 Arm_Motion_SetTCS()
ArmDragStatus	拖动示教锁轴状态
ArmSoftLimit	单轴用户软限位
ArmPayloadInfo	负载完整信息
ArmPayloadSummary	负载列表摘要
ArmPayloadIdentifyState	负载测定状态

类别	规则
全局参数	OVC 为速度比例，读取范围 0~1 ，写入范围 0~1 且大于 0 ；OAC 为加速度比例，读取范围 0~1.2 ，写入范围 0.01~1.2 。
坐标系编号	TF 和 UF 编号范围为 0~50 ；坐标系切换会影响后续位姿转换和运动执行。
位姿结构	ArmMotionPose.poseType 指示使用 joint 或 cartesian ； jointSize 、 cartesianSize 表示对应数组有效长度。
位姿转换	输入和输出位姿结构都由调用方分配；未显式使用用户 / 工具坐标系时传 0 。
拖动状态	ArmDragStatus.cartStatus[6] 和 jointStatus[9] 表示笛卡尔轴、关节轴示教状态， isContinuousDrag 表示是否连续拖动。
数组输出	GetDHParam 、 GetUserSoftLimit 、 Payload_GetAll 使用 outArray + maxCount + outCount ；调用方应按业务预期准备足够容量。
动作型接口	MoveJoint 、 MoveLine 、 MoveCircle 、位置控制、拖动、负载识别会改变现场状态。
UDP 反馈	doList 为可选 DO 列表， doCount 表示元素数量，最多 10 个。

兼容性

功能	协作机器人	工业机器人
全局参数、坐标系、位姿转换、基础运动	v7.5.0.0+	v7.5.0.0+
DH 参数	v7.5.0.0+	不支持
拖动示教	v7.5.0.0+	不支持
用户软限位	v7.5.0.0+	v7.5.0.0+
UDP 反馈参数	v7.5.2.0+	不支持
负载查询和配置	v7.5.0.0+	v7.5.0.0+
负载测定	v7.5.2.0+	不支持

负载测定流程

步骤	C99 接口	说明
1	Arm_Motion_Payload_CheckAxisThreeHorizontal	检查 3 轴水平角度，满足水平条件后继续。
2	Arm_Motion_Payload_IdentifyStart	进入负载测定准备状态。
3	Arm_Motion_Payload_StartIdentify	传入负载重量和 6 轴转动角度，开始测定。
4	Arm_Motion_Payload_GetIdentifyState	查询测定状态。
5	Arm_Motion_Payload_GetIdentifyResult	读取测定结果。
6	Arm_Motion_Payload_IdentifyDone	结束负载测定准备状态。
一步完成	Arm_Motion_Payload_Identify	执行完整流程并输出 ArmPayloadInfo 。

最小调用示例

#include <stdio.h>  // 引入 printf，用于打印速度比例
#include "c_arm_api.h"  // 引入 C99 SDK 总头文件
int main(void)  // 示例程序入口
{  // 进入示例主函数
    ArmHandle* h = Arm_Create();  // 创建 C99 会话句柄
    double ovc = 0.0;  // 准备 OVC 输出变量
    if (h == NULL) {  // 判断句柄是否创建失败
        return 1;  // 创建失败时退出
    }  // 结束句柄判断
    if (Arm_Connect(h, "10.27.1.2", "10.27.1.102") != 0) {  // 连接控制器
        Arm_Destroy(h);  // 连接失败时释放句柄
        return 1;  // 返回错误
    }  // 结束连接判断
    int ret = Arm_Motion_GetOVC(h, &ovc);  // 读取全局速度比例
    printf("ovc=%f\n", ovc);  // 打印全局速度比例
    Arm_Disconnect(h);  // 断开连接
    Arm_Destroy(h);  // 销毁句柄
    return ret == 0 ? 0 : 1;  // 根据读取结果返回
}  // 结束示例主函数

场景化示例

读取和设置运动参数

double ovc = 0.0;  // 准备速度比例输出
double oac = 0.0;  // 准备加速度比例输出
int tf = 0;  // 准备工具坐标系编号输出
int uf = 0;  // 准备用户坐标系编号输出
int tcs = 0;  // 准备示教坐标系输出
int ovcRet = Arm_Motion_GetOVC(h, &ovc);  // 读取 OVC
int oacRet = Arm_Motion_GetOAC(h, &oac);  // 读取 OAC
int tfRet = Arm_Motion_GetTF(h, &tf);  // 读取当前 TF
int ufRet = Arm_Motion_GetUF(h, &uf);  // 读取当前 UF
int tcsRet = Arm_Motion_GetTCS(h, &tcs);  // 读取当前 TCS
/* int setOvcRet = Arm_Motion_SetOVC(h, ovc); */  // 写速度比例会改变运动参数，确认后再执行
/* int setOacRet = Arm_Motion_SetOAC(h, oac); */  // 写加速度比例会改变运动参数，确认后再执行
/* int setTfRet = Arm_Motion_SetTF(h, tf); */  // 写 TF 会改变当前工具坐标系，确认后再执行
/* int setUfRet = Arm_Motion_SetUF(h, uf); */  // 写 UF 会改变当前用户坐标系，确认后再执行
/* int setTcsRet = Arm_Motion_SetTCS(h, tcs); */  // 写 TCS 会改变示教坐标系，确认后再执行
(void)ovcRet;  // 示例中保留状态码
(void)oacRet;  // 示例中保留状态码
(void)tfRet;  // 示例中保留状态码
(void)ufRet;  // 示例中保留状态码
(void)tcsRet;  // 示例中保留状态码

位姿与转换

ArmMotionPose jointPose = {0};  // 准备关节位姿
ArmMotionPose cartPose = {0};  // 准备笛卡尔位姿
int poseRet = Arm_Motion_GetCurrentPose(h, ARM_POSE_TYPE_JOINT, &jointPose);  // 获取当前关节位姿
int jointToCartRet = Arm_Motion_ConvertJointToCart(h, &jointPose, 0, 0, &cartPose);  // 关节转笛卡尔
int cartToJointRet = Arm_Motion_ConvertCartToJoint(h, &cartPose, 0, 0, &jointPose);  // 笛卡尔转关节
int simpleRet = Arm_Motion_ConvertCartToJointSimple(h, &cartPose, 0, 0, &jointPose);  // 简化笛卡尔转关节
(void)poseRet;  // 示例中保留状态码
(void)jointToCartRet;  // 示例中保留状态码
(void)cartToJointRet;  // 示例中保留状态码
(void)simpleRet;  // 示例中保留状态码

运动、DH、位置控制、拖动和负载

ArmDhParam dh[9] = {0};  // 准备 DH 参数数组
size_t dhCount = 0U;  // 准备 DH 数量输出
ArmSoftLimit limits[9] = {0};  // 准备软限位数组
size_t limitCount = 0U;  // 准备软限位数量输出
ArmDragStatus drag = {0};  // 准备拖动状态结构
ArmPayloadSummary payloads[16] = {0};  // 准备负载摘要数组
size_t payloadCount = 0U;  // 准备负载数量输出
int dhRet = Arm_Motion_GetDHParam(h, dh, 9, &dhCount);  // 读取 DH 参数
int limitRet = Arm_Motion_GetUserSoftLimit(h, limits, 9, &limitCount);  // 读取用户软限位
int dragRet = Arm_Motion_GetDragSet(h, &drag);  // 读取拖动状态
int payloadRet = Arm_Motion_Payload_GetAll(h, payloads, 16, &payloadCount);  // 查询负载列表
/* int moveJRet = Arm_Motion_MoveJoint(h, &jointPose, 20.0, 20.0); */  // 关节运动会移动机器人，确认后再执行
/* int moveLRet = Arm_Motion_MoveLine(h, &cartPose, 20.0, 20.0); */  // 直线运动会移动机器人，确认后再执行
/* int moveCRet = Arm_Motion_MoveCircle(h, &cartPose, &cartPose, 20.0, 20.0); */  // 圆弧运动会移动机器人，确认后再执行
/* int enterPositionRet = Arm_Motion_EnterPositionControl(h); */  // 进入位置控制模式会改变控制模式，确认后再执行
/* int setPositionParamRet = Arm_Motion_SetPositionTrajectoryParams(h, 10, 10, 5, 20.0, 120.0); */  // 写位置控制参数会改变轨迹参数，确认后再执行
/* int exitPositionRet = Arm_Motion_ExitPositionControl(h); */  // 退出位置控制模式会改变控制模式，确认后再执行
/* int setDhRet = Arm_Motion_SetDHParam(h, dh, dhCount); */  // 写 DH 会改变运动学参数，确认后再执行
/* int enableDragRet = Arm_Motion_EnableDrag(h, 1); */  // 开启拖动会改变控制模式，确认后再执行
/* int setDragRet = Arm_Motion_SetDragStatus(h, &drag); */  // 写拖动状态会改变拖动设置，确认后再执行
(void)dhRet;  // 示例中保留状态码
(void)limitRet;  // 示例中保留状态码
(void)dragRet;  // 示例中保留状态码
(void)payloadRet;  // 示例中保留状态码

示例代码

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