Upper-layer Motion Control and Development

The development of upper-layer motion control is based on the PNDbotics robot control system. By calling the underlying motion control interfaces, the upper-layer motion control functions can be achieved. Additionally, personalized development can also be carried out based on the open interfaces and the built-in motion planning and control algorithms.

The implementation method of upper-layer motion control is gRPC. Users can customize the client according to the example routines to call relevant functions for robot control and development. Currently, the server side does not support secondary development.

Version v1.0.0

Interface Definition File 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 Examples

Dependency Installation and Compilation

Client sample project

Clone the gRPC Repository

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

Build and Install gRPC

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

Install Protocol Buffers

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

Install nlohmann json

sudo apt-get install nlohmann-json3-dev

Client Description

The "Client" package is a client-side sample project. The "proto" folder contains the protocol files that define the functions related to motion control at the control end. The "include" folder contains the source files and header files related to gRPC generated by Protobuf according to the.proto files. Subsequently, the generated API interfaces can be directly rewritten and called. The "src" folder contains the C++ client sample code, and the "python" folder contains the Python client sample code. After installing the dependencies according to the above steps, use the following script files to compile and generate the corresponding client-side executable files.

Client IP

Before connecting to the robot server, please modify the server IP in Client/ip_config.json, which is the corresponding IP of the robot host. (For the C++ version client, please recompile after modifying the IP.) + Precautions.

note

Since the server port number is fixed at 6666, please do not modify the port number in the client.

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

Client Compilation and Running

There are three script files under the client.
build.sh: Generate gRPC code and compile the C++ client.
run.sh: Run the client, and you can choose the C++ or Python version.
clean.sh: Clean up the compiled files.

###### 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 Code & Interface Call Instructions

The "Client" package provides two client implementation methods in Python and C++. The corresponding control functions are implemented using the interfaces defined in the proto file. Users can refer to the client sample code to rewrite the client or call the API.

Interface Call Examples (Python)

SetMode

Method Description: Send commands to set the mode. The available modes are Start, Zero, Stand, Walk, Run, Stop. Other subsequently updated modes can also be sent through this method.

Note

The robot starts in the Start mode by default. When sending the mode command, pay attention to capitalizing the first letter to match the state machine. For the actual mode execution, please strictly operate according to the executable modes in the mode_enbale_list.

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

SetStandMotion

Method Description: Set the actions to be executed in the standing mode (such as Greeting, Chest Expansion, Stretching, Gentleman's Salute, etc.).

Note

This command can only be executed when the robot is in the Stand mode and is not executing other actions. Please operate according to the executable actions in the motion_enable_list.

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

SetStandCarryBox

Method Description: Set the carrybox parameters in the standing mode (such as Squatting to Pick up the Box, Standing to Pick up the Box, Put Down the Box when in the stand mode).

Note

This command can only be executed when the robot is in the Stand mode and is not executing other actions. Please operate according to the executable actions in the carrybox_enable_list.

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

SetStandAction

Method Description: Set the action parameters when standing (such as stand_pitch, stand_roll, stand_yaw, stand_height can be adjusted in real time in the stand mode).

Note

This command can only be executed when the robot is in the Stand mode and is not executing other actions.

  # Test SetStandAction method, set the robot's posture to (0.05, 0.05, 0.05), and the descent height to 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

Method Description: Set the movement speed parameters (x, y, yaw) of the robot.

Note

This command can only be executed when the robot is in the Walk/Run mode (Since there is a danger in the client controlling the robot's movement speed, the client commands in this mode are not currently open for execution. To control the speed, please use the handle key control).

  # Test SetSpeed method, set the speed in the x direction 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

Method Description: Enable the adjustment of the robot's center of mass offset to ensure the stability of the in-place gait.

Note

This command can only be executed when the robot is in the Walk/Run mode.

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

SetErrorClear

Method Description: Used in the real machine to clear the error state of the robot so that it can continue to start and execute without powering off.

Note

This command can only be executed when the robot driver is in an error state or in the Stop state.

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

GetStandList

Method Description: The action list and posture list in the standing mode can be obtained in any mode.

Note

This list is a fixed list. Please do not confuse it with the enable_list.

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

GetRobotState

Method Description: Obtain the current state of the robot, the list of executable modes and actions enable_list, etc.

Note

The client routine will judge and send commands according to the enable_list. When users modify the client, they should pay attention that commands outside the enable_list cannot be executed.

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

Python Interface Call Examples

The way of calling interfaces in Python is similar to that in C++. For details, please refer to Client/python/adam_command_client.py.

Client Call Instructions

Both GetStandList and GetRobotState need to be obtained in real time. Before sending commands, commands should be sent according to the lists. Modes, actions, etc. that do not meet this requirement cannot be executed.

Interface Description & Parameter Call Method Overview

Interface Name	Description	Call Parameter	Assignment Example
`SetMode`	Set the robot mode	SetMode	`Zero`, `Stand`, `Walk`, `Run`, `Stop`
`SetStandMotion`	In the standing mode - the robot executes predefined motion capture actions	SetStandMotion	`Greeting` `Chest Expansion` `Stretching` `Gentleman's Salute`
`SetStandCarryBox`	In the standing mode - the robot executes box-carrying actions	SetStandCarryBox	`Squatting to Pick up the Box` `Standing to Pick up the Box` `Put Down the Box`
`SetStandAction`	In the standing mode - the robot executes posture control and squatting height control	SetStandAction	`0.0 0.0 0.0 0.0`
`SetStandDynamic`	In the standing mode - adjust whether to have Dynamic Stand	SetStandDynamic	`true` `false`
`SetSpeed`	In the `Walk` and `Run` modes - set the speed	SetSpeed	`0.0 0.0 0.0`
`AutoUnigaitCOM`	In the `Walk` and `Run` modes - balance the X-direction offset of the COM	AutoUnigaitCOM	`true` `false`
`SetErrorClear`	Reset errors without restarting	SetErrorClear
`GetStandList`	Obtain the robot mode list	GetStandList
`GetRobotState`	Obtain the current executable state	GetRobotState

Python Client Call Examples

The usage is consistent with the C++ version. For details, please refer to Client/python/adam_command_client.py. Compared with the C++ version, it has more convenient Tab auto-completion, command review, and case-insensitive features, providing a better user experience.

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++ Client Call Examples

The usage is generally consistent with the Python version. For details, please refer to 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
>