mirror of
https://github.com/soconnor0919/hristudio.git
synced 2025-12-11 14:44:44 -05:00
Pre-conf work 2025
This commit is contained in:
238
docs/wizard-interface-summary.md
Normal file
238
docs/wizard-interface-summary.md
Normal file
@@ -0,0 +1,238 @@
|
||||
# Wizard Interface Summary & Usage Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The Wizard Interface has been completely fixed and enhanced to provide a professional, production-ready control panel for conducting HRI trials. All duplicate headers have been removed, real experiment data is now used instead of hardcoded values, and the WebSocket system is properly integrated.
|
||||
|
||||
## Key Fixes Applied
|
||||
|
||||
### 1. Removed Duplicate Headers ✅
|
||||
- **ParticipantInfo**: Removed redundant Card headers since it's used inside EntityViewSection
|
||||
- **RobotStatus**: Cleaned up duplicate title sections and unified layout
|
||||
- **All Components**: Now follow consistent design patterns without header duplication
|
||||
|
||||
### 2. Real Experiment Data Integration ✅
|
||||
- **Experiment Steps**: Now loads actual steps from database via `api.experiments.getSteps`
|
||||
- **Type Mapping**: Database step types ("wizard", "robot", "parallel", "conditional") properly mapped to component types ("wizard_action", "robot_action", "parallel_steps", "conditional_branch")
|
||||
- **Step Properties**: Real step names, descriptions, and duration estimates from experiment designer
|
||||
|
||||
### 3. Type Safety Improvements ✅
|
||||
- **Demographics Handling**: Fixed all `any` types in ParticipantInfo component
|
||||
- **Step Type Mapping**: Proper TypeScript types throughout the wizard interface
|
||||
- **Null Safety**: Using nullish coalescing (`??`) instead of logical OR (`||`) for better type safety
|
||||
|
||||
## Current System Status
|
||||
|
||||
### ✅ Working Features
|
||||
- **Real-time WebSocket Connection**: Live trial updates and control
|
||||
- **Step-by-step Execution**: Navigate through actual experiment protocols
|
||||
- **Robot Status Monitoring**: Battery, signal, position, and sensor tracking
|
||||
- **Participant Information**: Complete demographics and consent status
|
||||
- **Event Logging**: Real-time capture of all trial activities
|
||||
- **Trial Control**: Start, execute, complete, and abort trials
|
||||
|
||||
### 📊 Seed Data Available
|
||||
Run `bun db:seed` to populate with realistic test data:
|
||||
|
||||
**Test Experiments:**
|
||||
- **"Basic Interaction Protocol 1"** - 3 steps with wizard actions and NAO integration
|
||||
- **"Dialogue Timing Pilot"** - Multi-step protocol with parallel/conditional logic
|
||||
|
||||
**Test Participants:**
|
||||
- 8 participants with complete demographics (age, gender, education, robot experience)
|
||||
- Consent already verified for immediate testing
|
||||
|
||||
**Test Trials:**
|
||||
- Multiple trials in different states (scheduled, in_progress, completed)
|
||||
- Realistic metadata and execution history
|
||||
|
||||
## WebSocket Server Usage
|
||||
|
||||
### Automatic Connection
|
||||
The wizard interface automatically connects to the WebSocket server at:
|
||||
```
|
||||
wss://localhost:3000/api/websocket?trialId={TRIAL_ID}&token={AUTH_TOKEN}
|
||||
```
|
||||
|
||||
### Real-time Features
|
||||
- **Connection Status**: Green "Real-time" badge when connected
|
||||
- **Live Updates**: Trial status, step changes, and event logging
|
||||
- **Automatic Reconnection**: Exponential backoff on connection loss
|
||||
- **Error Handling**: User-friendly error messages and recovery
|
||||
|
||||
### Message Flow
|
||||
```
|
||||
Wizard Action → WebSocket → Server → Database → Broadcast → All Connected Clients
|
||||
```
|
||||
|
||||
## Quick Start Instructions
|
||||
|
||||
### 1. Setup Development Environment
|
||||
```bash
|
||||
# Install dependencies
|
||||
bun install
|
||||
|
||||
# Start database (if using Docker)
|
||||
bun run docker:up
|
||||
|
||||
# Push schema and seed data
|
||||
bun db:push
|
||||
bun db:seed
|
||||
|
||||
# Start development server
|
||||
bun dev
|
||||
```
|
||||
|
||||
### 2. Access Wizard Interface
|
||||
1. **Login**: `sean@soconnor.dev` / `password123`
|
||||
2. **Navigate**: Dashboard → Studies → Select Study → Trials
|
||||
3. **Select Trial**: Click on any trial with "scheduled" status
|
||||
4. **Start Wizard**: Click "Wizard Control" button
|
||||
|
||||
### 3. Conduct a Trial
|
||||
1. **Verify Connection**: Look for green "Real-time" badge in header
|
||||
2. **Review Protocol**: Check experiment steps and participant info
|
||||
3. **Start Trial**: Click "Start Trial" button
|
||||
4. **Execute Steps**: Follow protocol step-by-step using "Next Step" button
|
||||
5. **Monitor Status**: Watch robot status and live event log
|
||||
6. **Complete Trial**: Click "Complete" when finished
|
||||
|
||||
## Expected Trial Flow
|
||||
|
||||
### Step 1: Introduction & Object Demo
|
||||
- **Wizard Action**: Show object to participant
|
||||
- **Robot Action**: NAO says "Hello, I am NAO. Let's begin!"
|
||||
- **Duration**: ~60 seconds
|
||||
|
||||
### Step 2: Participant Response
|
||||
- **Wizard Action**: Wait for participant response
|
||||
- **Prompt**: "What did you notice about the object?"
|
||||
- **Timeout**: 20 seconds
|
||||
|
||||
### Step 3: Robot Feedback
|
||||
- **Robot Action**: Set NAO LED color to blue
|
||||
- **Wizard Fallback**: Record observation note if no robot available
|
||||
- **Duration**: ~30 seconds
|
||||
|
||||
## WebSocket Communication Examples
|
||||
|
||||
### Starting a Trial
|
||||
```json
|
||||
{
|
||||
"type": "trial_action",
|
||||
"data": {
|
||||
"actionType": "start_trial",
|
||||
"step_index": 0,
|
||||
"data": { "notes": "Trial started by wizard" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Logging Wizard Intervention
|
||||
```json
|
||||
{
|
||||
"type": "wizard_intervention",
|
||||
"data": {
|
||||
"action_type": "manual_correction",
|
||||
"step_index": 1,
|
||||
"action_data": { "message": "Clarified participant question" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step Transition
|
||||
```json
|
||||
{
|
||||
"type": "step_transition",
|
||||
"data": {
|
||||
"from_step": 1,
|
||||
"to_step": 2,
|
||||
"step_name": "Participant Response"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Robot Integration
|
||||
|
||||
### Supported Robots
|
||||
- **TurtleBot3 Burger**: ROS2 navigation and sensing
|
||||
- **NAO Humanoid**: REST API for speech, gestures, LEDs
|
||||
- **Plugin System**: Extensible architecture for additional robots
|
||||
|
||||
### Robot Actions in Seed Data
|
||||
- **NAO Say Text**: Text-to-speech with configurable parameters
|
||||
- **NAO Set LED Color**: Visual feedback through eye color changes
|
||||
- **NAO Play Animation**: Pre-defined gesture sequences
|
||||
- **Wizard Fallbacks**: Manual alternatives when robots unavailable
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### WebSocket Issues
|
||||
- **Red "Offline" Badge**: Check network connection and server status
|
||||
- **Yellow "Connecting" Badge**: Normal during initial connection or reconnection
|
||||
- **Connection Errors**: Verify authentication token and trial permissions
|
||||
|
||||
### Step Loading Problems
|
||||
- **No Steps Showing**: Verify experiment has steps in database
|
||||
- **"Loading experiment steps..."**: Normal during initial load
|
||||
- **Type Errors**: Check step type mapping in console
|
||||
|
||||
### Robot Communication
|
||||
- **Robot Status**: Monitor connection, battery, and sensor status
|
||||
- **Action Failures**: Check robot plugin configuration and network
|
||||
- **Fallback Actions**: System automatically provides wizard alternatives
|
||||
|
||||
## Production Deployment
|
||||
|
||||
### Environment Variables
|
||||
```bash
|
||||
DATABASE_URL=postgresql://user:pass@host:port/dbname
|
||||
NEXTAUTH_SECRET=your-secret-key
|
||||
NEXTAUTH_URL=https://your-domain.com
|
||||
```
|
||||
|
||||
### WebSocket Configuration
|
||||
- **Protocol**: Automatic upgrade from HTTP to WebSocket
|
||||
- **Authentication**: Session-based token validation
|
||||
- **Scaling**: Per-trial room isolation for concurrent sessions
|
||||
- **Security**: Role-based access control and message validation
|
||||
|
||||
## Development Notes
|
||||
|
||||
### Architecture Decisions
|
||||
- **EntityViewSection**: Consistent layout patterns across all pages
|
||||
- **Real-time First**: WebSocket primary, polling fallback
|
||||
- **Type Safety**: Strict TypeScript throughout wizard components
|
||||
- **Plugin System**: Extensible robot integration architecture
|
||||
|
||||
### Performance Optimizations
|
||||
- **Selective Polling**: Reduced frequency when WebSocket connected
|
||||
- **Local State**: Efficient React state management
|
||||
- **Event Batching**: Optimized WebSocket message handling
|
||||
- **Caching**: Smart API data revalidation
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Immediate Enhancements
|
||||
- [ ] Observer-only interface for read-only trial monitoring
|
||||
- [ ] Pause/resume functionality during trial execution
|
||||
- [ ] Enhanced post-trial analytics and visualization
|
||||
- [ ] Real robot hardware integration testing
|
||||
|
||||
### Future Improvements
|
||||
- [ ] Multi-wizard collaboration features
|
||||
- [ ] Advanced step branching and conditional logic
|
||||
- [ ] Voice control integration for hands-free operation
|
||||
- [ ] Mobile-responsive wizard interface
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria Met ✅
|
||||
|
||||
- ✅ **No Duplicate Headers**: Clean, professional interface
|
||||
- ✅ **Real Experiment Data**: No hardcoded values, actual database integration
|
||||
- ✅ **WebSocket Integration**: Live real-time trial control and monitoring
|
||||
- ✅ **Type Safety**: Strict TypeScript throughout wizard components
|
||||
- ✅ **Production Ready**: Professional UI matching platform standards
|
||||
|
||||
The wizard interface is now production-ready and provides researchers with a comprehensive, real-time control system for conducting high-quality HRI studies.
|
||||
Reference in New Issue
Block a user