mirror of
https://github.com/soconnor0919/hristudio.git
synced 2025-12-11 22:54:45 -05:00
233 lines
7.8 KiB
Markdown
233 lines
7.8 KiB
Markdown
# 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+ |