4.5 C99 Program 程序接口

概述

C99 Program 覆盖程序启动、停止、暂停、恢复、运行中程序查询、BasScript 执行和程序点位读写。

对应头文件：

• include/c_arm_program.h
• include/c_arm_types.h

接口签名

Arm_Program_Start

int Arm_Program_Start(ArmHandle* h, const char* programName);

项	说明
描述	启动指定程序。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 programName : const char* ，待启动的程序名称，不能为 NULL
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Program_Stop

int Arm_Program_Stop(ArmHandle* h, const char* programName);

项	说明
描述	停止指定程序或当前程序。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 programName : const char* ，程序名称；传 NULL 或空字符串时停止当前运行程序
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Program_Pause

int Arm_Program_Pause(ArmHandle* h, const char* programName);

项	说明
描述	暂停指定程序或当前程序。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 programName : const char* ，程序名称；传 NULL 或空字符串时暂停当前运行程序
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Program_Resume

int Arm_Program_Resume(ArmHandle* h, const char* programName);

项	说明
描述	恢复指定程序或当前程序。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 programName : const char* ，程序名称；传 NULL 或空字符串时恢复当前暂停程序
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Program_GetAllRunning

int Arm_Program_GetAllRunning(ArmHandle* h, ArmRunningProgramInfo* outArray, size_t maxCount, size_t* outCount);

项	说明
描述	查询当前运行中的程序列表。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 outArray : ArmRunningProgramInfo* ，输出数组，由调用方分配 maxCount : size_t ，输出数组容量，表示调用方最多可接收多少个元素 outCount : size_t* ，输出数量指针，成功时写入实际数量
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理
备注	数组输出由调用方分配， maxCount 表示容量， outCount 返回实际数量。

Arm_Program_ExecuteBasScript

int Arm_Program_ExecuteBasScript(ArmHandle* h, const char** lines, size_t lineCount);

项	说明
描述	执行 BAS 脚本文本行。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 lines : const char** ，BAS 脚本文本行数组； lineCount > 0 时数组和每一行都不能为 NULL lineCount : size_t ，脚本文本行数量
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Program_ExecuteBasScriptEx

int Arm_Program_ExecuteBasScriptEx(ArmHandle* h, const ArmBasScript* script);

项	说明
描述	执行结构化 BasScript 对象。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 script : const ArmBasScript* ，结构化 BasScript 脚本参数
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_ProgramPose_Read

int Arm_ProgramPose_Read(ArmHandle* h, const char* programName, int32_t index, int32_t programType, ArmProgramPose* outPose);

项	说明
描述	读取指定程序点位。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 programName : const char* ，程序名称，不能为 NULL index : int32_t ，程序点位索引 programType : int32_t ，程序类型，取值见 ArmProgramType outPose : ArmProgramPose* ，位姿输出结构体指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_ProgramPose_Write

int Arm_ProgramPose_Write(ArmHandle* h, const char* programName, int32_t index, int32_t programType, const ArmProgramPose* pose);

项	说明
描述	写入指定程序点位。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 programName : const char* ，程序名称，不能为 NULL index : int32_t ，程序点位索引 programType : int32_t ，程序类型，取值见 ArmProgramType pose : const ArmProgramPose* ，待写入的程序点位
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_ProgramPose_Add

int Arm_ProgramPose_Add(ArmHandle* h, const char* programName, int32_t index, int32_t programType, const ArmProgramPose* pose);

项	说明
描述	新增程序点位。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 programName : const char* ，程序名称，不能为 NULL index : int32_t ，新增点位插入索引 programType : int32_t ，程序类型，取值见 ArmProgramType pose : const ArmProgramPose* ，待新增的程序点位
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_ProgramPose_ReadAll

int Arm_ProgramPose_ReadAll(ArmHandle* h, const char* programName, int32_t programType, ArmProgramPose* outArray, size_t maxCount, size_t* outCount);

项	说明
描述	读取指定程序的全部点位。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 programName : const char* ，程序名称，不能为 NULL programType : int32_t ，程序类型，取值见 ArmProgramType outArray : ArmProgramPose* ，输出数组，由调用方分配 maxCount : size_t ，输出数组容量，表示调用方最多可接收多少个元素 outCount : size_t* ，输出数量指针，成功时写入实际数量
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理
备注	数组输出由调用方分配， maxCount 表示容量， outCount 返回实际数量。

Arm_ProgramPose_WriteBatch

int Arm_ProgramPose_WriteBatch(ArmHandle* h, const char* programName, const ArmProgramPose* poses, size_t count);

项	说明
描述	批量写入程序点位。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 programName : const char* ，程序名称，不能为 NULL poses : const ArmProgramPose* ，程序点位数组； count > 0 时不能为 NULL count : size_t ，数组元素数量
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_ProgramPose_Convert

int Arm_ProgramPose_Convert(ArmHandle* h, const ArmProgramPose* inPose, int32_t fromType, int32_t toType, ArmProgramPose* outPose);

项	说明
描述	转换程序点位类型。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 inPose : const ArmProgramPose* ，输入位姿或点位结构体指针 fromType : int32_t ，源点位类型 toType : int32_t ，目标点位类型 outPose : ArmProgramPose* ，位姿输出结构体指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

语义规则

ArmProgramType

枚举值	值	说明
ARM_PROGRAM_USER	0	用户程序
ARM_PROGRAM_BLOCK	1	积木程序

ArmRunningProgramInfo

字段	类型	说明
threadId	int32_t	程序运行线程 ID
programName	char[128]	程序名称
xpath	char[256]	程序节点路径
programStatus	int32_t	程序运行状态
programType	char[32]	程序类型字符串

ArmBasScript

字段	类型	说明
name	const char*	脚本名称；为 NULL 时按空字符串处理
lines	const char**	脚本文本行数组
lineCount	size_t	脚本文本行数量
flagIf	int32_t	IF 结构闭合计数
flagSwitch	int32_t	SWITCH 结构闭合计数
flagWhile	int32_t	WHILE 结构闭合计数

ArmProgramPose

字段	类型	说明
id	int32_t	程序点位 ID
name	char[128]	程序点位名称
comment	char[256]	程序点位备注
pose	ArmMotionPose	点位姿态数据
uf	int32_t	用户坐标系编号
tf	int32_t	工具坐标系编号

程序执行

场景	规则
Arm_Program_Start	程序不存在时返回 PROGRAM_NOT_FOUND
Arm_Program_Stop / Pause / Resume	programName 传 NULL 或空字符串时作用于当前程序
Arm_Program_GetAllRunning	支持 outArray == NULL 的 count-only 模式
Arm_Program_ExecuteBasScript	按调用方传入文本行直接执行
Arm_Program_ExecuteBasScriptEx	先校验 ArmBasScript 的结构闭合状态；校验通过后自动补 RETURN / END

程序点位

场景	返回
程序不存在	PROGRAM_NOT_FOUND
点位不存在	PROGRAM_POSE_NOT_FOUND
批量写入块程序点位	UNSUPPORTED_FILETYPE
批量写入空数组	INVALID_PARAMETER

Arm_ProgramPose_ReadAll() 支持 outArray == NULL 的 count-only 模式；缓冲区容量小于实际点位数量时返回 BUFFER_TOO_SMALL 。写入、新增和批量写入会修改控制器程序内容，执行前需要确认目标程序和点位索引。

最小调用示例

#include <stdio.h>  // 引入 printf，用于打印运行中程序数量
#include "c_arm_api.h"  // 引入 C99 SDK 总头文件
int main(void)  // 示例程序入口
{  // 进入示例主函数
    ArmHandle* h = Arm_Create();  // 创建 C99 会话句柄
    ArmRunningProgramInfo programs[8] = {0};  // 准备运行中程序数组
    size_t count = 0U;  // 准备接收程序数量
    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_Program_GetAllRunning(h, programs, 8, &count);  // 查询运行中程序
    printf("running_count=%zu\n", count);  // 打印运行中程序数量
    Arm_Disconnect(h);  // 断开连接
    Arm_Destroy(h);  // 销毁句柄
    return ret == 0 ? 0 : 1;  // 根据查询结果返回
}  // 结束示例主函数

场景化示例

查询运行中程序

size_t requiredCount = 0U;  // 准备接收运行中程序数量
int countRet = Arm_Program_GetAllRunning(h, NULL, 0, &requiredCount);  // 只查询数量
ArmRunningProgramInfo programs[16] = {0};  // 准备运行中程序数组
size_t actualCount = 0U;  // 准备实际写入数量
int listRet = Arm_Program_GetAllRunning(h, programs, 16, &actualCount);  // 查询运行中程序详情
(void)countRet;  // 示例中保留数量查询状态码
(void)listRet;  // 示例中保留列表查询状态码

执行 BasScript 文本

const char* lines[] = {  // 准备 BAS 脚本文本行
    "WAIT SEC 0.1"  // 等待 0.1 秒
};  // 结束脚本行数组
/* int execRet = Arm_Program_ExecuteBasScript(h, lines, 1); */  // 执行脚本会改变控制器状态，确认后再执行
ArmBasScript script = {0};  // 准备结构化脚本参数
script.name = "demo.bas";  // 设置脚本名
script.lines = lines;  // 设置脚本行数组
script.lineCount = 1;  // 设置脚本行数量
/* int execExRet = Arm_Program_ExecuteBasScriptEx(h, &script); */  // 执行结构化脚本，确认后再执行

程序点位读写

ArmProgramPose pose = {0};  // 准备程序点位结构
int readRet = Arm_ProgramPose_Read(h, "demo", 1, ARM_PROGRAM_USER, &pose);  // 读取 1 号程序点位
ArmProgramPose converted = {0};  // 准备转换后的程序点位
int convertRet = Arm_ProgramPose_Convert(h, &pose, ARM_POSE_TYPE_JOINT, ARM_POSE_TYPE_CART, &converted);  // 转换点位类型
ArmProgramPose poses[2] = {0};  // 准备批量写入点位数组
/* int writeRet = Arm_ProgramPose_Write(h, "demo", 1, ARM_PROGRAM_USER, &pose); */  // 写点位会修改程序，确认后再执行
/* int addRet = Arm_ProgramPose_Add(h, "demo", 2, ARM_PROGRAM_USER, &pose); */  // 新增点位会修改程序，确认后再执行
/* int batchRet = Arm_ProgramPose_WriteBatch(h, "demo", poses, 2); */  // 批量写点位会修改程序，确认后再执行
(void)readRet;  // 示例中保留读取状态码
(void)convertRet;  // 示例中保留转换状态码

控制程序执行

/* int startRet = Arm_Program_Start(h, "demo"); */  // 启动程序会改变控制器执行状态，确认后再执行
/* int pauseRet = Arm_Program_Pause(h, NULL); */  // 暂停当前程序，确认后再执行
/* int resumeRet = Arm_Program_Resume(h, NULL); */  // 恢复当前程序，确认后再执行
/* int stopRet = Arm_Program_Stop(h, NULL); */  // 停止当前程序，确认后再执行

示例代码

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

    // [ZH] 查询全部运行中程序。
    // [EN] Query all running programs.
    ArmRunningProgramInfo runningPrograms[8] = {0};
    size_t runningCount = 0U;
    ret = Arm_Program_GetAllRunning(handle, runningPrograms, 8U, &runningCount);
    printf("[c99_program] GetAllRunning 状态码 / GetAllRunning status code: %d, 数量 / Count: %zu\n", ret, runningCount);
    for (size_t index = 0U; index < runningCount; ++index) {
        printf("[c99_program] 运行中程序 / Running program #%zu: thread_id=%d, name=%s, xpath=%s, status=%d, type=%s\n",
            index,
            runningPrograms[index].threadId,
            runningPrograms[index].programName,
            runningPrograms[index].xpath,
            runningPrograms[index].programStatus,
            runningPrograms[index].programType);
    }

    // [ZH] 直接执行程序控制接口。
    // [EN] Execute the program control APIs directly.
    ret = Arm_Program_Start(handle, "demo.bas");
    printf("[c99_program] Start 状态码 / Start status code: %d\n", ret);
    ret = Arm_Program_Pause(handle, "demo.bas");
    printf("[c99_program] Pause 状态码 / Pause status code: %d\n", ret);
    ret = Arm_Program_Resume(handle, "demo.bas");
    printf("[c99_program] Resume 状态码 / Resume status code: %d\n", ret);
    ret = Arm_Program_Stop(handle, "demo.bas");
    printf("[c99_program] Stop 状态码 / Stop status code: %d\n", ret);

    // [ZH] 顺序执行 BAS 脚本接口。
    // [EN] Execute the BAS script APIs in sequence.
    const char* lines[3] = {
        "PRINT \"SDK example\"",
        "WAIT 0.1",
        "END"
    };
    ArmBasScript script = {0};
    script.name = "example_bas_script.bas";
    script.lines = lines;
    script.lineCount = 3U;
    ret = Arm_Program_ExecuteBasScript(handle, lines, 3U);
    printf("[c99_program] ExecuteBasScript 状态码 / ExecuteBasScript status code: %d\n", ret);
    ret = Arm_Program_ExecuteBasScriptEx(handle, &script);
    printf("[c99_program] ExecuteBasScriptEx 状态码 / ExecuteBasScriptEx status code: %d\n", ret);

    // [ZH] 构造程序点位并顺序执行全部 ProgramPose 接口。
    // [EN] Build a program pose and execute all ProgramPose APIs in sequence.
    ArmProgramPose pose = {0};
    ArmProgramPose readPose = {0};
    ArmProgramPose convertedPose = {0};
    ArmProgramPose poseList[8] = {0};
    size_t poseCount = 0U;
    pose.id = 1;
    snprintf(pose.name, sizeof(pose.name), "P1");
    snprintf(pose.comment, sizeof(pose.comment), "sdk example");
    pose.pose.poseType = ARM_POSE_TYPE_JOINT;
    pose.pose.jointSize = 6;
    pose.uf = 0;
    pose.tf = 0;
    ret = Arm_Motion_GetCurrentPose(handle, ARM_POSE_TYPE_JOINT, &pose.pose);
    printf("[c99_program] GetCurrentPose(for pose) 状态码 / GetCurrentPose(for pose) status code: %d\n", ret);
    ret = Arm_ProgramPose_Convert(handle, &pose, ARM_POSE_TYPE_JOINT, ARM_POSE_TYPE_CART, &convertedPose);
    printf("[c99_program] ProgramPose_Convert 状态码 / ProgramPose_Convert status code: %d\n", ret);
    ret = Arm_ProgramPose_Read(handle, "demo.bas", 1, ARM_PROGRAM_USER, &readPose);
    printf("[c99_program] ProgramPose_Read 状态码 / ProgramPose_Read status code: %d, id=%d, name=%s\n", ret, readPose.id, readPose.name);
    ret = Arm_ProgramPose_Write(handle, "demo.bas", 1, ARM_PROGRAM_USER, &pose);
    printf("[c99_program] ProgramPose_Write 状态码 / ProgramPose_Write status code: %d\n", ret);
    ret = Arm_ProgramPose_Add(handle, "demo.bas", 2, ARM_PROGRAM_USER, &pose);
    printf("[c99_program] ProgramPose_Add 状态码 / ProgramPose_Add status code: %d\n", ret);
    ret = Arm_ProgramPose_ReadAll(handle, "demo.bas", ARM_PROGRAM_USER, poseList, 8U, &poseCount);
    printf("[c99_program] ProgramPose_ReadAll 状态码 / ProgramPose_ReadAll status code: %d, 数量 / Count: %zu\n", ret, poseCount);
    if (poseCount == 0U) {
        poseList[0] = pose;
        poseCount = 1U;
    }
    ret = Arm_ProgramPose_WriteBatch(handle, "demo.bas", poseList, poseCount);
    printf("[c99_program] ProgramPose_WriteBatch 状态码 / ProgramPose_WriteBatch status code: %d\n", ret);

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