Skip to content

3.2 ControllerInfo Class

Overview

ControllerInfo handles basic controller status queries and a small set of basic controls, including version, controller status, robot status, servo status, soft mode, user operation mode, and host-side access keepalive.

Prerequisites

All ControllerInfo APIs require Arm::Connect() to succeed first. If the interface module is not bound:

  • Query APIs return an empty string or UNKNOWN , with status code OTHER_ERR .
  • Control APIs usually return OTHER_ERR .
  • AcquireAccess() / ReleaseAccess() do not have a status code; when not connected, they return directly.

3.2.1 Query APIs

3.2.1.1 Get Robot Controller Version

cpp
GetControllerVersion() -> std::pair<std::string, STATUS_CODE>
ItemDescription
DescriptionGets the current Agilebot robot controller version
Request ParametersNone
Return Valuestd::string: controller version
STATUS_CODE: function execution result
NotesArm::Connect() also reads this version internally and fills arm.version
Compatible Robot Software VersionsCollaborative (Copper): v7.5.0.0+
Industrial (Bronze): v7.5.0.0+

3.2.1.2 Get Current Controller Running Status

cpp
GetCtrlStatus() -> std::pair<CtrlStatusEnum, STATUS_CODE>
ItemDescription
DescriptionGets the current Agilebot robot controller running status
Request ParametersNone
Return ValueCtrlStatusEnum: controller running status
STATUS_CODE: function execution result
Compatible Robot Software VersionsCollaborative (Copper): v7.5.0.0+
Industrial (Bronze): v7.5.0.0+

3.2.1.3 Get Robot Running Status

cpp
GetRobotStatus() -> std::pair<RobotStatusEnum, STATUS_CODE>
ItemDescription
DescriptionGets the Agilebot robot running status
Request ParametersNone
Return ValueRobotStatusEnum: robot running status
STATUS_CODE: function execution result
Compatible Robot Software VersionsCollaborative (Copper): v7.5.0.0+
Industrial (Bronze): v7.5.0.0+

3.2.1.4 Get Current Servo Controller Status

cpp
GetServoStatus() -> std::pair<ServoStatusEnum, STATUS_CODE>
ItemDescription
DescriptionGets the current Agilebot robot servo controller status
Request ParametersNone
Return ValueServoStatusEnum: servo controller status
STATUS_CODE: function execution result
Compatible Robot Software VersionsCollaborative (Copper): v7.5.0.0+
Industrial (Bronze): v7.5.0.0+

3.2.1.5 Get Current Robot Model

cpp
GetArmModelInfo() -> std::pair<std::string, STATUS_CODE>
ItemDescription
DescriptionGets the current robot model information
Request ParametersNone
Return Valuestd::string: robot model, such as "GBT-C5A"
STATUS_CODE: function execution result
Compatible Robot Software VersionsCollaborative (Copper): v7.5.0.0+
Industrial (Bronze): v7.5.0.0+

3.2.1.6 Get Current Robot Soft Mode

cpp
GetSoftMode() -> std::pair<SoftModeEnum, STATUS_CODE>
ItemDescription
DescriptionGets the current robot soft mode, namely the manual/auto state in PC mode
Request ParametersNone
Return ValueSoftModeEnum: soft mode
STATUS_CODE: function execution result
Compatible Robot Software VersionsCollaborative (Copper): v7.5.0.0+
Industrial (Bronze): v7.5.0.0+

3.2.1.7 Get Robot Operation Mode

cpp
GetOpMode() -> std::pair<OpModeEnum, STATUS_CODE>
ItemDescription
DescriptionGets the current robot operation mode, such as manual/auto operation permission state for a robot or virtual controller
Request ParametersNone
Return ValueOpModeEnum: operation mode
STATUS_CODE: function execution result
NotesIf the controller does not return a valid mode, the value falls back to OpModeEnum::UNKNOWN
Compatible Robot Software VersionsCollaborative (Copper): v7.5.0.0+
Industrial (Bronze): v7.5.0.0+

3.2.2 Control APIs

3.2.2.1 Robot Servo On

cpp
ServoOn() -> STATUS_CODE
ItemDescription
DescriptionTurns on servo power for the Agilebot robot
Request ParametersNone
Return ValueSTATUS_CODE: function execution result
Compatible Robot Software VersionsCollaborative (Copper): v7.5.0.0+
Industrial (Bronze): v7.5.0.0+

3.2.2.2 Robot Servo Off

cpp
ServoOff() -> STATUS_CODE
ItemDescription
DescriptionTurns off servo power for the Agilebot robot
Request ParametersNone
Return ValueSTATUS_CODE: function execution result
Compatible Robot Software VersionsCollaborative (Copper): v7.5.0.0+
Industrial (Bronze): v7.5.0.0+

3.2.2.3 Robot Servo Reset

cpp
ServoReset() -> STATUS_CODE
ItemDescription
DescriptionResets the Agilebot robot servo
Request ParametersNone
Return ValueSTATUS_CODE: function execution result
Compatible Robot Software VersionsCollaborative (Copper): v7.5.0.0+
Industrial (Bronze): v7.5.0.0+

3.2.2.4 Set Current Robot Soft Mode

cpp
SetSoftMode(SoftModeEnum mode) -> STATUS_CODE
ItemDescription
DescriptionSets the current robot soft mode, namely the manual/auto state in PC mode
Request Parametersmode : SoftModeEnum soft-mode value
Return ValueSTATUS_CODE: function execution result
Compatible Robot Software VersionsCollaborative (Copper): v7.5.0.0+
Industrial (Bronze): v7.5.0.0+

3.2.2.5 Set Robot Operation Mode

cpp
SetOpMode(OpModeEnum mode) -> STATUS_CODE
ItemDescription
DescriptionSets the robot operation mode. Only virtual robots / simulation controllers are supported
Request Parametersmode : OpModeEnum target operation mode. It must not be UNKNOWN
Return ValueSTATUS_CODE: function execution result
NotesIf OpModeEnum::UNKNOWN is passed, the API returns UNSUPPORTED_PARAMETER
Compatible Robot Software VersionsCollaborative (Copper): simulation only; Industrial (Bronze): simulation only

3.2.2.6 Set Robot LED Indicator

cpp
SwitchLedLight(bool mode) -> STATUS_CODE
ItemDescription
DescriptionControls the Agilebot robot LED indicator
Request Parametersmode : bool indicator state. true turns it on, false turns it off
Return ValueSTATUS_CODE: function execution result
Compatible Robot Software VersionsCollaborative (Copper): v7.5.1.3+
Industrial (Bronze): Not supported

3.2.2.7 Robot Emergency Stop

cpp
Estop() -> STATUS_CODE
ItemDescription
DescriptionEmergency-stops the Agilebot robot
Request ParametersNone
Return ValueSTATUS_CODE: function execution result
Compatible Robot Software VersionsCollaborative (Copper): v7.5.0.0+
Industrial (Bronze): v7.5.0.0+

3.2.3 Access Control APIs

3.2.3.1 Host Acquires Operation Access

cpp
AcquireAccess()
ItemDescription
DescriptionThe host acquires operation access and puts the robot into PC mode. The SDK periodically sends keepalive messages to the controller
Request ParametersNone
Return ValueNo return value
Behavior- Returns directly when not connected
- Executes ReleaseAccess() before each call to avoid registering duplicates
- Registers a 2000ms keepalive timer task on the dedicated Arm network thread
NotesOnly industrial robots need this API to keep PC mode active. Collaborative robots and P7A do not need it
Compatible Robot Software VersionsCollaborative (Copper): Not supported
Industrial (Bronze): v7.5.0.0+

3.2.3.2 Host Returns Operation Access

cpp
ReleaseAccess()
ItemDescription
DescriptionThe host returns operation access, exits PC mode, and stops the keepalive timer task registered by AcquireAccess()
Request ParametersNone
Return ValueNo return value
Behavior- Cancels the keepalive timer task in the current session
- Arm::Disconnect() , Info::Reset() , and destruction also call it actively
NotesOnly industrial robots need this API
Compatible Robot Software VersionsCollaborative (Copper): Not supported
Industrial (Bronze): v7.5.0.0+

Common Return Semantics

ScenarioReturn
Query API called while not connectedOTHER_ERR , with the data value falling back to an empty string or UNKNOWN
Control API called while not connectedOTHER_ERR
AcquireAccess / ReleaseAccess called while not connectedReturns directly, with no additional error code

Call Recommendations

  1. After connecting, call GetControllerVersion() and GetArmModelInfo() first for device identification.
  2. Read a mode before writing it to avoid blind writes.
  3. AcquireAccess() is commonly used for PUMA / industrial robot PC-mode keepalive scenarios; collaborative robots usually do not need it.

Minimal Call Example

cpp
#include <iostream>      // Standard output stream for printing query results
#include "arm_api.h"    // Arm entry point; after connection, information APIs are accessed through arm.controllerInfo
#include "status_code.h" // STATUS_CODE for checking SDK call results

int main()
{
    Arm arm;
    STATUS_CODE connectRet = arm.Connect("192.168.110.2", "");
    if (connectRet != STATUS_CODE::OK) {
        return 1;
    }

    auto [version, versionRet] = arm.controllerInfo.GetControllerVersion();
    auto [servoStatus, servoRet] = arm.controllerInfo.GetServoStatus();
    auto [softMode, softModeRet] = arm.controllerInfo.GetSoftMode();
    auto [opMode, opModeRet] = arm.controllerInfo.GetOpMode();
    if (versionRet != STATUS_CODE::OK ||
        servoRet != STATUS_CODE::OK ||
        softModeRet != STATUS_CODE::OK ||
        opModeRet != STATUS_CODE::OK) {
        return 1;
    }

    std::cout << "version=" << version << "\n";
    std::cout << "servo_status=" << static_cast<int>(servoStatus) << "\n";
    std::cout << "soft_mode=" << static_cast<int>(softMode) << "\n";
    std::cout << "op_mode=" << static_cast<int>(opMode) << "\n";
    arm.controllerInfo.AcquireAccess();
    arm.controllerInfo.ReleaseAccess();
    return 0;
}

Scenario Examples

The snippets below cover read-only status, mode setting, robot actions, and PC access. They assume the arm object from the minimal example is already connected. Calls that change robot state remain commented out; run them only after checking the site.

Read Version, Model, and Status

cpp
auto [version, versionRet] = arm.controllerInfo.GetControllerVersion();
auto [model, modelRet] = arm.controllerInfo.GetArmModelInfo();
auto [ctrlStatus, ctrlRet] = arm.controllerInfo.GetCtrlStatus();
auto [robotStatus, robotRet] = arm.controllerInfo.GetRobotStatus();
auto [servoStatus, servoRet] = arm.controllerInfo.GetServoStatus();
if (versionRet == STATUS_CODE::OK && modelRet == STATUS_CODE::OK && ctrlRet == STATUS_CODE::OK && robotRet == STATUS_CODE::OK && servoRet == STATUS_CODE::OK) {
    std::cout << "version=" << version << " model=" << model << "\n";
    std::cout << "ctrl=" << static_cast<int>(ctrlStatus) << " robot=" << static_cast<int>(robotStatus) << " servo=" << static_cast<int>(servoStatus) << "\n";
}

Read and Set Modes

cpp
auto [softMode, softRet] = arm.controllerInfo.GetSoftMode();
auto [opMode, opRet] = arm.controllerInfo.GetOpMode();
if (softRet == STATUS_CODE::OK && opRet == STATUS_CODE::OK) {
    std::cout << "soft=" << static_cast<int>(softMode) << " op=" << static_cast<int>(opMode) << "\n";
}
// STATUS_CODE setSoftRet = arm.controllerInfo.SetSoftMode(softMode);
// STATUS_CODE setOpRet = arm.controllerInfo.SetOpMode(opMode);

Servo, LED, and Emergency Stop Actions

cpp
// STATUS_CODE servoOnRet = arm.controllerInfo.ServoOn();
// STATUS_CODE servoOffRet = arm.controllerInfo.ServoOff();
// STATUS_CODE resetRet = arm.controllerInfo.ServoReset();
// STATUS_CODE ledRet = arm.controllerInfo.SwitchLedLight(true);
// STATUS_CODE estopRet = arm.controllerInfo.Estop();

Industrial Robot PC Access

cpp
// arm.controllerInfo.AcquireAccess();
// arm.controllerInfo.ReleaseAccess();

Example code:

cpp17/info_get_controller_version/src/query_version_and_model/run.cpp
cpp
#include <iostream>
#include "arm_api.h"
#include "status_code.h"

#include "query_version_and_model/run.h"

/**
 * 查询版本与型号门面。
 * @return 0 表示成功,否则返回 1。
 */
int RunInfoGetControllerVersionQueryVersionAndModel(void)
{
    // [ZH] 连接机器人,请直接修改下面的魔鬼字符串。
    // [EN] Connect to the robot and edit the hard-coded magic strings below directly.
    Arm arm;
    STATUS_CODE connectRet = arm.Connect("10.27.1.2", "10.27.1.102");
    if (connectRet != STATUS_CODE::OK) {
        std::cerr << "[cpp17_info_basic] 连接机器人失败 / Connect to the robot failed, 状态码 / Status code: "
                  << static_cast<int>(connectRet) << "\n";
        return 1;
    }
    std::cout << "[cpp17_info_basic] 机器人连接成功 / Robot connected successfully\n";
    // [ZH] 获取控制器版本和机械臂型号。
    // [EN] Get the controller version and robot model.
    std::pair<std::string, STATUS_CODE> versionPair = arm.controllerInfo.GetControllerVersion();
    std::pair<std::string, STATUS_CODE> modelPair = arm.controllerInfo.GetArmModelInfo();
    std::cout << "[cpp17_info_basic] GetControllerVersion 状态码 / GetControllerVersion status code: "
              << static_cast<int>(versionPair.second)
              << ", 版本 / Version: " << versionPair.first << "\n";
    std::cout << "[cpp17_info_basic] GetArmModelInfo 状态码 / GetArmModelInfo status code: "
              << static_cast<int>(modelPair.second)
              << ", 型号 / Model: " << modelPair.first << "\n";

    // [ZH] 断开连接,结束示例。
    // [EN] Disconnect and finish the example.
    arm.Disconnect();
    std::cout << "[cpp17_info_basic] 示例结束 / Example finished\n";
    return 0;
}
cpp17/info_state_modes/src/query_state_modes/run.cpp
cpp
#include <iostream>
#include "arm_api.h"
#include "status_code.h"

#include "query_state_modes/run.h"

/**
 * 查询状态与模式门面。
 * @return 0 表示成功,否则返回 1。
 */
int RunInfoStateModesQueryStateModes(void)
{
    // [ZH] 连接机器人,请直接修改下面的魔鬼字符串。
    // [EN] Connect to the robot and edit the hard-coded magic strings below directly.
    Arm arm;
    STATUS_CODE connectRet = arm.Connect("10.27.1.2", "10.27.1.102");
    if (connectRet != STATUS_CODE::OK) {
        std::cerr << "[cpp17_arm_state] 连接机器人失败 / Connect to the robot failed, 状态码 / Status code: "
                  << static_cast<int>(connectRet) << "\n";
        return 1;
    }
    std::cout << "[cpp17_arm_state] 机器人连接成功 / Robot connected successfully\n";
    // [ZH] 获取伺服状态、软模式和操作模式。
    // [EN] Get the servo status, soft mode, and operation mode.
    std::pair<ServoStatusEnum, STATUS_CODE> servoPair = arm.controllerInfo.GetServoStatus();
    std::pair<SoftModeEnum, STATUS_CODE> softPair = arm.controllerInfo.GetSoftMode();
    std::pair<OpModeEnum, STATUS_CODE> opPair = arm.controllerInfo.GetOpMode();
    std::cout << "[cpp17_arm_state] GetServoStatus 状态码 / GetServoStatus status code: "
              << static_cast<int>(servoPair.second)
              << ", 伺服状态 / Servo status: " << static_cast<int>(servoPair.first) << "\n";
    std::cout << "[cpp17_arm_state] GetSoftMode 状态码 / GetSoftMode status code: "
              << static_cast<int>(softPair.second)
              << ", 软模式 / Soft mode: " << static_cast<int>(softPair.first) << "\n";
    std::cout << "[cpp17_arm_state] GetOpMode 状态码 / GetOpMode status code: "
              << static_cast<int>(opPair.second)
              << ", 操作模式 / Operation mode: " << static_cast<int>(opPair.first) << "\n";

    // [ZH] 断开连接,结束示例。
    // [EN] Disconnect and finish the example.
    arm.Disconnect();
    std::cout << "[cpp17_arm_state] 示例结束 / Example finished\n";
    return 0;
}
cpp17/info_state_modes/src/write_back_modes/run.cpp
cpp
#include <iostream>
#include "arm_api.h"
#include "status_code.h"

#include "write_back_modes/run.h"

/**
 * 写回软模式与操作模式门面。
 * @return 0 表示成功,否则返回 1。
 */
int RunInfoStateModesWriteBackModes(void)
{
    // [ZH] 连接机器人,请直接修改下面的魔鬼字符串。
    // [EN] Connect to the robot and edit the hard-coded magic strings below directly.
    Arm arm;
    STATUS_CODE connectRet = arm.Connect("10.27.1.2", "10.27.1.102");
    if (connectRet != STATUS_CODE::OK) {
        std::cerr << "[cpp17_arm_state] 连接机器人失败 / Connect to the robot failed, 状态码 / Status code: "
                  << static_cast<int>(connectRet) << "\n";
        return 1;
    }
    std::cout << "[cpp17_arm_state] 机器人连接成功 / Robot connected successfully\n";
    // [ZH] 读取并写回软模式与操作模式。
    // [EN] Read and write back the soft mode and operation mode.
    std::pair<SoftModeEnum, STATUS_CODE> softPair = arm.controllerInfo.GetSoftMode();
    std::pair<OpModeEnum, STATUS_CODE> opPair = arm.controllerInfo.GetOpMode();
    STATUS_CODE setSoftRet = arm.controllerInfo.SetSoftMode(softPair.first);
    STATUS_CODE setOpRet = arm.controllerInfo.SetOpMode(opPair.first);
    std::cout << "[cpp17_arm_state] SetSoftMode 状态码 / SetSoftMode status code: "
              << static_cast<int>(setSoftRet) << "\n";
    std::cout << "[cpp17_arm_state] SetOpMode 状态码 / SetOpMode status code: "
              << static_cast<int>(setOpRet) << "\n";

    // [ZH] 断开连接,结束示例。
    // [EN] Disconnect and finish the example.
    arm.Disconnect();
    std::cout << "[cpp17_arm_state] 示例结束 / Example finished\n";
    return 0;
}
cpp17/info_state_modes/src/access_control/run.cpp
cpp
#include <iostream>
#include "arm_api.h"
#include "status_code.h"

#include "access_control/run.h"

/**
 * 获取和归还控制权门面。
 * @return 0 表示成功,否则返回 1。
 */
int RunInfoStateModesAccessControl(void)
{
    // [ZH] 连接机器人,请直接修改下面的魔鬼字符串。
    // [EN] Connect to the robot and edit the hard-coded magic strings below directly.
    Arm arm;
    STATUS_CODE connectRet = arm.Connect("10.27.1.2", "10.27.1.102");
    if (connectRet != STATUS_CODE::OK) {
        std::cerr << "[cpp17_arm_state] 连接机器人失败 / Connect to the robot failed, 状态码 / Status code: "
                  << static_cast<int>(connectRet) << "\n";
        return 1;
    }
    std::cout << "[cpp17_arm_state] 机器人连接成功 / Robot connected successfully\n";
    // [ZH] 获取并归还 SDK 控制权。
    // [EN] Acquire and release the SDK access token.
    arm.controllerInfo.AcquireAccess();
    std::cout << "[cpp17_arm_state] 已获取控制权 / SDK access acquired\n";
    arm.controllerInfo.ReleaseAccess();
    std::cout << "[cpp17_arm_state] 已归还控制权 / SDK access released\n";

    // [ZH] 断开连接,结束示例。
    // [EN] Disconnect and finish the example.
    arm.Disconnect();
    std::cout << "[cpp17_arm_state] 示例结束 / Example finished\n";
    return 0;
}
cpp17/info_state_modes/src/action_apis/run.cpp
cpp
#include <iostream>
#include "arm_api.h"
#include "status_code.h"

#include "action_apis/run.h"

/**
 * 动作接口门面。
 * @return 0 表示成功,否则返回 1。
 */
int RunInfoStateModesActionApis(void)
{
    // [ZH] 连接机器人,请直接修改下面的魔鬼字符串。
    // [EN] Connect to the robot and edit the hard-coded magic strings below directly.
    Arm arm;
    STATUS_CODE connectRet = arm.Connect("10.27.1.2", "10.27.1.102");
    if (connectRet != STATUS_CODE::OK) {
        std::cerr << "[cpp17_arm_state] 连接机器人失败 / Connect to the robot failed, 状态码 / Status code: "
                  << static_cast<int>(connectRet) << "\n";
        return 1;
    }
    std::cout << "[cpp17_arm_state] 机器人连接成功 / Robot connected successfully\n";
    // [ZH] 顺序执行全部动作接口。
    // [EN] Execute all action APIs in sequence.
    STATUS_CODE servoOnRet = arm.controllerInfo.ServoOn();
    STATUS_CODE servoOffRet = arm.controllerInfo.ServoOff();
    STATUS_CODE ledRet = arm.controllerInfo.SwitchLedLight(true);
    STATUS_CODE resetRet = arm.controllerInfo.ServoReset();
    STATUS_CODE estopRet = arm.controllerInfo.Estop();
    std::cout << "[cpp17_arm_state] ServoOn 状态码 / ServoOn status code: "
              << static_cast<int>(servoOnRet) << "\n";
    std::cout << "[cpp17_arm_state] ServoOff 状态码 / ServoOff status code: "
              << static_cast<int>(servoOffRet) << "\n";
    std::cout << "[cpp17_arm_state] SwitchLedLight 状态码 / SwitchLedLight status code: "
              << static_cast<int>(ledRet) << "\n";
    std::cout << "[cpp17_arm_state] ServoReset 状态码 / ServoReset status code: "
              << static_cast<int>(resetRet) << "\n";
    std::cout << "[cpp17_arm_state] Estop 状态码 / Estop status code: "
              << static_cast<int>(estopRet) << "\n";

    // [ZH] 断开连接,结束示例。
    // [EN] Disconnect and finish the example.
    arm.Disconnect();
    std::cout << "[cpp17_arm_state] 示例结束 / Example finished\n";
    return 0;
}