{"id":49862826,"url":"https://github.com/ncbdrck/uniros","last_synced_at":"2026-05-14T22:11:02.367Z","repository":{"id":212256903,"uuid":"728595782","full_name":"ncbdrck/UniROS","owner":"ncbdrck","description":"A comprehensive framework for reinforcement learning in robotics, which allows users to train their robots in both simulated and real-world environments. ","archived":false,"fork":false,"pushed_at":"2026-05-14T11:35:04.000Z","size":148,"stargazers_count":110,"open_issues_count":1,"forks_count":11,"subscribers_count":2,"default_branch":"gymnasium","last_synced_at":"2026-05-14T11:37:59.172Z","etag":null,"topics":["gym","gymnasium","gymnasium-robotics","multiros","realros","reinforcement-learning-environments","robotics","ros","uniros"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ncbdrck.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-12-07T09:27:33.000Z","updated_at":"2026-05-14T11:35:10.000Z","dependencies_parsed_at":"2023-12-19T01:52:46.457Z","dependency_job_id":"612f73f5-650b-4a13-a500-d6a3bacab5d8","html_url":"https://github.com/ncbdrck/UniROS","commit_stats":{"total_commits":20,"total_committers":1,"mean_commits":20.0,"dds":0.0,"last_synced_commit":"fb94327b327259d7d0f33957700699e0bd3519d2"},"previous_names":["ncbdrck/uniros"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/ncbdrck/UniROS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncbdrck%2FUniROS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncbdrck%2FUniROS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncbdrck%2FUniROS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncbdrck%2FUniROS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ncbdrck","download_url":"https://codeload.github.com/ncbdrck/UniROS/tar.gz/refs/heads/gymnasium","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncbdrck%2FUniROS/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33045216,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gym","gymnasium","gymnasium-robotics","multiros","realros","reinforcement-learning-environments","robotics","ros","uniros"],"created_at":"2026-05-14T22:11:01.739Z","updated_at":"2026-05-14T22:11:02.360Z","avatar_url":"https://github.com/ncbdrck.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# UniROS: ROS-Based Reinforcement Learning Across Simulated and Real-world Robotics\n\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Documentation Status](https://readthedocs.org/projects/uniros/badge/?version=latest)](https://uniros.readthedocs.io/en/latest/?badge=latest)\n\n📚 **Full documentation**: [uniros.readthedocs.io](https://uniros.readthedocs.io/)\n\nA comprehensive framework for reinforcement learning in robotics,\nwhich allows users to train their robots in both simulated and real-world environments concurrently.\nIt simplifies the process of creating reinforcement learning environments for robots\nand provides a unified interface for training\nand evaluating the robots in both simulated and real-world environments.\n\n## Overview\nThis repository, UniROS, is designed to integrate two separate repositories, [MultiROS](https://github.com/ncbdrck/multiros) and [RealROS](https://github.com/ncbdrck/realros), giving users the flexibility to use them either as standalone modules or as integrated parts of UniROS.\n\n## Options for Setup\nThere are two ways to set up this repository:\n\n1. **As an Integrated System (with Submodules):** Use this option if you do not have [MultiROS](https://github.com/ncbdrck/multiros) and [RealROS](https://github.com/ncbdrck/realros) already set up. UniROS will include both as submodules.\n\n2. **Using Existing MultiROS and RealROS:** Choose this if you already have these repositories cloned and set up independently. \n\n## Pre-Setup: Check Existing Repositories\nBefore proceeding with the setup, determine if you already have multiros and realros on your system. The [check_repos.sh](#script-check_repossh) snippet below this README does that automatically — copy its contents into a file called `check_repos.sh` in your home directory (or anywhere on `$PATH`), make it executable (`chmod +x check_repos.sh`), then run it:\n\n```bash\n./check_repos.sh\n```\n\nIf the script finds the repositories, follow the instructions for using existing repositories. If not, proceed with the integrated system setup.\n\n## 1. Setup as an Integrated System\nIf you do not have `MultiROS` and `RealROS`, or you wish to use them as submodules of `UniROS`, follow these steps:\n\n```bash\ncd ~/catkin_ws/src\ngit clone --recurse-submodules -b gymnasium https://github.com/ncbdrck/uniros\n\n# update the submodules to the latest version\ncd uniros\ngit checkout gymnasium\ngit submodule update --remote --recursive\n\n# Install pip if you haven't already by running this command\nsudo apt-get install python3-pip\n\n# install the required Python packages for UniROS by running\ncd ~/catkin_ws/src/uniros/uniros/\npip3 install -r requirements.txt\n\n# set the branch of the submodules to gymnasium\ncd ~/catkin_ws/src/uniros/multiros\ngit checkout gymnasium\ngit pull\ncd ~/catkin_ws/src/uniros/realros\ngit checkout gymnasium\ngit pull\n\n# before building the workspace, install the dependencies for MultiROS and RealROS\n# You can find the dependencies in the respective repositories\n# Not installing the dependencies may cause build errors\n\n# build the workspace\ncd ~/catkin_ws\nrosdep install --from-paths src --ignore-src -r -y\ncatkin build\nsource devel/setup.bash\n```\n\n**Note:** MultiROS and RealROS have their own dependencies. Please follow the instructions in their respective repositories to install the dependencies.\n\n## 2. Setup Using Existing MultiROS and RealROS\nIf you have existing clones of `multiros` and `realros`, follow these instructions:\n\n```bash\ncd ~/catkin_ws/src\ngit clone -b gymnasium  https://github.com/ncbdrck/uniros\n\n# continue with the installation as above\n```\n**Note:** Make sure that the branches of `multiros` and `realros` are set to `gymnasium`. If not, you can switch to the `gymnasium` branch by running the following commands:\n\n```bash\ncd ~/catkin_ws/src/multiros  # or the path to your multiros repository\ngit checkout gymnasium  # switch to the gymnasium branch\ngit pull  # to update the repository\n\ncd ~/catkin_ws/src/realros  # or the path to your realros repository\ngit checkout gymnasium  # switch to the gymnasium branch\ngit pull  # to update the repository\n```\n\n\n## Usage\n\n- Once you have set up UniROS, which includes MultiROS and RealROS, you can use each package to create reinforcement learning environments for your robots. \n- You can follow the instructions in the respective repositories to create your own environments. Use the provided [examples](https://github.com/ncbdrck/uniros_support_materials) as a starting point.\n- Then, register the created environment with gymnasium.  \n\n    ```python\n    # gymnasium registration - example\n    from gymnasium.envs.registration import register\n    \n    register(\n         id='MyEnv-v0',\n         entry_point='multiros.templates.task_envs.MyTaskEnv:MyEnv',\n         max_episode_steps=1000,\n    )\n    ```\n- Finally instead of using `import gymnasium as gym` and then `gym.make('MyEnv-v0')` use the following to create the environment. This will create **separate processes** for each environment, making it possible to run multiple environments in parallel.\n    ```python\n    # for both simulated and real environments\n    import uniros as gym\n    env = gym.make('MyEnv-v0')\n    ```\n\n## Script: `check_repos.sh`\nBelow is the `check_repos.sh` script. Save it in your `home` directory and run it to check if `multiros` and `realros` are already downloaded.\n\n```bash\n#!/bin/bash\n\n# Function to check if a directory is a Git repository\nis_git_repo() {\n    if git -C \"$1\" rev-parse 2\u003e/dev/null; then\n        return 0\n    else\n        return 1\n    fi\n}\n\n# Directories where multiros and realros might exist.\n# Adjust these to match your workspace.\nMULTIROS_DIR=\"$HOME/catkin_ws/src/multiros\"\nREALROS_DIR=\"$HOME/catkin_ws/src/realros\"\n\n# Check multiros\nif [ -d \"$MULTIROS_DIR\" ] \u0026\u0026 is_git_repo \"$MULTIROS_DIR\"; then\n    echo \"multiros repository found at $MULTIROS_DIR\"\nelse\n    echo \"multiros repository not found (looked in $MULTIROS_DIR)\"\nfi\n\n# Check realros\nif [ -d \"$REALROS_DIR\" ] \u0026\u0026 is_git_repo \"$REALROS_DIR\"; then\n    echo \"realros repository found at $REALROS_DIR\"\nelse\n    echo \"realros repository not found (looked in $REALROS_DIR)\"\nfi\n```\n\nUpdate `MULTIROS_DIR` and `REALROS_DIR` to match where these repositories live in your workspace. The typical layout for a ROS catkin workspace is `~/\u003cworkspace_name\u003e_ws/src/\u003crepo_name\u003e/`.\n\n## Documentation\n\nThe full ecosystem documentation — installation, ready-made\nenvironments, environment creation (sim and real), training with\nany gymnasium-compatible framework, joint sim+real training, and\nthe API reference — lives at\n[uniros.readthedocs.io](https://uniros.readthedocs.io/).\n\n(Contributors who want to build the docs locally: see\n[docs/guides/contributing](https://uniros.readthedocs.io/en/latest/guides/contributing.html#development-setup).)\n\n## Cite\n\nIf you use UniROS in your research or work and would like to cite it, please cite the journal paper:\n\n```bibtex\n@article{kapukotuwa_uniros_2025,\n\ttitle = {{UniROS}: {ROS}-{Based} {Reinforcement} {Learning} Across {Simulated} and {Real}-{World} {Robotics}},\n\tshorttitle = {{UniROS}},\n\tdoi = {10.3390/s25185679},\n\tjournal = {Sensors},\n\tauthor = {Kapukotuwa, Jayasekara and Lee, Brian and Devine, Declan and Qiao, Yuansong},\n\tvolume = {25},\n\tnumber = {18},\n\tmonth = sep,\n\tyear = {2025},\n\tpages = {5679},\n\tpublisher = {{MDPI}},\n\turl = {https://www.mdpi.com/1424-8220/25/18/5679},\n}\n```\nThe earlier conference paper on the MultiROS sub-package:\n\n```bibtex\n@inproceedings{kapukotuwa_multiros_2022,\n\ttitle = {{MultiROS}: {ROS}-{Based} {Robot} {Simulation} {Environment} for {Concurrent} {Deep} {Reinforcement} {Learning}},\n\tshorttitle = {{MultiROS}},\n\tdoi = {10.1109/CASE49997.2022.9926475},\n\tbooktitle = {2022 {IEEE} 18th {International} {Conference} on {Automation} {Science} and {Engineering} ({CASE})},\n\tauthor = {Kapukotuwa, Jayasekara and Lee, Brian and Devine, Declan and Qiao, Yuansong},\n\tmonth = aug,\n\tyear = {2022},\n\tnote = {ISSN: 2161-8089},\n\tpages = {1098--1103},\n}\n```\n\nRepository:\n\n```bibtex\n@misc{uniros,\n  author = {Kapukotuwa, Jayasekara},\n  booktitle = {GitHub repository},\n  publisher = {GitHub},\n  title = {UniROS: ROS-Based Reinforcement Learning Across Simulated and Real-world Robotics},\n  url = {https://github.com/ncbdrck/uniros},\n  year = {2023}\n}\n```\n\n## Contact\n\nFor questions, suggestions, or collaborations, feel free to reach out to the project maintainer at [j.kapukotuwa@research.ait.ie](mailto:j.kapukotuwa@research.ait.ie).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncbdrck%2Funiros","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fncbdrck%2Funiros","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncbdrck%2Funiros/lists"}