hristudio/docs/nao6-integration-summary.md

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+