{"id":25953552,"url":"https://github.com/taherfattahi/tars-robot","last_synced_at":"2026-04-11T11:35:17.436Z","repository":{"id":280497635,"uuid":"942192806","full_name":"taherfattahi/tars-robot","owner":"taherfattahi","description":"TARS Robot AI-Agent Data-over-Sound Commands and Bluetooth-Controlled Mecanum Chassis","archived":false,"fork":false,"pushed_at":"2025-03-03T19:30:57.000Z","size":3080,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-03T19:31:06.527Z","etag":null,"topics":["agent","bluetooth","ggwave","langchain","llm","openai","raspberry-pi","robotics"],"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/taherfattahi.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}},"created_at":"2025-03-03T18:11:47.000Z","updated_at":"2025-03-03T19:31:01.000Z","dependencies_parsed_at":"2025-03-03T19:41:24.190Z","dependency_job_id":null,"html_url":"https://github.com/taherfattahi/tars-robot","commit_stats":null,"previous_names":["taherfattahi/tars-robot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/taherfattahi/tars-robot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taherfattahi%2Ftars-robot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taherfattahi%2Ftars-robot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taherfattahi%2Ftars-robot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taherfattahi%2Ftars-robot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/taherfattahi","download_url":"https://codeload.github.com/taherfattahi/tars-robot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taherfattahi%2Ftars-robot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31679480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T08:18:19.405Z","status":"ssl_error","status_checked_at":"2026-04-11T08:17:08.892Z","response_time":54,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["agent","bluetooth","ggwave","langchain","llm","openai","raspberry-pi","robotics"],"created_at":"2025-03-04T15:29:08.594Z","updated_at":"2026-04-11T11:35:17.420Z","avatar_url":"https://github.com/taherfattahi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TARS Robot\n\n**TARS Robot**: AI-Agent Data-over-Sound Commads and Bluetooth-Controlled Mecanum Chassis 🤖\n\n## Demo Video\n[![IMAGE](images/screens.png)](https://youtu.be/kBwK15pydL0)\n\n- **Audio Decoding** via [ggwave](https://github.com/ggerganov/ggwave) to capture and decode sound-based commands.\n- **Natural Language Processing** with [LangChain](https://github.com/langchain-ai/langchain) and OpenAI’s GPT-4 to interpret user commands.\n- **Bluetooth Communication** using [PyBluez](https://github.com/pybluez/pybluez) to send movement instructions.\n- **Mecanum Chassis Control** for precise movement on a robot with mecanum wheels.\n- **Raspberry Pi Hardware** serves as the central processing unit of the robot, handling all computational tasks and coordinating the various systems.\n\n## Project Structure\n\n- **agent.py**  \n  - Listens for audio commands using `pyaudio` and decodes them with `ggwave`.\n  - Processes commands with a LangChain agent that uses a custom tool (`robot_movement`) for parsing movement instructions.\n  - Sends formatted commands to the robot via Bluetooth.\n\n- **tars-robot.py**  \n  - Runs on the robot (or its controlling device), waiting for Bluetooth commands.\n  - Decodes received commands and translates them into movement actions using the HiwonderSDK’s mecanum module.\n  - Supports commands for moving forward/backward and turning.\n\n- **mecanum.py**  \n  - Implements the `MecanumChassis` class to compute motor control signals from polar movement parameters.\n  - Converts velocity, direction, and angular rates into individual motor speeds.\n\n- **board.py**  \n  - Provides low-level functions to control motors, servos, and other hardware components via I2C and GPIO.\n  - Interfaces with the Raspberry Pi hardware and any attached motor controllers.\n\n## Prerequisites\n\n- **Hardware**:\n  - A Raspberry Pi (or similar device) with Bluetooth and audio input support.\n  - A robot chassis equipped with mecanum wheels and compatible motor drivers.\n  - A microphone for audio command capture.\n  \n- **Software**:\n  - [ggwave](https://github.com/ggerganov/ggwave)\n  - [PyAudio](https://people.csail.mit.edu/hubert/pyaudio)\n  - [PyBluez](https://github.com/pybluez/pybluez)\n  - [LangChain](https://github.com/langchain-ai/langchain)\n\n## Installation\n\n1. **Clone the Repository**:\n   ``` bash\n   git clone https://github.com/taherfattahi/tars-robot.git\n   cd tars-robot\n   ```\n\n2. **Install Dependencies:** Install required packages:\n\n    ``` bash\n    sudo apt-get install portaudio19-dev python-pyaudio python3-pyaudio\n    ```\n    ``` bash\n    pip install ggwave pyaudio pybluez langchain langchain_openai\n    ```\n\n3. **Set Up Hardware:**\n    - Ensure your Raspberry Pi is set up with the necessary hardware (microphone, Bluetooth adapter, motor drivers).\n\n## Usage\n1. **Running the Command Processor**\nOn your controller device (e.g., a Raspberry Pi acting as the command center), run the following:\n\n    ```bash\n    python agent.py\n    ```\n    - The script listens for audio commands via the microphone.\n    - It decodes audio using ggwave and processes the command using a LangChain agent.\n    - Processed commands and then sent over Bluetooth to the robot.\n    - Note: You will be prompted to enter your OpenAI API key.\n\n2. **Running the Robot Control Script**\nOn the robot (or its dedicated controller), run:\n\n    ```bash\n    python tars-robot.py\n    ```\n\n    - The script sets up an RFCOMM Bluetooth server and waits for incoming commands.\n    - Upon receiving a command, it decodes the message and uses the mecanum module (via mecanum.py) to execute movement.\n3. **Open the ggwave website and enter your command**\n    - https://waver.ggerganov.com\n\n## Command Examples\nSystem supports natural language commands transmitted via the Waver website, which leverages ggwave's audio data-over-sound capabilities. Audio signals are captured through a microphone, decoded into text by ggwave, and then processed by your LangChain agent before being sent via Bluetooth to the robot.\n\nExample commands: \n  - ```Move the robot forward 25 centimeters and then turn left```\n  - ```Turn right now```\n  - ```Move the robot backward 25 centimeters```\n\n\u003cimg src=\"images/robot.jpg\" width=\"500\"/\u003e\n\n## Resources\n- [ggwave](https://github.com/ggerganov/ggwave) – For the innovative audio data-over-sound library.\n- [PyBluez](https://github.com/pybluez/pybluez) – For enabling Bluetooth communication.\n- [LangChain](https://github.com/langchain-ai/langchain) and [OpenAI](https://platform.openai.com/docs/overview) – For powering natural language command interpretation.\n\n## Contact\nFor questions, feedback, or contributions, please open an issue on GitHub or contact [taherfattahi11@gmail.com](mailto:taherfattahi11@gmail.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaherfattahi%2Ftars-robot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaherfattahi%2Ftars-robot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaherfattahi%2Ftars-robot/lists"}