{"id":27445858,"url":"https://github.com/thomasonzhou/parallel_manipulator","last_synced_at":"2026-02-09T21:35:28.339Z","repository":{"id":269386141,"uuid":"855993497","full_name":"thomasonzhou/parallel_manipulator","owner":"thomasonzhou","description":"ball balancing robot with camera feedback","archived":false,"fork":false,"pushed_at":"2024-12-28T04:13:46.000Z","size":2349,"stargazers_count":3,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-28T15:11:21.286Z","etag":null,"topics":["computer-vision","pid-control","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/thomasonzhou.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":"2024-09-11T19:54:04.000Z","updated_at":"2025-03-11T15:25:50.000Z","dependencies_parsed_at":"2024-12-23T08:19:05.564Z","dependency_job_id":"6f0955c4-0e78-4f04-82a6-561df832c3ad","html_url":"https://github.com/thomasonzhou/parallel_manipulator","commit_stats":null,"previous_names":["thomasonzhou/ball-balancing-software","thomasonzhou/parallel_manipulator"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomasonzhou%2Fparallel_manipulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomasonzhou%2Fparallel_manipulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomasonzhou%2Fparallel_manipulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomasonzhou%2Fparallel_manipulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thomasonzhou","download_url":"https://codeload.github.com/thomasonzhou/parallel_manipulator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249001276,"owners_count":21196346,"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":["computer-vision","pid-control","robotics"],"created_at":"2025-04-15T03:30:19.490Z","updated_at":"2026-02-09T21:35:28.250Z","avatar_url":"https://github.com/thomasonzhou.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ball Balancing Robot\n\nMoving a ball along trajectories using computer vision, PID control, inverse kinematics, and three stepper motors.\n\nhttps://github.com/user-attachments/assets/f4a4e480-b639-42fb-8478-f429e09720b2\n\n\n# Architecture\n\n| **Package**           | **Input**                         | **Details**                                      | **Output**                                  |\n|-|-|-|-|\n| **computer_vision** | camera frames (USB) | compute ball position using Circle Hough Transform | ball (x, y) in global frame|\n| **trajectory_planner** | ball (x, y) | stores and updates target waypoints | current target position |\n| **pid** | ball (x, y) and target (x, y) | calculates tilt adjustments to minimize positional, accumulated, velocity errors  | direction and angle of platform tilt |\n| **inverse_kinematics** | direction and angle of platform tilt | convert tilt target to stepper motor angles | angle for each stepper motor |\n| **py2motor** | 3 stepper motor angles | communicate with stepper driver over serial | instructions encoded with custom protocol |\n| **core** | static config specifying trajectory and controller params |integration of modules, sanity checks between packages | None |\n| **serial2py** | joystick position over serial | convert joystick commands of target tilt positions (used to test subsystems) | direction and angle of platform tilt | \n\n```mermaid\nflowchart LR\n    subgraph core.main\n        serial2py.read_arduino_joystick --\u003e inverse_kinematics\n        computer_vision --\u003e pid\n        computer_vision --\u003e motion_planner\n        motion_planner --\u003e pid\n        pid --\u003e inverse_kinematics --\u003e py2motor\n    end\n```\n\n# Installation\n\n1. **Install Dependencies:**\n\n    ```sh\n    pip install -e src\n    ```\n\n2. **Start the Application:**\n\n    ```sh\n    start\n    ```\n\nTo change the mode of operation, the static config can be changed in src/core/main.py\n\nSince serial interfaces may vary between devices, they may need to be changed.\n\n# Reproducing the Setup\n\n## Required Hardware\n\n- **Camera:** Connected to the device running `core.main` (e.g. Raspberry Pi)\n- **Transparent plate:** (polycarbonate)\n- **Three linkages:** Connecting the plate to the motors\n- **Three motors**\n- **Motor driver:** Implements the protocol specified below\n\n## Embedded Protocol\n\nAll commands should be ASCII encoded and insensitive to blank spaces.\n\nOn startup, the motor driver should receive a `\u003ch\u003e` command via serial, raise the platform to an acceptable starting position, and emit a `HOME` command via serial in response.\n\nThe driver should accept commands of the format `\u003ca,rad1,rad2,rad3\u003e` representing an absolute movement of the motors to a given degree in radians.\n\n## Computer Vision\n\nThe computer_vision module can be run independently with\n```sh\npython src/computer_vision/ball_detection.py\n```\n\nIt may be necessary to adjust the parameters for the Hough Circle Transform to improve ball detection.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomasonzhou%2Fparallel_manipulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthomasonzhou%2Fparallel_manipulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomasonzhou%2Fparallel_manipulator/lists"}