mirror of
https://github.com/soconnor0919/robot-plugins.git
synced 2025-12-15 08:24:45 -05:00
Update for new HRIStudio build
This commit is contained in:
290
docs/schema.md
290
docs/schema.md
@@ -1,227 +1,243 @@
|
||||
# Plugin Schema Documentation
|
||||
# HRIStudio Plugin Schema Documentation
|
||||
|
||||
This document describes the schema for HRIStudio robot plugins.
|
||||
This document describes the schema for HRIStudio robot plugins, including both repository metadata and individual plugin definitions.
|
||||
|
||||
## Repository Metadata
|
||||
## Repository Metadata (`repository.json`)
|
||||
|
||||
The repository itself is defined by a `repository.json` file with the following structure:
|
||||
The repository metadata file defines the plugin repository and its capabilities:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": string,
|
||||
"name": string,
|
||||
"description": string?,
|
||||
"id": "string (required) - Unique repository identifier",
|
||||
"name": "string (required) - Display name",
|
||||
"description": "string (optional) - Repository description",
|
||||
"apiVersion": "string (required) - Repository API version",
|
||||
"pluginApiVersion": "string (required) - Plugin API version supported",
|
||||
"urls": {
|
||||
"repository": string (URL),
|
||||
"git": string (URL)?
|
||||
"repository": "string (URL, required) - Repository base URL",
|
||||
"git": "string (URL, optional) - Git repository URL"
|
||||
},
|
||||
"official": boolean,
|
||||
"official": "boolean (required) - Whether this is an official repository",
|
||||
"trust": "string (enum: official|verified|community, required)",
|
||||
"author": {
|
||||
"name": string,
|
||||
"email": string (email)?,
|
||||
"url": string (URL)?,
|
||||
"organization": string?
|
||||
"name": "string (required)",
|
||||
"email": "string (email, optional)",
|
||||
"url": "string (URL, optional)",
|
||||
"organization": "string (optional)"
|
||||
},
|
||||
"maintainers": [
|
||||
{
|
||||
"name": string,
|
||||
"email": string (email)?,
|
||||
"url": string (URL)?
|
||||
"name": "string (required)",
|
||||
"email": "string (email, optional)",
|
||||
"url": "string (URL, optional)"
|
||||
}
|
||||
]?,
|
||||
"homepage": string (URL)?,
|
||||
"license": string,
|
||||
"defaultBranch": string,
|
||||
"lastUpdated": string (ISO date),
|
||||
"trust": "official" | "verified" | "community",
|
||||
"assets": {
|
||||
"icon": string?,
|
||||
"logo": string?,
|
||||
"banner": string?
|
||||
},
|
||||
],
|
||||
"homepage": "string (URL, optional)",
|
||||
"license": "string (required) - License identifier",
|
||||
"defaultBranch": "string (required) - Default Git branch",
|
||||
"lastUpdated": "string (ISO date, required)",
|
||||
"categories": [
|
||||
{
|
||||
"id": "string (required) - Category identifier",
|
||||
"name": "string (required) - Display name",
|
||||
"description": "string (required) - Category description"
|
||||
}
|
||||
],
|
||||
"compatibility": {
|
||||
"hristudio": {
|
||||
"min": string,
|
||||
"recommended": string?
|
||||
"min": "string (semver, required) - Minimum HRIStudio version",
|
||||
"recommended": "string (semver, optional) - Recommended version"
|
||||
},
|
||||
"ros2": {
|
||||
"distributions": string[],
|
||||
"recommended": string?
|
||||
}?
|
||||
"distributions": "string[] (optional) - Supported ROS2 distributions",
|
||||
"recommended": "string (optional) - Recommended distribution"
|
||||
}
|
||||
},
|
||||
"tags": string[],
|
||||
"assets": {
|
||||
"icon": "string (path, optional) - Repository icon",
|
||||
"logo": "string (path, optional) - Repository logo",
|
||||
"banner": "string (path, optional) - Repository banner"
|
||||
},
|
||||
"tags": "string[] (required) - Repository tags",
|
||||
"stats": {
|
||||
"plugins": number
|
||||
}?
|
||||
"plugins": "number (required) - Number of plugins"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Plugin Schema
|
||||
|
||||
Each plugin is defined in a JSON file with the following top-level structure:
|
||||
Each plugin is defined in a JSON file with HRIStudio-specific extensions:
|
||||
|
||||
### Core Properties
|
||||
|
||||
```json
|
||||
{
|
||||
"robotId": string,
|
||||
"name": string,
|
||||
"description": string?,
|
||||
"platform": string,
|
||||
"version": string,
|
||||
"manufacturer": object,
|
||||
"documentation": object,
|
||||
"assets": object,
|
||||
"specs": object,
|
||||
"ros2Config": object,
|
||||
"actions": array
|
||||
"robotId": "string (required) - Unique robot identifier",
|
||||
"name": "string (required) - Display name",
|
||||
"description": "string (optional) - Robot description",
|
||||
"platform": "string (required) - Robot platform (e.g., 'ROS2')",
|
||||
"version": "string (required) - Plugin version (semver)",
|
||||
"pluginApiVersion": "string (required) - Plugin API version",
|
||||
"hriStudioVersion": "string (required) - Minimum HRIStudio version",
|
||||
"trustLevel": "string (enum: official|verified|community, required)",
|
||||
"category": "string (required) - Plugin category identifier"
|
||||
}
|
||||
```
|
||||
|
||||
## Core Properties
|
||||
|
||||
### Required Properties
|
||||
|
||||
- `robotId`: Unique identifier for the robot (e.g., "turtlebot3-burger")
|
||||
- `name`: Display name of the robot
|
||||
- `platform`: Robot platform/framework (e.g., "ROS2")
|
||||
- `version`: Plugin version (semver format)
|
||||
|
||||
### Optional Properties
|
||||
|
||||
- `description`: Detailed description of the robot
|
||||
|
||||
## Manufacturer Information
|
||||
### Manufacturer Information
|
||||
|
||||
```json
|
||||
"manufacturer": {
|
||||
"name": string,
|
||||
"website": string (URL)?,
|
||||
"support": string (URL)?
|
||||
"name": "string (required)",
|
||||
"website": "string (URL, optional)",
|
||||
"support": "string (URL, optional)"
|
||||
}
|
||||
```
|
||||
|
||||
## Documentation Links
|
||||
### Documentation Links
|
||||
|
||||
```json
|
||||
"documentation": {
|
||||
"mainUrl": string (URL),
|
||||
"apiReference": string (URL)?,
|
||||
"wikiUrl": string (URL)?,
|
||||
"videoUrl": string (URL)?
|
||||
"mainUrl": "string (URL, required)",
|
||||
"apiReference": "string (URL, optional)",
|
||||
"wikiUrl": "string (URL, optional)",
|
||||
"videoUrl": "string (URL, optional)"
|
||||
}
|
||||
```
|
||||
|
||||
## Assets Configuration
|
||||
### Assets Configuration
|
||||
|
||||
```json
|
||||
"assets": {
|
||||
"thumbnailUrl": string,
|
||||
"logo": string?,
|
||||
"thumbnailUrl": "string (path, required)",
|
||||
"images": {
|
||||
"main": string,
|
||||
"main": "string (path, required)",
|
||||
"angles": {
|
||||
"front": string?,
|
||||
"side": string?,
|
||||
"top": string?
|
||||
}
|
||||
"front": "string (path, optional)",
|
||||
"side": "string (path, optional)",
|
||||
"top": "string (path, optional)"
|
||||
},
|
||||
"logo": "string (path, optional)"
|
||||
},
|
||||
"model": {
|
||||
"format": "URDF" | "glTF" | "other",
|
||||
"url": string (URL)
|
||||
}?
|
||||
"format": "string (enum: URDF|glTF|STL, optional)",
|
||||
"url": "string (URL, optional)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Robot Specifications
|
||||
### Robot Specifications
|
||||
|
||||
```json
|
||||
"specs": {
|
||||
"dimensions": {
|
||||
"length": number,
|
||||
"width": number,
|
||||
"height": number,
|
||||
"weight": number
|
||||
"length": "number (meters, required)",
|
||||
"width": "number (meters, required)",
|
||||
"height": "number (meters, required)",
|
||||
"weight": "number (kg, required)"
|
||||
},
|
||||
"capabilities": string[],
|
||||
"maxSpeed": number,
|
||||
"batteryLife": number
|
||||
"capabilities": "string[] (required) - List of robot capabilities",
|
||||
"maxSpeed": "number (m/s, optional)",
|
||||
"batteryLife": "number (hours, optional)"
|
||||
}
|
||||
```
|
||||
|
||||
## ROS2 Configuration
|
||||
### ROS2 Configuration
|
||||
|
||||
```json
|
||||
"ros2Config": {
|
||||
"namespace": string,
|
||||
"nodePrefix": string,
|
||||
"namespace": "string (required) - Default ROS2 namespace",
|
||||
"nodePrefix": "string (required) - Node name prefix",
|
||||
"defaultTopics": {
|
||||
[key: string]: string
|
||||
"[topicName]": "string (topic path) - Default topic mappings"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Actions
|
||||
## Action Definitions
|
||||
|
||||
Each action in the `actions` array follows this structure:
|
||||
Actions define the operations that can be performed with the robot. Each action follows this HRIStudio-specific schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"actionId": string,
|
||||
"type": "move" | "speak" | "wait" | "input" | "gesture" | "record" | "condition" | "loop",
|
||||
"title": string,
|
||||
"description": string,
|
||||
"icon": string?,
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"id": "string (required) - Unique action identifier (snake_case)",
|
||||
"name": "string (required) - Display name for UI",
|
||||
"description": "string (optional) - Action description",
|
||||
"category": "string (enum: movement|interaction|sensors|logic, required)",
|
||||
"icon": "string (optional) - Lucide icon name",
|
||||
"timeout": "number (milliseconds, optional) - Default timeout",
|
||||
"retryable": "boolean (optional) - Whether action can be retried on failure",
|
||||
"parameterSchema": {
|
||||
"type": "object (required)",
|
||||
"properties": {
|
||||
[key: string]: {
|
||||
"type": string,
|
||||
"title": string,
|
||||
"description": string?,
|
||||
"default": any?,
|
||||
"minimum": number?,
|
||||
"maximum": number?,
|
||||
"enum": string[]?,
|
||||
"unit": string?
|
||||
"[paramName]": {
|
||||
"type": "string (JSON Schema type, required)",
|
||||
"minimum": "number (optional) - For numeric types",
|
||||
"maximum": "number (optional) - For numeric types",
|
||||
"default": "any (optional) - Default value",
|
||||
"description": "string (required) - Parameter description",
|
||||
"enum": "string[] (optional) - For enum types"
|
||||
}
|
||||
},
|
||||
"required": string[]
|
||||
"required": "string[] (required) - List of required parameters"
|
||||
},
|
||||
"ros2": {
|
||||
"messageType": string,
|
||||
"topic": string?,
|
||||
"service": string?,
|
||||
"action": string?,
|
||||
"messageType": "string (required) - ROS2 message type",
|
||||
"topic": "string (optional) - Topic name for publishers",
|
||||
"service": "string (optional) - Service name for service calls",
|
||||
"action": "string (optional) - Action name for action calls",
|
||||
"payloadMapping": {
|
||||
"type": "direct" | "transform",
|
||||
"map": object?,
|
||||
"transformFn": string?
|
||||
"type": "string (enum: transform|static, required)",
|
||||
"transformFn": "string (optional) - Transform function name",
|
||||
"payload": "object (optional) - Static payload for static type"
|
||||
},
|
||||
"qos": {
|
||||
"reliability": "reliable" | "best_effort",
|
||||
"durability": "volatile" | "transient_local",
|
||||
"history": "keep_last" | "keep_all",
|
||||
"depth": number?
|
||||
}?
|
||||
"reliability": "string (enum: reliable|best_effort, optional)",
|
||||
"durability": "string (enum: volatile|transient_local, optional)",
|
||||
"history": "string (enum: keep_last|keep_all, optional)",
|
||||
"depth": "number (optional) - Queue depth for keep_last"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## QoS Settings
|
||||
## Action Categories
|
||||
|
||||
When specifying ROS2 QoS settings:
|
||||
HRIStudio organizes actions into these standard categories:
|
||||
|
||||
- `reliability`: Message delivery guarantee
|
||||
- `reliable`: Guaranteed delivery
|
||||
- `best_effort`: Fast but may drop messages
|
||||
- **movement**: Robot locomotion and positioning
|
||||
- **interaction**: Communication and social behaviors
|
||||
- **sensors**: Data collection and environmental sensing
|
||||
- **logic**: Control flow and decision making
|
||||
|
||||
- `durability`: Message persistence
|
||||
- `volatile`: Only delivered to active subscribers
|
||||
- `transient_local`: Stored for late-joining subscribers
|
||||
## Trust Levels
|
||||
|
||||
- `history`: Message queue behavior
|
||||
- `keep_last`: Store up to N messages (specify with depth)
|
||||
- `keep_all`: Store all messages
|
||||
Plugins are classified by trust level:
|
||||
|
||||
## Example
|
||||
- **official**: Maintained by HRIStudio team or robot manufacturer
|
||||
- **verified**: Third-party plugins that have been reviewed and tested
|
||||
- **community**: User-contributed plugins without formal verification
|
||||
|
||||
See the TurtleBot3 Burger plugin for a complete example implementation.
|
||||
## Validation Requirements
|
||||
|
||||
### Required Fields
|
||||
All plugins must include:
|
||||
- Core properties (robotId, name, platform, version)
|
||||
- HRIStudio metadata (pluginApiVersion, hriStudioVersion, trustLevel, category)
|
||||
- At least one action definition
|
||||
- Valid manufacturer information
|
||||
- Asset thumbnailUrl
|
||||
|
||||
### Naming Conventions
|
||||
- `robotId`: lowercase with hyphens (e.g., "turtlebot3-burger")
|
||||
- `action.id`: snake_case (e.g., "move_velocity")
|
||||
- `category`: predefined enum values only
|
||||
|
||||
### Version Requirements
|
||||
- Plugin version must follow semantic versioning (semver)
|
||||
- HRIStudio version must use semver range syntax (e.g., ">=0.1.0")
|
||||
|
||||
## Example Implementation
|
||||
|
||||
See `plugins/turtlebot3-burger.json` for a complete reference implementation demonstrating all schema features and best practices.
|
||||
Reference in New Issue
Block a user