关节控制 API

本章按能力域介绍核心接口，并补充 Ti5SdkDemo_linux_arm64/README-zh.md 中常用 CAN 指令映射，便于联调抓包时快速对照。详细参数与枚举以 MotorCtrlApi.h 为准。

1. 日志初始化与输出开关（必填）

接口	功能	备注
`Motor_LogInit(const char* logFile, int async, MotorLogLevelEnum level)`	初始化 SDK 日志系统	建议调用：日志输出依赖初始化。
`Motor_LogSetLevel(MotorLogLevelEnum level)`	设置 SDK 日志级别	用于运行期调整输出等级。
`Motor_LogGetLevel()`	获取当前日志级别	返回当前 `MotorLogLevelEnum`。
`Motor_LogShutdown()`	关闭 SDK 日志系统	建议调用且必须与 `Motor_LogInit` 配对,主程序退出前调用,调用后不应继续使用logger输出：没有 `init + shutdown` 配对时，SDK 可能不会产生任何日志输出。只有init没有shutdown可能导致程序异常

最小示例（对应 @include/api/MotorCtrlApi.h 中的日志接口）：

Motor_LogInit(nullptr, /*async=*/1, MOTOR_LOG_INFO);
Motor_LogSetLevel(MOTOR_LOG_INFO);

// ... 调用 SDK 相关 API ...

Motor_LogShutdown();

如果没有启用日志,那么SDK将不会有任何的输出,建议启用日志,如果不需要输出使用OFF枚举关闭即可 补充说明：

logFile = nullptr 表示仅控制台输出。
async = 1 为异步日志（更符合示例用法）。
日志级别可用 MOTOR_LOG_INFO / MOTOR_LOG_DEBUG / ...。

2. 关节控制 API

本节按调用阶段梳理 MotorCtrlApi.h 的关节控制接口，主要分为两类：

控制器生命周期与连接：创建控制实例、选择连接方式、必要时查询总线节点信息，最后断开并释放资源。
参数设置与常用码流：设置通信参数、设备阈值、运行模式与各环（电流/速度/位置）相关参数，配合你选择的 motion/运行计划生效。

建议的调用顺序是：Motor_CreateController -> 连接（Motor_ConnectCan 或 Motor_ConnectSocketCan）-> 参数设置 -> 运行/查询 -> Motor_RemoveController（结束时务必调用）。

2.1 控制器生命周期与连接

接口	功能	备注
`Motor_CreateController`	创建电机控制实例	调用其他接口前必须先创建
`Motor_ConnectCan`	通过 CAN 分析仪连接	适用于外置 CAN 设备
`Motor_ConnectSocketCan`	通过 SocketCAN 连接	适用于 Linux `can0/can1`
`Motor_RemoveController`	断开并释放实例	结束时务必调用
`Motor_CanGetNodeInfo`	获取总线节点信息	排查总线设备是否在线

2.2 参数设置接口（含常用 CAN 码流）

接口	参数类型（示例）	功能	CAN 码流示例
`Motor_SetCommuPara`	`MOTOR_COMMU_PARA_CAN_ID`	修改电机响应 CANID	`0x2E 64 00 00 00`
	`MOTOR_COMMU_PARA_BAUD_RATE`	修改总线波特率	`0x3F 64 00 00 00`
	`MOTOR_COMMU_TIMER`	设置报文上传/掉线保护时间	`0x59 64 00 C8 00`
`Motor_SetDevicePara`	`MOTOR_DEVICE_PARA_MOTOR_MAX_TEMP`	设置线圈最大温度	`0x8D 64 00 00 00`
	`MOTOR_DEVICE_PARA_PCB_MAX_TEMP`	设置驱动板最大温度	`0x91 64 00 00 00`
	`MOTOR_DEVICE_PARA_MAX_VOLTAGE`	设置过压阈值（重启生效）	`0x87 64 00 00 00`
	`MOTOR_DEVICE_PARA_MIN_VOLTAGE`	设置低压阈值（重启生效）	`0x89 64 00 00 00`
	`MOTOR_DEVICE_PARA_NTC_TYPE`	设置 NTC 类型	`0x96 20 64 00 00 00`
`Motor_SetRunMode`	`MOTOR_RUN_MODE_STOP`	停止电机	`0x02`
	`MOTOR_RUN_MODE_CURRENT`	电流模式	`0x1D 64 00 00 00`
	`MOTOR_RUN_MODE_SPEED`	速度模式	`0x1C 64 00 00 00`
	`MOTOR_RUN_MODE_POS`	位置模式	`0x1E 64 00 00 00`
`Motor_SetCurrentPara`	`CURR_PARA_MAX_VAL / MIN_VAL`	电流上下限	`0x20/0x21 64 00 00 00`
	`CURR_PARA_PROPORTIONAL / INTEGRAL`	电流环 KP/KI	`0x83/0x84 64 00 00 00`
`Motor_SetSpeedPara`	`SPEED_PARA_MAX_ACC / MIN_ACC`	加速度上下限	`0x22/0x23 64 00 00 00`
	`SPEED_PARA_MAX_SPEED / MIN_SPEED`	速度上下限	`0x24/0x25 64 00 00 00`
	`SPEED_PARA_PROPORTIONAL / INTEGRAL`	速度环 KP/KI	`0x29/0x2A 64 00 00 00`
`Motor_SetPositionPara`	`POS_PARA_MAX_VALUE / MIN_VALUE`	位置软限位	`0x26/0x27 64 00 00 00`
	`POS_PARA_PROPORTIONAL / DIFFERENTIAL`	位置环 KP/KD	`0x2B/0x2D 64 00 00 00`
	`POS_PARA_OFFSET`	位置偏移	`0x53 64 00 00 00`
`Motor_SetSysCmd`	`MOTOR_SYS_CMD_RESET_FAULT`	清错	`0x0B`
	`MOTOR_SYS_CMD_FACTORY_RESET`	恢复出厂	`0x0F`
	`MOTOR_SYS_CMD_STORE_TO_FLASH`	参数写入 Flash	`0x0E`
	`MOTOR_SYS_CMD_RESTORE_FROM_FLASH`	从 Flash 恢复	`0x0D`

2.3 参数读取接口

接口	参数类型（示例）	功能	CAN 码流示例
`Motor_GetDevicePara`	`MOTOR_DEVICE_PARA_GET_FAULT`	获取故障状态	`0x0A`
	`MOTOR_DEVICE_PARA_GET_BUS_VOLTAGE`	获取母线电压	`0x14`
	`MOTOR_DEVICE_PARA_GET_TEMP`	获取线圈温度	`0x31`
	`MOTOR_DEVICE_PARA_GET_PCB_TEMP`	获取驱动板温度	`0x32`
	`MOTOR_DEVICE_PARA_GET_SOFTWARE_VERSION`	获取软件版本	`0x65`
`Motor_GetRunMode`	`-`	获取当前运行模式	`0x03`
`Motor_GetCurrentPara`	`CURR_PARA_GET_CUR_VAL`	获取当前电流	`0x04`
	`CURR_PARA_GET_TARGET_VAL`	获取目标电流	`0x05`
	`CURR_PARA_GET_CSP`	获取电流/速度/位置	`0x41`
`Motor_GetSpeedPara`	`SPEED_PARA_GET_CUR_VAL`	获取当前速度	`0x06`
	`SPEED_PARA_GET_TARGET_VAL`	获取目标速度	`0x07`
`Motor_GetPositionPara`	`POS_PARA_GET_CUR_VAL`	获取当前位置	`0x08`
	`POS_PARA_GET_TARGET_VAL`	获取目标位置	`0x09`

2.4 扩展控制与调试接口

接口	功能	使用场景
`Motor_Raw_CanWrite`	发送原始 CAN 数据	协议联调、透传验证
`Motor_SetDecodeFailedStrategy`	设置解码失败策略	丢弃/回调/裸上传
`Motor_GetDecodeFailedStrategy`	获取当前策略	排查异常帧处理逻辑

3. 运动模式与运动控制 API

`Motor_SetRunMode`

参数	含义
`ctrlId`	控制实例 ID（`Motor_CreateController` 返回值）
`mode`	运行模式，见下表 `MotorRunModeEnum`
`value`	与 `mode` 相关的目标或命令字；头文件约定：电流模式为电流（mA）；速度模式为内圈速度（0.01 Hz）；位置模式为位置（cnt）；`MOTOR_RUN_MODE_STOP` 时按实现可不使用或填 0

MotorRunModeEnum（节选，完整见头文件）：

枚举值	说明
`MOTOR_RUN_MODE_STOP`	停止
`MOTOR_RUN_MODE_CURRENT`	电流模式
`MOTOR_RUN_MODE_POS`	位置模式
`MOTOR_RUN_MODE_CYCLIC_SYN_POS` / `CYCLIC_SYN_SPEED` / `CYCLIC_SYN_TORQUE`	周期同步位置/速度/转矩

`Motor_GetRunMode`

参数	含义
`ctrlId`	控制实例 ID

发起查询；成功后通过 Motor_ReadRspMsg 读取 MotorGetParaRsp，其中 paraType = MOTOR_RUN_MODE_PARA。

`Motor_SendCSP`

参数	含义
`ctrlId`	控制实例 ID
`type`	`CSP_TYPE_POSITION` / `CSP_TYPE_CURRENT` / `CSP_TYPE_SPEED`
`value`	目标：位置（cnt）/ 电流（mA）/ 速度（0.01 Hz）

周期性调用以设置目标并获取电流/速度/位置等反馈（与 CSP 运行方式一致）。

`Motor_AngleToPositionCnt`

参数	含义
`encoderNum`	`MOTOR_ENCODER_NUM_SINGLE`（单编）或 `MOTOR_ENCODER_NUM_DUAL`（双编）
`gearRatio`	减速比；双编时换算公式中不使用 `gearRatio`（见头文件注释）
`angleUnit`	`MOTOR_ANGLE_UNIT_DEG`（度）或 `MOTOR_ANGLE_UNIT_RAD`（弧度）
`angle`	外圈角度
`posCnt`	输出：电机端位置计数（`int *`）

换算关系（与 MotorCtrlApi.h 注释一致）：单编时 posCnt 与 angle * gearRatio * 65536 及 360° 或 2π 相关；双编时与 262144 及 360° 或 2π 相关。

`Motor_PositionCntToAngle`

参数	含义
`encoderNum`	单编 / 双编，同上
`gearRatio`	减速比；双编公式中不乘 `gearRatio`
`posCnt`	电机端位置计数
`angleUnit`	输出角度单位：度或弧度
`angle`	输出：外圈角度（`double *`）

`Motor_MoveTargetAngle`

参数	含义
`ctrlId`	控制实例 ID
`encoderNum`	单编 / 双编
`gearRatio`	减速比
`angleUnit`	`targetAngle` 的单位（度或弧度）
`targetAngle`	目标外圈角度

`Motor_MoveDeltaAngle`

参数	含义
`ctrlId`	控制实例 ID
`encoderNum`	单编 / 双编
`gearRatio`	减速比
`angleUnit`	`curAngle`、`deltaAngle` 的单位（度或弧度）
`curAngle`	当前外圈角度
`deltaAngle`	相对当前角度的增量

`Motor_CntSpeedToOutputSpeed`

参数	含义
`cntSpeed`	电机端转速，单位 0.01 Hz（与 `Motor_SetRunMode` 速度模式一致）
`gearRatio`	减速比
`speedUnit`	输出物理量单位：`MOTOR_SPEED_UNIT_RPM`、`MOTOR_SPEED_UNIT_DEG_PER_SEC`、`MOTOR_SPEED_UNIT_RAD_PER_SEC`
`outputSpeed`	输出端转速（`double *`）

头文件给定换算：例如输出为 RPM 时 outputRpm = cntSpeed * 0.6 / gearRatio；度/s、弧度/s 见 MotorCtrlApi.h 注释。

`Motor_OutputSpeedToCntSpeed`

参数	含义
`outputSpeed`	输出端转速（数值，单位由 `speedUnit` 指定）
`gearRatio`	减速比
`speedUnit`	与 `Motor_CntSpeedToOutputSpeed` 相同三选一
`cntSpeed`	输出：电机端转速（0.01 Hz，`int *`）

3.1 示例（目标角）

// 与 MotorCtrlApi.h 声明一致；ctrlId / gearRatio / encoderNum 按实机填写
int ctrlId = 0;
int gearRatio = 101;
int posCnt = 0;

Motor_AngleToPositionCnt(MOTOR_ENCODER_NUM_DUAL, gearRatio,
                         MOTOR_ANGLE_UNIT_DEG, 15.0, &posCnt);

Motor_MoveTargetAngle(ctrlId, MOTOR_ENCODER_NUM_DUAL, gearRatio,
                      MOTOR_ANGLE_UNIT_DEG, 15.0);

// 当前位置 cnt 需先 Motor_GetPositionLoopPara 发起查询，再通过 Motor_ReadRspMsg 取回后再调用 PositionCntToAngle

4. PT 模式控制

PT 实时控制使用 Motor_ConfigPTMode（初始化一次）+ Motor_SetPT（周期调用）。

`Motor_ConfigPTMode`

在运行前配置静态 PT 参数（通常初始化时调用一次）；之后可用 Motor_SetPT 做周期控制。

参数	含义
`ctrlId`	控制实例 ID
`maxCurrent` / `minCurrent`	电流上下限（A）
`maxTorque` / `minTorque`	扭矩上下限（Nm）
`defRatio`	减速比
`defKT`	扭矩常数（Nm/A）
`maxKP` / `maxKD`	KP/KD 最大值（量化用）

`Motor_SetPT`

周期调用；必须先 Motor_ConfigPTMode。

参数	含义
`ctrlId`	控制实例 ID
`kp`	位置刚度系数
`kd`	阻尼系数
`targetPos`	目标位置（rad）
`targetSpeed`	目标速度（rad/s）
`targetTorque`	前馈扭矩（Nm）

`Motor_GetForceKPDPara` / `Motor_SetForceKPDPara`

接口	参数	含义
`Motor_GetForceKPDPara`	`ctrlId`	控制实例 ID
	`paraType`	`ForceKPDTypeEnum`，见下表
`Motor_SetForceKPDPara`	`ctrlId`	控制实例 ID
	`paraType`	`FORCE_KP_MAX` / `FORCE_KD_MAX` 等（设置项）
	`value`	参数值

ForceKPDTypeEnum：

枚举	说明
`FORCE_KP`	KP
`FORCE_KD`	KD
`FORCE_KT`	KT
`FORCE_KI`	KI
`FORCE_KILIMIT`	KI 限幅
`FORCE_KP_MAX`	KP 最大值（设置接口常用）
`FORCE_KD_MAX`	KD 最大值（设置接口常用）

读取结果通过 Motor_ReadRspMsg 获取。

`Motor_GetPTTIPara` / `Motor_SetPTTIPara`

接口	参数	含义
`Motor_GetPTTIPara`	`ctrlId`	控制实例 ID
	`paraType`	`PT_TITypeEnum`
`Motor_SetPTTIPara`	`ctrlId`	控制实例 ID
	`paraType`	`PT_TMAX` / `PT_TMIN` / `PT_IMAX` / `PT_IMIN`
	`value`	参数值

PT_TITypeEnum：

枚举	说明
`PT_TMAX`	扭矩最大值
`PT_TMIN`	扭矩最小值
`PT_IMAX`	电流最大值
`PT_IMIN`	电流最小值

读取结果通过 Motor_ReadRspMsg 获取。

关节控制 API

1. 日志初始化与输出开关（必填）

2. 关节控制 API

2.1 控制器生命周期与连接

2.2 参数设置接口（含常用 CAN 码流）

2.3 参数读取接口

2.4 扩展控制与调试接口

3. 运动模式与运动控制 API

Motor_SetRunMode

Motor_GetRunMode

Motor_SendCSP

Motor_AngleToPositionCnt

Motor_PositionCntToAngle

Motor_MoveTargetAngle

Motor_MoveDeltaAngle

Motor_CntSpeedToOutputSpeed

Motor_OutputSpeedToCntSpeed