hristudio/nao6_integration_README.md

NAO6 HRIStudio Integration

Complete integration package for NAO6 humanoid robots with the HRIStudio research platform

🎯 Overview

This repository contains all components needed to integrate NAO6 robots with HRIStudio for Human-Robot Interaction research. It provides production-ready ROS2 packages, web interface plugins, control scripts, and comprehensive documentation for seamless robot operation through the HRIStudio platform.

📦 Repository Structure

nao6-hristudio-integration/
├── README.md                     # This file
├── launch/                       # ROS2 launch configurations
│   ├── nao6_production.launch.py      # Production-optimized launch
│   └── nao6_hristudio_enhanced.launch.py # Enhanced with monitoring
├── scripts/                      # Utilities and automation
│   ├── test_nao_topics.py            # ROS topics simulator
│   ├── test_websocket.py             # WebSocket bridge tester
│   ├── verify_nao6_bridge.sh         # Integration verification
│   └── seed-nao6-plugin.ts           # Database seeding for HRIStudio
├── plugins/                      # HRIStudio plugin definitions
│   ├── repository.json               # Plugin repository metadata
│   ├── nao6-ros2-enhanced.json      # Complete NAO6 plugin
│   └── README.md                     # Plugin documentation
├── examples/                     # Usage examples and tools
│   ├── nao_control.py                # Command-line robot control
│   └── start_nao6_hristudio.sh       # Automated startup script
└── docs/                         # Documentation
    ├── NAO6_INTEGRATION_COMPLETE.md  # Complete integration guide
    ├── INSTALLATION.md               # Installation instructions
    ├── USAGE.md                      # Usage examples
    └── TROUBLESHOOTING.md            # Common issues and solutions

🚀 Quick Start

Prerequisites

• NAO6 Robot with NAOqi 2.8.7.4+
• Ubuntu 22.04 with ROS2 Humble
• HRIStudio Platform (web interface)
• Network connectivity between computer and robot

1. Clone Repository

git clone <repository-url> ~/nao6-hristudio-integration
cd ~/nao6-hristudio-integration

2. Install Dependencies

# Install ROS2 packages
sudo apt update
sudo apt install ros-humble-rosbridge-suite ros-humble-naoqi-driver

# Install Python dependencies
pip install websocket-client

3. Setup NAOqi ROS2 Workspace

# Build the enhanced nao_launch package
cd ~/naoqi_ros2_ws
colcon build --packages-select nao_launch
source install/setup.bash

4. Start Integration

# Option A: Use automated startup script
./examples/start_nao6_hristudio.sh --nao-ip nao.local --password robolab

# Option B: Manual launch
ros2 launch nao_launch nao6_production.launch.py nao_ip:=nao.local password:=robolab

5. Configure HRIStudio

# Seed NAO6 plugin into HRIStudio database
cd ~/Documents/Projects/hristudio
bun run ../nao6-hristudio-integration/scripts/seed-nao6-plugin.ts

# Start HRIStudio web interface
bun dev

6. Test Integration

• Open: http://localhost:3000/nao-test
• Login: sean@soconnor.dev / password123
• Click "Connect" to establish WebSocket connection
• Try robot commands and verify responses

🎮 Available Robot Actions

The NAO6 plugin provides 9 comprehensive actions for HRIStudio experiments:

🗣️ Communication

• Speak Text - Text-to-speech with volume/speed control
• LED Control - Visual feedback with colors and patterns

🚶 Movement & Posture

• Move Robot - Walking, turning with safety limits
• Set Posture - Stand, sit, crouch positions
• Move Head - Gaze control and attention direction
• Perform Gesture - Wave, point, applause, custom animations

📡 Sensors & Monitoring

• Monitor Sensors - Touch, bumper, sonar detection
• Check Robot Status - Battery, joints, system health

🛡️ Safety & System

• Emergency Stop - Immediate motion termination
• Wake Up / Rest - Power management

🔧 Command-Line Tools

Robot Control

# Direct robot control
python3 examples/nao_control.py --ip nao.local wake
python3 examples/nao_control.py --ip nao.local speak "Hello world"
python3 examples/nao_control.py --ip nao.local move 0.1 0 0
python3 examples/nao_control.py --ip nao.local pose Stand
python3 examples/nao_control.py --ip nao.local emergency

Integration Testing

# Verify all components
./scripts/verify_nao6_bridge.sh

# Test WebSocket connectivity
python3 scripts/test_websocket.py

# Simulate robot topics (without hardware)
python3 scripts/test_nao_topics.py

🌐 WebSocket Communication

Connection Details

• URL: ws://localhost:9090
• Protocol: rosbridge v2.0
• Format: JSON messages

Sample Messages

// Speech command
{
  "op": "publish",
  "topic": "/speech",
  "type": "std_msgs/String",
  "msg": {"data": "Hello from HRIStudio!"}
}

// Movement command
{
  "op": "publish",
  "topic": "/cmd_vel",
  "type": "geometry_msgs/Twist",
  "msg": {
    "linear": {"x": 0.1, "y": 0.0, "z": 0.0},
    "angular": {"x": 0.0, "y": 0.0, "z": 0.0}
  }
}

// Subscribe to sensors
{
  "op": "subscribe",
  "topic": "/naoqi_driver/joint_states",
  "type": "sensor_msgs/JointState"
}

📋 Key Topics

Input Topics (Robot Control)

• /speech - Text-to-speech commands
• /cmd_vel - Movement control
• /joint_angles - Joint positioning
• /led_control - Visual feedback

Output Topics (Sensor Data)

• /naoqi_driver/joint_states - Joint positions/velocities
• /naoqi_driver/bumper - Foot sensors
• /naoqi_driver/hand_touch - Hand touch sensors
• /naoqi_driver/head_touch - Head touch sensors
• /naoqi_driver/sonar/left - Left ultrasonic sensor
• /naoqi_driver/sonar/right - Right ultrasonic sensor
• /naoqi_driver/battery - Battery level

🛡️ Safety Features

Automated Safety

• Velocity Limits - Maximum speed constraints (0.2 m/s linear, 0.8 rad/s angular)
• Emergency Stop - Immediate motion termination
• Battery Monitoring - Low battery warnings
• Fall Detection - Automatic safety responses
• Wake-up Management - Proper robot state handling

Manual Safety Controls

# Emergency stop via CLI
ros2 topic pub --once /cmd_vel geometry_msgs/msg/Twist '{linear: {x: 0.0, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 0.0}}'

# Emergency stop via script
python3 examples/nao_control.py --ip nao.local emergency

# Or use HRIStudio emergency stop action

🔍 Troubleshooting

Common Issues

Robot not responding to commands

# Check robot is awake
python3 examples/nao_control.py --ip nao.local status

# Wake up robot
python3 examples/nao_control.py --ip nao.local wake
# OR press chest button for 3 seconds

WebSocket connection failed

# Check rosbridge is running
ros2 node list | grep rosbridge

# Restart integration
pkill -f rosbridge && pkill -f rosapi
ros2 launch nao_launch nao6_production.launch.py nao_ip:=nao.local

Network connectivity issues

# Test basic connectivity
ping nao.local
telnet nao.local 9559

# Check robot credentials
ssh nao@nao.local  # Password: robolab (institution-specific)

For detailed troubleshooting, see docs/TROUBLESHOOTING.md

📖 Documentation

Complete Guides

• Installation Guide - Detailed setup instructions
• Usage Guide - Examples and best practices
• Integration Complete - Comprehensive overview
• Troubleshooting - Problem resolution

Quick References

• Launch Files - See launch/ directory
• Plugin Definitions - See plugins/ directory
• Example Scripts - See examples/ directory

🎯 Research Applications

Experiment Types

• Social Interaction - Gestures, speech, gaze studies
• Human-Robot Collaboration - Shared task experiments
• Behavior Analysis - Touch, proximity, response studies
• Navigation Studies - Movement and spatial interaction
• Multimodal Interaction - Combined speech, gesture, movement

Data Capture

• Synchronized Timestamps - All robot actions and sensor events
• Sensor Fusion - Touch, vision, audio, movement data
• Real-time Logging - Comprehensive event capture
• Export Capabilities - Data analysis and visualization

🏆 Features & Benefits

✅ Production Ready

• Tested Integration - Verified with NAO V6.0 / NAOqi 2.8.7.4
• Safety First - Comprehensive safety monitoring
• Performance Optimized - Tuned for stable experiments
• Error Handling - Robust failure management

✅ Researcher Friendly

• Web Interface - No programming required for experiments
• Visual Designer - Drag-and-drop experiment creation
• Real-time Control - Live robot operation during trials
• Multiple Roles - Researcher, wizard, observer access

✅ Developer Friendly

• Open Source - MIT licensed components
• Modular Design - Extensible architecture
• Comprehensive APIs - ROS2 and WebSocket interfaces
• Documentation - Complete setup and usage guides

🚀 Getting Started Examples

Basic Experiment Workflow

1. Design - Create experiment in HRIStudio visual designer
2. Configure - Set robot parameters and safety limits
3. Execute - Run trial with real-time robot control
4. Analyze - Review captured data and events
5. Iterate - Refine experiment based on results

Sample Experiment: Greeting Interaction

// HRIStudio experiment sequence
[
  {"action": "nao_wake_rest", "parameters": {"action": "wake"}},
  {"action": "nao_pose", "parameters": {"posture": "Stand"}},
  {"action": "nao_speak", "parameters": {"text": "Hello! Welcome to our study."}},
  {"action": "nao_gesture", "parameters": {"gesture": "wave"}},
  {"action": "nao_sensor_monitor", "parameters": {"sensorType": "touch", "duration": 30}}
]

🤝 Contributing

Development Setup

1. Fork this repository
2. Create feature branch: git checkout -b feature-name
3. Test with real NAO6 hardware
4. Submit pull request with documentation updates

Guidelines

• Follow ROS2 conventions for launch files
• Test all changes with physical robot
• Update documentation for new features
• Ensure backward compatibility

📞 Support

Resources

• GitHub Issues - Report bugs and request features
• Documentation - Complete guides in docs/ folder
• HRIStudio Platform - Web interface documentation

Requirements

• NAO6 Robot - NAO V6.0 with NAOqi 2.8.7.4+
• ROS2 Humble - Ubuntu 22.04 recommended
• Network Setup - Robot and computer on same network
• HRIStudio - Web platform for experiment design

📄 License

MIT License - See LICENSE file for details

🏅 Citation

If you use this integration in your research, please cite:

@software{nao6_hristudio_integration,
  title={NAO6 HRIStudio Integration},
  author={HRIStudio RoboLab Team},
  year={2024},
  url={https://github.com/hristudio/nao6-integration},
  version={2.0.0}
}

---

Status: Production Ready ✅
Tested With: NAO V6.0 / NAOqi 2.8.7.4 / ROS2 Humble / HRIStudio v1.0
Last Updated: December 2024

Advancing Human-Robot Interaction research through standardized, accessible, and reliable tools.