soconnor/hristudio
1
0
Fork 0
mirror of https://github.com/soconnor0919/hristudio.git synced 2026-05-08 13:58:55 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity

feat(tutorials): add comprehensive tutorials for HRIStudio including Getting Started, Your First Study, Designing Experiments, Running Trials, Wizard Interface, Robot Integration, Forms & Surveys, Data & Analysis, and Simulation Mode

Browse Source
This commit is contained in:
Sean O'Connor
2026-03-25 22:48:42 -04:00
parent 3959cf23f7
commit 1c7f0297a6
34 changed files with 6298 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tutorials/05-wizard-interface.md
+393
View File
@@ -0,0 +1,393 @@
# Tutorial 5: Wizard Interface
Learn how to use the real-time wizard control interface for Wizard-of-Oz studies.
## Objectives
- Navigate the wizard interface
- Control robot actions in real-time
- Make branching decisions
- Handle trial interruptions
## What is the Wizard Interface?
The **Wizard Interface** is your control center during trials. It provides:
- Real-time trial monitoring
- Robot action controls
- Decision-making tools
- Intervention capabilities
- Event logging
```
┌──────────────────────────────────────────────────────────────┐
│ WIZARD INTERFACE │
├────────────────┬─────────────────────┬──────────────────────┤
│ │ │ │
│ Trial │ Timeline │ Robot │
│ Controls │ Progress │ Status │
│ │ │ │
│ ┌──────────┐ │ ┌───────────────┐ │ ┌────────────────┐ │
│ │ ▶ Play │ │ │ 1 → 2 → 3 → │ │ │ ● Connected │ │
│ │ ⏸ Pause │ │ │ ↑ │ │ │ Battery: 85% │ │
│ │ ⏹ Stop │ │ │ Step 2 │ │ │ Position: (0,0)│ │
│ └──────────┘ │ └───────────────┘ │ └────────────────┘ │
│ │ │ │
│ ┌──────────┐ │ Progress: 40% │ ┌────────────────┐ │
│ │ 📝 Notes │ │ Time: 00:05:23 │ │ Action Panel │ │
│ │ ⚠ Alert │ │ │ │ │ │
│ └──────────┘ │ │ │ [Say Text] │ │
│ │ │ │ [Move Robot] │ │
│ │ │ │ [Wave] │ │
│ │ │ │ [Custom...] │ │
│ │ │ └────────────────┘ │
└────────────────┴─────────────────────┴──────────────────────┘
```
## Step 1: Accessing the Wizard Interface
### Method 1: From Trials List
1. Go to **Trials** in sidebar
2. Find your scheduled trial
3. Click **Open Wizard**
### Method 2: Direct URL
```
/trials/{trialId}/wizard
```
### Method 3: Trial Queue
1. Go to **Wizard Queue**
2. See all pending trials
3. Click **Start** on any trial
## Step 2: Understanding the Layout
### Left Panel: Trial Controls
| Control | Function |
|---------|----------|
| Play/Pause | Start or pause trial |
| Stop | End trial early |
| Notes | Add timestamped observations |
| Alert | Send alert to researchers |
### Center Panel: Timeline
- **Visual Progress**: See step progression
- **Current Position**: Highlighted current step
- **Navigation**: Click to jump to step (if allowed)
- **Time Display**: Elapsed and estimated remaining
### Right Panel: Robot Control
**Status Section:**
- Connection indicator
- Battery level
- Position tracking
- Sensor readings
**Action Section:**
- Quick action buttons
- Custom action builder
- Action history
## Step 3: Controlling the Robot
### Quick Actions
Pre-configured robot actions:
| Action | Description |
|--------|-------------|
| Say Text | Make robot speak |
| Wave | Wave gesture |
| Look at Me | Turn head toward participant |
| Look Away | Turn head elsewhere |
| Nod | Confirmation nod |
| Shake Head | Negation shake |
### Custom Say Text
1. Click **Say Text**
2. Enter text in popup:
```
"Hello! Nice to meet you."
```
3. Select options:
- Speed: Normal / Slow / Fast
- Emotion: Neutral / Happy / Excited
4. Click **Execute**
5. Robot speaks the text
### Move Robot
1. Click **Move Robot**
2. Select movement type:
- Walk Forward/Back
- Turn Left/Right
- Move Head
- Move Arm
3. Set parameters
4. Execute
### Custom Actions
For advanced control:
1. Click **Custom...**
2. Select action from plugin
3. Configure parameters
4. Execute
## Step 4: Making Decisions
When the experiment reaches a branching point:
### Decision Popup
A popup appears with options:
```
┌─────────────────────────────────────────────────────────────┐
│ Branch Decision Required │
├─────────────────────────────────────────────────────────────┤
│ │
│ Step: Comprehension Check │
│ Question: "What color was the rock?" │
│ │
│ Participant's response: They said "blue" (incorrect) │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ ○ Correct Response (Red) │ │
│ │ → Robot celebrates │ │
│ │ │ │
│ │ ● Incorrect Response (Other) │ │
│ │ → Robot gently corrects │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ [Cancel] [Confirm Selection] │
└─────────────────────────────────────────────────────────────┘
```
### Decision Guidelines
1. **Observe** participant's actual response
2. **Consider** protocol criteria
3. **Select** appropriate branch
4. **Confirm** selection
### After Selection
- Decision is logged with timestamp
- Trial continues on selected path
- Both participant and robot continue
## Step 5: Handling Interruptions
### Pause Trial
When you need to pause:
1. Click **Pause** button
2. Optionally add reason:
- Participant needs break
- Technical issue
- External interruption
3. Trial pauses, robot holds position
### Resume Trial
1. Click **Play** button
2. Trial resumes from pause point
3. Pause duration is logged
### Stop Trial
For early termination:
1. Click **Stop** button
2. Select reason:
- Participant fatigue
- Technical failure
- Protocol deviation
- Participant withdrawal
3. Confirm stop
4. Partial data is saved
### Add Notes
Record observations:
1. Click **Notes** button
2. Enter observation:
```
Participant laughed at the robot's gesture.
```
3. Note is timestamped automatically
4. Notes appear in event log
### Send Alert
Notify researchers:
1. Click **Alert** button
2. Select alert type:
- Technical issue
- Safety concern
- Protocol question
- Other
3. Add description
4. Send alert
## Step 6: Monitoring Robot Status
### Connection Status
| Status | Icon | Meaning |
|--------|------|---------|
| Connected | ● Green | Robot responding |
| Connecting | ● Yellow | Attempting connection |
| Disconnected | ● Red | No robot connection |
| Error | ⚠ Orange | Connection error |
### Battery Monitor
View battery level:
- Green: > 50%
- Yellow: 20-50%
- Red: < 20%
### Sensor Display
Real-time sensor readings:
- Joint positions
- Touch sensors
- Sonar distances
- Camera feed (if available)
### Action Queue
See pending/executing actions:
```
Executing: Say Text "Hello!"
Pending: Move Head (queued)
```
## Step 7: Keyboard Shortcuts
Speed up your workflow:
| Key | Action |
|-----|--------|
| Space | Play/Pause toggle |
| Escape | Stop trial |
| N | Add note |
| A | Send alert |
| 1-9 | Execute quick action |
| ← → | Navigate timeline |
| ↑ ↓ | Select branch option |
## Step 8: Event Logging
All actions are logged automatically:
```
[14:32:05] Trial started
[14:32:07] Step 1: The Hook
[14:32:08] Action: Say Text "Hello!"
[14:32:11] Action: Move Arm Wave
[14:32:15] Step 2: The Narrative
[14:32:16] Action: Say Text "Once upon a time..."
[14:33:05] Step 3: Comprehension Check
[14:33:06] Action: Say Text "What color was the rock?"
[14:33:28] Wizard Note: "Participant said blue"
[14:33:30] Branch: Incorrect selected
[14:33:31] Step 4b: Correction
[14:33:32] Action: Say Text "Actually, it was red."
[14:34:05] Trial completed
```
## Trial Modes
### Observer Mode
For observers (read-only):
- View trial progress
- See robot status
- Cannot execute actions
- Can add notes
### Active Wizard Mode
Full control:
- Execute actions
- Make decisions
- Pause/resume
- Add notes/alerts
### Training Mode
Practice without real data:
- Simulated robot
- No data saved
- Safe to experiment
## Best Practices
### Before Trial
- [ ] Review experiment protocol
- [ ] Test robot connection
- [ ] Familiarize with action panel
- [ ] Know decision criteria
### During Trial
- [ ] Stay focused on participant
- [ ] Make decisions based on observation
- [ ] Document notable events
- [ ] Keep action log clean
### After Trial
- [ ] Review event log
- [ ] Add final notes
- [ ] Confirm data saved
- [ ] Prepare for next trial
## Troubleshooting
### Robot Not Responding
1. Check connection indicator
2. Verify network
3. Check robot power
4. Restart connection
### Actions Not Executing
1. Check action queue
2. Verify parameters
3. Check robot state (not in rest mode)
### Decision Popup Not Appearing
1. Check if step has branches
2. Verify step type is "conditional"
3. Contact researcher
## Next Steps
Mastered the wizard interface?
1. **[Robot Integration](06-robot-integration.md)** - Deep dive into robot control
2. **[Data & Analysis](08-data-and-analysis.md)** - Review trial data
3. **[Simulation Mode](09-simulation-mode.md)** - Practice without a robot
---
**Previous**: [Running Trials](04-running-trials.md) | **Next**: [Robot Integration](06-robot-integration.md)