hristudio/WIZARD_INTERFACE_README.md

Wizard Interface - Implementation Complete ✅

Overview

The Wizard Interface for HRIStudio has been completely implemented and is production-ready. All issues identified have been resolved, including duplicate headers, hardcoded data usage, and WebSocket integration.

What Was Fixed

🔧 Duplicate Headers Removed

• Problem: Cards on the right side had duplicated headers when wrapped in EntityViewSection
• Solution: Removed redundant Card components and replaced with simple div elements
• Files Modified:
  • ParticipantInfo.tsx - Removed Card headers, used direct div styling
  • RobotStatus.tsx - Cleaned up duplicate title sections
  • WizardInterface.tsx - Proper EntityViewSection usage

📊 Real Experiment Data Integration

• Problem: Using hardcoded mock data instead of actual experiment steps
• Solution: Integrated with api.experiments.getSteps to load real database content
• Implementation:

  const { data: experimentSteps } = api.experiments.getSteps.useQuery({
    experimentId: trial.experimentId
  });
  

• Type Mapping: Database step types ("wizard", "robot") mapped to component types ("wizard_action", "robot_action")

🔗 WebSocket System Integration

• Status: Fully operational WebSocket server at /api/websocket
• Features:
  • Real-time trial status updates
  • Live step transitions
  • Wizard intervention logging
  • Automatic reconnection with exponential backoff
• Visual Indicators: Connection status badges (green "Real-time", yellow "Connecting", red "Offline")

🛡️ Type Safety Improvements

• Fixed: All any types in ParticipantInfo demographics handling
• Improved: Nullish coalescing (??) instead of logical OR (||)
• Added: Proper type mapping for step properties

Current System State

✅ Production Ready Features

• Trial Execution: Start, conduct, and finish trials using real experiment data
• Step Navigation: Execute actual protocol steps from experiment designer
• Robot Integration: Support for TurtleBot3 and NAO robots via plugin system
• Real-time Monitoring: Live event logging and status updates
• Participant Management: Complete demographic information display
• Professional UI: Consistent with platform design standards

📋 Seed Data Available

Run bun db:seed to populate test environment:

• 2 Experiments: "Basic Interaction Protocol 1" and "Dialogue Timing Pilot"
• 8 Participants: Complete demographics and consent status
• Multiple Trials: Various states (scheduled, in_progress, completed)
• Robot Plugins: NAO and TurtleBot3 configurations

How to Use the WebSocket System

1. Automatic Connection

The wizard interface connects automatically when you access a trial:

• URL: wss://localhost:3000/api/websocket?trialId={ID}&token={AUTH}
• Authentication: Session-based token validation
• Reconnection: Automatic with exponential backoff

2. Message Types

Outgoing (Wizard → Server):

• trial_action: Start, complete, or abort trials
• wizard_intervention: Log manual interventions
• step_transition: Advance to next protocol step

Incoming (Server → Wizard):

• trial_status: Current trial state and step index
• trial_action_executed: Action confirmation
• step_changed: Step transition notifications

3. Real-time Features

• Live Status: Trial progress and robot status updates
• Event Logging: All actions logged with timestamps
• Multi-client: Multiple wizards can monitor same trial
• Error Handling: Graceful fallback to polling if WebSocket fails

Quick Start Guide

1. Setup Environment

bun install           # Install dependencies
bun db:push          # Apply database schema
bun db:seed          # Load test data
bun dev              # Start development server

2. Access Wizard Interface

1. Login: sean@soconnor.dev / password123
2. Navigate: Dashboard → Studies → Select Study → Trials
3. Find trial with "scheduled" status
4. Click "Wizard Control" button

3. Conduct Trial

1. Verify green "Real-time" connection badge
2. Review experiment steps and participant info
3. Click "Start Trial" to begin
4. Execute steps using "Next Step" button
5. Monitor robot status and live event log
6. Click "Complete" when finished

Testing with Seed Data

Available Experiments

"Basic Interaction Protocol 1":

• Step 1: Wizard shows object + NAO says greeting
• Step 2: Wizard waits for participant response
• Step 3: Robot LED feedback or wizard note

"Dialogue Timing Pilot":

• Parallel actions (wizard gesture + robot animation)
• Conditional logic with timer-based transitions
• Complex multi-step protocol

Robot Actions

• NAO Say Text: TTS with configurable parameters
• NAO Set LED Color: Visual feedback system
• NAO Play Animation: Gesture sequences
• Wizard Fallbacks: Manual alternatives when robots unavailable

Architecture Highlights

Design Patterns

• EntityViewSection: Consistent layout across all pages
• Unified Components: Maximum reusability, minimal duplication
• Type Safety: Strict TypeScript throughout
• Real-time First: WebSocket primary, polling fallback

Performance Features

• Smart Polling: Reduced frequency when WebSocket connected
• Local State: Efficient React state management
• Event Batching: Optimized message handling
• Selective Updates: Only relevant changes broadcast

Files Modified

Core Components

• src/components/trials/wizard/WizardInterface.tsx - Main wizard control panel
• src/components/trials/wizard/ParticipantInfo.tsx - Demographics display
• src/components/trials/wizard/RobotStatus.tsx - Robot monitoring panel

API Integration

• src/hooks/useWebSocket.ts - WebSocket connection management
• src/app/api/websocket/route.ts - Real-time server endpoint

Documentation

• docs/wizard-interface-guide.md - Complete usage documentation
• docs/wizard-interface-summary.md - Technical implementation details

Production Deployment

Environment Setup

DATABASE_URL=postgresql://user:pass@host:port/dbname
NEXTAUTH_SECRET=your-secret-key
NEXTAUTH_URL=https://your-domain.com

WebSocket Configuration

• Protocol: Automatic HTTP → WebSocket upgrade
• Security: Role-based access control
• Scaling: Per-trial room isolation
• Monitoring: Connection status and error logging

Success Criteria Met ✅

• ✅ No Duplicate Headers: Clean, professional interface
• ✅ Real Data Integration: Uses actual experiment steps from database
• ✅ WebSocket Functionality: Live real-time trial control
• ✅ Type Safety: Strict TypeScript throughout
• ✅ Production Quality: Matches platform design standards

Next Steps (Optional Enhancements)

• Observer-only interface for read-only monitoring
• Pause/resume functionality during trials
• Enhanced analytics and visualization
• Voice control for hands-free operation
• Mobile-responsive design

---

Status: ✅ COMPLETE - Production Ready Last Updated: December 2024 Version: 1.0.0

The wizard interface is now a fully functional, professional-grade control system for conducting Human-Robot Interaction studies with real-time monitoring and comprehensive data capture.