4.16 Natural Language Control

Overview

The NLUControl module provides the ability to control robots through natural language instructions. Users can describe desired robot actions in everyday language, and the system automatically converts them into executable code and executes it after safety checks.

Constructor

Method Name	NLUControl( controller_ip : str)
Description	Natural language control class for controlling robot motion through natural language. Usually accessed via arm.nlu , no manual instantiation needed.
Request Parameters	controller_ip : str Controller IP address
Return Value	No return value
Notes	This class is automatically created when the Arm class is instantiated. Users can access it directly through arm.nlu .
Compatible robot software version	Collaborative (Copper): v7.7.0.0+ Industrial (Bronze): v7.7.0.0+

4.16.1 Execute Natural Language Instruction

Method Name	execute( natural_language : str) -> tuple[NLUGeneratedCode, StatusCodeEnum]
Description	Control the robot through natural language instructions. The system translates the natural language into executable code and returns it.
Request Parameters	natural_language : str Natural language instruction, e.g., "Move the robot to zero point and get the current position" Supports complex multi-step instructions such as sequential execution, conditional judgments, etc.
Return Value	NLUGeneratedCode: Generated code object containing executable code and approval status StatusCodeEnum: Function execution result
Notes	- The returned NLUGeneratedCode object contains a needs_approval property indicating whether user approval is required - If needs_approval=True , you must call the approve() method before execution - You can view the generated code content via result.code
Compatible robot software version	Collaborative (Copper): v7.7.0.0+ Industrial (Bronze): v7.7.0.0+

NLUGeneratedCode Class

Overview

The NLUGeneratedCode class is used to encapsulate, manage, and safely execute Python code snippets generated by the NLU service. This class provides a security mechanism for code approval and execution, ensuring that code requiring approval must be explicitly approved before execution.

Properties

Property Name	Type	Description
needs_approval	bool	Whether approval is required before execution, determined by the code's danger level
code	str	The generated executable Python code string

4.16.2 Approve Code Execution

Method Name	approve()
Description	Approve code execution. After calling this method, the code is marked as approved and can be executed via the execute_code() method.
Request Parameters	No parameters
Return Value	No return
Notes	- This method only needs to be called when needs_approval=True - Executing code that requires approval without calling approve() will return an error
Compatible robot software version	Collaborative (Copper): v7.7.0.0+ Industrial (Bronze): v7.7.0.0+

4.16.3 Execute Generated Code

Method Name	execute_code() -> tuple[Any, StatusCodeEnum]
Description	Execute the NLU-generated code. If the code requires approval and has not been approved, an error is returned.
Request Parameters	No parameters
Return Value	Any: Code execution result, type depends on the generated code StatusCodeEnum: Function execution result
Notes	- If needs_approval=True but approve() was not called, returns NLU_APPROVAL_REQUIRED error - Any exceptions during code execution are caught and returned as corresponding error status codes
Compatible robot software version	Collaborative (Copper): v7.7.0.0+ Industrial (Bronze): v7.7.0.0+

4.16.4 Print Generated Code

Method Name	print_code()
Description	Print the generated code for user review. Output format includes syntax highlighting.
Request Parameters	No parameters
Return Value	No return
Notes	It is recommended to call this method to view the code content before deciding whether to approve execution when approval is needed
Compatible robot software version	Collaborative (Copper): v7.7.0.0+ Industrial (Bronze): v7.7.0.0+

Usage Examples

Example 1: Basic Query Operation

nlu_control/get_controller_version.py

#!python
"""
Copyright © 2016 Agilebot Robotics Ltd. All rights reserved.
Instruction: 自然语言基础控制示例 / Natural Language Basic Control Example
"""

from Agilebot import Arm, StatusCodeEnum

# [ZH] 初始化捷勃特机器人
# [EN] Initialize the Agilebot robot
arm = Arm()
# [ZH] 连接捷勃特机器人
# [EN] Connect to the Agilebot robot
ret = arm.connect("10.27.1.254")

# [ZH] 检查是否连接成功
# [EN] Check if connection is successful
if ret == StatusCodeEnum.OK:
    print("机器人连接成功 / Robot connected successfully")
else:
    print(f"机器人连接失败，错误代码 / Robot connection failed, error code: {ret.errmsg}")
    arm.disconnect()
    exit(1)


# [ZH] 示例：使用自然语言获取控制器版本信息
# [EN] Example: Use natural language to get controller version information
result, ret = arm.nlu.execute("获取控制器版本信息")

if ret == StatusCodeEnum.OK:
    print("自然语言指令执行成功 / Natural language command executed successfully")

    if result.needs_approval:
        print("\n" + "=" * 50)
        print("警告：需要用户确认 / Warning: User Approval Required")
        print("=" * 50)

        result.print_code()
        print("\n请确认是否执行此代码 / Please confirm if you want to execute this code:")
        user_input = input("\n(yes/no): ").strip().lower()
        if user_input not in ["yes", "y"]:
            print("用户拒绝执行代码 / User rejected code execution")
            arm.disconnect()
            exit(1)
        else:
            result.approve()
    exec_result, ret = result.execute_code()
    if ret == StatusCodeEnum.OK:
        print(f"执行结果 / Execution result: {exec_result}")
else:
    print(f"自然语言指令执行失败 / Natural language command failed: {ret.errmsg}")

# [ZH] 断开捷勃特机器人连接
# [EN] Disconnect from Agilebot robot
arm.disconnect()
print("\n机器人断开连接成功 / Robot disconnected successfully")

Example 2: Sequential Execution of Multiple Tasks

nlu_control/serial_execution.py

#!python
"""
Copyright © 2016 Agilebot Robotics Ltd. All rights reserved.
Instruction: 自然语言顺序执行示例 / Natural Language Sequential Execution Example
"""

from Agilebot import Arm, StatusCodeEnum

# [ZH] 初始化捷勃特机器人
# [EN] Initialize the Agilebot robot
arm = Arm()
# [ZH] 连接捷勃特机器人
# [EN] Connect to the Agilebot robot
ret = arm.connect("10.27.1.254")

# [ZH] 检查是否连接成功
# [EN] Check if connection is successful
if ret == StatusCodeEnum.OK:
    print("机器人连接成功 / Robot connected successfully")
else:
    print(f"机器人连接失败，错误代码 / Robot connection failed, error code: {ret.errmsg}")
    arm.disconnect()
    exit(1)


# [ZH] 示例：使用自然语言让机器人按顺序执行任务
# [EN] Example: Use natural language to instruct the robot to execute tasks sequentially
result, ret = arm.nlu.execute(
    """
按顺序执行：
1. 清除报警；
2. 控制机械臂所有关节运动至零点位置；
3. 启动程序 'Put_into_box'，等待下发完成，并等待其执行结束；
4. 获取当前位姿。
"""
)

if ret == StatusCodeEnum.OK:
    print("自然语言指令执行成功 / Natural language command executed successfully")
    if result.needs_approval:
        print("\n" + "=" * 50)
        print("警告：需要用户确认 / Warning: User Approval Required")
        print("=" * 50)

        result.print_code()
        print("\n请确认是否执行此代码 / Please confirm if you want to execute this code:")
        user_input = input("\n(yes/no): ").strip().lower()
        if user_input not in ["yes", "y"]:
            print("用户拒绝执行代码 / User rejected code execution")
            arm.disconnect()
            exit(1)
        else:
            result.approve()
    exec_result, ret = result.execute_code()
    if ret == StatusCodeEnum.OK:
        print(f"执行结果 / Execution result: {exec_result}")
else:
    print(f"自然语言指令执行失败 / Natural language command failed: {ret.errmsg}")

# [ZH] 断开捷勃特机器人连接
# [EN] Disconnect from Agilebot robot
arm.disconnect()
print("\n机器人断开连接成功 / Robot disconnected successfully")