4.8 C99 Registers 寄存器接口

概述

C99 Registers 提供 R、PR、SR、MR、MH、MI 寄存器读写。C99 函数是扁平入口，字符串和结构体由调用方提供缓冲区。

对应头文件：

• include/c_arm_registers.h

接口签名

Arm_Registers_ReadR

int Arm_Registers_ReadR(ArmHandle* h, int index, double* outValue);

项	说明
描述	读取 R 寄存器。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 index : int ，R 寄存器编号 outValue : double* ，输出 R 值指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Registers_WriteR

int Arm_Registers_WriteR(ArmHandle* h, int index, double value);

项	说明
描述	写入 R 寄存器。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 index : int ，R 寄存器编号 value : double ，R 寄存器写入值
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Registers_DeleteR

int Arm_Registers_DeleteR(ArmHandle* h, int index);

项	说明
描述	删除 R 寄存器。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 index : int ，R 寄存器编号
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Registers_ReadPR

int Arm_Registers_ReadPR(ArmHandle* h, int index, ArmPoseRegister* outReg);

项	说明
描述	读取 PR 点位寄存器。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 index : int ，PR 寄存器编号 outReg : ArmPoseRegister* ，输出 PR 结构体，由调用方分配
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Registers_WritePR

int Arm_Registers_WritePR(ArmHandle* h, const ArmPoseRegister* reg);

项	说明
描述	写入 PR 点位寄存器。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 reg : const ArmPoseRegister* ，指针参数，调用前需要保证生命周期有效
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Registers_DeletePR

int Arm_Registers_DeletePR(ArmHandle* h, int index);

项	说明
描述	删除 PR 点位寄存器。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 index : int ，PR 寄存器编号
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Registers_ReadSR

int Arm_Registers_ReadSR(ArmHandle* h, int index, char* outBuf, size_t bufSize);

项	说明
描述	读取 SR 字符串寄存器。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 index : int ，SR 寄存器编号 outBuf : char* ，输出字符串缓冲区，由调用方分配 bufSize : size_t ，输出缓冲区大小，包含结尾 \0 的空间
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理
备注	字符串输出使用调用方提供的缓冲区，缓冲区不足时按状态码返回。

Arm_Registers_WriteSR

int Arm_Registers_WriteSR(ArmHandle* h, int index, const char* value);

项	说明
描述	写入 SR 字符串寄存器。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 index : int ，SR 寄存器编号 value : const char* ，SR 字符串写入值
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Registers_DeleteSR

int Arm_Registers_DeleteSR(ArmHandle* h, int index);

项	说明
描述	删除 SR 字符串寄存器。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 index : int ，SR 寄存器编号
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Registers_ReadMR

int Arm_Registers_ReadMR(ArmHandle* h, int index, int* outValue);

项	说明
描述	读取 MR 寄存器。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 index : int ，MR 寄存器编号 outValue : int* ，输出 MR 值指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Registers_WriteMR

int Arm_Registers_WriteMR(ArmHandle* h, int index, int value);

项	说明
描述	写入 MR 寄存器。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 index : int ，MR 寄存器编号 value : int ，MR 寄存器写入值
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Registers_DeleteMR

int Arm_Registers_DeleteMR(ArmHandle* h, int index);

项	说明
描述	删除 MR 寄存器。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 index : int ，MR 寄存器编号
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Registers_ReadMH

int Arm_Registers_ReadMH(ArmHandle* h, int index, int* outValue);

项	说明
描述	读取 MH 寄存器。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 index : int ，MH 寄存器编号 outValue : int* ，输出 MH 值指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Registers_WriteMH

int Arm_Registers_WriteMH(ArmHandle* h, int index, int value);

项	说明
描述	写入 MH 寄存器。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 index : int ，MH 寄存器编号 value : int ，MH 寄存器写入值
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Registers_ReadMI

int Arm_Registers_ReadMI(ArmHandle* h, int index, int* outValue);

项	说明
描述	读取 MI 寄存器。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 index : int ，MI 寄存器编号 outValue : int* ，输出 MI 值指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Registers_WriteMI

int Arm_Registers_WriteMI(ArmHandle* h, int index, int value);

项	说明
描述	写入 MI 寄存器。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 index : int ，MI 寄存器编号 value : int ，MI 寄存器写入值
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

寄存器类型

类型	读	写	删除	数据
R	Arm_Registers_ReadR	Arm_Registers_WriteR	Arm_Registers_DeleteR	double
PR	Arm_Registers_ReadPR	Arm_Registers_WritePR	Arm_Registers_DeletePR	ArmPoseRegister
SR	Arm_Registers_ReadSR	Arm_Registers_WriteSR	Arm_Registers_DeleteSR	字符串
MR	Arm_Registers_ReadMR	Arm_Registers_WriteMR	Arm_Registers_DeleteMR	int
MH	Arm_Registers_ReadMH	Arm_Registers_WriteMH	无删除接口	int
MI	Arm_Registers_ReadMI	Arm_Registers_WriteMI	无删除接口	int

参数与规则

项	规则
index	控制器侧寄存器编号
Arm_Registers_ReadSR()	使用 char* + bufSize 输出字符串，缓冲区需要包含结尾 \0
Arm_Registers_ReadPR()	输出 ArmPoseRegister ，调用方传入有效结构体指针
Arm_Registers_WritePR()	使用 ArmPoseRegister.id 指定写入的 PR 编号
MH / MI	提供读写接口，不提供删除接口
写入和删除	会修改控制器寄存器状态，运行前确认现场业务

ArmPoseRegister 字段

字段	类型	说明
id	int	PR 寄存器编号
cart	double[6]	笛卡尔位姿数据
joint	double[9]	关节位姿数据
poseType	int	位姿类型，取值见 ArmPoseType
turnCycle	int[9]	关节圈数信息
wristFlip	int	腕部翻转标志
armUpDown	int	手臂上下姿态标志
armBackFront	int	手臂前后姿态标志
armLeftRight	int	手臂左右姿态标志
name	char[64]	点位名称
comment	char[128]	点位备注

最小调用示例

#include <stdio.h>  // 引入 printf，用于打印 R 寄存器
#include "c_arm_api.h"  // 引入 C99 SDK 总头文件
int main(void)  // 示例程序入口
{  // 进入示例主函数
    ArmHandle* h = Arm_Create();  // 创建 C99 会话句柄
    double rValue = 0.0;  // 准备 R 寄存器输出变量
    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_Registers_ReadR(h, 1, &rValue);  // 读取 R1
    printf("r1=%f\n", rValue);  // 打印 R1 值
    Arm_Disconnect(h);  // 断开连接
    Arm_Destroy(h);  // 销毁句柄
    return ret == 0 ? 0 : 1;  // 根据读取结果返回
}  // 结束示例主函数

场景化示例

double rValue = 0.0;  // 准备 R 输出
ArmPoseRegister pr = {0};  // 准备 PR 输出
char sr[128] = {0};  // 准备 SR 输出缓冲区
int mr = 0;  // 准备 MR 输出
int mh = 0;  // 准备 MH 输出
int mi = 0;  // 准备 MI 输出
int readRRet = Arm_Registers_ReadR(h, 1, &rValue);  // 读取 R1
int readPRRet = Arm_Registers_ReadPR(h, 1, &pr);  // 读取 PR1
int readSRRet = Arm_Registers_ReadSR(h, 1, sr, sizeof(sr));  // 读取 SR1
int readMRRet = Arm_Registers_ReadMR(h, 1, &mr);  // 读取 MR1
int readMHRet = Arm_Registers_ReadMH(h, 1, &mh);  // 读取 MH1
int readMIRet = Arm_Registers_ReadMI(h, 1, &mi);  // 读取 MI1
/* int writeRRet = Arm_Registers_WriteR(h, 1, rValue); */  // 写 R 会修改寄存器，确认后再执行
/* int writePRRet = Arm_Registers_WritePR(h, &pr); */  // 写 PR 会修改寄存器，确认后再执行
/* int writeSRRet = Arm_Registers_WriteSR(h, 1, "demo"); */  // 写 SR 会修改寄存器，确认后再执行
/* int writeMRRet = Arm_Registers_WriteMR(h, 1, mr); */  // 写 MR 会修改寄存器，确认后再执行
/* int writeMHRet = Arm_Registers_WriteMH(h, 1, mh); */  // 写 MH 会修改寄存器，确认后再执行
/* int writeMIRet = Arm_Registers_WriteMI(h, 1, mi); */  // 写 MI 会修改寄存器，确认后再执行
/* int deleteRRet = Arm_Registers_DeleteR(h, 1); */  // 删除 R 会修改寄存器，确认后再执行
/* int deletePRRet = Arm_Registers_DeletePR(h, 1); */  // 删除 PR 会修改寄存器，确认后再执行
/* int deleteSRRet = Arm_Registers_DeleteSR(h, 1); */  // 删除 SR 会修改寄存器，确认后再执行
/* int deleteMRRet = Arm_Registers_DeleteMR(h, 1); */  // 删除 MR 会修改寄存器，确认后再执行
(void)readRRet;  // 示例中保留状态码
(void)readPRRet;  // 示例中保留状态码
(void)readSRRet;  // 示例中保留状态码
(void)readMRRet;  // 示例中保留状态码
(void)readMHRet;  // 示例中保留状态码
(void)readMIRet;  // 示例中保留状态码

示例代码

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

    // [ZH] 顺序读取全部寄存器类型。
    // [EN] Read all register types in sequence.
    double rValue = 0.0;
    ArmPoseRegister prValue;
    char srValue[256] = {0};
    int mrValue = 0;
    int mhValue = 0;
    int miValue = 0;
    memset(&prValue, 0, sizeof(prValue));
    ret = Arm_Registers_ReadR(handle, 0, &rValue);
    printf("[c99_registers] ReadR 状态码 / ReadR status code: %d, R[0]=%.6f\n", ret, rValue);
    ret = Arm_Registers_ReadPR(handle, 0, &prValue);
    printf("[c99_registers] ReadPR 状态码 / ReadPR status code: %d, PR[0].id=%d, name=%s\n", ret, prValue.id, prValue.name);
    ret = Arm_Registers_ReadSR(handle, 0, srValue, sizeof(srValue));
    printf("[c99_registers] ReadSR 状态码 / ReadSR status code: %d, SR[0]=%s\n", ret, srValue);
    ret = Arm_Registers_ReadMR(handle, 0, &mrValue);
    printf("[c99_registers] ReadMR 状态码 / ReadMR status code: %d, MR[0]=%d\n", ret, mrValue);
    ret = Arm_Registers_ReadMH(handle, 0, &mhValue);
    printf("[c99_registers] ReadMH 状态码 / ReadMH status code: %d, MH[0]=%d\n", ret, mhValue);
    ret = Arm_Registers_ReadMI(handle, 0, &miValue);
    printf("[c99_registers] ReadMI 状态码 / ReadMI status code: %d, MI[0]=%d\n", ret, miValue);

    // [ZH] 顺序执行全部写接口与删除接口。
    // [EN] Execute all write APIs and delete APIs in sequence.
    ret = Arm_Registers_WriteR(handle, 0, rValue);
    printf("[c99_registers] WriteR 状态码 / WriteR status code: %d\n", ret);
    ret = Arm_Registers_DeleteR(handle, 0);
    printf("[c99_registers] DeleteR 状态码 / DeleteR status code: %d\n", ret);
    ret = Arm_Registers_WritePR(handle, &prValue);
    printf("[c99_registers] WritePR 状态码 / WritePR status code: %d\n", ret);
    ret = Arm_Registers_DeletePR(handle, prValue.id);
    printf("[c99_registers] DeletePR 状态码 / DeletePR status code: %d\n", ret);
    ret = Arm_Registers_WriteSR(handle, 0, srValue);
    printf("[c99_registers] WriteSR 状态码 / WriteSR status code: %d\n", ret);
    ret = Arm_Registers_DeleteSR(handle, 0);
    printf("[c99_registers] DeleteSR 状态码 / DeleteSR status code: %d\n", ret);
    ret = Arm_Registers_WriteMR(handle, 0, mrValue);
    printf("[c99_registers] WriteMR 状态码 / WriteMR status code: %d\n", ret);
    ret = Arm_Registers_DeleteMR(handle, 0);
    printf("[c99_registers] DeleteMR 状态码 / DeleteMR status code: %d\n", ret);
    ret = Arm_Registers_WriteMH(handle, 0, mhValue);
    printf("[c99_registers] WriteMH 状态码 / WriteMH status code: %d\n", ret);
    ret = Arm_Registers_WriteMI(handle, 0, miValue);
    printf("[c99_registers] WriteMI 状态码 / WriteMI status code: %d\n", ret);

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