上层运动控制及开发

上层运动控制开发基于PNDbotics机器人控制系统开发，通过调用底层运动控制接口可实现上层运动控制功能，也可基于开放接口及内置运动规划控制算法进行个性化开发。 上层运动控制实现方式为grpc，用户可根据例程自定义客户端调用相关进行机器人控制及开发，服务端暂不支持二次开发。

v1.0.0版本

接口定义文件proto

syntax = "proto3";
package adam_control;
// Define services
service RobotControl {
  rpc SetMode (SetModeRequest) returns (SetModeResponse); 
  rpc SetStandMotion (SetStandMotionRequest) returns (SetStandMotionResponse); 
  rpc SetStandCarryBox (SetCarryBoxRequest) returns (SetCarryBoxResponse); 
  rpc SetStandAction (SetActionRequest) returns (SetActionResponse); 
  rpc SetStandDynamic (SetDynamicStandRequest) returns (SetDynamicStandResponse); 
  rpc SetSpeed (SetSpeedRequest) returns (SetSpeedResponse); 
  rpc AutoUnigaitCOM (SetUnigaitCOMRequest) returns (SetUnigaitCOMResponse);
  rpc SetErrorClear (SetErrorClearRequest) returns (SetErrorClearResponse); 
  rpc GetStandList (GetStandListRequest) returns (GetStandListResponse);
  rpc GetRobotState (GetRobotStateRequest) returns (GetRobotStateResponse); 
}

客户端示例

依赖安装及编译

client示例工程

克隆 gRPC 仓库

git clone -b v1.46.3 https://github.com/grpc/grpc
cd grpc
git submodule update --init
# python install
pip install grpcio-tools

构建和安装 gRPC

mkdir -p cmake/build
cd cmake/build
cmake ../..
make -j$(nproc)
sudo make install

安装 Protocol Buffers

sudo apt-get install -y protobuf-compiler
sudo apt-get install -y libprotobuf-dev

安装 nlohmann json

sudo apt-get install nlohmann-json3-dev

Client说明

Client包为客户端示例工程，其中proto文件夹中包含定义完毕的运控端控制相关功能的协议文件；include文件夹中包含使用protobuf根据.proto文件生成的grpc相关的源文件以及头文件，后续可直接根据生成的api接口进行复写以及调用；src文件夹中为 C++ 客户端示例代码，python文件夹中为 python 客户端示例代码，按照上述步骤安装完依赖后使用下列脚本文件编译完成后生成对应客户端执行文件。

客户端IP

在连接机器人服务端之前，请先修改Client/ip_config.json中的服务端ip，即对应的机器人主机ip。(C++ 版本客户端请在修改ip之后请重新编译)

注意事项

由于服务端端口号固定为6666，所以请勿修改客户端中端口号。

{
  "server": {
    "ip": "xx.xx.xx.xx*"
  }
}

客户端编译运行

客户端下有三个脚本文件。
build.sh: grpc代码生成与 C++ 客户端编译。
run.sh: 客户端运行，可选择 C++ 或 Python 版本。
clean.sh: 清理编译文件。

###### Compile & Build ######
cd Client
chmod +x build.sh
./build.sh
# Since the version of the proto compiler may vary, use the following command to regenerate and replace files locally on the client (different versions of proto generation do not affect usage)
# The following files will be generated in the include and python directories:
# adam_control.grpc.pb.cc, adam_control.grpc.pb.h, adam_control_pb2_grpc.py: gRPC service and client code.
# adam_control.pb.cc, adam_control.pb.h, adam_control_pb2.py: Protocol Buffers message type code.

###### Run ######
chmod +x run.sh
./run.sh
# When using the run.sh script to start a client, add parameters to select the type of client to start. If no parameters are added, it defaults to the Python version client.
# Example: ./run.sh bin && ./run.sh python.

###### Clean ######
chmod +x clean.sh
./clean.sh
# The clean script will clean up the compiled files related to the C++client generated by build, but will not delete the generated grpc dependency files.

客户端代码&接口调用说明

Client包中给出了 python 以及 C++ 两种客户端实现方式，使用proto文件中定义的接口实现对应的控制功能，用户可参考客户端示例代码进行客户端或者调用api的复写。

接口调用示例(python)

SetMode
方法说明: 设置模式下发，模式开放有Start，Zero，Stand，Walk，Run，Stop。其他后续更新模式均可通过该方法下发。

注意事项

机器人启动默认为Start模式，下发模式注意首字母大写与状态机对应。实际模式执行请严格按照mode_enbale_list中可执行模式进行操作。

  # Test SetMode method
  success, message = client.set_mode("Start")
  # success returns the command execution result (true/false), message returns the command execution result information.

SetStandMotion
方法说明: 设置站立模式下的动作执行(Greeting， Chest Expansion， Stretching， Gentleman's Salute等)。

注意事项

只有机器人在Stand模式下，且没有执行其他动作时才可执行此指令。请按照motion_enable_list中的可执行动作进行操作。

  # Test SetStandMotion method
  motion = "Greeting"
  success, message = client.set_stand_motion(motion)

SetStandCarryBox
方法说明: 设置站立模式下的 carrybox 参数(stand模式下执行Squatting to Pick up the Box， Standing to Pick up the Box， Put Down the Box)。

注意事项

只有机器人在Stand模式下，且没有执行其他动作时才可执行此指令。请按照carrybox_enable_list中的可执行动作进行操作。

  # Test SetStandCarryBox method
  carry_box = "Squatting to Pick up the Box"
  success, message = client.set_stand_carry_box(carry_box)

SetStandAction
方法说明:设置站立时的动作参数(stand模式下实时调节stand_pitch, stand_roll, stand_yaw, stand_height)。

注意事项

只有机器人在Stand模式下，且没有执行其他动作时才可执行此指令。

  # Test SetStandAction method, set robot posture to (0.05, 0.05, 0.05) and lower height by 0.1.
  stand_pitch = 0.05
  stand_roll = 0.05
  stand_yaw = 0.05
  stand_height = -0.1
  success, message = client.set_stand_action(stand_pitch, stand_roll, stand_yaw, stand_height)

SetSpeed
方法说明: 设置机器人的移动速度参数(x,y,yaw)。

注意事项

只有机器人在Walk/Run模式下，才可执行此指令(由于客户端控制机器人运动速度存在危险性，暂未开放该模式下的客户端命令执行，控制速度请使用手柄键控)。

  # Test SetSpeed method, set x-direction speed to 0.5 m/s.
  x_speed = 0.5
  y_speed = 0.0
  yaw_speed = 0.0
  success, message = client.set_speed(x_speed, y_speed, yaw_speed)

AutoUnigaitCOM
方法说明: 开启调节机器人质心偏置，保证原地步态稳定。

注意事项

只有机器人在Walk/Run模式下，才可执行此指令。

  # Test AutoUnigaitCOM method
  unigait_mode_com_x = True
  success, message = client.auto_unigait_com(unigait_mode_com_x)

SetErrorClear
方法说明: 真机中使用，清除机器人错误状态，可不关电继续启动执行。

注意事项

只有在机器人驱动器处于错误状态时或Stop状态下，才可执行此指令。

  # Test SetErrorClear method
  error_clear_flag = True
  success, message = client.set_error_clear(error_clear_flag)

GetStandList
方法说明: 可在任意模式下获取站立模式下动作列表及姿态列表等。

注意事项

该列表为固定列表，请勿与enable_list混淆。

  # Test GetStandList method
  success, message = client.get_stand_list()

GetRobotState
方法说明: 获取机器人的当前状态，可执行的模式动作列表enable_list等。

注意事项

客户端例程会根据enable_list进行输入指令判断与下发，用户修改客户端需注意enable_list外的指令无法执行。

  # Test GetRobotState method
  success, message = client.get_robot_state(True)

python接口调用示例

python中接口调用方式与C++类似，具体请参考Client/python/adam_command_client.py。

客户端调用说明

GetStandList与GetRobotState均需实时获取，下发指令之前需根据列表进行指令下发，不满足该需求下的模式动作等均无法执行。

接口描述&参数调用方式一览

接口名称	描述	调用参数	赋值示例
SetMode	设置机器人模式	SetMode	Zero, Stand, Walk, Run, Stop
SetStandMotion	站立模式下 - 机器人执行预定义动捕动作	SetStandMotion	Greeting Chest Expansion Stretching Gentleman's Salute
SetStandCarryBox	站立模式下 - 机器人执行搬箱子动作	SetStandCarryBox	Squatting to Pick up the Box Standing to Pick up the Box Put Down the Box
SetStandAction	站立模式下 - 机器人执行姿态控制和蹲起高度控制	SetStandAction	0.0 0.0 0.0 0.0
SetStandDynamic	站立模式下 - 调整是否Dynamic Stand	SetStandDynamic	true false
SetSpeed	Walk和Run模式下 - 速度设置	SetSpeed	0.0 0.0 0.0
AutoUnigaitCOM	Walk和Run模式下 - COM的X方向偏置平衡	AutoUnigaitCOM	true false
SetErrorClear	不重启错误复位	SetErrorClear	\
GetStandList	获取机器人模式列表	GetStandList	\
GetRobotState	获取当前可执行状态	GetRobotState	\

python 客户端调用示例

使用方式与 C++ 版本一致，具体请参考Client/python/adam_command_client.py。相比 C++ 版本，拥有更方便的Tab补全、指令回看、混淆大小写功能，使用体验更佳。

cd python/
python3 adam_command_client.py
Adam Command Client v1.0.0
Type 'help' for usage information.

# Use the `help` to retrieve all executable commands
> help
Available commands:
  SetMode
  SetStandMotion
  SetStandCarryBox
  SetStandAction
  SetStandDynamic
  SetSpeed
  AutoUnigaitCOM
  SetErrorClear
  GetStandList
  GetRobotState
  exit

# The client will wait for the user to input the correct command
> SetMode
Available Modes:  Stand, Stop
Enter parameter for Setmode: a
Error: Invalid parameter. Please enter a valid option from the enable list.
Enter parameter for Setmode: Stand
Success: Mode set successfully

# The client will determine whether the user's input is executable based on the current robot status
> SetStandDynamic
Dynamic Stand State: False.
Enter 'true' or 'false' for enable balance: false
Already in the state: False. No change needed.
Enter 'true' or 'false' for enable balance: true
Success: Dynamic stand turn on

# Use Tab to complete the currently executable commands or parameters
> 
GetRobotState     SetStandAction    SetStandMotion    
GetStandList      SetStandCarryBox  exit              
SetMode           SetStandDynamic   help 
> SetStandMotion
Available Motions:  Greeting, Chest Expansion, Stretching, Gentleman’s Salute
Enter parameter for Setstandmotion: Greeting
Success: Stand motion set successfully

# Interaction logic of separating instruction and parameter interfaces
> SetStandAction
Action> Enter action values (stand_pitch stand_roll stand_yaw stand_height): 0 0 0 -0.1
Success: Stand pose set successfully
Action> Enter action values (stand_pitch stand_roll stand_yaw stand_height): exit
Exiting current command interface.
> exit
Exiting Adam Command Client.

# Obtain the robot command list and status information using the GetStandList and GetRobotState
> GetStandList
Modes: ['Start', 'Zero', 'Stand', 'Walk', 'Run', 'Stop']
Motions: ['Greeting', 'Chest Expansion', 'Stretching', "Gentleman's Salute"]
Actions: ['Roll', 'Pitch', 'Yaw', 'Floating Base Height']
Carry Boxes: ['Standing to Pick up the Box', 'Squatting to Pick up the Box', 'Put Down the Box']
Balance Control: Dynamic Stand
> GetRobotState
Current Mode: Stand
Current Motion: 
Enable Mode List: ['Walk', 'Zero', 'Stop']
Enable Motion List: ['Greeting', 'Chest Expansion', 'Stretching', "Gentleman's Salute"]
Enable Action List: ['Roll', 'Pitch', 'Yaw', 'Floating Base Height']
Enable Carry Box List: ['Standing to Pick up the Box', 'Squatting to Pick up the Box']
Balance Control Enable: Dynamic Stand
Stand Pitch: 0.0
Stand Roll: 0.0
Stand Yaw: 0.0
Stand Height: 0.0
X Velocity: 0.0
Y Velocity: 0.0
Yaw Velocity: 0.0
Balance Control State: False

C++客户端调用示例

使用方式与 python 版本大体一致，具体请参考Client/src/adam_command.cpp。

# Start client
cd bin/
./adam_command_client 
Adam Command Client v1.0.0
Type 'help' for usage information.
> help   
Available commands:
  SetMode
  SetStandMotion
  SetStandCarryBox
  SetStandAction
  SetStandDynamic
  SetSpeed
  AutoUnigaitCOM
  SetErrorClear
  GetStandList
  GetRobotState
  exit

# Ensure the server is running before sending commands, otherwise the terminal will print:
Failed to get robot state: RPC failed: failed to connect to all addresses

# Example: Mode setting
# Inputs not in the Available list (mode, motion, carrybox...) cannot be executed.
> SetMode
Available Modes: Zero 
Enter parameter for SetMode: > Stand
Invalid parameter. Please enter a valid option from the enable list.
> SetMode
Available Modes: Zero 
Enter parameter for SetMode: > Zero
Success: Mode set successfully!

# Example: Robot speed setting
> SetSpeed
Enter speed values (x y yaw) or type 'exit' to quit:
Speed> 0.1 0.0 0.0
Speed set successfully.
# Continuous speed setting is possible
Speed> 0.2 0.0 0.0
Speed> exit
>