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 codeOTHER_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>| Item | Description |
|---|---|
| Description | Gets the current Agilebot robot controller version |
| Request Parameters | None |
| Return Value | std::string: controller version STATUS_CODE: function execution result |
| Notes | Arm::Connect() also reads this version internally and fills arm.version |
| Compatible Robot Software Versions | Collaborative (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>| Item | Description |
|---|---|
| Description | Gets the current Agilebot robot controller running status |
| Request Parameters | None |
| Return Value | CtrlStatusEnum: controller running status STATUS_CODE: function execution result |
| Compatible Robot Software Versions | Collaborative (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>| Item | Description |
|---|---|
| Description | Gets the Agilebot robot running status |
| Request Parameters | None |
| Return Value | RobotStatusEnum: robot running status STATUS_CODE: function execution result |
| Compatible Robot Software Versions | Collaborative (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>| Item | Description |
|---|---|
| Description | Gets the current Agilebot robot servo controller status |
| Request Parameters | None |
| Return Value | ServoStatusEnum: servo controller status STATUS_CODE: function execution result |
| Compatible Robot Software Versions | Collaborative (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>| Item | Description |
|---|---|
| Description | Gets the current robot model information |
| Request Parameters | None |
| Return Value | std::string: robot model, such as "GBT-C5A" STATUS_CODE: function execution result |
| Compatible Robot Software Versions | Collaborative (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>| Item | Description |
|---|---|
| Description | Gets the current robot soft mode, namely the manual/auto state in PC mode |
| Request Parameters | None |
| Return Value | SoftModeEnum: soft mode STATUS_CODE: function execution result |
| Compatible Robot Software Versions | Collaborative (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>| Item | Description |
|---|---|
| Description | Gets the current robot operation mode, such as manual/auto operation permission state for a robot or virtual controller |
| Request Parameters | None |
| Return Value | OpModeEnum: operation mode STATUS_CODE: function execution result |
| Notes | If the controller does not return a valid mode, the value falls back to OpModeEnum::UNKNOWN |
| Compatible Robot Software Versions | Collaborative (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| Item | Description |
|---|---|
| Description | Turns on servo power for the Agilebot robot |
| Request Parameters | None |
| Return Value | STATUS_CODE: function execution result |
| Compatible Robot Software Versions | Collaborative (Copper): v7.5.0.0+ Industrial (Bronze): v7.5.0.0+ |
3.2.2.2 Robot Servo Off
cpp
ServoOff() -> STATUS_CODE| Item | Description |
|---|---|
| Description | Turns off servo power for the Agilebot robot |
| Request Parameters | None |
| Return Value | STATUS_CODE: function execution result |
| Compatible Robot Software Versions | Collaborative (Copper): v7.5.0.0+ Industrial (Bronze): v7.5.0.0+ |
3.2.2.3 Robot Servo Reset
cpp
ServoReset() -> STATUS_CODE| Item | Description |
|---|---|
| Description | Resets the Agilebot robot servo |
| Request Parameters | None |
| Return Value | STATUS_CODE: function execution result |
| Compatible Robot Software Versions | Collaborative (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| Item | Description |
|---|---|
| Description | Sets the current robot soft mode, namely the manual/auto state in PC mode |
| Request Parameters | mode : SoftModeEnum soft-mode value |
| Return Value | STATUS_CODE: function execution result |
| Compatible Robot Software Versions | Collaborative (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| Item | Description |
|---|---|
| Description | Sets the robot operation mode. Only virtual robots / simulation controllers are supported |
| Request Parameters | mode : OpModeEnum target operation mode. It must not be UNKNOWN |
| Return Value | STATUS_CODE: function execution result |
| Notes | If OpModeEnum::UNKNOWN is passed, the API returns UNSUPPORTED_PARAMETER |
| Compatible Robot Software Versions | Collaborative (Copper): simulation only; Industrial (Bronze): simulation only |
3.2.2.6 Set Robot LED Indicator
cpp
SwitchLedLight(bool mode) -> STATUS_CODE| Item | Description |
|---|---|
| Description | Controls the Agilebot robot LED indicator |
| Request Parameters | mode : bool indicator state. true turns it on, false turns it off |
| Return Value | STATUS_CODE: function execution result |
| Compatible Robot Software Versions | Collaborative (Copper): v7.5.1.3+ Industrial (Bronze): Not supported |
3.2.2.7 Robot Emergency Stop
cpp
Estop() -> STATUS_CODE| Item | Description |
|---|---|
| Description | Emergency-stops the Agilebot robot |
| Request Parameters | None |
| Return Value | STATUS_CODE: function execution result |
| Compatible Robot Software Versions | Collaborative (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()| Item | Description |
|---|---|
| Description | The host acquires operation access and puts the robot into PC mode. The SDK periodically sends keepalive messages to the controller |
| Request Parameters | None |
| Return Value | No 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 |
| Notes | Only industrial robots need this API to keep PC mode active. Collaborative robots and P7A do not need it |
| Compatible Robot Software Versions | Collaborative (Copper): Not supported Industrial (Bronze): v7.5.0.0+ |
3.2.3.2 Host Returns Operation Access
cpp
ReleaseAccess()| Item | Description |
|---|---|
| Description | The host returns operation access, exits PC mode, and stops the keepalive timer task registered by AcquireAccess() |
| Request Parameters | None |
| Return Value | No return value |
| Behavior | - Cancels the keepalive timer task in the current session - Arm::Disconnect() , Info::Reset() , and destruction also call it actively |
| Notes | Only industrial robots need this API |
| Compatible Robot Software Versions | Collaborative (Copper): Not supported Industrial (Bronze): v7.5.0.0+ |
Common Return Semantics
| Scenario | Return |
|---|---|
| Query API called while not connected | OTHER_ERR , with the data value falling back to an empty string or UNKNOWN |
| Control API called while not connected | OTHER_ERR |
AcquireAccess / ReleaseAccess called while not connected | Returns directly, with no additional error code |
Call Recommendations
- After connecting, call
GetControllerVersion()andGetArmModelInfo()first for device identification. - Read a mode before writing it to avoid blind writes.
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:
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;
}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;
}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;
}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;
}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;
}