tanjianbin/lzwc-terminal-unitreeGo2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新README文档以反映最新功能变更

Browse Source 
- 添加导航和SLAM功能说明
- 更新MQTT配置和命令结构
- 修改编译时配置说明
- 调整项目结构描述
This commit is contained in:
Sucan126
2025-09-20 19:37:00 +08:00
parent ae8b01cf24
commit f7acf6ff51
1 changed files with 125 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files

235
README.md
View File

@@ -10,6 +10,7 @@ A high-performance C++ implementation for controlling Unitree GO2 robot with rea
- **🛡️ Safety Systems**: Emergency stop, timeout handling, and safety limits - **🛡️ Safety Systems**: Emergency stop, timeout handling, and safety limits
- **📝 Comprehensive Logging**: Multi-level logging with file and console output - **📝 Comprehensive Logging**: Multi-level logging with file and console output
- **⚙️ Configuration Management**: JSON-based configuration with runtime presets - **⚙️ Configuration Management**: JSON-based configuration with runtime presets
- **🧭 Navigation Support**: SLAM and navigation capabilities
- **📊 State Publishing**: Real-time robot state broadcasting - **📊 State Publishing**: Real-time robot state broadcasting
- **🎭 Special Actions**: Support for dances, tricks, and custom motions - **🎭 Special Actions**: Support for dances, tricks, and custom motions
- **🚀 High Performance**: Optimized for real-time control with configurable frequencies - **🚀 High Performance**: Optimized for real-time control with configurable frequencies
@@ -22,6 +23,7 @@ The system consists of several key components:
- **CustomRobot**: Main orchestrator class handling MQTT and robot coordination - **CustomRobot**: Main orchestrator class handling MQTT and robot coordination
- **Controller**: Direct interface to Unitree SDK2 for robot control - **Controller**: Direct interface to Unitree SDK2 for robot control
- **MqttClient**: Asynchronous MQTT client with reconnection and message queuing - **MqttClient**: Asynchronous MQTT client with reconnection and message queuing
- **Navigation**: Navigation and SLAM functionality
- **Config**: Configuration loading, validation, and management - **Config**: Configuration loading, validation, and management
- **Logger**: Thread-safe logging system with multiple output targets - **Logger**: Thread-safe logging system with multiple output targets
@@ -51,6 +53,9 @@ This project requires the Unitree SDK2 to be available at `../unitree_sdk2` rela
## Quick Start ## Quick Start
```bash ```bash
# Install dependencies
./scripts/install_deps.sh
# Create build directory # Create build directory
mkdir build && cd build mkdir build && cd build
@@ -60,7 +65,7 @@ cmake ..
# Build the project # Build the project
make -j$(nproc) make -j$(nproc)
# Run the robot (that's it!) # Run the robot
./main ./main
``` ```
@@ -68,58 +73,39 @@ The robot will start immediately with default settings and be ready to receive M
## Configuration ## Configuration
The system supports flexible configuration through JSON files and built-in presets. Configuration files are optional - the system can run with compile-time defaults. The system supports flexible configuration through compile-time defaults. Configuration files are optional - the system can run with compile-time defaults.
### Configuration File Structure ### Compile-time Configuration
Create `config/robot_config.json` for custom settings: The default configuration is defined in `include/config.hpp`:
```json ```cpp
{ // Network settings
"network": { constexpr std::string_view NETWORK_INTERFACE = "eth0";
"interface": "eth0"
}, // MQTT settings
"mqtt": { constexpr std::string_view MQTT_BROKER = "192.168.2.236";
"broker": "localhost", constexpr int MQTT_PORT = 1883;
"port": 1883, constexpr std::string_view MQTT_CLIENT_ID = "unitree_go2_client";
"username": "", constexpr std::string_view MQTT_USERNAME = "lzwc";
"password": "", constexpr std::string_view MQTT_PASSWORD = "Lzwc@4187.";
"client_id": "unitree_go2_client",
"keep_alive": 60, // Topic settings
"qos": 1 constexpr std::string_view TOPIC_PREFIX = "unitree/go2";
}, constexpr std::string_view TOPIC_CMD = "cmd";
"control": { constexpr std::string_view TOPIC_STATE = "state";
"frequency": 200,
"state_publish_frequency": 50 // Robot control settings
}, constexpr double CONTROL_FREQUENCY = 200.0; // Hz
"safety": { constexpr double STATE_PUBLISH_FREQUENCY = 50.0; // Hz
"max_linear_velocity": 1.5,
"max_angular_velocity": 2.0, // Safety settings
"emergency_stop_timeout": 5.0, constexpr double MAX_LINEAR_VELOCITY = 1.5; // m/s
"command_timeout": 2.0 constexpr double MAX_ANGULAR_VELOCITY = 2.0; // rad/s
}, constexpr double EMERGENCY_STOP_TIMEOUT = 5.0; // seconds
"logging": {
"level": "INFO",
"file_output": false,
"console_output": true
}
}
``` ```
### Using Configuration Presets To customize these settings, modify the values in `include/config.hpp` and rebuild the project.
Instead of creating JSON files, you can use built-in presets:
```bash
# High performance mode
./build/unitree_go2_custom --preset high-perf
# Development mode
./build/unitree_go2_custom --preset dev
# Safety-first mode
./build/unitree_go2_custom --preset safety
```
## Usage ## Usage
@@ -127,7 +113,7 @@ Instead of creating JSON files, you can use built-in presets:
```bash ```bash
# Simple execution - just run it! # Simple execution - just run it!
./build/main ./main
# That's it! No parameters needed. # That's it! No parameters needed.
# The robot will start with default settings and be ready to receive MQTT commands. # The robot will start with default settings and be ready to receive MQTT commands.
@@ -137,8 +123,9 @@ Instead of creating JSON files, you can use built-in presets:
The robot runs with sensible defaults out of the box: The robot runs with sensible defaults out of the box:
- **Network Interface**: `eth0` (auto-detected) - **Network Interface**: `eth0`
- **MQTT Broker**: `localhost:1883` - **MQTT Broker**: `192.168.2.236:1883`
- **MQTT Credentials**: Username `lzwc`, Password `Lzwc@4187.`
- **Control Frequency**: 200Hz - **Control Frequency**: 200Hz
- **Safety Limits**: Conservative settings for safe operation - **Safety Limits**: Conservative settings for safe operation
- **Logging**: INFO level to console - **Logging**: INFO level to console
@@ -151,9 +138,10 @@ The robot communicates via MQTT using the following topic structure:
### Command Topics ### Command Topics
- `unitree/go2/cmd/motion`: Motion commands - `unitree/go2/cmd/oac`: Obstacle avoidance commands
- `unitree/go2/cmd/control`: System control commands - `unitree/go2/cmd/sport`: Sport mode commands
- `unitree/go2/cmd/config`: Configuration updates - `unitree/go2/cmd/rsc`: Robot state commands
- `unitree/go2/cmd/nav`: Navigation commands
### State Topics ### State Topics
@@ -162,93 +150,117 @@ The robot communicates via MQTT using the following topic structure:
- `unitree/go2/state/response`: Command execution responses - `unitree/go2/state/response`: Command execution responses
- `unitree/go2/state/error`: Error messages - `unitree/go2/state/error`: Error messages
### Motion Commands ### Sport Commands
```json ```json
{ {
"request_id": "unique_id", "request_id": "unique_id",
"type": "motion", "cmd": "StandUp"
"motion_type": "velocity",
"linear_velocity": [1.0, 0.0, 0.0],
"angular_velocity": [0.0, 0.0, 0.5],
"duration": 2.0
} }
``` ```
### Special Actions Supported sport commands:
- `StandUp`: Stand up from lying position
- `StandDown`: Lie down from standing position
- `Sit`: Sit down
- `Damp`: Enable damping mode
- `RecoveryStand`: Recovery from emergency stop
- `BalanceStand`: Balanced standing with pose control
- `StopMove`: Stop all movement
- `Dance1`: Dance routine 1
- `Dance2`: Dance routine 2
- `Hello`: Greeting gesture
### Navigation Commands
```json ```json
{ {
"request_id": "unique_id", "request_id": "unique_id",
"type": "special_action", "cmd": "startMapping"
"action": "dance1",
"params": {}
} }
``` ```
Supported navigation commands:
- `startMapping`: Start SLAM mapping
- `endMapping`: End SLAM mapping
- `pauseNavigation`: Pause navigation
- `resumeNavigation`: Resume navigation
- `closeSlam`: Close SLAM service
### System Commands ### System Commands
```json ```json
{ {
"request_id": "unique_id", "request_id": "unique_id",
"type": "system", "cmd": "GetServiceList"
"command": "emergency_stop"
} }
``` ```
Supported system commands:
- `GetServiceList`: Get list of available services
- `SwitchService`: Enable/disable a service
- `SetReportFreq`: Set state reporting frequency
## Supported Actions ## Supported Actions
### Basic Motions ### Basic Motions
- `stand_up`: Stand up from lying position - `StandUp`: Stand up from lying position
- `stand_down`: Lie down from standing position - `StandDown`: Lie down from standing position
- `sit`: Sit down - `Sit`: Sit down
- `damp`: Enable damping mode - `Damp`: Enable damping mode
- `balance_stand`: Balanced standing with pose control - `RecoveryStand`: Recovery from emergency stop
- `recovery_stand`: Recovery from emergency stop - `BalanceStand`: Balanced standing with pose control
- `StopMove`: Stop all movement
### Special Actions ### Special Actions
- `dance1`, `dance2`: Dance routines - `Dance1`: Dance routine 1
- `hello`: Greeting gesture - `Dance2`: Dance routine 2
- `stretch`: Stretching motion - `Hello`: Greeting gesture
- `front_flip`, `back_flip`: Acrobatic flips (use with caution)
### Movement ### Navigation Actions
- Velocity control: Linear and angular velocity commands - `startMapping`: Start SLAM mapping
- Position control: Move to absolute positions - `endMapping`: End SLAM mapping and save map
- Body pose control: Roll, pitch, yaw, and height adjustment - `pauseNavigation`: Pause navigation
- `resumeNavigation`: Resume navigation
- `closeSlam`: Close SLAM service
## Safety Features ## Safety Features
- **Emergency Stop**: Immediate motion halt and damping activation - **Emergency Stop**: Immediate motion halt and damping activation
- **Velocity Limits**: Configurable maximum linear and angular velocities - **Velocity Limits**: Configurable maximum linear and angular velocities
- **Command Timeout**: Automatic stop if no commands received within timeout - **Command Timeout**: Automatic stop if no commands received within timeout
- **Battery Monitoring**: Low battery detection and safe shutdown
- **Connection Monitoring**: Automatic reconnection and error handling - **Connection Monitoring**: Automatic reconnection and error handling
## Development ## Development
### Adding New Actions ### Adding New Actions
1. Add action handler in `Controller::performAction()` 1. Add action handler in `Controller` class (`include/controller.hpp`, `src/controller.cpp`)
2. Update MQTT command processing in `CustomRobot::processSpecialAction()` 2. Update MQTT command processing in `CustomRobot::processSportCmd()` or appropriate processor
3. Add action documentation 3. Add action documentation
### Extending MQTT API ### Extending MQTT API
1. Define new message types in the appropriate handler functions 1. Define new message types in the appropriate handler functions in `CustomRobot`
2. Update JSON parsing and validation 2. Update JSON parsing and validation
3. Add corresponding response handling 3. Add corresponding response handling
### Custom Configurations ### Custom Configurations
Create specialized configuration files for different environments: To customize the configuration, modify the values in `include/config.hpp`:
```cpp
// Example: Change MQTT broker address
constexpr std::string_view MQTT_BROKER = "192.168.1.100";
// Example: Change control frequency
constexpr double CONTROL_FREQUENCY = 400.0; // Hz
```
After making changes, rebuild the project:
```bash ```bash
# Development configuration cd build
cp config/robot_config.json config/dev_config.json make -j$(nproc)
# Production configuration
cp config/robot_config.json config/prod_config.json
``` ```
## Quick Start Scripts ## Quick Start Scripts
@@ -276,17 +288,21 @@ unitree-go2/
│ ├── controller.hpp # Robot controller │ ├── controller.hpp # Robot controller
│ ├── custom_robot.hpp # Main orchestrator │ ├── custom_robot.hpp # Main orchestrator
│ ├── logger.hpp # Logging system │ ├── logger.hpp # Logging system
│ └── mqtt.hpp # MQTT client │ ├── mqtt.hpp # MQTT client
│ ├── navigation.hpp # Navigation and SLAM
│ └── nlohmann/ # JSON library
├── src/ # Source files ├── src/ # Source files
│ ├── config.cpp │ ├── config.cpp
│ ├── controller.cpp │ ├── controller.cpp
│ ├── custom_robot.cpp │ ├── custom_robot.cpp
│ ├── logger.cpp │ ├── logger.cpp
│ ├── main.cpp │ ├── main.cpp
│ └── mqtt.cpp │ ├── mqtt.cpp
└── scripts/ # Utility scripts │ └── navigation.cpp
├── install_deps.sh # Install dependencies ├── scripts/ # Utility scripts
└── run_robot.sh # Run with optimal settings │ ├── install_deps.sh # Install dependencies
│ └── run_robot.sh # Run with optimal settings
└── build/ # Build directory (created during build)
``` ```
## Troubleshooting ## Troubleshooting
@@ -299,7 +315,6 @@ unitree-go2/
4. **Permission Denied**: Run with appropriate privileges for network access 4. **Permission Denied**: Run with appropriate privileges for network access
5. **Build Errors**: Run `./scripts/install_deps.sh` to install required packages 5. **Build Errors**: Run `./scripts/install_deps.sh` to install required packages
### Network Issues ### Network Issues
Test network connectivity to the robot: Test network connectivity to the robot:
@@ -312,7 +327,7 @@ ip addr show eth0
ping 192.168.123.15 ping 192.168.123.15
# Check if MQTT broker is accessible # Check if MQTT broker is accessible
telnet localhost 1883 telnet 192.168.2.236 1883
``` ```
### Performance Tuning ### Performance Tuning
@@ -320,38 +335,38 @@ telnet localhost 1883
For optimal performance: For optimal performance:
```bash ```bash
# Use high-performance preset # Modify control frequency in include/config.hpp
./build/unitree_go2_custom --preset high-perf # Rebuild the project
cd build
# Or customize control frequency make -j$(nproc)
./build/unitree_go2_custom -c config/high_freq_config.json
``` ```
## License ## License
This project is licensed under the same terms as the original custom_unitree Python implementation. This project is licensed under the MIT License - see the LICENSE file for details.
## Performance Notes ## Performance Notes
- **Control Frequency**: Default 200Hz, configurable up to 500Hz for high-performance applications - **Control Frequency**: Default 200Hz, configurable up to 400Hz for high-performance applications
- **State Publishing**: Default 50Hz, can be adjusted based on network bandwidth - **State Publishing**: Default 50Hz, can be adjusted based on network bandwidth
- **Memory Usage**: Optimized for minimal heap allocations during runtime - **Memory Usage**: Optimized for minimal heap allocations during runtime
- **CPU Usage**: Multi-threaded design with separate threads for control, MQTT, and state publishing - **CPU Usage**: Multi-threaded design with separate threads for control, MQTT, and state publishing
## Contributing ## Contributing
1. Follow the existing code style and patterns 1. Fork the repository
2. Add appropriate error handling and logging 2. Create a feature branch
3. Update documentation for new features 3. Commit your changes
4. Test thoroughly with the actual robot hardware 4. Push to the branch
5. Use the provided scripts for consistent development environment 5. Create a Pull Request
## Version History ## Version History
- **v1.0.0**: Initial release with full MQTT API and safety systems - **v1.0.0**: Initial release with full MQTT API and safety systems
- Modular architecture with clean separation of concerns - Modular architecture with clean separation of concerns
- Support for configuration presets and runtime parameter adjustment - Support for configuration through compile-time constants
- Comprehensive logging and error handling - Comprehensive logging and error handling
- Navigation and SLAM capabilities
## Acknowledgments ## Acknowledgments