From b264901f34ed6281c6b2b524e50941ec44bd13bf Mon Sep 17 00:00:00 2001 From: Sean O'Connor Date: Wed, 12 Feb 2025 13:45:20 -0500 Subject: [PATCH] first commit --- LICENSE | 21 +++ README.md | 55 ++++++ .../turtlebot3-burger-dimensions.png | 7 + .../turtlebot3-burger-front.png | 7 + .../turtlebot3-burger-main.png | 7 + .../turtlebot3-burger-side.png | 7 + .../turtlebot3-burger-thumb.png | 7 + .../turtlebot3-burger-top.png | 7 + docs/schema.md | 174 ++++++++++++++++++ plugins/index.json | 1 + plugins/turtlebot3-burger.json | 156 ++++++++++++++++ repository.json | 24 +++ 12 files changed, 473 insertions(+) create mode 100644 LICENSE create mode 100644 README.md create mode 100644 assets/turtlebot3-burger/turtlebot3-burger-dimensions.png create mode 100644 assets/turtlebot3-burger/turtlebot3-burger-front.png create mode 100644 assets/turtlebot3-burger/turtlebot3-burger-main.png create mode 100644 assets/turtlebot3-burger/turtlebot3-burger-side.png create mode 100644 assets/turtlebot3-burger/turtlebot3-burger-thumb.png create mode 100644 assets/turtlebot3-burger/turtlebot3-burger-top.png create mode 100644 docs/schema.md create mode 100644 plugins/index.json create mode 100644 plugins/turtlebot3-burger.json create mode 100644 repository.json diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..5eef3ff --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 HRIStudio Contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..40f6867 --- /dev/null +++ b/README.md @@ -0,0 +1,55 @@ +# HRIStudio Robot Plugins + +This repository contains robot plugins for use with HRIStudio, a platform for designing and executing human-robot interaction experiments. + +## Repository Structure + +``` +robot-plugins/ +├── plugins/ # Robot plugin definitions (JSON) +├── assets/ # Robot images and 3D models +│ └── {robotId}/ # Assets for each robot +└── docs/ # Plugin documentation +``` + +## Adding a New Robot Plugin + +1. Create a new JSON file in the `plugins` directory with your robot's plugin definition +2. Add required assets to the `assets/{robotId}` directory +3. Update documentation if needed +4. Submit a pull request + +## Required Files + +For each robot plugin, you need: + +### Plugin Definition +- `plugins/{robotId}.json` - Plugin configuration file + +### Assets +- `assets/{robotId}/thumb.png` - Thumbnail image (160x160px) +- `assets/{robotId}/main.png` - Main image (16:9 aspect ratio) +- `assets/{robotId}/dimensions.png` - Technical drawing (optional) +- Additional views (optional): + - `assets/{robotId}/front.png` + - `assets/{robotId}/side.png` + - `assets/{robotId}/top.png` + +## Plugin Schema + +See [docs/schema.md](docs/schema.md) for the complete plugin schema documentation. + +## Example Plugin + +See the TurtleBot3 Burger plugin (`plugins/turtlebot3-burger.json`) for a complete example. + +## Contributing + +1. Fork this repository +2. Create your plugin following the structure above +3. Test your plugin with HRIStudio +4. Submit a pull request + +## License + +MIT License - See LICENSE file for details \ No newline at end of file diff --git a/assets/turtlebot3-burger/turtlebot3-burger-dimensions.png b/assets/turtlebot3-burger/turtlebot3-burger-dimensions.png new file mode 100644 index 0000000..dbfda7d --- /dev/null +++ b/assets/turtlebot3-burger/turtlebot3-burger-dimensions.png @@ -0,0 +1,7 @@ + + + + + Image Coming Soon + TurtleBot3 Burger + \ No newline at end of file diff --git a/assets/turtlebot3-burger/turtlebot3-burger-front.png b/assets/turtlebot3-burger/turtlebot3-burger-front.png new file mode 100644 index 0000000..dbfda7d --- /dev/null +++ b/assets/turtlebot3-burger/turtlebot3-burger-front.png @@ -0,0 +1,7 @@ + + + + + Image Coming Soon + TurtleBot3 Burger + \ No newline at end of file diff --git a/assets/turtlebot3-burger/turtlebot3-burger-main.png b/assets/turtlebot3-burger/turtlebot3-burger-main.png new file mode 100644 index 0000000..dbfda7d --- /dev/null +++ b/assets/turtlebot3-burger/turtlebot3-burger-main.png @@ -0,0 +1,7 @@ + + + + + Image Coming Soon + TurtleBot3 Burger + \ No newline at end of file diff --git a/assets/turtlebot3-burger/turtlebot3-burger-side.png b/assets/turtlebot3-burger/turtlebot3-burger-side.png new file mode 100644 index 0000000..dbfda7d --- /dev/null +++ b/assets/turtlebot3-burger/turtlebot3-burger-side.png @@ -0,0 +1,7 @@ + + + + + Image Coming Soon + TurtleBot3 Burger + \ No newline at end of file diff --git a/assets/turtlebot3-burger/turtlebot3-burger-thumb.png b/assets/turtlebot3-burger/turtlebot3-burger-thumb.png new file mode 100644 index 0000000..dbfda7d --- /dev/null +++ b/assets/turtlebot3-burger/turtlebot3-burger-thumb.png @@ -0,0 +1,7 @@ + + + + + Image Coming Soon + TurtleBot3 Burger + \ No newline at end of file diff --git a/assets/turtlebot3-burger/turtlebot3-burger-top.png b/assets/turtlebot3-burger/turtlebot3-burger-top.png new file mode 100644 index 0000000..dbfda7d --- /dev/null +++ b/assets/turtlebot3-burger/turtlebot3-burger-top.png @@ -0,0 +1,7 @@ + + + + + Image Coming Soon + TurtleBot3 Burger + \ No newline at end of file diff --git a/docs/schema.md b/docs/schema.md new file mode 100644 index 0000000..4193c96 --- /dev/null +++ b/docs/schema.md @@ -0,0 +1,174 @@ +# Plugin Schema Documentation + +This document describes the schema for HRIStudio robot plugins. + +## Overview + +Each plugin is defined in a JSON file with the following top-level structure: + +```json +{ + "robotId": string, + "name": string, + "description": string?, + "platform": string, + "version": string, + "manufacturer": object, + "documentation": object, + "assets": object, + "specs": object, + "ros2Config": object, + "actions": array +} +``` + +## 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 + +```json +"manufacturer": { + "name": string, + "website": string (URL), + "support": string (URL)? +} +``` + +## Documentation Links + +```json +"documentation": { + "mainUrl": string (URL), + "apiReference": string (URL)?, + "wikiUrl": string (URL)?, + "videoUrl": string (URL)? +} +``` + +## Assets Configuration + +```json +"assets": { + "thumbnailUrl": string, + "images": { + "main": string, + "angles": { + "front": string?, + "side": string?, + "top": string? + }, + "dimensions": string? + }, + "model": { + "format": "URDF" | "glTF" | "other", + "url": string (URL) + }? +} +``` + +## Robot Specifications + +```json +"specs": { + "dimensions": { + "length": number, + "width": number, + "height": number, + "weight": number + }, + "capabilities": string[], + "maxSpeed": number, + "batteryLife": number, + "payload": number? +} +``` + +## ROS2 Configuration + +```json +"ros2Config": { + "namespace": string, + "nodePrefix": string, + "defaultTopics": { + [key: string]: string + } +} +``` + +## Actions + +Each action in the `actions` array follows this structure: + +```json +{ + "actionId": string, + "type": "move" | "speak" | "wait" | "input" | "gesture" | "record" | "condition" | "loop", + "title": string, + "description": string, + "icon": string?, + "parameters": { + "type": "object", + "properties": { + [key: string]: { + "type": string, + "title": string, + "description": string?, + "default": any?, + "minimum": number?, + "maximum": number?, + "enum": string[]?, + "unit": string? + } + }, + "required": string[] + }, + "ros2": { + "messageType": string, + "topic": string?, + "service": string?, + "action": string?, + "payloadMapping": { + "type": "direct" | "transform", + "map": object?, + "transformFn": string? + }, + "qos": { + "reliability": "reliable" | "best_effort", + "durability": "volatile" | "transient_local", + "history": "keep_last" | "keep_all", + "depth": number? + }? + } +} +``` + +## QoS Settings + +When specifying ROS2 QoS settings: + +- `reliability`: Message delivery guarantee + - `reliable`: Guaranteed delivery + - `best_effort`: Fast but may drop messages + +- `durability`: Message persistence + - `volatile`: Only delivered to active subscribers + - `transient_local`: Stored for late-joining subscribers + +- `history`: Message queue behavior + - `keep_last`: Store up to N messages (specify with depth) + - `keep_all`: Store all messages + +## Example + +See the TurtleBot3 Burger plugin for a complete example implementation. \ No newline at end of file diff --git a/plugins/index.json b/plugins/index.json new file mode 100644 index 0000000..0519ecb --- /dev/null +++ b/plugins/index.json @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/plugins/turtlebot3-burger.json b/plugins/turtlebot3-burger.json new file mode 100644 index 0000000..02fc61f --- /dev/null +++ b/plugins/turtlebot3-burger.json @@ -0,0 +1,156 @@ +{ + "robotId": "turtlebot3-burger", + "name": "TurtleBot3 Burger", + "description": "A compact, affordable, programmable, ROS2-based mobile robot for education and research", + "platform": "ROS2", + "version": "2.0.0", + + "manufacturer": { + "name": "ROBOTIS", + "website": "https://www.robotis.com/", + "support": "https://emanual.robotis.com/docs/en/platform/turtlebot3/overview/" + }, + + "documentation": { + "mainUrl": "https://emanual.robotis.com/docs/en/platform/turtlebot3/overview/", + "apiReference": "https://emanual.robotis.com/docs/en/platform/turtlebot3/ros2_manipulation/", + "wikiUrl": "https://wiki.ros.org/turtlebot3", + "videoUrl": "https://www.youtube.com/watch?v=rVM994ZhsEM" + }, + + "assets": { + "thumbnailUrl": "assets/turtlebot3-burger/thumb.png", + "images": { + "main": "assets/turtlebot3-burger/main.png", + "angles": { + "front": "assets/turtlebot3-burger/front.png", + "side": "assets/turtlebot3-burger/side.png", + "top": "assets/turtlebot3-burger/top.png" + }, + "dimensions": "assets/turtlebot3-burger/dimensions.png" + }, + "model": { + "format": "URDF", + "url": "https://raw.githubusercontent.com/ROBOTIS-GIT/turtlebot3/master/turtlebot3_description/urdf/turtlebot3_burger.urdf" + } + }, + + "specs": { + "dimensions": { + "length": 0.138, + "width": 0.178, + "height": 0.192, + "weight": 1.0 + }, + "capabilities": [ + "differential_drive", + "lidar", + "imu", + "odometry" + ], + "maxSpeed": 0.22, + "batteryLife": 2.5 + }, + + "ros2Config": { + "namespace": "turtlebot3", + "nodePrefix": "hri_studio", + "defaultTopics": { + "cmd_vel": "/cmd_vel", + "odom": "/odom", + "scan": "/scan", + "imu": "/imu", + "joint_states": "/joint_states" + } + }, + + "actions": [ + { + "actionId": "move-velocity", + "type": "move", + "title": "Set Velocity", + "description": "Control the robot's linear and angular velocity", + "icon": "navigation", + "parameters": { + "type": "object", + "properties": { + "linear": { + "type": "number", + "title": "Linear Velocity", + "description": "Forward/backward velocity", + "default": 0, + "minimum": -0.22, + "maximum": 0.22, + "unit": "m/s" + }, + "angular": { + "type": "number", + "title": "Angular Velocity", + "description": "Rotational velocity", + "default": 0, + "minimum": -2.84, + "maximum": 2.84, + "unit": "rad/s" + } + }, + "required": ["linear", "angular"] + }, + "ros2": { + "messageType": "geometry_msgs/msg/Twist", + "topic": "/cmd_vel", + "payloadMapping": { + "type": "transform", + "transformFn": "transformToTwist" + }, + "qos": { + "reliability": "reliable", + "durability": "volatile", + "history": "keep_last", + "depth": 1 + } + } + }, + { + "actionId": "move-to-pose", + "type": "move", + "title": "Move to Position", + "description": "Navigate to a specific position on the map", + "icon": "target", + "parameters": { + "type": "object", + "properties": { + "x": { + "type": "number", + "title": "X Position", + "description": "X coordinate in meters", + "default": 0, + "unit": "m" + }, + "y": { + "type": "number", + "title": "Y Position", + "description": "Y coordinate in meters", + "default": 0, + "unit": "m" + }, + "theta": { + "type": "number", + "title": "Orientation", + "description": "Final orientation", + "default": 0, + "unit": "rad" + } + }, + "required": ["x", "y", "theta"] + }, + "ros2": { + "messageType": "geometry_msgs/msg/PoseStamped", + "action": "/navigate_to_pose", + "payloadMapping": { + "type": "transform", + "transformFn": "transformToPoseStamped" + } + } + } + ] +} \ No newline at end of file diff --git a/repository.json b/repository.json new file mode 100644 index 0000000..69e9d34 --- /dev/null +++ b/repository.json @@ -0,0 +1,24 @@ +{ + "id": "hristudio-official", + "name": "HRIStudio Official Robot Plugins", + "description": "Official collection of robot plugins maintained by the HRIStudio team", + "url": "https://github.com/soconnor0919/robot-plugins", + "official": true, + "author": { + "name": "HRIStudio Team", + "email": "team@hristudio.org", + "url": "https://hristudio.org", + "organization": "HRIStudio" + }, + "maintainers": [ + { + "name": "Sean O'Connor", + "url": "https://github.com/soconnor0919" + } + ], + "homepage": "https://hristudio.org/plugins", + "license": "MIT", + "defaultBranch": "main", + "lastUpdated": "2024-02-12T00:00:00Z", + "trust": "official" +} \ No newline at end of file