mirror of
https://github.com/soconnor0919/hristudio.git
synced 2026-03-23 19:27:51 -04:00
Sean O'Connor
cf3597881b
- Move 30+ outdated docs to docs/_archive/ - Move obsolete root files to _archive/ - Update README.md (Better Auth, current features) - Update docs/README.md (new architecture diagram) - Update docs/quick-reference.md (consolidated) - Update docs/project-status.md (March 2026 state) - Update docs/nao6-quick-reference.md (14 actions, Docker services) - Update docs/implementation-guide.md (Better Auth, git submodule) - Update docs/proposal.tex (timeline updates) - Archive errors.txt, plugin_dump.json, test HTML files
149 lines
3.3 KiB
Markdown
Executable File
149 lines
3.3 KiB
Markdown
Executable File
# HRIStudio Quick Reference Guide
|
|
|
|
## Quick Setup
|
|
|
|
```bash
|
|
# Clone with submodules
|
|
git clone https://github.com/soconnor0919/hristudio.git
|
|
cd hristudio
|
|
git submodule update --init --recursive
|
|
|
|
# Install and setup
|
|
bun install
|
|
bun run docker:up
|
|
bun db:push
|
|
bun db:seed
|
|
|
|
# Start
|
|
bun dev
|
|
```
|
|
|
|
**Login**: `sean@soconnor.dev` / `password123`
|
|
|
|
---
|
|
|
|
## Key Concepts
|
|
|
|
### Hierarchy
|
|
```
|
|
Study → Experiment → Trial → Step → Action
|
|
```
|
|
|
|
### User Roles
|
|
- **Administrator**: Full system access
|
|
- **Researcher**: Create studies, design experiments
|
|
- **Wizard**: Execute trials, control robots
|
|
- **Observer**: Read-only monitoring
|
|
|
|
### Plugin Identifier System
|
|
- `identifier`: Machine-readable key (e.g., `nao6-ros2`)
|
|
- `name`: Display name (e.g., `NAO6 Robot (ROS2 Integration)`)
|
|
- Lookup order: identifier → name → fallback
|
|
|
|
---
|
|
|
|
## Development Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `bun dev` | Start dev server |
|
|
| `bun build` | Production build |
|
|
| `bun typecheck` | TypeScript validation |
|
|
| `bun db:push` | Push schema changes |
|
|
| `bun db:seed` | Seed data + sync plugins |
|
|
| `bun run docker:up` | Start PostgreSQL |
|
|
|
|
---
|
|
|
|
## NAO6 Robot Docker
|
|
|
|
```bash
|
|
cd ~/Documents/Projects/nao6-hristudio-integration
|
|
docker compose up -d
|
|
```
|
|
|
|
**Services**: nao_driver, ros_bridge (:9090), ros_api
|
|
|
|
**Topics**:
|
|
- `/speech` - TTS
|
|
- `/cmd_vel` - Movement
|
|
- `/leds/eyes` - LEDs
|
|
|
|
---
|
|
|
|
## Architecture Layers
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ UI: Design / Execute / Playback │
|
|
├─────────────────────────────────────┤
|
|
│ Server: tRPC, Auth, Trial Logic │
|
|
├─────────────────────────────────────┤
|
|
│ Data: PostgreSQL, File Storage │
|
|
│ Robot: ROS2 via WebSocket │
|
|
└─────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## WebSocket Architecture
|
|
|
|
- **Trial Updates**: `ws://localhost:3001/api/websocket`
|
|
- **ROS Bridge**: `ws://localhost:9090` (rosbridge)
|
|
- **Real-time**: Auto-reconnect with exponential backoff
|
|
- **Message Types**: trial_event, trial_status, connection_established
|
|
|
|
---
|
|
|
|
## Database Schema
|
|
|
|
### Core Tables
|
|
- `users` - Authentication
|
|
- `studies` - Research projects
|
|
- `experiments` - Protocol templates
|
|
- `trials` - Execution instances
|
|
- `steps` - Experiment phases
|
|
- `actions` - Atomic tasks
|
|
- `plugins` - Robot integrations (identifier column)
|
|
- `trial_events` - Execution logs
|
|
|
|
---
|
|
|
|
## Route Structure
|
|
|
|
```
|
|
/dashboard - Global overview
|
|
/studies - Study list
|
|
/studies/[id] - Study details
|
|
/studies/[id]/experiments
|
|
/studies/[id]/trials
|
|
/studies/[id]/participants
|
|
/trials/[id]/wizard - Trial execution
|
|
/experiments/[id]/designer - Visual editor
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
**Build errors**: `rm -rf .next && bun build`
|
|
|
|
**Database reset**: `bun db:push --force && bun db:seed`
|
|
|
|
**Check types**: `bun typecheck`
|
|
|
|
---
|
|
|
|
## Plugin System
|
|
|
|
```typescript
|
|
// Loading a plugin by identifier
|
|
const plugin = await trialExecution.loadPlugin("nao6-ros2");
|
|
|
|
// Action execution
|
|
await robot.execute("nao6-ros2.say_with_emotion", { text: "Hello" });
|
|
```
|
|
|
|
---
|
|
|
|
Last updated: March 2026 |