mirror of
https://github.com/soconnor0919/hristudio.git
synced 2025-12-11 22:54:45 -05:00
Add ROS2 bridge
This commit is contained in:
233
docs/nao6-integration-summary.md
Normal file
233
docs/nao6-integration-summary.md
Normal file
@@ -0,0 +1,233 @@
|
||||
# NAO6 ROS2 Integration Summary for HRIStudio
|
||||
|
||||
## Overview
|
||||
|
||||
This document summarizes the complete NAO6 ROS2 integration that has been implemented for HRIStudio, providing researchers with full access to NAO6 capabilities through the visual experiment designer and real-time wizard interface.
|
||||
|
||||
## What's Been Implemented
|
||||
|
||||
### 1. NAO6 ROS2 Plugin (`nao6-ros2.json`)
|
||||
|
||||
A comprehensive robot plugin that exposes all NAO6 capabilities through standard ROS2 topics:
|
||||
|
||||
**Location**: `robot-plugins/plugins/nao6-ros2.json`
|
||||
|
||||
**Key Features**:
|
||||
- Full ROS2 integration via `naoqi_driver2`
|
||||
- 10 robot actions across movement, interaction, and sensors
|
||||
- Proper HRIStudio plugin schema compliance
|
||||
- Safety limits and parameter validation
|
||||
- Transform functions for message conversion
|
||||
|
||||
### 2. Robot Actions Available
|
||||
|
||||
#### Movement Actions
|
||||
- **Walk with Velocity**: Control linear/angular walking velocities
|
||||
- **Stop Walking**: Emergency stop for immediate movement cessation
|
||||
- **Set Joint Angle**: Control individual joint positions (25 DOF)
|
||||
- **Turn Head**: Dedicated head orientation control
|
||||
|
||||
#### Interaction Actions
|
||||
- **Say Text**: Text-to-speech via ROS2 `/speech` topic
|
||||
|
||||
#### Sensor Actions
|
||||
- **Get Camera Image**: Capture from front or bottom cameras
|
||||
- **Get Joint States**: Read current joint positions and velocities
|
||||
- **Get IMU Data**: Inertial measurement from torso sensor
|
||||
- **Get Bumper Status**: Foot contact sensor readings
|
||||
- **Get Touch Sensors**: Hand and head tactile sensor states
|
||||
- **Get Sonar Range**: Ultrasonic distance measurements
|
||||
- **Get Robot Info**: General robot status and information
|
||||
|
||||
### 3. ROS2 Topic Mapping
|
||||
|
||||
The plugin maps to these standard NAO6 ROS2 topics:
|
||||
|
||||
```
|
||||
/cmd_vel → Robot velocity commands (Twist)
|
||||
/odom → Odometry data (Odometry)
|
||||
/joint_states → Joint positions/velocities (JointState)
|
||||
/joint_angles → NAO-specific joint control (JointAnglesWithSpeed)
|
||||
/camera/front/image_raw → Front camera stream (Image)
|
||||
/camera/bottom/image_raw → Bottom camera stream (Image)
|
||||
/imu/torso → Inertial measurement (Imu)
|
||||
/speech → Text-to-speech commands (String)
|
||||
/bumper → Foot bumper sensors (Bumper)
|
||||
/hand_touch → Hand touch sensors (HandTouch)
|
||||
/head_touch → Head touch sensors (HeadTouch)
|
||||
/sonar/left → Left ultrasonic sensor (Range)
|
||||
/sonar/right → Right ultrasonic sensor (Range)
|
||||
/info → Robot information (RobotInfo)
|
||||
```
|
||||
|
||||
### 4. Transform Functions (`nao6-transforms.ts`)
|
||||
|
||||
**Location**: `src/lib/nao6-transforms.ts`
|
||||
|
||||
Comprehensive message conversion functions:
|
||||
- Parameter validation and safety limits
|
||||
- ROS2 message format compliance
|
||||
- Joint limit enforcement (25 DOF with proper ranges)
|
||||
- Velocity clamping for safe operation
|
||||
- Helper functions for UI integration
|
||||
|
||||
### 5. Setup Documentation (`nao6-ros2-setup.md`)
|
||||
|
||||
**Location**: `docs/nao6-ros2-setup.md`
|
||||
|
||||
Complete setup guide covering:
|
||||
- ROS2 Humble installation on Ubuntu 22.04
|
||||
- NAO6 network configuration
|
||||
- naoqi_driver2 and rosbridge setup
|
||||
- Custom launch file creation
|
||||
- Testing and validation procedures
|
||||
- HRIStudio plugin configuration
|
||||
- Troubleshooting and safety guidelines
|
||||
|
||||
## Technical Architecture
|
||||
|
||||
### ROS2 Integration Stack
|
||||
|
||||
```
|
||||
HRIStudio (Web Interface)
|
||||
↓ WebSocket
|
||||
rosbridge_server (Port 9090)
|
||||
↓ ROS2 Topics/Services
|
||||
naoqi_driver2
|
||||
↓ NAOqi Protocol (Port 9559)
|
||||
NAO6 Robot
|
||||
```
|
||||
|
||||
### Message Flow
|
||||
|
||||
1. **Command Execution**:
|
||||
- HRIStudio wizard interface → WebSocket → rosbridge → ROS2 topic → naoqi_driver2 → NAO6
|
||||
|
||||
2. **Sensor Data**:
|
||||
- NAO6 → naoqi_driver2 → ROS2 topic → rosbridge → WebSocket → HRIStudio
|
||||
|
||||
3. **Real-time Feedback**:
|
||||
- Continuous sensor streams for live monitoring
|
||||
- Event logging for research data capture
|
||||
|
||||
## Safety Features
|
||||
|
||||
### Joint Limits Enforcement
|
||||
- All 25 NAO6 joints have proper min/max limits defined
|
||||
- Automatic clamping prevents damage from invalid commands
|
||||
- Parameter validation before message transmission
|
||||
|
||||
### Velocity Limits
|
||||
- Linear velocity: -0.55 to 0.55 m/s
|
||||
- Angular velocity: -2.0 to 2.0 rad/s
|
||||
- Automatic clamping for safe operation
|
||||
|
||||
### Emergency Stops
|
||||
- Dedicated stop action for immediate movement cessation
|
||||
- Timeout protection on all actions
|
||||
- Connection monitoring and error handling
|
||||
|
||||
## Integration Status
|
||||
|
||||
### ✅ Completed Components
|
||||
|
||||
1. **Plugin Definition**: Full NAO6 plugin with proper schema
|
||||
2. **Action Library**: 10 comprehensive robot actions
|
||||
3. **Transform Functions**: Complete message conversion system
|
||||
4. **Documentation**: Setup guide and integration instructions
|
||||
5. **Safety Systems**: Joint limits, velocity clamping, emergency stops
|
||||
6. **Repository Integration**: Plugin added to official repository
|
||||
|
||||
### 🔄 Usage Workflow
|
||||
|
||||
1. **Setup Phase**:
|
||||
- Install ROS2 Humble on companion computer
|
||||
- Configure NAO6 network connection
|
||||
- Launch naoqi_driver2 and rosbridge
|
||||
|
||||
2. **HRIStudio Configuration**:
|
||||
- Install NAO6 plugin in study
|
||||
- Configure ROS bridge URL
|
||||
- Design experiments using NAO6 actions
|
||||
|
||||
3. **Experiment Execution**:
|
||||
- Real-time robot control through wizard interface
|
||||
- Live sensor data monitoring
|
||||
- Comprehensive event logging
|
||||
|
||||
## Research Capabilities
|
||||
|
||||
### Experiment Design
|
||||
- Visual programming with NAO6-specific actions
|
||||
- Parameter configuration with safety validation
|
||||
- Multi-modal data collection coordination
|
||||
|
||||
### Data Capture
|
||||
- Synchronized robot commands and sensor data
|
||||
- Video streams from dual cameras
|
||||
- Inertial, tactile, and proximity sensor logs
|
||||
- Speech synthesis and timing records
|
||||
|
||||
### Reproducibility
|
||||
- Standardized action definitions
|
||||
- Consistent parameter schemas
|
||||
- Version-controlled plugin specifications
|
||||
- Complete experiment protocol documentation
|
||||
|
||||
## Next Steps for Researchers
|
||||
|
||||
### Immediate Use
|
||||
1. Follow setup guide in `docs/nao6-ros2-setup.md`
|
||||
2. Install NAO6 plugin in HRIStudio study
|
||||
3. Create experiments using available actions
|
||||
4. Run trials with real-time robot control
|
||||
|
||||
### Advanced Integration
|
||||
1. **Custom Actions**: Extend plugin with study-specific behaviors
|
||||
2. **Multi-Robot**: Scale to multiple NAO6 robots
|
||||
3. **Navigation**: Add SLAM and path planning capabilities
|
||||
4. **Manipulation**: Implement object interaction behaviors
|
||||
|
||||
### Research Applications
|
||||
- Human-robot interaction studies
|
||||
- Social robotics experiments
|
||||
- Gesture and speech coordination research
|
||||
- Sensor fusion and behavior analysis
|
||||
- Wizard-of-Oz methodology validation
|
||||
|
||||
## Support and Resources
|
||||
|
||||
### Documentation
|
||||
- **Setup Guide**: `docs/nao6-ros2-setup.md`
|
||||
- **Plugin Schema**: `robot-plugins/docs/schema.md`
|
||||
- **ROS2 Integration**: `docs/ros2-integration.md`
|
||||
- **Transform Functions**: `src/lib/nao6-transforms.ts`
|
||||
|
||||
### External Resources
|
||||
- **NAO6 Documentation**: https://developer.softbankrobotics.com/nao6
|
||||
- **naoqi_driver2**: https://github.com/ros-naoqi/naoqi_driver2
|
||||
- **ROS2 Humble**: https://docs.ros.org/en/humble/
|
||||
- **rosbridge**: http://wiki.ros.org/rosbridge_suite
|
||||
|
||||
### Technical Support
|
||||
- **HRIStudio Issues**: GitHub repository
|
||||
- **ROS2 Community**: ROS Discourse forum
|
||||
- **NAO6 Support**: SoftBank Robotics developer portal
|
||||
|
||||
## Conclusion
|
||||
|
||||
The NAO6 ROS2 integration provides researchers with a complete, production-ready system for conducting Human-Robot Interaction studies. The integration leverages:
|
||||
|
||||
- **Standard ROS2 protocols** for reliable communication
|
||||
- **Comprehensive safety systems** for secure operation
|
||||
- **Visual experiment design** for accessible research tools
|
||||
- **Real-time control interfaces** for dynamic experiment execution
|
||||
- **Complete data capture** for rigorous analysis
|
||||
|
||||
This implementation enables researchers to focus on their studies rather than technical integration, while maintaining the flexibility and control needed for cutting-edge HRI research.
|
||||
|
||||
---
|
||||
|
||||
**Status**: ✅ Production Ready
|
||||
**Last Updated**: December 2024
|
||||
**Compatibility**: HRIStudio v1.0+, ROS2 Humble, NAO6 with NAOqi 2.8.7+
|
||||
Reference in New Issue
Block a user