hristudio/docs/tutorials/09-simulation-mode.md

Tutorial 9: Simulation Mode

Learn how to test HRIStudio experiments without a physical robot.

Objectives

• Enable simulation mode
• Use the mock robot server
• Test experiments end-to-end
• Practice trial execution

Why Simulation Mode?

Simulation mode allows you to:

• Test protocols without a robot
• Train wizards before live sessions
• Debug experiments in development
• Run pilots without robot access
• Develop on any computer

Understanding Simulation Options

HRIStudio offers two simulation approaches:

Approach	Pros	Cons
Client-side	No server needed, instant	Limited robot simulation
Mock Server	Full rosbridge protocol	Requires running server

Client-Side Simulation

Simulates robot locally in the browser:

• No network required
• Instant startup
• Basic action timing
• Fake sensor data

Mock Server

Full WebSocket server simulating rosbridge:

• Complete protocol support
• Realistic timing
• Sensor data simulation
• Better for integration testing

Step 1: Enable Client-Side Simulation

Quick Start

1. Create or edit hristudio/.env.local
2. Add:

   NEXT_PUBLIC_SIMULATION_MODE=true
   

3. Restart the dev server:

   bun dev
   

Verify Enabled

Look for the simulation indicator in the UI:

┌─────────────────────────────────────────────────────────────┐
│  Wizard Interface                    [🔵 SIMULATION MODE] │
├─────────────────────────────────────────────────────────────┤

Features Available

In simulation mode:

• ✅ All robot actions execute (simulated timing)
• ✅ Speech actions show estimated duration
• ✅ Movement actions track position
• ✅ Sensor data is simulated
• ✅ Trial execution works normally
• ❌ Real robot not controlled
• ❌ Physical interactions not possible

Step 2: Start Mock Robot Server

For more complete testing, use the mock server:

Option 1: Standalone Server

cd hristudio/scripts/mock-robot
bun install
bun dev

Server starts on ws://localhost:9090

Option 2: Docker

cd nao6-hristudio-integration
docker compose -f docker-compose.yml -f docker-compose.mock.yml --profile mock up -d

Verify Server Running

# Check container
docker ps

# Should show:
# CONTAINER ID   IMAGE         STATUS
# abc123def456   hristudio-mock-robot   Up 2 minutes

Step 3: Connect to Mock Server

1. Go to the NAO Test Page: /nao-test
2. Ensure NEXT_PUBLIC_SIMULATION_MODE is NOT set (or set to false)
3. Click Connect
4. You should see:

   Connected to rosbridge
   Subscribed to: /joint_states, /bumper, /sonar/left, ...
   

Step 4: Test Robot Actions

From NAO Test Page

1. Speech Test

   • Enter text: "Hello, this is a test"
   • Click Say
   • See simulated speech duration

2. Movement Test

   • Set walk speed: 0.1 m/s
   • Click Walk Forward
   • Watch position update

3. Head Control

   • Set yaw: 1.0, pitch: 0.0
   • Click Move Head
   • See joint angles update

From Wizard Interface

1. Start a trial
2. Execute actions as normal
3. Actions are sent to mock server
4. Mock server responds with simulated data

Step 5: Simulated Actions Reference

Speech Actions

Action	Simulation Behavior
say_text	Duration = 1.5s + 300ms × word_count
say_with_emotion	Duration = 1.5s + 300ms × word_count + emotion_overhead
wave_goodbye	Duration = 3.0s

Movement Actions

Action	Simulation Behavior
walk_forward	Position updates over 500ms
walk_backward	Position updates over 500ms
turn_left	Angle decreases over 500ms
turn_right	Angle increases over 500ms
stop	Velocity set to 0

Sensor Simulation

Sensor	Simulated Value
Battery	85% ± 2% variation
Joint States	Random positions ±0.1 rad
Bumper	False (no contact)
Sonar	0.5-1.0m (random)
Touch	False (no touch)

Step 6: Testing Experiment Protocols

Full Protocol Test

1. Enable simulation mode
2. Create or open experiment
3. Schedule trial
4. Start trial in wizard interface
5. Execute through all steps
6. Verify timing and flow

Test Checklist

• All steps execute in order
• Branching decisions work
• Timing estimates are accurate
• Event log captures everything
• No errors or warnings
• Trial completes successfully

Debug Mode

Enable verbose logging:

# In browser console, run:
localStorage.setItem('debug', 'true')

# Refresh page
# Now see detailed action logs in console

Step 7: Training Wizards

Simulation mode is perfect for training:

Training Scenario 1: Basic Operation

1. Enable simulation mode
2. Load simple experiment
3. Practice:
   • Starting/pausing trials
   • Executing quick actions
   • Adding notes

Training Scenario 2: Decision Making

1. Load branching experiment
2. Practice:
   • Observing participant cues
   • Selecting appropriate branches
   • Documenting decisions

Training Scenario 3: Handling Issues

1. Practice:
   • Pausing for breaks
   • Responding to alerts
   • Stopping trials early

Step 8: Development Workflow

TDD with Simulation

┌─────────────────────────────────────────────────────────────┐
│                    Development Cycle                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. Design experiment in UI                                 │
│         │                                                  │
│         ▼                                                  │
│  2. Enable simulation mode                                 │
│         │                                                  │
│         ▼                                                  │
│  3. Run test trial                                         │
│         │                                                  │
│         ▼                                                  │
│  4. Review event log                                       │
│         │                                                  │
│         ▼                                                  │
│  5. Fix issues found                                       │
│         │                                                  │
│         └────────────┐                                     │
│                      │                                     │
│                      └ (repeat)                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Testing Checklist

Before running real trials:

• Experiment works in simulation
• All actions execute correctly
• Timing is acceptable
• Branching works as expected
• Wizard notes function properly
• Data exports correctly

Step 9: Transitioning to Real Robot

When ready to test with real robot:

Step 1: Disable Simulation

Remove or set to false:

NEXT_PUBLIC_SIMULATION_MODE=false

Step 2: Connect Robot

1. Start Docker services
2. Verify robot connection
3. Test with NAO Test Page

Step 3: Run Comparison Trial

1. Run same experiment on real robot
2. Compare timing and behavior
3. Adjust parameters as needed

Step 4: Document Differences

Note any protocol adjustments needed:

• Timing differences
• Action parameter changes
• Branch criteria updates

Troubleshooting

Simulation Actions Not Working

1. Check NEXT_PUBLIC_SIMULATION_MODE=true is set
2. Verify no errors in browser console
3. Try refreshing the page

Mock Server Connection Failed

# Check if server is running
docker ps | grep mock

# Check server logs
docker compose logs mock_robot

# Restart if needed
docker compose restart mock_robot

Actions Execute But Nothing Happens

1. Check WebSocket URL is correct
2. Verify port 9090 is not blocked
3. Try client-side simulation instead

Comparison: Simulation vs Real

Aspect	Simulation	Real Robot
Setup time	1 min	30+ min
Availability	Always	Requires robot
Cost	Free	Robot access needed
Timing accuracy	Estimated	Actual
Physical interaction	✗	✓
Sensor accuracy	Fake	Real
Network dependent	No	Yes

Best Practices

When to Use Simulation

• During experiment design
• While robot unavailable
• For wizard training
• For debugging protocols
• For quick iteration

When to Use Real Robot

• Final protocol validation
• Timing accuracy critical
• Physical interaction matters
• Sensor data needed
• Pre-study pilot

Transition Checklist

Before real trials:

• Protocol tested in simulation
• Timing verified
• Actions calibrated
• Wizard team trained
• Backup plan ready

Next Steps

Now that you've mastered simulation:

1. Robot Integration - Connect real robot
2. Running Trials - Execute live trials
3. Your First Study - Run complete study

---

Previous: Data & Analysis | Back: Tutorials Overview