{"id":16689234,"url":"https://github.com/sskorol/minipupper-teleop","last_synced_at":"2025-04-10T00:44:30.940Z","repository":{"id":55109125,"uuid":"522347482","full_name":"sskorol/minipupper-teleop","owner":"sskorol","description":"MiniPupper robot teleoperation via ROS and WebRTC","archived":false,"fork":false,"pushed_at":"2023-09-15T22:55:00.000Z","size":11336,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-10T00:44:24.896Z","etag":null,"topics":["champ","depthai","docker","docker-compose","fastapi","minipupper","mobx","mui","noetic","oak-d","pydantic","reactjs","robotics","ros","rosbridge","roslibjs","streaming","teleop","teleoperation","webrtc"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/sskorol.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}},"created_at":"2022-08-07T23:23:55.000Z","updated_at":"2024-06-17T08:20:26.000Z","dependencies_parsed_at":"2023-01-18T22:31:12.631Z","dependency_job_id":null,"html_url":"https://github.com/sskorol/minipupper-teleop","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sskorol%2Fminipupper-teleop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sskorol%2Fminipupper-teleop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sskorol%2Fminipupper-teleop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sskorol%2Fminipupper-teleop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sskorol","download_url":"https://codeload.github.com/sskorol/minipupper-teleop/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137997,"owners_count":21053775,"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":["champ","depthai","docker","docker-compose","fastapi","minipupper","mobx","mui","noetic","oak-d","pydantic","reactjs","robotics","ros","rosbridge","roslibjs","streaming","teleop","teleoperation","webrtc"],"created_at":"2024-10-12T15:47:36.948Z","updated_at":"2025-04-10T00:44:30.920Z","avatar_url":"https://github.com/sskorol.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## MiniPupper Teleop\n\n![Build Status](https://github.com/sskorol/minipupper-teleop/actions/workflows/main.yml/badge.svg?branch=main)\n\nThis project allows streaming video from [MiniPupper](https://minipupperdocs.readthedocs.io/en/latest/) via WebRTC and teleoperating it via ROS. Note that the [backend](https://github.com/sskorol/minipupper-teleop/tree/main/backend) expects you've already connected [OAK-D Lite](https://shop.luxonis.com/products/oak-d-lite-1) camera to your robot. If you don't have one yet, you can still teleoperate the robot via keyboard, but w/o a camera stream. Also, note that technically you are not forced to use this project with MiniPupper only. It should work for any robot with OAK camera.\n\n\u003cdiv\u003e\u003cvideo src='https://user-images.githubusercontent.com/6638780/184704954-94f721f5-6219-48b2-9696-3da01e509eec.mp4'\u003e\u003c/div\u003e\n\n- [MiniPupper Teleop](#minipupper-teleop)\n  - [Architecture](#architecture)\n  - [Installation](#installation)\n  - [Running on MiniPupper](#running-on-minipupper)\n  - [Simulated Environment](#running-in-simulated-environment)\n  - [Building FE and BE](#building-fe-and-be)\n  - [Known Issues](#known-issues)\n  - [ToDo](#todo)\n\n### Architecture\n\nThe following diagram reflects the most recent implementation:\n\n![RoboticsDiagram](https://user-images.githubusercontent.com/6638780/184701436-863ccb48-9bcd-44c4-ba8f-c6ebf35d10d9.png)\n\n- **roscore**: a master node that handles all the ROS requests;\n- **rosbridge**: WS proxy between FE and ROS that accepts messages (keys) from the remote browser and passes them to ROS nodes;\n- **webrtc-be**: Python BE, which streams OAK-D Lite camera video to the remote browser via WebRTC (internally uses [DepthAI](https://docs.luxonis.com/projects/api/en/latest/index.html) API);\n- **teleop-fe**: ReactJS FE which uses [roslibjs](https://github.com/RobotWebTools/roslibjs) to communicate with ROS bridge and WebRTC API for camera streaming;\n- **servo-drv**: MiniPupper's servo driver node, which listens to CHAMP messages and changes joints' angles;\n- **CHAMP/vel-smoother**: [CHAMP](https://github.com/chvmp/champ) framework controls the robot's movements;\n- **teleop**: a slightly modified [teleop-legged-robots](https://github.com/SoftServeSAG/teleop_legged_robots) node that accepts remote keys rather than local keyboard events.\n\nNote that `velocity-smoother` was intentionally splitted from `champ` due to netwroking issue mentioned in a [known issues](#known-issues) section.\n\n### Installation\n\nThe following [ROS image](https://drive.google.com/file/d/1Mk_bSmIvnN8EIzB8IilS9M4pofTUH9r2/view?usp=sharing) already comes with all the required drivers pre-installed. Just flash it to SD card and you are almost ready to go.\n\nCheck the [official guide](https://docs.docker.com/engine/install/ubuntu/) if you don't have Docker yet. Note that you need both `docker` and `docker-compose` CLI tools installed on MiniPupper.\n\nClone the source code:\n\n```shell\ngit clone https://github.com/sskorol/minipupper-teleop.git \u0026\u0026 cd minipupper-teleop\n```\n\nPrepare calibration and env files:\n\n```shell\n./generate_configs.sh [MINI_PUPPER_IP_ADDRESS]\n```\n\nAdjust angles in `calibration_settings.yaml` to match your own robot's calibration data. Note that MiniPupper's legs should be calibrated to 90 degress as on the following screenshot, as CHAMP framework automatically adjusts angles during bringup process to make your robot stand:\n\n![image](https://user-images.githubusercontent.com/6638780/183618832-c133ddef-484c-4974-b6e9-04f7e1d81e6e.png)\n\nMiniPupper's IP is required for the FE container to be able to communicate with the BE via remote browser.\n\nUse the following steps to relax your web-browser restrictions:\n\n- Open Chrome\n- Type `chrome://flags/` in the address bar and hit Enter\n- Enable `Insecure origins treated as secure` option, and type the IP address of your MiniPupper\n- Restart Chrome\n\n### Running on MiniPupper\n\nRun the following command to start a stack of docker images required to perform teleoperation:\n\n```shell\ndocker compose pull \u0026\u0026 docker compose up -d\n```\n\nAn old docker cli uses a bit different syntax: `docker-compose up -d`.\n\nOpen your web browser and go to: `http://[MINI_PUPPER_IP_ADDRESS]`\n\n### Running in simulated environment\n\nIf you don't have a robot yet, you can still play with teleoperation locally in a simulated environment.\n\n\u003cvideo src='https://user-images.githubusercontent.com/6638780/184727365-927b5755-99b4-4098-9010-52444ad33856.mp4'\u003e\u003c/video\u003e\n\n```shell\n# Required for running Gazebo in container\nxhost +local:docker\n# Download images\ndocker compose -f docker-compose-sim.yaml pull\n# Run services required for simulation\ndocker compose -f docker-compose-sim.yaml up -d\n```\n\nThen open your web-browser on a localhost, wait until teleop is ready, and you're good to go.\n\n### Building FE and BE\n\nRun the following command on MiniPupper to build FE and BE images:\n\n```shell\ndocker compose build\n```\n\n### Local deployment\n\nInstall backend dependencies:\n```shell\ncd ./backend \u0026\u0026 python3 venv .venv\nsource .venv/bin/activate \u0026\u0026 pip3 install pip --upgrade \u0026\u0026 pip3 install -r requirements.txt\n```\n\nStart backend:\n```shell\n./run.sh\n```\n\nInstall frontend dependencies:\n```shell\ncd ../frontend \u0026\u0026 npm install\n```\n\nPrepare `.env` with required environment variables:\n```shell\ncp .env.example .env\n```\n\nHere are sample values:\n```properties\nREACT_APP_ROSBRIDGE_SERVER_IP=localhost\nREACT_APP_ROSBRIDGE_SERVER_PORT=9090\nREACT_APP_RECONNECTION_TIMER=1000\nREACT_APP_BE_URL=http://localhost:8080\nREACT_APP_IS_SIMULATION=true\n```\n\nStart frontend:\n```shell\nnpm run start\n```\n\nGo to [http://localhost:3000](http://localhost:3000) to see the web UI.\n\nNote that frontend and backend depend on the ROS bridge and a custom teleop node. Make sure you've started them beforehand.\n\n### Known issues\n\nIn rare cases `teleop`, `smoother` and `servo` nodes can't correctly publish/subscribe to `/cmd_vel` topic due to registration failure. The current workaround is displayed on the following diagram.\n\nYou can try to restart docker images to see if it helps. I couldn't yet found the root cause of these Docker \u003c---\u003e ROS networking issues. Feel free to contact [author](mailto:serhii.s.korol@gmail.com) if you have any idea on how to stabilize it.\n\nRun the following command on MiniPupper to diagnose potential errors in logs:\n\n```shell\ndocker compose logs -f\n```\n\n### ToDo\n\n- [x] Polish FE code\n- [ ] Polish BE code\n- [x] Add local deployment instructions\n- [ ] Add docker-cross builds\n- [ ] Push teleop and mini-pupper core sources\n- [ ] Migrate to ROS2\n- [ ] Get rid of velocity-smoother, which seems to cause most networking issues\n- [ ] Add map for SLAM and navigation\n- [ ] Potentially integrate this code into MiniPupper repo\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsskorol%2Fminipupper-teleop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsskorol%2Fminipupper-teleop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsskorol%2Fminipupper-teleop/lists"}