{"id":19584244,"url":"https://github.com/utiasdsl/upright","last_synced_at":"2025-04-07T12:04:12.847Z","repository":{"id":174759792,"uuid":"360239962","full_name":"utiasDSL/upright","owner":"utiasDSL","description":"[RA-L 2023, 2025] Model predictive control and trajectory optimization for fast nonprehensile object transportation with a mobile manipulator.","archived":false,"fork":false,"pushed_at":"2025-03-11T16:47:00.000Z","size":11881,"stargazers_count":92,"open_issues_count":0,"forks_count":9,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-24T09:03:19.278Z","etag":null,"topics":["control","mobile-manipulation","mpc","planning","robotics"],"latest_commit_sha":null,"homepage":"https://arxiv.org/abs/2305.17484","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/utiasDSL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2021-04-21T16:41:19.000Z","updated_at":"2025-03-22T02:58:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"bc79b809-baa4-4d1f-88f3-2608e60583eb","html_url":"https://github.com/utiasDSL/upright","commit_stats":null,"previous_names":["utiasdsl/upright"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utiasDSL%2Fupright","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utiasDSL%2Fupright/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utiasDSL%2Fupright/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utiasDSL%2Fupright/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/utiasDSL","download_url":"https://codeload.github.com/utiasDSL/upright/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246457965,"owners_count":20780676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["control","mobile-manipulation","mpc","planning","robotics"],"created_at":"2024-11-11T07:47:21.799Z","updated_at":"2025-03-31T11:02:23.299Z","avatar_url":"https://github.com/utiasDSL.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://static.adamheins.com//upright/logo.svg\" alt=\"Robot waiter.\" width=\"15%\"/\u003e\n\u003c/p\u003e\n\nCode for solving the *waiter's problem* with online (MPC) or offline planning on\na mobile manipulator. The waiter's problem refers to moving while keeping\nobjects balanced on a tray-like end effector (like a waiter in a restaurant),\nwhich is an example of *nonprehensile* manipulation.\n\nThe code in this repository accompanies two papers:\n* [Keep It Upright: Model Predictive Control for Nonprehensile Object Transportation With Obstacle Avoidance on a Mobile Manipulator](https://arxiv.org/abs/2305.17484),\n* [Robust Nonprehensile Object Transportation with Uncertain Inertial Parameters](https://arxiv.org/abs/2411.07079).\n\nFull citations can be found [below](#citations).\n\nVideos from the two papers can be found [here](http://tiny.cc/keep-it-upright) and [here](http://tiny.cc/upright-robust).\n\nSome examples include reacting to sudden changes in the environment:\n\n![Sudden obstacle avoidance](https://static.adamheins.com/upright/sudden.gif)\n\nand avoiding dynamic obstacles like thrown balls:\n\n![Dynamic obstacle avoidance](https://static.adamheins.com/upright/dodge.gif)\n\n## Contents\n* `upright_assets`: URDF and mesh files.\n* `upright_core`: Core API for computing motion constraints required to\n  balance objects.\n* `upright_control`: Model predictive controller using the\n  [OCS2](https://github.com/leggedrobotics/ocs2) framework.\n* `upright_cmd`: Configuration and command scripts. Simulations and experiments\n  are run from here, as well as other smaller scripts and tools.\n* `upright_ros_interface`: Tools for ROS communication. These can be useful in\n  simulation for multi-processing, or to support real hardware.\n* `upright_sim`: (PyBullet) simulation environments for balancing objects.\n* `upright_robust`: Robust planning for balancing objects with uncertain inertial parameters. See [here](upright_robust/README.md) for more details.\n\n## Setup and Installation\n\nThe code is designed to run on ROS Noetic under Ubuntu 20.04. For experiments\non real hardware, it is highly recommended to use a real-time system like Linux\nwith the PREEMPT_RT patch.\n\nFirst, follow the instructions to setup the\n[mobile_manipulation_central](https://github.com/utiasDSL/mobile_manipulation_central)\nrepo in your catkin workspace.\n\nNext, clone our custom fork of [OCS2](https://github.com/utiasDSL/ocs2):\n```\ngit clone -b upright https://github.com/utiasDSL/ocs2\n```\nInstall dependencies as listed\n[here](https://leggedrobotics.github.io/ocs2/installation.html).\n\nNow you can clone this repo into the catkin workspace:\n```\ngit clone https://github.com/utiasDSL/upright catkin_ws/src/upright\n```\n\nInstall Python dependencies:\n```\npython3 -m pip install -r catkin_ws/src/upright/requirements.txt\n```\n\nThere are many OCS2 packages that can be skipped. You can use the catkin\n[config.yaml](https://github.com/utiasDSL/mobile_manipulation_central/blob/main/catkin/config/yaml)\nfile; place it under `catkin_ws/.catkin_tools/profiles/default/`.\n\nFinally, build the workspace:\n```\ncatkin build\n```\n\n\n## Simulation Experiments\n\nSimulation scripts are in `upright_cmd/scripts/simulations`. For example, to\nrun a simulation without ROS, do something like:\n```\ncd upright_cmd/scripts/simulations\n./mpc_sim --config \u003cpath to yaml file\u003e\n\n# for example\n# thing_demo.yaml uses the entire mobile manipulator\n# ur10_demo.yaml uses only the arm\n./mpc_sim --config $(rospack find upright_cmd)/config/demos/thing_demo.yaml\n```\nAll experiments, whether simulated or real, are specified by configuration\nfiles in the YAML format, which are stored under `upright_cmd/config`. Configuration parameters are documented [here](docs/configuration.md).\n\nNote that once the simulation is setup (this can take some time when\nre-compiling auto-differentiated libraries), you will be dropped into an\nIPython shell, which should look something like:\n```\nIn [1]:\n```\nThis allows you to inspect any variables of interest. If you just want to start\nexecuting the simulated trajectory, type `exit` and press Enter to exit the\nshell and continue.\n\n## Hardware Experiments\n\nInteraction with hardware is done over ROS via\n[mobile_manipulation_central](https://github.com/utiasDSL/mobile_manipulation_central).\nSo far we have targetted an omnidirectional mobile manipulator consisting of a\nRidgeback mobile base and a UR10 manipulator arm (collectively named the\n\"Thing\"). The general flow of experiments is to connect to the robot, and run\n```\nroslaunch mobile_manipulation_central thing.launch\n```\nThen in another terminal run\n```\nroslaunch upright_ros_interface mpc_mrt.launch config:=\u003cpath to yaml file\u003e\n```\nYou may wish to record the results in a bag file using the\n`upright_cmd/scripts/record.py` script, which is just a wrapper around `rosbag`.\n\n## Tests\n\nSome packages contain tests. Python tests use [pytest](https://pytest.org/).\nRun `pytest .` inside a package's `tests` directory to run the Python tests.\n\n## Citations\n\nIf you find this work useful, feel free to cite (one of) the accompanying\npapers.\n\nThe [original paper](https://doi.org/10.1109/LRA.2023.3324520) on fast MPC for\nthe waiter's problem is:\n```\n@article{heins2023upright,\n  title = {Keep It Upright: Model Predictive Control for Nonprehensile Object Transportation With Obstacle Avoidance on a Mobile Manipulator},\n  author = {Adam Heins and Angela P. Schoellig},\n  journal = {{IEEE Robotics and Automation Letters}},\n  number = {12},\n  volume = {8},\n  pages = {7986--7993},\n  doi = {10.1109/LRA.2023.3324520},\n  year = {2023},\n}\n```\n\nThe [follow-up paper](https://arxiv.org/abs/2411.07079) on robust planning for\nthe waiter's problem under inertial parameter uncertainty:\n```\n@article{heins2025robust,\n  title = {Robust Nonprehensile Object Transportation with Uncertain Inertial Parameters},\n  author = {Adam Heins and Angela P. Schoellig},\n  journal = {{IEEE Robotics and Automation Letters}},\n  number = {5},\n  volume = {10},\n  pages = {4492--4499},\n  doi = {10.1109/LRA.2025.3551067},\n  year = {2025},\n}\n```\n\n## License\n\nMIT (see the LICENSE file).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Futiasdsl%2Fupright","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Futiasdsl%2Fupright","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Futiasdsl%2Fupright/lists"}