robot-plugins/docs/plugins.md

HRIStudio Robot Plugins

This document explains how robot plugins work in HRIStudio and provides guidance for plugin developers.

Overview

HRIStudio uses a plugin-based architecture to support different robot platforms. Each plugin defines:

• Robot capabilities and specifications
• Available actions for experiment design
• ROS2 integration details
• Communication protocols

Plugin Structure

Core Components

1. Robot Definition: Basic information about the robot platform
2. Action Library: Operations that can be performed during experiments
3. ROS2 Integration: Message types, topics, and communication setup
4. Assets: Images, models, and visual resources

Plugin Lifecycle

1. Repository Registration: Plugin repositories are added to HRIStudio
2. Plugin Discovery: Available plugins are fetched from repositories
3. Study Installation: Plugins are installed for specific studies
4. Experiment Integration: Actions become available in the experiment designer
5. Trial Execution: Actions are executed during live trials

Action System

Action Types

Actions are the building blocks of experiments. HRIStudio supports four main categories:

Movement Actions

• Robot locomotion and positioning
• Navigation and path planning
• Velocity control and stopping

Interaction Actions

• Speech synthesis and audio playback
• Gesture and animation control
• Display and lighting effects

Sensor Actions

• Data collection from sensors
• Environmental monitoring
• State queries and feedback

Logic Actions

• Conditional operations
• Loops and iteration
• Variable manipulation

Parameter Schema

Each action defines parameters using JSON Schema format:

{
  "type": "object",
  "properties": {
    "speed": {
      "type": "number",
      "minimum": 0,
      "maximum": 1.0,
      "default": 0.5,
      "description": "Movement speed as fraction of maximum"
    }
  },
  "required": ["speed"]
}

ROS2 Integration

Actions can integrate with ROS2 through:

• Topics: Publishing messages for robot control
• Services: Synchronous request/response operations
• Actions: Long-running operations with feedback

Plugin Development

Basic Plugin Structure

{
  "robotId": "my-robot",
  "name": "My Robot",
  "description": "Custom robot for research",
  "platform": "ROS2",
  "version": "1.0.0",
  "pluginApiVersion": "1.0",
  "hriStudioVersion": ">=0.1.0",
  "trustLevel": "community",
  "category": "mobile-robot",
  
  "manufacturer": {
    "name": "Research Lab",
    "website": "https://example.com"
  },
  
  "assets": {
    "thumbnailUrl": "assets/my-robot/thumb.png"
  },
  
  "actions": []
}

Creating Actions

Each action needs:

1. Unique ID: Snake_case identifier
2. Clear Name: Human-readable title
3. Category: One of the four main types
4. Parameters: JSON Schema definition
5. ROS2 Config: Communication details

Example action:

{
  "id": "move_forward",
  "name": "Move Forward",
  "description": "Move the robot forward by a specified distance",
  "category": "movement",
  "icon": "arrow-up",
  "timeout": 30000,
  "retryable": true,
  
  "parameterSchema": {
    "type": "object",
    "properties": {
      "distance": {
        "type": "number",
        "minimum": 0.1,
        "maximum": 5.0,
        "default": 1.0,
        "description": "Distance to move in meters"
      }
    },
    "required": ["distance"]
  },
  
  "ros2": {
    "messageType": "geometry_msgs/msg/Twist",
    "topic": "/cmd_vel",
    "payloadMapping": {
      "type": "transform",
      "transformFn": "transformToTwist"
    }
  }
}

Asset Management

Plugins should include visual assets:

• Thumbnail: 200x150px preview image
• Main Image: High-resolution robot photo
• Angle Views: Front, side, top perspectives
• Logo: Manufacturer or robot series logo

Assets are served relative to the repository URL.

Testing Plugins

Before publishing, test your plugin:

1. Validate JSON syntax and schema
2. Verify all asset URLs are accessible
3. Test ROS2 message formats
4. Check parameter validation
5. Ensure timeout values are reasonable

Integration with HRIStudio

Repository Management

Administrators can add plugin repositories in HRIStudio:

1. Navigate to Admin > Plugin Repositories
2. Add repository URL
3. Set trust level and enable sync
4. Plugins become available for installation

Study-Level Installation

Researchers install plugins for specific studies:

1. Go to Study > Plugins
2. Browse available plugins
3. Install required plugins
4. Configure plugin settings

Experiment Design

Installed plugin actions appear in the experiment designer:

1. Drag actions from the block library
2. Configure parameters in the properties panel
3. Connect actions to create experiment flow
4. Test and validate the experiment protocol

Trial Execution

During trials, HRIStudio:

1. Establishes ROS2 connections
2. Validates action parameters
3. Sends commands to robots
4. Monitors execution status
5. Logs all events for analysis

Best Practices

Plugin Design

• Use clear, descriptive action names
• Provide comprehensive parameter validation
• Include helpful descriptions for all parameters
• Choose appropriate timeout values
• Make actions atomic and focused

ROS2 Integration

• Follow ROS2 naming conventions
• Use appropriate QoS settings
• Handle connection failures gracefully
• Implement proper error reporting
• Document message format requirements

Asset Management

• Use consistent image dimensions
• Optimize file sizes for web delivery
• Provide high-quality thumbnails
• Include multiple viewing angles
• Ensure assets load quickly

Documentation

• Document all action behaviors
• Provide usage examples
• Explain parameter effects
• Include troubleshooting tips
• Maintain version compatibility notes

Repository Hosting

File Structure

repository/
├── repository.json       # Repository metadata
├── index.html           # Web interface
├── plugins/
│   ├── index.json       # Plugin list
│   └── robot-name.json  # Individual plugins
└── assets/
    ├── repository-icon.png
    └── robot-name/
        ├── thumb.png
        ├── main.jpg
        └── angles/

Hosting Requirements

• HTTPS enabled
• CORS headers configured
• Static file serving
• Reliable uptime
• Fast response times

Version Management

• Use semantic versioning
• Maintain backward compatibility
• Document breaking changes
• Provide migration guides
• Archive old versions

Security Considerations

Trust Levels

• Official: Signed and verified plugins
• Verified: Community plugins that passed review
• Community: User-contributed, use with caution

Validation

• All plugins are validated against schema
• Parameters are sanitized before execution
• ROS2 messages are type-checked
• Network communications are monitored

Permissions

• Plugins run with limited permissions
• Robot access is study-scoped
• Actions can be disabled by administrators
• Audit logs track all plugin activities

Troubleshooting

Common Issues

1. Plugin Not Loading: Check JSON syntax and schema compliance
2. Assets Not Found: Verify asset URLs and file paths
3. ROS2 Connection Failed: Check topic names and message types
4. Action Timeout: Increase timeout or check robot connectivity
5. Parameter Validation: Ensure all required parameters are provided

Debug Tools

• Use browser developer tools for network issues
• Check HRIStudio logs for plugin errors
• Validate JSON files with online tools
• Test ROS2 connections independently
• Monitor robot topics and services

Contributing

To contribute to the official plugin repository:

1. Fork the repository
2. Create a new plugin file
3. Add assets and documentation
4. Test thoroughly
5. Submit a pull request

For questions or support, contact the HRIStudio development team.