soconnor/hristudio
1
0
Fork 0
mirror of https://github.com/soconnor0919/hristudio.git synced 2025-12-11 06:34:44 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
5be4ff037275688d7a72a25bb15c35f06fd9c432
hristudio/public/nao6-plugins/README.md

9.9 KiB
Raw Blame History

NAO6 HRIStudio Plugin Repository

Official NAO6 robot integration plugins for the HRIStudio platform

Overview

This repository contains production-ready plugins for integrating NAO6 robots with HRIStudio experiments. The plugins provide comprehensive robot control capabilities including movement, speech synthesis, sensor monitoring, and safety features optimized for human-robot interaction research.

Available Plugins

🤖 NAO6 Enhanced ROS2 Integration (nao6-ros2-enhanced.json)

Complete NAO6 robot control for HRIStudio experiments

Features:

  • ✅ Speech Synthesis - Text-to-speech with volume and speed control
  • ✅ Movement Control - Walking, turning, and precise positioning
  • ✅ Posture Management - Stand, sit, crouch, and custom poses
  • ✅ Head Movement - Gaze control and attention direction
  • ✅ Gesture Library - Wave, point, applause, and custom animations
  • ✅ LED Control - Visual feedback with colors and patterns
  • ✅ Sensor Monitoring - Touch, bumper, sonar, and camera sensors
  • ✅ Safety Features - Emergency stop and velocity limits
  • ✅ System Control - Wake/rest and status monitoring

Requirements:

  • NAO6 robot with NAOqi 2.8.7.4+
  • ROS2 Humble or compatible
  • Network connectivity to robot
  • nao_launch package for ROS integration

Installation:

  1. Install in HRIStudio study via Plugin Management
  2. Configure robot IP and WebSocket URL
  3. Launch ROS integration: ros2 launch nao_launch nao6_production.launch.py
  4. Test connection in HRIStudio experiment designer

Plugin Actions Reference

Speech & Communication

Action Description Parameters
Speak Text Text-to-speech synthesis text, volume, speed, wait
LED Control Visual feedback with colors ledGroup, color, intensity, pattern

Movement & Posture

Action Description Parameters
Move Robot Linear and angular movement direction, distance, speed, duration
Set Posture Predefined poses posture, speed, waitForCompletion
Move Head Gaze and attention control yaw, pitch, speed, presetDirection
Perform Gesture Animations and gestures gesture, intensity, speed, repeatCount

Sensors & Monitoring

Action Description Parameters
Monitor Sensors Touch, bumper, sonar detection sensorType, duration, sensitivity
Check Robot Status Battery, joints, system health statusType, logToExperiment

Safety & System

Action Description Parameters
Emergency Stop Immediate motion termination stopType, safePosture
Wake Up / Rest Power management action, waitForCompletion

Quick Start Examples

1. Basic Greeting

{
  "sequence": [
    {"action": "nao_wake_rest", "parameters": {"action": "wake"}},
    {"action": "nao_speak", "parameters": {"text": "Hello! Welcome to our experiment."}},
    {"action": "nao_gesture", "parameters": {"gesture": "wave"}}
  ]
}

2. Interactive Task

{
  "sequence": [
    {"action": "nao_speak", "parameters": {"text": "Please touch my head when ready."}},
    {"action": "nao_sensor_monitor", "parameters": {"sensorType": "touch", "duration": 30}},
    {"action": "nao_speak", "parameters": {"text": "Thank you! Let's begin."}}
  ]
}

3. Attention Direction

{
  "sequence": [
    {"action": "nao_head_movement", "parameters": {"presetDirection": "left"}},
    {"action": "nao_speak", "parameters": {"text": "Look over there please."}},
    {"action": "nao_gesture", "parameters": {"gesture": "point_left"}}
  ]
}

Installation & Setup

Prerequisites

  • HRIStudio Platform - Web-based WoZ research platform
  • NAO6 Robot - With NAOqi 2.8.7.4 or compatible
  • ROS2 Humble - Robot Operating System 2
  • Network Setup - Robot and computer on same network

Step 1: Install NAO ROS2 Packages

# Clone and build NAO ROS2 workspace
cd ~/naoqi_ros2_ws
colcon build --packages-select nao_launch
source install/setup.bash

Step 2: Start Robot Integration

# Launch comprehensive NAO integration
ros2 launch nao_launch nao6_production.launch.py \
  nao_ip:=nao.local \
  password:=robolab \
  bridge_port:=9090

Step 3: Install Plugin in HRIStudio

  1. Access HRIStudio - Open your study in HRIStudio
  2. Plugin Management - Go to Study → Plugins
  3. Browse Store - Find "NAO6 Robot (Enhanced ROS2 Integration)"
  4. Install Plugin - Click install and configure settings
  5. Configure WebSocket - Set URL to ws://localhost:9090

Step 4: Test Integration

  1. Open Experiment Designer - Create or edit an experiment
  2. Add Robot Action - Drag NAO6 action from plugin section
  3. Configure Parameters - Set speech text, movement, etc.
  4. Test Connection - Use "Check Robot Status" action
  5. Run Trial - Execute experiment and verify robot responds

Configuration Options

Robot Connection

  • Robot IP - IP address or hostname (default: nao.local)
  • Password - Robot authentication password
  • WebSocket URL - ROS bridge connection (default: ws://localhost:9090)

Safety Settings

  • Max Linear Velocity - Maximum movement speed (default: 0.2 m/s)
  • Max Angular Velocity - Maximum rotation speed (default: 0.8 rad/s)
  • Safety Monitoring - Enable automatic safety checks
  • Auto Wake-up - Automatically wake robot when experiment starts

Performance Tuning

  • Speech Volume - Default volume level (default: 0.7)
  • Movement Speed - Default movement speed factor (default: 0.5)
  • Battery Monitoring - Track battery level during experiments

Troubleshooting

❌ Robot Not Responding

Problem: Commands sent but robot doesn't react
Solution:

  • Check robot is awake: Press chest button for 3 seconds
  • Verify network connectivity: ping nao.local
  • Use "Wake Up / Rest Robot" action in experiment

❌ WebSocket Connection Failed

Problem: HRIStudio cannot connect to robot
Solution:

  • Verify rosbridge is running: ros2 node list | grep rosbridge
  • Check port availability: ss -an | grep 9090
  • Restart integration: Kill processes and relaunch

❌ Movements Too Fast/Unsafe

Problem: Robot moves too quickly or unpredictably
Solution:

  • Reduce max velocities in plugin configuration
  • Lower movement speed parameters in actions
  • Use "Emergency Stop" action if needed

❌ Speech Not Working

Problem: Robot doesn't speak or audio issues
Solution:

  • Check robot volume settings
  • Verify text-to-speech service: ros2 topic echo /speech
  • Ensure speakers are functioning

Safety Guidelines

⚠️ Important Safety Notes

  • Clear Space - Ensure 2m clearance around robot during movement
  • Emergency Stop - Keep emergency stop action easily accessible
  • Supervision - Never leave robot unattended during experiments
  • Battery Monitoring - Check battery level for long sessions
  • Stable Surface - Keep robot on level, stable flooring

Emergency Procedures

# Immediate 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}}'

# Or use HRIStudio emergency stop action
# Add "Emergency Stop" action to experiment for quick access

Technical Details

ROS2 Topics Used

  • Input Topics (Robot Control):

    • /speech - Text-to-speech commands
    • /cmd_vel - Movement commands
    • /joint_angles - Joint position control
    • /led_control - LED color control

  • Output Topics (Sensor Data):

    • /naoqi_driver/joint_states - Joint positions
    • /naoqi_driver/bumper - Foot sensors
    • /naoqi_driver/hand_touch - Hand sensors
    • /naoqi_driver/head_touch - Head sensors
    • /naoqi_driver/sonar/* - Ultrasonic sensors

WebSocket Communication

  • Protocol - rosbridge v2.0 WebSocket
  • Default Port - 9090
  • Message Format - JSON-based ROS message serialization
  • Authentication - None (local network)

Development & Contributing

Plugin Development

  1. Follow Schema - Use provided JSON schema for action definitions
  2. Test Thoroughly - Verify with real NAO6 hardware
  3. Document Actions - Provide clear parameter descriptions
  4. Safety First - Include appropriate safety measures

Testing Checklist

  • Robot connectivity and wake-up
  • All movement actions with safety limits
  • Speech synthesis with various texts
  • Sensor monitoring and event detection
  • Emergency stop functionality
  • WebSocket communication stability

Support & Resources

Documentation

Community & Support

Version Information

  • Plugin Version - 2.0.0 (Enhanced Integration)
  • HRIStudio Compatibility - v1.0+
  • ROS2 Distro - Humble (recommended)
  • NAO6 Compatibility - NAOqi 2.8.7.4+
  • Last Updated - December 2024

License

MIT License - See LICENSE file for details

Citation

If you use these plugins in your research, please cite:

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

Maintained by: HRIStudio RoboLab Team
Contact: robolab@hristudio.com
Repository: hristudio/nao6-ros2-plugins

Part of the HRIStudio platform for advancing Human-Robot Interaction research

Reference in New Issue View Git Blame Copy Permalink