diff --git a/.github/workflows/pages.yaml b/.github/workflows/pages.yaml new file mode 100644 index 0000000..edd0e4c --- /dev/null +++ b/.github/workflows/pages.yaml @@ -0,0 +1,59 @@ +name: Deploy Documentation + +on: + push: + branches: + - "main" + paths: + - "docs/**" + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +# Allow one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + # Build job + build: + runs-on: ubuntu-latest + defaults: + run: + working-directory: docs + steps: + - name: Checkout + uses: actions/checkout@v3 + - name: Setup Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: '3.1' # Not needed with a .ruby-version file + bundler-cache: true # runs 'bundle install' and caches installed gems automatically + cache-version: 0 # Increment this number if you need to re-download cached gems + working-directory: '${{ github.workspace }}/docs' + - name: Setup Pages + id: pages + uses: actions/configure-pages@v3 + - name: Build with Jekyll + run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" + env: + JEKYLL_ENV: production + - name: Upload artifact + uses: actions/upload-pages-artifact@v1 + with: + path: "docs/_site/" + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 0000000..3aec09b --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,7 @@ +source 'https://rubygems.org' + +gem "jekyll", "~> 4.3.3" # installed by `gem jekyll` +# gem "webrick" # required when using Ruby >= 3 and Jekyll <= 4.2.2 + +gem "just-the-docs", "0.7.0" # pinned to the current release +# gem "just-the-docs" # always download the latest release diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..21893ae --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,9 @@ +title: DROID Docs +description: Developer documentation for recreating the DROID platform setup. +theme: just-the-docs + +url: https://peterdavidfagan.github.io/DROID # this url not being used right now +color_scheme: r2d2 # TODO: update name to DROID + +aux_links: + Official GitHub Repository: https://github.com/AlexanderKhazatsky/R2D2 diff --git a/docs/_sass/color_schemes/r2d2.scss b/docs/_sass/color_schemes/r2d2.scss new file mode 100644 index 0000000..fae21f8 --- /dev/null +++ b/docs/_sass/color_schemes/r2d2.scss @@ -0,0 +1,7 @@ +@import "./color_schemes/light"; + +// add custom colours here +$cardinal-red: #8C1515; // can be updated assumed primary author's university color scheme + +$link-color: $cardinal-red; +$btn-primary-color: $cardinal-red; diff --git a/docs/assets/hardware-setup/2637b668f68af7c3cf43491924fd1a41.png b/docs/assets/hardware-setup/2637b668f68af7c3cf43491924fd1a41.png new file mode 100644 index 0000000..5708110 Binary files /dev/null and b/docs/assets/hardware-setup/2637b668f68af7c3cf43491924fd1a41.png differ diff --git a/docs/assets/hardware-setup/arm_wire1.jpg b/docs/assets/hardware-setup/arm_wire1.jpg new file mode 100644 index 0000000..8560b7f Binary files /dev/null and b/docs/assets/hardware-setup/arm_wire1.jpg differ diff --git a/docs/assets/hardware-setup/arm_wire10.jpg b/docs/assets/hardware-setup/arm_wire10.jpg new file mode 100644 index 0000000..1e0cef8 Binary files /dev/null and b/docs/assets/hardware-setup/arm_wire10.jpg differ diff --git a/docs/assets/hardware-setup/arm_wire11.jpg b/docs/assets/hardware-setup/arm_wire11.jpg new file mode 100644 index 0000000..caca0bb Binary files /dev/null and b/docs/assets/hardware-setup/arm_wire11.jpg differ diff --git a/docs/assets/hardware-setup/arm_wire12.jpg b/docs/assets/hardware-setup/arm_wire12.jpg new file mode 100644 index 0000000..7ad0dc6 Binary files /dev/null and b/docs/assets/hardware-setup/arm_wire12.jpg differ diff --git a/docs/assets/hardware-setup/arm_wire13.jpg b/docs/assets/hardware-setup/arm_wire13.jpg new file mode 100644 index 0000000..cfe1e9e Binary files /dev/null and b/docs/assets/hardware-setup/arm_wire13.jpg differ diff --git a/docs/assets/hardware-setup/arm_wire14.jpg b/docs/assets/hardware-setup/arm_wire14.jpg new file mode 100644 index 0000000..5767b72 Binary files /dev/null and b/docs/assets/hardware-setup/arm_wire14.jpg differ diff --git a/docs/assets/hardware-setup/arm_wire15.jpg b/docs/assets/hardware-setup/arm_wire15.jpg new file mode 100644 index 0000000..82a872a Binary files /dev/null and b/docs/assets/hardware-setup/arm_wire15.jpg differ diff --git a/docs/assets/hardware-setup/arm_wire16.jpg b/docs/assets/hardware-setup/arm_wire16.jpg new file mode 100644 index 0000000..bec725b Binary files /dev/null and b/docs/assets/hardware-setup/arm_wire16.jpg differ diff --git a/docs/assets/hardware-setup/arm_wire17.jpg b/docs/assets/hardware-setup/arm_wire17.jpg new file mode 100644 index 0000000..0c89892 Binary files /dev/null and b/docs/assets/hardware-setup/arm_wire17.jpg differ diff --git a/docs/assets/hardware-setup/arm_wire18.jpg b/docs/assets/hardware-setup/arm_wire18.jpg new file mode 100644 index 0000000..4c0817c Binary files /dev/null and b/docs/assets/hardware-setup/arm_wire18.jpg differ diff --git a/docs/assets/hardware-setup/arm_wire2.jpg b/docs/assets/hardware-setup/arm_wire2.jpg new file mode 100644 index 0000000..8c84b18 Binary files /dev/null and b/docs/assets/hardware-setup/arm_wire2.jpg differ diff --git a/docs/assets/hardware-setup/arm_wire3.jpg b/docs/assets/hardware-setup/arm_wire3.jpg new file mode 100644 index 0000000..8536778 Binary files /dev/null and b/docs/assets/hardware-setup/arm_wire3.jpg differ diff --git a/docs/assets/hardware-setup/arm_wire4.jpg b/docs/assets/hardware-setup/arm_wire4.jpg new file mode 100644 index 0000000..e7997d7 Binary files /dev/null and b/docs/assets/hardware-setup/arm_wire4.jpg differ diff --git a/docs/assets/hardware-setup/arm_wire5.jpg b/docs/assets/hardware-setup/arm_wire5.jpg new file mode 100644 index 0000000..db37961 Binary files /dev/null and b/docs/assets/hardware-setup/arm_wire5.jpg differ diff --git a/docs/assets/hardware-setup/arm_wire6.jpg b/docs/assets/hardware-setup/arm_wire6.jpg new file mode 100644 index 0000000..0d9a3a0 Binary files /dev/null and b/docs/assets/hardware-setup/arm_wire6.jpg differ diff --git a/docs/assets/hardware-setup/arm_wire7.jpg b/docs/assets/hardware-setup/arm_wire7.jpg new file mode 100644 index 0000000..d8d8c50 Binary files /dev/null and b/docs/assets/hardware-setup/arm_wire7.jpg differ diff --git a/docs/assets/hardware-setup/arm_wire8.jpg b/docs/assets/hardware-setup/arm_wire8.jpg new file mode 100644 index 0000000..01bbb95 Binary files /dev/null and b/docs/assets/hardware-setup/arm_wire8.jpg differ diff --git a/docs/assets/hardware-setup/arm_wire9.jpg b/docs/assets/hardware-setup/arm_wire9.jpg new file mode 100644 index 0000000..1e5596d Binary files /dev/null and b/docs/assets/hardware-setup/arm_wire9.jpg differ diff --git a/docs/assets/hardware-setup/breadboard_base1.jpg b/docs/assets/hardware-setup/breadboard_base1.jpg new file mode 100644 index 0000000..c7bce97 Binary files /dev/null and b/docs/assets/hardware-setup/breadboard_base1.jpg differ diff --git a/docs/assets/hardware-setup/breadboard_base2.jpg b/docs/assets/hardware-setup/breadboard_base2.jpg new file mode 100644 index 0000000..47dd0ee Binary files /dev/null and b/docs/assets/hardware-setup/breadboard_base2.jpg differ diff --git a/docs/assets/hardware-setup/breadboard_base3.jpg b/docs/assets/hardware-setup/breadboard_base3.jpg new file mode 100644 index 0000000..1d416df Binary files /dev/null and b/docs/assets/hardware-setup/breadboard_base3.jpg differ diff --git a/docs/assets/hardware-setup/breadboard_base4.jpg b/docs/assets/hardware-setup/breadboard_base4.jpg new file mode 100644 index 0000000..8a79bf0 Binary files /dev/null and b/docs/assets/hardware-setup/breadboard_base4.jpg differ diff --git a/docs/assets/hardware-setup/breadboard_base5.jpg b/docs/assets/hardware-setup/breadboard_base5.jpg new file mode 100644 index 0000000..b8b82e9 Binary files /dev/null and b/docs/assets/hardware-setup/breadboard_base5.jpg differ diff --git a/docs/assets/hardware-setup/breadboard_base6.jpg b/docs/assets/hardware-setup/breadboard_base6.jpg new file mode 100644 index 0000000..7dddc13 Binary files /dev/null and b/docs/assets/hardware-setup/breadboard_base6.jpg differ diff --git a/docs/assets/hardware-setup/breadboard_base7.jpg b/docs/assets/hardware-setup/breadboard_base7.jpg new file mode 100644 index 0000000..6a7f415 Binary files /dev/null and b/docs/assets/hardware-setup/breadboard_base7.jpg differ diff --git a/docs/assets/hardware-setup/calibration_board1.jpg b/docs/assets/hardware-setup/calibration_board1.jpg new file mode 100644 index 0000000..21ff27a Binary files /dev/null and b/docs/assets/hardware-setup/calibration_board1.jpg differ diff --git a/docs/assets/hardware-setup/calibration_board2.jpg b/docs/assets/hardware-setup/calibration_board2.jpg new file mode 100644 index 0000000..c16f398 Binary files /dev/null and b/docs/assets/hardware-setup/calibration_board2.jpg differ diff --git a/docs/assets/hardware-setup/calibration_board3.jpg b/docs/assets/hardware-setup/calibration_board3.jpg new file mode 100644 index 0000000..6dff67a Binary files /dev/null and b/docs/assets/hardware-setup/calibration_board3.jpg differ diff --git a/docs/assets/hardware-setup/calibration_board4.jpg b/docs/assets/hardware-setup/calibration_board4.jpg new file mode 100644 index 0000000..cbfe8fa Binary files /dev/null and b/docs/assets/hardware-setup/calibration_board4.jpg differ diff --git a/docs/assets/hardware-setup/calibration_board5.jpg b/docs/assets/hardware-setup/calibration_board5.jpg new file mode 100644 index 0000000..73d27a8 Binary files /dev/null and b/docs/assets/hardware-setup/calibration_board5.jpg differ diff --git a/docs/assets/hardware-setup/calibration_board6.jpg b/docs/assets/hardware-setup/calibration_board6.jpg new file mode 100644 index 0000000..b4d4ead Binary files /dev/null and b/docs/assets/hardware-setup/calibration_board6.jpg differ diff --git a/docs/assets/hardware-setup/calibration_board7.jpg b/docs/assets/hardware-setup/calibration_board7.jpg new file mode 100644 index 0000000..675e81e Binary files /dev/null and b/docs/assets/hardware-setup/calibration_board7.jpg differ diff --git a/docs/assets/hardware-setup/calibration_board8.jpg b/docs/assets/hardware-setup/calibration_board8.jpg new file mode 100644 index 0000000..f29a5ae Binary files /dev/null and b/docs/assets/hardware-setup/calibration_board8.jpg differ diff --git a/docs/assets/hardware-setup/camera_mount1.jpg b/docs/assets/hardware-setup/camera_mount1.jpg new file mode 100644 index 0000000..d21a2fa Binary files /dev/null and b/docs/assets/hardware-setup/camera_mount1.jpg differ diff --git a/docs/assets/hardware-setup/camera_mount2.jpg b/docs/assets/hardware-setup/camera_mount2.jpg new file mode 100644 index 0000000..2eefbdd Binary files /dev/null and b/docs/assets/hardware-setup/camera_mount2.jpg differ diff --git a/docs/assets/hardware-setup/camera_mount3.jpg b/docs/assets/hardware-setup/camera_mount3.jpg new file mode 100644 index 0000000..1e418f5 Binary files /dev/null and b/docs/assets/hardware-setup/camera_mount3.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring1.jpg b/docs/assets/hardware-setup/miscellaneous_wiring1.jpg new file mode 100644 index 0000000..13577dd Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring1.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring10.jpg b/docs/assets/hardware-setup/miscellaneous_wiring10.jpg new file mode 100644 index 0000000..1b3f2e4 Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring10.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring11.jpg b/docs/assets/hardware-setup/miscellaneous_wiring11.jpg new file mode 100644 index 0000000..68fba86 Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring11.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring12.jpg b/docs/assets/hardware-setup/miscellaneous_wiring12.jpg new file mode 100644 index 0000000..6f4c054 Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring12.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring13.jpg b/docs/assets/hardware-setup/miscellaneous_wiring13.jpg new file mode 100644 index 0000000..975d146 Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring13.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring14.jpg b/docs/assets/hardware-setup/miscellaneous_wiring14.jpg new file mode 100644 index 0000000..a15931f Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring14.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring15.jpg b/docs/assets/hardware-setup/miscellaneous_wiring15.jpg new file mode 100644 index 0000000..90ab625 Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring15.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring16.jpg b/docs/assets/hardware-setup/miscellaneous_wiring16.jpg new file mode 100644 index 0000000..26f721e Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring16.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring17.jpg b/docs/assets/hardware-setup/miscellaneous_wiring17.jpg new file mode 100644 index 0000000..f176ff5 Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring17.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring18.jpg b/docs/assets/hardware-setup/miscellaneous_wiring18.jpg new file mode 100644 index 0000000..02a983d Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring18.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring19.jpg b/docs/assets/hardware-setup/miscellaneous_wiring19.jpg new file mode 100644 index 0000000..bd85966 Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring19.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring2.jpg b/docs/assets/hardware-setup/miscellaneous_wiring2.jpg new file mode 100644 index 0000000..cbb6521 Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring2.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring3.jpg b/docs/assets/hardware-setup/miscellaneous_wiring3.jpg new file mode 100644 index 0000000..bcf73dc Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring3.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring4.jpg b/docs/assets/hardware-setup/miscellaneous_wiring4.jpg new file mode 100644 index 0000000..62f9227 Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring4.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring5.jpg b/docs/assets/hardware-setup/miscellaneous_wiring5.jpg new file mode 100644 index 0000000..88c68df Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring5.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring6.jpg b/docs/assets/hardware-setup/miscellaneous_wiring6.jpg new file mode 100644 index 0000000..fece2c7 Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring6.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring7.jpg b/docs/assets/hardware-setup/miscellaneous_wiring7.jpg new file mode 100644 index 0000000..eaa406b Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring7.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring8.jpg b/docs/assets/hardware-setup/miscellaneous_wiring8.jpg new file mode 100644 index 0000000..50336ad Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring8.jpg differ diff --git a/docs/assets/hardware-setup/miscellaneous_wiring9.jpg b/docs/assets/hardware-setup/miscellaneous_wiring9.jpg new file mode 100644 index 0000000..88f6e3c Binary files /dev/null and b/docs/assets/hardware-setup/miscellaneous_wiring9.jpg differ diff --git a/docs/assets/hardware-setup/mobile_base1.jpg b/docs/assets/hardware-setup/mobile_base1.jpg new file mode 100644 index 0000000..f2b4b8f Binary files /dev/null and b/docs/assets/hardware-setup/mobile_base1.jpg differ diff --git a/docs/assets/hardware-setup/mobile_base2.jpg b/docs/assets/hardware-setup/mobile_base2.jpg new file mode 100644 index 0000000..4fd0adb Binary files /dev/null and b/docs/assets/hardware-setup/mobile_base2.jpg differ diff --git a/docs/assets/hardware-setup/mobile_base3.jpg b/docs/assets/hardware-setup/mobile_base3.jpg new file mode 100644 index 0000000..73017e2 Binary files /dev/null and b/docs/assets/hardware-setup/mobile_base3.jpg differ diff --git a/docs/assets/hardware-setup/mobile_base4.jpg b/docs/assets/hardware-setup/mobile_base4.jpg new file mode 100644 index 0000000..2460a1e Binary files /dev/null and b/docs/assets/hardware-setup/mobile_base4.jpg differ diff --git a/docs/assets/hardware-setup/mobile_base5.jpg b/docs/assets/hardware-setup/mobile_base5.jpg new file mode 100644 index 0000000..ef3e769 Binary files /dev/null and b/docs/assets/hardware-setup/mobile_base5.jpg differ diff --git a/docs/assets/hardware-setup/mobile_base6.jpg b/docs/assets/hardware-setup/mobile_base6.jpg new file mode 100644 index 0000000..9510003 Binary files /dev/null and b/docs/assets/hardware-setup/mobile_base6.jpg differ diff --git a/docs/assets/hardware-setup/overview1.png b/docs/assets/hardware-setup/overview1.png new file mode 100644 index 0000000..401a59a Binary files /dev/null and b/docs/assets/hardware-setup/overview1.png differ diff --git a/docs/assets/hardware-setup/overview2.png b/docs/assets/hardware-setup/overview2.png new file mode 100644 index 0000000..382f2b5 Binary files /dev/null and b/docs/assets/hardware-setup/overview2.png differ diff --git a/docs/assets/hardware-setup/robotiq_attach1.jpg b/docs/assets/hardware-setup/robotiq_attach1.jpg new file mode 100644 index 0000000..452092f Binary files /dev/null and b/docs/assets/hardware-setup/robotiq_attach1.jpg differ diff --git a/docs/assets/hardware-setup/robotiq_attach2.jpg b/docs/assets/hardware-setup/robotiq_attach2.jpg new file mode 100644 index 0000000..2bdc789 Binary files /dev/null and b/docs/assets/hardware-setup/robotiq_attach2.jpg differ diff --git a/docs/assets/hardware-setup/robotiq_attach3.jpg b/docs/assets/hardware-setup/robotiq_attach3.jpg new file mode 100644 index 0000000..7811cfc Binary files /dev/null and b/docs/assets/hardware-setup/robotiq_attach3.jpg differ diff --git a/docs/assets/hardware-setup/robotiq_attach4.jpg b/docs/assets/hardware-setup/robotiq_attach4.jpg new file mode 100644 index 0000000..91565e2 Binary files /dev/null and b/docs/assets/hardware-setup/robotiq_attach4.jpg differ diff --git a/docs/assets/hardware-setup/robotiq_attach5.jpg b/docs/assets/hardware-setup/robotiq_attach5.jpg new file mode 100644 index 0000000..6161af9 Binary files /dev/null and b/docs/assets/hardware-setup/robotiq_attach5.jpg differ diff --git a/docs/assets/hardware-setup/robotiq_attach6.jpg b/docs/assets/hardware-setup/robotiq_attach6.jpg new file mode 100644 index 0000000..c6730b6 Binary files /dev/null and b/docs/assets/hardware-setup/robotiq_attach6.jpg differ diff --git a/docs/assets/hardware-setup/robotiq_wiring1.jpg b/docs/assets/hardware-setup/robotiq_wiring1.jpg new file mode 100644 index 0000000..37cff39 Binary files /dev/null and b/docs/assets/hardware-setup/robotiq_wiring1.jpg differ diff --git a/docs/assets/hardware-setup/robotiq_wiring2.jpg b/docs/assets/hardware-setup/robotiq_wiring2.jpg new file mode 100644 index 0000000..3a8e8f3 Binary files /dev/null and b/docs/assets/hardware-setup/robotiq_wiring2.jpg differ diff --git a/docs/assets/hardware-setup/robotiq_wiring3.jpg b/docs/assets/hardware-setup/robotiq_wiring3.jpg new file mode 100644 index 0000000..c675c4f Binary files /dev/null and b/docs/assets/hardware-setup/robotiq_wiring3.jpg differ diff --git a/docs/assets/hardware-setup/robotiq_wiring4.jpg b/docs/assets/hardware-setup/robotiq_wiring4.jpg new file mode 100644 index 0000000..67421ce Binary files /dev/null and b/docs/assets/hardware-setup/robotiq_wiring4.jpg differ diff --git a/docs/assets/hardware-setup/robotiq_wiring5.jpg b/docs/assets/hardware-setup/robotiq_wiring5.jpg new file mode 100644 index 0000000..91dc377 Binary files /dev/null and b/docs/assets/hardware-setup/robotiq_wiring5.jpg differ diff --git a/docs/assets/hardware-setup/robotiq_wiring6.jpg b/docs/assets/hardware-setup/robotiq_wiring6.jpg new file mode 100644 index 0000000..fa8a058 Binary files /dev/null and b/docs/assets/hardware-setup/robotiq_wiring6.jpg differ diff --git a/docs/assets/hardware-setup/robotiq_wiring7.jpg b/docs/assets/hardware-setup/robotiq_wiring7.jpg new file mode 100644 index 0000000..3a8328d Binary files /dev/null and b/docs/assets/hardware-setup/robotiq_wiring7.jpg differ diff --git a/docs/assets/hardware-setup/robotiq_wiring8.jpg b/docs/assets/hardware-setup/robotiq_wiring8.jpg new file mode 100644 index 0000000..b93d6e7 Binary files /dev/null and b/docs/assets/hardware-setup/robotiq_wiring8.jpg differ diff --git a/docs/assets/hardware-setup/robotiq_wiring9.jpg b/docs/assets/hardware-setup/robotiq_wiring9.jpg new file mode 100644 index 0000000..2140f1a Binary files /dev/null and b/docs/assets/hardware-setup/robotiq_wiring9.jpg differ diff --git a/docs/assets/hardware-setup/third_person1.png b/docs/assets/hardware-setup/third_person1.png new file mode 100644 index 0000000..198052f Binary files /dev/null and b/docs/assets/hardware-setup/third_person1.png differ diff --git a/docs/assets/hardware-setup/third_person2.jpg b/docs/assets/hardware-setup/third_person2.jpg new file mode 100644 index 0000000..8641177 Binary files /dev/null and b/docs/assets/hardware-setup/third_person2.jpg differ diff --git a/docs/assets/index/banner.jpeg b/docs/assets/index/banner.jpeg new file mode 100644 index 0000000..70a86e4 Binary files /dev/null and b/docs/assets/index/banner.jpeg differ diff --git a/docs/assets/software-setup/polymetis_controller_manager.png b/docs/assets/software-setup/polymetis_controller_manager.png new file mode 100644 index 0000000..e4cc144 Binary files /dev/null and b/docs/assets/software-setup/polymetis_controller_manager.png differ diff --git a/docs/contribution-guidelines.md b/docs/contribution-guidelines.md new file mode 100644 index 0000000..e72f6b8 --- /dev/null +++ b/docs/contribution-guidelines.md @@ -0,0 +1,7 @@ +--- +layout: default +title: Contribution Guidelines +nav_order: 6 +--- + +# Contribution Guidelines diff --git a/docs/dataset-schema.md b/docs/dataset-schema.md new file mode 100644 index 0000000..fecdd12 --- /dev/null +++ b/docs/dataset-schema.md @@ -0,0 +1,38 @@ +--- +layout: default +title: Dataset Schema +nav_order: 5 +--- + +# Dataset Schema + +| Field | Datatype | +| --------- | -------- | +| steps | `Dataset` | +| steps/action | `Tensor(shape=(6,), dtype=float64)` | +| steps/action_dict | `FeaturesDict` | +|steps/action_dict/cartesian_position| `Tensor(shape=(6,), dtype=float64)` | +|steps/action_dict/cartesian_velocity| `Tensor(shape=(6,), dtype=float64)` | +|steps/action_dict/gripper_position| `Tensor(shape=(1,), dtype=float64)` | +|steps/action_dict/gripper_velocity| `Tensor(shape=(1,), dtype=float64)` | +|steps/action_dict/joint_position| `Tensor(shape=(7,), dtype=float64)` | +|steps/action_dict/joint_velocity| `Tensor(shape=(7,), dtype=float64)` | +|steps/discount| `Scalar(shape=(), dtype=float32)` | +|steps/is_first| `Scalar(shape=(), dtype=bool)` | +|steps/is_last| `Scalar(shape=(), dtype=bool)` | +|steps/is_terminal| `Scalar(shape=(), dtype=bool)` | +|steps/language_embedding| `Tensor(shape=(512,), dtype=float32)` | +|steps/language_embedding_2| `Tensor(shape=(512,), dtype=float32)` | +|steps/language_embedding_3| `Tensor(shape=(512,), dtype=float32)` | +|steps/language_instruction| `Text(shape=(), dtype=string)` | +|steps/language_instruction_2| `Text(shape=(), dtype=string)` | +|steps/language_instruction_3| `Text(shape=(), dtype=string)` | +|steps/observation| `FeaturesDict` | +|steps/observation/cartesian_position| `Tensor(shape=(6,), dtype=float64)` | +|steps/observation/exterior_image_1_left| `Image(shape=(180, 320, 3), dtype=uint8)` | +|steps/observation/exterior_image_2_left| `Image(shape=(180, 320, 3), dtype=uint8)` | +|steps/observation/gripper_position| `Tensor(shape=(1,), dtype=float64)` | +|steps/observation/joint_position| `Tensor(shape=(7,), dtype=float64)` | +|steps/observation/wrist_image_left| `Image(shape=(180, 320, 3), dtype=uint8)` | +|reward| `Scalar(shape=(), dtype=float32)` | + diff --git a/docs/example-workflows/calibrating-cameras.md b/docs/example-workflows/calibrating-cameras.md new file mode 100644 index 0000000..8104d68 --- /dev/null +++ b/docs/example-workflows/calibrating-cameras.md @@ -0,0 +1,32 @@ +--- +layout: default +title: Calibrating Cameras +parent: Example Workflows +nav_order: 2 +--- + +# Prerequisites + +This guide assumes you have already setup DROID application software to run on your host machine or through Docker. Proceed with this guide having launched the control server on the NUC and the GUI application on the laptop. + +# Calibrating Cameras + +The GUI will let you know if any of your camera’s have yet to be calibrated, or if any of your camera’s haven’t been calibrated in a while (this is to make sure you don’t accidentally move them and forget). Since the hand camera is relatively fixed, it is okay to calibrate significantly less frequently than the other cameras, but it is still good practice to calibrate it every now and then. + +Useful Information: +* If calibration is successful, you will be brought back to the calibration hub. If it is unsuccessful, the GUI will inform you as such. +* During calibration, you will see a visualization of the pose estimation of the charuco board. Stable, green boxes along with stable axes lines are good! When these are not present, a calibration is likely to fail. If things start to significantly jumble during the automated calibration procedure, feel free to press B and try again. +* Because the board is heavy, the robot may move differently when the board is attached to the gripper. +* **WARNING:** If A button click is taking a really long time. The camera might have failed. You can confirm this by looking in the terminal for a line that resembles “can’t claim interface…”. The solution is to simply close the GUI, and load it up again. Your previous calibration info will not be lost. + +## Mounting Calibration Board + +Please follow the instructions in the assembly guide for mounting the calibration board. + +## Calibrating a 3rd-Person Camera + + + +## Calibration a Hand-Mounted Camera + + diff --git a/docs/example-workflows/data-collection.md b/docs/example-workflows/data-collection.md new file mode 100644 index 0000000..9dec330 --- /dev/null +++ b/docs/example-workflows/data-collection.md @@ -0,0 +1,44 @@ +--- +layout: default +title: Collecting Data +parent: Example Workflows +nav_order: 3 +--- + +# Prerequisites + +**Important:** Before proceeding please ensure you have followed the camera calibration guide and calibrated your cameras. + +This guide assumes you have already setup DROID application software to run on your host machine or through Docker. Proceed with this guide having launched the control server on the NUC and the GUI application on the laptop. + +# Collecting Data + +## Using the GUI + +* The GUI will start by prompting you to enter your name. + * Note 1: Your trajectories will be associated with the name you type in. So, make sure to be consistent, and type in your full name! The login page will not let you pass until you have done so. + * Note 2: Press shift to see the camera feed. Anytime you see a camera feed, confirm that there are exactly 6 images on screen. If there is anything different, halt data collection, unplug and replug the 3 camera wires, and restart the GUI. + +* After this, you will be presented with the task configuration page. This is where you enter all the tasks that are currently doable from the scene you have created for your robot. You may select from the predefined tasks using the checkboxes, or enter your own tasks in the text box. For your convenience, use the shift button to toggle between this page and the camera feed. This can be useful for checking what is in view of your cameras. + * In the upper left corner are 3 tabs: + * Task Ideas: A google doc of task ideas for inspiration split by room type (ex: bedroom, kitchen, etc) + * Preferred Tasks: We will be collecting demonstrations for 20 abstract tasks, and 20 specific tasks as a backup. These latter 20 tasks are specific instances of the 20 abstract tasks. We ask that you make sure that around once every couple xdays, you collect some trajectories for as many of these tasks as possible. Clicking this tab will bring you to a page that lists all of the specific tasks and allows you to keep track of which ones you have collected data for. + * Franka Website: This will bring you to your Franka’s website, where you can lock / unlock robot joints, as well as activate FCI mode. + +* In the lower right corner are another 3 tabs: + * Collect Trajectory: This will bring you to the requested task page, where you will be prompted with your task for the next trajectory. You may press A to begin the trajectory, or B to sample a new task if it’s necessary. + * Calibrate: This will bring you to the camera calibration page. Click the camera that you would like to calibrate. Note that because we need to turn the cameras on in high resolution, button clicks may take a while here. See the section below for more information on camera calibration. + * Practice: This will allow you to collect a trajectory without the data being saved. You can use this tool however you see fit. + +* Periodically, the GUI will prompt you with desired scene changes. Proceed with them as instructed. When the scene changes involve altering a camera position, make sure to recalibrate the associated camera! + +* Miscellaneous Notes: + * Finish trajectories in such a way that the robot can be reset (ex: nothing in gripper, as it will be dropped. + * Try to create scenes with as many available tasks as possible. + * Although we want you to stick to the requested tasks, use your best judgment. + * At any time, hold 'Return' for 5 seconds to reset the robot + +# Uploading Data + +Instructions for uploading data can be found in [this](https://github.com/AlexanderKhazatsky/R2D2/tree/main/scripts) readme. + diff --git a/docs/example-workflows/evaluating-policies.md b/docs/example-workflows/evaluating-policies.md new file mode 100644 index 0000000..b60715a --- /dev/null +++ b/docs/example-workflows/evaluating-policies.md @@ -0,0 +1,15 @@ +--- +layout: default +title: Evaluating Policies +parent: Example Workflows +nav_order: 5 +--- + +# Evaluating Policies + +* Run a variant of [this](https://github.com/AlexanderKhazatsky/R2D2/blob/main/scripts/evaluation/evaluate_policy.py) file with the desired properties. + * Make sure to update policy_logdir and model_id with the desired values + * Any properties that are added to the variant will be loaded from the training folder values. +* It is recommended to start off by evaluating policies in the “Practice” tab for simplicity. +* Note: The robot will only move when you are holding down the side button of the controller. However, instead of the actions coming from your handle as during data collection, the actions will come from the policy. + diff --git a/docs/example-workflows/example-workflows.md b/docs/example-workflows/example-workflows.md new file mode 100644 index 0000000..255cde3 --- /dev/null +++ b/docs/example-workflows/example-workflows.md @@ -0,0 +1,7 @@ +--- +layout: default +title: Example Workflows +nav_order: 4 +has_children: true +permalink: /docs/example-workflows +--- diff --git a/docs/example-workflows/teleoperation.md b/docs/example-workflows/teleoperation.md new file mode 100644 index 0000000..a040d0f --- /dev/null +++ b/docs/example-workflows/teleoperation.md @@ -0,0 +1,21 @@ +--- +layout: default +title: Teleoperating the Robot +parent: Example Workflows +nav_order: 1 +--- + +# Prerequisites + +This guide assumes you have already setup DROID application software to run on your host machine or through Docker. Proceed with this guide having launched the control server on the NUC and the GUI application on the laptop. + +# Teleoperating the Robot + +* To teleoperate the robot, your oculus controller should be plugged into your laptop, and the permissions prompt should be accepted (done by putting the headset on and clicking “Accept”. Also, the controller has to be in view of the headset cameras. It detects the pose of the handle via infrared stickers on the handle. +* To control the robot, we will use only the right controller. If you would like to use the left controller for teleoperation instead, change [this](https://github.com/AlexanderKhazatsky/R2D2/blob/5f2f96b5cf9d95dde67fda21a8ab776683aeeae7/r2d2/controllers/oculus_controller.py#L16) parameter. +* Teleoperation works by applying the changes to the oculus handle’s pose to the robot gripper’s pose. The trigger on the front of the controller is used to control the gripper. Actions are only applied when the trigger on the side of the controller is being held. +* It is important for intuitive control that the controller’s definition of forward is aligned with the direction of the robot. The controller defines “forward” on the first step where the side button of the controller is held. At any point, you can redefine the forward direction by pressing down on the joystick until you hear a click. At some point, try changing the definition of forward to get a better feel for its purpose. +* To practice, select `Practice` from the GUI application. + + + diff --git a/docs/example-workflows/training-policies.md b/docs/example-workflows/training-policies.md new file mode 100644 index 0000000..f34b98e --- /dev/null +++ b/docs/example-workflows/training-policies.md @@ -0,0 +1,13 @@ +--- +layout: default +title: Training Policies +parent: Example Workflows +nav_order: 4 +--- + +# Training Policies + +* Run a variant of [this](https://github.com/AlexanderKhazatsky/R2D2/blob/main/scripts/training/train_policy.py) file with the desired properties. + * If you are doing a simple BC from images sanity check task, run [this](https://github.com/AlexanderKhazatsky/R2D2/blob/main/scripts/training/sanity_check/image_obs.py) file +* If the function of any hyperparameters are unclear, message Sasha to inquire about their utility. + diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 0000000..fcd8da3 Binary files /dev/null and b/docs/favicon.ico differ diff --git a/docs/hardware-setup/assembly.md b/docs/hardware-setup/assembly.md new file mode 100644 index 0000000..a0841b3 --- /dev/null +++ b/docs/hardware-setup/assembly.md @@ -0,0 +1,406 @@ +--- +layout: default +title: Assembly +parent: Hardware Setup +nav_order: 2 +--- + +This assembly guide starts from constructing the standing desk, before progressing to mounting the robot on the desk and installing various other components to the platform. There are a number of design options/variations for the mobile platform, these are discussed under each of the major headings. + +
+ + Table of contents + + {: .text-delta } +1. TOC +{:toc} +
+ +## Building the Desk + +It is expected that you have procured a standing desk similar to the one listed in the shopping list. The desk you procured should be accompanied with an assembly guide please follow this guide to construct your standing desk. + +**Important:** at this stage, don't attach any extras such as trays and/or cable management items to the bottom of the desk as we will be installing components to the underside of the table in future sections of the guide. + + + +## Mounting Robot on the Desk + +### Option 1: Breadboard Base + +A flexible option for mounting the robot on the desk is to bolt a set of rails to a breadboard and subsequently mount the robot on these rails. The main advantage of this form of mount is that it is possible to reposition the rails and mount position of the robot. + +The first thing we will do is construct the rails upon which the robot will be mounted: + +* Take a 1 foot aluminum bar, and slide the bracket circled in red in the below image (yours may look different) into the left and right side of it. +* Put two of the screws (1 cm long, 5mm wide) into a corner bracket and loosely screw one side into the bracket within the 1 foot aluminum bar on either side. +* Use this technique to create a rail that looks like the rail in the third image below, and another that looks is a mirrored version of this (ie. one corner bracket in the upper right and one in the lower right) + +

+image +image +image +

+ + +Next we will mount these rails on to our breadboard: + +* Screw the aluminum bars into the breadboard in the configuration shown below. Unfortunately it’s not possible to achieve perfect symmetry when bolting the rails to the breadboard. Feel free to nudge the centering a row or column over for diversity (ex: configure it so there are two holes on the right instead of the left). + * Make sure this is one hole between the bars on the top, and 5 holes between the bars on the bottom + * **Hint:** to keep the screws from colliding when screwing them in, (lift up the bar before screwing so the screw sits at the bottom. (Insert picture) +* Slide two brackets into the top levels of each aluminum bar, we will be using these to attach the Franka. + +

+image +image +

+ +image + + +Now we mount the robot: + +* Align the brackets with the Franka screw holes, and loosely screw the robot to the base. + * If you’re using an FR3, use the[ ⅝” long screws](https://www.mcmaster.com/92949A539/) to mount the robot instead of the original screws. + +* Once everything is loosely screwed in, tighten ALL SCREWS until everything is entirely fixed! + +image + +Next place the breadboard on your standing desk: + +* Center the broadboard as much as you can on top of the desk. It should look roughly like the below image (minus the wires on the robot): + * Important: Make sure that the franka is facing the side without any desk protrusions. An example of a desk protrusion is the height adjuster on the recommended desk (seen on the back, left side of the desk below). + +image + +* Use four clamps (two on either side) to connect the breadboard to the desk. + +

+image +image +

+ +* Place the Franka power box, laptop, and NUC in the following configuration: + +

+image +image +image +

+ + + +## Mounting Additional Components on the Desk + +A requirement of the DROID platform is that it can easily be transported from one location to the next. In this section, we outline configurations for components on the desk in a way that enables greater ease of transportation. Some important points to this end: + +* Throughout this section, take time to organize loose wiring with zip ties, velcro strips and/or sticky hooks in order to keep your desk organised, it is important that wiring be as permanent as possible. +* Getting rid of as much loose wiring and making things as organized as possible during this step will make your life much easier later on! +* Cameras are mounted to the sides of the desk ensure your organise wiring such that you keep space open for moving around the camera mounting location! +* When this doc discusses the location under the desk, we will define forward using the robot. For example “Attach X to the back right side of the desk” means with respect to the direction that the robot is facing. +* Be generous with the amount of industrial strength velcro you use on power boxes, they can be heavy! +* Scroll down to see what the end product should look like. It would be a good idea to frequently come back to these images and compare. + + +### Option 1: Configuring Components on Underside of Table + +* Use velcro to attach the large power strip to the back left of the desk. +* Make sure you face the protruding wiring towards the back of the desk. +* Use velcro to attach the standing desk power box to the desk, organize the loose wiring, and plug it it into the power strip: + +image + +* Use velcro to attach the Franka emergency stop (the white button) to the the bottom of the desk. Attach it on the right hand side directly under the Franka towards the outside of the desk so it is easily accessible. Face the protruding wire towards the center of the desk to keep it from protruding: + +

+image +image +image +

+ +* Connect the emergency stop wire to the X3 port on the Franka + +image + +* Use Velcro to attach the power unit for the Robotiq gripper. Face the built in wire towards the Franka. Plug the other side in and connect it to the power strip. + +

+image +image +

+ +* Use Velcro to attach the power unit for the NUC directly under it (middle right side of the desk). Face the built in cable towards the outside of the desk. Plug in the other side and connect it to the power strip. + +

+image +image +

+ +* Connect the Franka power box power cable to the power strip: + +image + +* Connect the cable from the X1 port on the Franka to the power box + +

+image +image +image +

+ +* Use Velcro to attach the Ethernet switch under the desk on the back right hand side of the desk (under the Franka control box). +* Connect and organize the Ethernet switch power cable, the switch to Franka power box ethernet cable, the switch to NUC ethernet cable, and the switch the laptop Ethernet cable. + +

+image +image +

+ +* If you’re using our recommended laptop, use velcro to attach the power box to the bottom of the desk on the back left side, with the built-in cable facing the robot. Plug in the detachable cable and connect it to the power strip. + +image + +* You’re done! Your setup should look something like the photos below. Ignore the wires going down the robot, and the hand camera, you’ll set those up later. +* Before proceeding, please set up your robot with the Franka software as we will need to put it into zero gravity mode for the next step. Once you’ve done this, familiarize yourself with the text in the “Powering Up Franka” section of this document. + +

+image +image +image +

+ + + + +## Mounting Hand Camera on Robot + +In this section, we will specify how to mount the zed mini camera on the Franka robot arm.It will be easier to perform this part of the assembly with the Franka robot arm in a position that you have easy access to the last link of the robot (often referred to as link8). + + +* Secure the camera in the custom mount specified in the shopping list, insert a nut into the hole on the back of the mount. Insert the 10mm screw on the other side, and tighten the screw in until the attachment is tight. + +image + +* Remove the back two screws in the Franka wrist: + +image + +* Use 30mm screws to attach the hand camera to the gripper (**Important:** these are different from the default screws that come with the arm). + +image + +## Mounting Robotiq Gripper on Robot + +In this section, we will first prepare the Robotiq gripper wiring as it is non-trivial. Following this we will specify how to mount the gripper on the arm. + +### Preparing Wires + +* You should have a thick cable that has 5 exposed wires colored red, black, white, green, and silver. We are going to connect them to ports as demonstrated in the below images. + +

+image +image +image +

+ +* To connect these wires into these ports, you need to cut off some of the rubber to expose ~5mm of metal thread. Then, unscrew the bolts up top to create some space for the metal threads. Jam the metal threads into the empty space, and screw the bolts tight again on top of them. \ + +* Connect the wires as follows: + +

+image +image +

+ +* Cover these wires with a plastic of some sort to keep things from pulling on them. Then, use a Velcro strip to tightly bound everything together so that there is no pressure on the loose open wires. Otherwise, they will come loose and the gripper will stop working. Make sure to leave the outlet uncovered. + +

+image +image +image +image +

+ +* Try connecting the gripper to the AC cable. Make sure that the gripper light shines red. + +### Mount Procedure + +* To start, you should collect these screws from the box (4 x 10mm, 4 x 30mm) + +image + +* Align the gripper mount with the screw holes on the Franka wrist, with the protruding wiring facing the right of the robot. The USB port on the camera should be facing the same direction and parallel to the protruding wire. +* Use the four smaller screws to connect the gripper mount to the Franka wrist. + +image + +* Align the Robotiq gripper with the metal pins on the wrist mount similar to the picture above. Then, use the long screws to attach the gripper in all four corners. + +

+image +image +

+ +* Place a small piece of thick Velcro (soft side) over the light on the gripper. Otherwise, it will shine into the camera. +* **Important:** Gripper is rotated 180 degrees in the below for better view. + +

+image +image +

+ +## Robot Cable Management + +In this section, we will outline how to manage cables on the Franka robot arm. You’ll want to put the Franka robot arm into zero gravity mode for this section. It is also strongly recommended that you use the 12 foot Zed Mini wire that came with the camera. + +Throughout this section we’ll be strapping the wires to the robot with the velcro strips. Use the best length for each connection, and be aware that for some connections you may need to connect two strips together: + +image + + +It's important to keep the following points in mind as we work through this section: + +* Leave enough slack between each wire-to-robot connection for any possible joint configuration. Joint limits are frequently reached, so make sure you do this CAREFULLY and TEST to make sure there’s enough slack meticulously! Otherwise you could damage the equipment. +* Keep the wires organized. We do not want them catching onto things during data collection! +* When you strap the Velcro straps, strap them as tight as possible! You also may want to put zip ties on either side of the wire to keep it from slipping around. Otherwise, you will compromise the amount of slack you allotted each joint. +* After you attach each strap, you may want to move the robot around to extreme positions to make sure there’s never tension on the wire. +* As you move along the wire, use zip ties about every 5cm! + +* When you plug in the camera wire, make sure: + * You use the long Zed wire that came with it! Other wires will not support fast enough data transfer. + * When plugging the wire into the camera the side with the arrow MUST face the side with the lenses. Otherwise you will get a segmentation fault when reading the camera, even though it is a USB C connection and plugs in either way! + * It’s a bit hard to see the arrows in the pictures below, but if you look at the ZED Mini wire in real life you’ll see what I am pointing at. + +image + +* Follow the pictures below to see the joint positions to move to before adding a tight velcro strap at the specified location. +* First picture is to visualize the neutral joint position, second picture is the extreme joint position that we need enough slack for, third picture is the wire velcro strapped with enough slack for that extreme joint position. + +

+image +image +image +

+ +* This second velcro strap is just to manage loose wire along a joint. + +image + +* Visualization of the second joint extreme, and the next velcro strap location. + +image + +* Visualization of the third joint extreme, and the next velcro strap location. + +image + +* Visualization of the fourth joint extreme, and the next velcro strap location. + +image + +* Visualization of the final wiring: + +

+image +image +image +image +

+ +* Now, we will connect these wires to the rest of the mobile base. +* Organize the Robotiq wire slack left over under the desk. If you bought our suggested desk, you can use the wire holders that came with the desk to hold the slack: + +

+image +image +

+ + +* Plug in the AC adapter to the power slot you left open in the Robotiq Gripper Cable Management section. + +

+image +image +

+ +* Organize the Zed Mini wire under the desk, so it only protrudes near the laptop as follows: + +image + +## Mounting Third-Person Cameras + +In this section, we will clamp mounts for third-person cameras to desk. + +* Clamp a camera stand to either side of the desk such that the camera attached to the stand can be positioned with a view of the scene. Take the following additional points into consideration when clamping the stand to the desk. + * The clamp and camera position of the stands should be randomized as much as possible during data collection. Don't fix the stand to a single position each time. + * The robot arm can shake the table slightly as it moves. Whenever setting up the camera stand, tighten the clamp and all joints as much as possible to prevent the camera from shaking. + +

+image +image +

+ +## General Electrical Wiring + +### Power Cable Wiring + +### Ethernet Cable Wiring + +### Camera Wiring + +* To keep the Alienware laptop PCI boards from getting overloaded, it is important to connect the cameras in a very specific manner. Otherwise, you will get a Segmentation Fault. +* Plug all cameras directly into the laptop ports, without the use of any Many2One USB converters OR extension chords! +* In other words, directly plug two cameras in through the USB ports on the right side of the computer, and one directly in through the usb port on the back side of the computer. +* This should leave one USB-C port open for the oculus wiring. + + +## Mounting Calibration Board + +In this section we will outline how to mount the calibration board. + + +### Option 1: Using Magnets + +* Split long magnets into three groups of 6 stacked magnets, and put a sticky tab (provided with them) on both magnet stacks. +* Attach either (NOT THE STICKY SIDE!) to the gripper, aligning them along the metal screws as visualized below (again, the sticky side should be pointing away from the gripper!), and additionally one of the two . Be careful to evenly space the magnets so the screws are in the middle. +* **Important:** Sticky adhesive not visualized in this photo + +

+image +image +image +

+ +* Firmly press the Charuco board into the sticky side of the magnets, and hold it there for 30 seconds. + +

+image +image +image +

+ +* Try moving the gripper around manually to make sure the board stays on during movement. +* **Important:** The board dents easily. Always be very careful not to drop it. +* During data collection, you can stick the charuco board to the standing desk (for transportation) using the magnets. +* Optionally, place 3 singular magnets in sequence near the other end of the board. This can be used to stick the board to the leg of the standing desk during transportation. + +

+image +image +

+ diff --git a/docs/hardware-setup/hardware-setup.md b/docs/hardware-setup/hardware-setup.md new file mode 100644 index 0000000..9bc5b2a --- /dev/null +++ b/docs/hardware-setup/hardware-setup.md @@ -0,0 +1,8 @@ +--- +layout: default +title: Hardware Setup +nav_order: 2 +has_children: true +permalink: /docs/hardware-setup +--- + diff --git a/docs/hardware-setup/shopping-list.md b/docs/hardware-setup/shopping-list.md new file mode 100644 index 0000000..646c481 --- /dev/null +++ b/docs/hardware-setup/shopping-list.md @@ -0,0 +1,77 @@ +--- +layout: default +title: Shopping List +parent: Hardware Setup +nav_order: 1 +--- + +# Shopping List + +## Approximate Total Cost: $20,000 + +## Robot: + +| Component | Quantity | Approximate Component Cost | Suppliers | +| --------- | -------- | -------------------------- | --------- | +| Franka Emika Panda (or) Franka Research 3 | 1 | $10,500 | [Franka Robotics](https://lp.franka.de/request-a-quote) | + +## Gripper: + +| Component | Quantity | Approximate Component Cost | Suppliers | +| --------- | -------- | -------------------------- | --------- | +| 2F-85 Robotiq Gripper | 1 | $4,700 | [Robotiq Official Site](https://robotiq.com/products/2f85-140-adaptive-robot-gripper) | +| Power Supply | 1 | $13 | [Amazon US](https://www.amazon.com/SHNITPWR-Converter-Transformer-100-240V-5-5x2-5mm/dp/B07SDRDV5B/ref=sr_1_5?gclid=Cj0KCQjwkOqZBhDNARIsAACsbfLAkpfvkq7tgnpHcJb2H4Eg7Q8Df5htlSW5inOVLktYBrb2sOOB500aAsY5EALw_wcB&hvadid=174221512760&hvdev=c&hvlocphy=9031969&hvnetw=g&hvqmt=e&hvrand=18374790677584297399&hvtargid=kwd-16464769873&hydadcr=19109_9441157&keywords=24v%2B2a%2Bpower%2Bsupply&qid=1664826676&qu=eyJxc2MiOiIzLjg2IiwicXNhIjoiMy41NyIsInFzcCI6IjMuNDIifQ%3D%3D&sr=8-5&th=1) | + +## Computers: + +| Component | Quantity | Approximate Component Cost | Suppliers | +| --------- | -------- | -------------------------- | --------- | +| NUC | 1 | $500 | [Amazon US](https://www.amazon.com/NUC11PAHi7-Mainsteam-Barebone%EF%BC%8CIntel-i7-1165G7-Components/dp/B09BKRRT2Y/ref=sr_1_3?crid=MA71JDIBHYBB&keywords=NUC%2B11%2Bi7&qid=1669688069&sprefix=nuc%2B11%2Bi7%2Caps%2C192&sr=8-3&th=1) | +| Razer Blade 15 - QHD 240 Hz - GeForce RTX 4070 - Black | 1 | $2,400 | [Razer](https://www.razer.com/gaming-laptops/Razer-Blade-15/RZ09-0485ZED3-R3U1) | +| Oculus Quest | 1 | $249 | [Meta Store](https://www.meta.com/us/quest/products/quest-2/) | +| Monitor and Keyboard (no specific specification) | 1 | $100 | | + +## Cameras: + +| Component | Quantity | Approximate Component Cost | Suppliers | +| --------- | -------- | -------------------------- | --------- | +| Zed 2 | 2 | $449 | [StereoLabs](https://store.stereolabs.com/en-gb/products/zed-2?_gl=1*1corjfm*_ga*MTE0NDI2NjE3LjE2NDk5NjcwMjM.*_ga_LQLTWBS792*MTY1MDQwMjQ2NC40LjAuMTY1MDQwMjQ2NC42MA..&_ga=2.198936172.278922144.1650231923-114426617.1649967023) | +| Zed Mini | 1 | $400 | [StereoLabs](https://store.stereolabs.com/products/zed-mini?_ga=2.58413544.391576102.1670373235-292338975.1668109772&_gl=1*1ep4wi8*_ga*MjkyMzM4OTc1LjE2NjgxMDk3NzI.*_ga_LQLTWBS792*MTY3MDcwODcxNC4xMS4xLjE2NzA3MDkzMjIuNjAuMC4w) | +| ULANZI Camera Mount | 2 | $80 | [Amazon US](https://www.amazon.com/Flexible-Adjustable-Articulated-Rotatable-Aluminum/dp/B08LV7GZVB/ref=sr_1_2?crid=2HACR1JZEBPRV&keywords=camera%2Bmount%2Bsturdy&qid=1670995104&s=electronics&sprefix=camera%2Bmount%2Bsturd%2Celectronics%2C183&sr=1-2&ufe=app_do%3Aamzn1.fos.006c50ae-5d4c-4777-9bc0-4513d670b6bc&th=1) | +| Charuco Board | 1 | $114 | [Calib.io](https://calib.io/products/charuco-targets?variant=9400454807599) | +| Camera Mount Files | 1 | $0 ($2 for print materials) | [STL files](https://drive.google.com/drive/folders/1k56XVdlfrXCX4iOlFlTlkoTh-2Px6CyD) | + +## Mobile Base: + +| Component | Quantity | Approximate Component Cost | Suppliers | +| --------- | -------- | -------------------------- | --------- | +| Screw Kit | 1 | $27 | [Amazon US](https://www.amazon.com/dp/B083SGJ7BD?ref_=cm_sw_r_cp_ud_dp_AQE4AW6MK6QAQ00SE417&th=1) | +| Standing Desk | 1 | $130 | [Amazon US](https://www.amazon.com/SHW-Electric-Height-Adjustable-Computer/dp/B08668Y49C/ref=mp_s_a_1_13?crid=21JB1RSHEAYFJ&keywords=40%2Brolling%2Bstanding%2Bdesk&qid=1644355171&sprefix=40%2Brolling%2Bstanding%2Bdesk%2Caps%2C298&sr=8-13&th=1) | +| Breadboard | 1 | $100 | [Newport](https://www.newport.com/p/SA2-13) | +| Clamps | 4 | $12 | [MSCDirect](https://www.mscdirect.com/product/details/67105742?cid=ppc-google-New+-+Clamping%2C+Workholding+%26+Positioning+-+PLA_sxxmVRNtt___164124448499_c_S&mkwid=sxxmVRNtt%7Cdc&pcrid=164124448499&rd=k&product_id=67105742&gclid=CjwKCAjw8e7mBRBsEiwAPVxxiGVA1SyGmWreg4kKH1lWPj3AiQYlmnwmHUBFVUUj3xBSkY_9NFEHZxoC_XYQAvD_BwE) | +| Aluminum Bars (12 inches) | 2 | $0.35 (per inch) | [8020](https://8020.net/1010.html) | +| Screws + T-Nuts | 12 | $0.66 | [8020](https://8020.net/3393.html) | +| Screws (For FR3 Only) | 1 | $10 | [McMaster-Carr](https://www.mcmaster.com/92949A539/) | + +## Chords: + +| Component | Quantity | Approximate Component Cost | Suppliers | +| --------- | -------- | -------------------------- | --------- | +| USB port | 1 | $10 | [Amazon US](https://www.amazon.com/BYEASY-Portable-Applicable-MacBook-Notebook/dp/B07FH7XJCD/ref=mp_s_a_1_1_sspa?crid=13LJFDB63AIUY&keywords=many%2Bto%2Bone%2Busb&qid=1674798390&sprefix=many%2Bto%2Bone%2Busb%2Caps%2C689&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUE1TVhTSDhZS0dXRTImZW5jcnlwdGVkSWQ9QTA0Njg0MjVSMEpFNzBUMzBOQ1cmZW5jcnlwdGVkQWRJZD1BMDc3NDUxOTFSTFdQOFNMQjFWMEcmd2lkZ2V0TmFtZT1zcF9waG9uZV9zZWFyY2hfYXRmJmFjdGlvbj1jbGlja1JlZGlyZWN0JmRvTm90TG9nQ2xpY2s9dHJ1ZQ&th=1) | +| Ethernet Cable | 3 | $5 | [Amazon US](https://www.amazon.com/AmazonBasics-Cat-6-Gigabit-Ethernet-Internet/dp/B089MGH8T5/ref=sr_1_1_sspa?crid=NNVN8X9N4SR4&keywords=short+ethernet+cable&qid=1669691593&sprefix=short+ethernet+cable+.%2Caps%2C227&sr=8-1-spons&psc=1&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEyMEtMVEtCWE5ZUERLJmVuY3J5cHRlZElkPUEwOTk4Njk5SlQ1UUdBQkRBMkU3JmVuY3J5cHRlZEFkSWQ9QTAyMDk5NDkxMzdOTlRaM1c4VFlWJndpZGdldE5hbWU9c3BfYXRmJmFjdGlvbj1jbGlja1JlZGlyZWN0JmRvTm90TG9nQ2xpY2s9dHJ1ZQ==) | + +## Miscellaneous: + +| Component | Quantity | Approximate Component Cost | Suppliers | +| --------- | -------- | -------------------------- | --------- | +| Magnets | 1 | $20 | [Amazon US](https://www.amazon.com/Neodymium-Magnets-Double-sided-Adhesive-Rare-Earth/dp/B078KTLWQ9/ref=sr_1_6?crid=1IOM068UZ4RDK&keywords=long%2Bmagnet&qid=1670802719&sprefix=long%2Bmagne%2Caps%2C133&sr=8-6&th=1) | +| Industrial Strength Velcro | 1 | $20 | [Amazon US](https://www.amazon.com/VELCRO-Brand-Industrial-Fasteners-VEL-30838-USA/dp/B0B74YZVSN/ref=sr_1_5?crid=3U9Y5NFUBJ3IH&keywords=industrial+velcro&qid=1669691954&sprefix=industtrial+velcro%2Caps%2C138&sr=8-5) | +| Chord Wraps | 1 | $18 | [Amazon US](https://www.amazon.com/VELCRO-Brand-Industrial-Fasteners-VEL-30838-USA/dp/B0B74YZVSN/ref=sr_1_5?crid=3U9Y5NFUBJ3IH&keywords=industrial+velcro&qid=1669691954&sprefix=industtrial+velcro%2Caps%2C138&sr=8-5) | +| Chord Hanger | 1 | $18 | [Amazon US](https://www.amazon.com/VELCRO-Brand-Industrial-Fasteners-VEL-30838-USA/dp/B0B74YZVSN/ref=sr_1_5?crid=3U9Y5NFUBJ3IH&keywords=industrial+velcro&qid=1669691954&sprefix=industtrial+velcro%2Caps%2C138&sr=8-5) | +| Zip Ties | 1 | $25 | [Amazon US](https://www.amazon.com/inch-Tensile-Strength-Resistant-Self-locking/dp/B09VL2RDH9/ref=sr_1_2_sspa?crid=3VSNR598R3WIB&keywords=zip+ties&qid=1669693628&sprefix=zip+tie%2Caps%2C205&sr=8-2-spons&psc=1&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUExOU42T1k4Q0VYUk5HJmVuY3J5cHRlZElkPUEwNDM4NjAyMUpFTDVCV0lUMVZLTCZlbmNyeXB0ZWRBZElkPUEwMDIxNDY2MTZMVUpWSEtPNFNHMSZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU=) | +| Duct Tape | 1 | $8 | [Amazon US](https://www.amazon.com/Original-Strength-Duck-Silver-394475/dp/B0000DH4ME/ref=sr_1_3?crid=1BATBX7XS37IH&keywords=duct%2Btape&qid=1669693579&sprefix=duct%2Btape%2Caps%2C135&sr=8-3&th=1) | +| Cables Ties | 1 | $6 | [Amazon US](https://www.amazon.com/dp/B08TTPX4KB?ref_=cm_sw_r_cp_ud_dp_E8TXV87317XD0AXHRXZ8&th=1) | +| Power Strip | 1 | $22 | [Amazon US](https://www.amazon.com/Alestor-Protector-Outlets-Extension-Essentials/dp/B08P5LRY37/ref=mp_s_a_1_8?crid=3F3BGM9NP2U08&keywords=power%2Bstrip&qid=1674789403&sprefix=power%2Bst%2Caps%2C182&sr=8-8&th=1) | +| Extension Cord | 1 | $11 | [Amazon US](https://www.amazon.com/AmazonBasics-Extension-Cord-feet-Black/dp/B075BCD1LP/ref=mp_s_a_1_5?crid=13A81TEC0APYS&keywords=3%2Bprong%2Bextension%2Bcord&qid=1674789516&sprefix=3%2Bprong%2B%2Caps%2C376&sr=8-5&th=1) | +| Ethernet Switch | 1 | $22 | [Amazon US](https://www.amazon.com/NETGEAR-Gigabit-Ethernet-Unmanaged-1000Mbps/dp/B00KFD0SMC/ref=mp_s_a_1_9?crid=25PREBQW9BS0N&keywords=netgear+ethernet+splitter&qid=1674794661&sprefix=netgear+ethern%2Caps%2C136&sr=8-9) | + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..23cf915 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,29 @@ +--- +layout: default +title: Introduction +nav_order: 1 +--- + +# 🤖 **D**istributed **RO**bot **I**nteraction **D**ataset + +![](./assets/index/banner.jpeg) + + +## 👋 Welcome to the DROID Developer Documentation + +This goal of this documentation site is to enable robotics researchers to: + +1. Replicate the hardware of the DROID data collection platform. +2. Configure software to make the DROID data collection platform operational. +3. Onboard developers/users on using the platform and contributing data to the DROID. + +The guides for accomplishing these goals are split into the following high-level sections: + +* 🔨 **Hardware Setup:** a list of the required hardware (with links to suppliers) and a guide for assembling the platform. +* 🖥️ **Software Setup:** guides on configuring device settings and software. +* 🤖 **Example Workflows:** tutorials for common workflows (e.g. data collection, policy deployment). +* 📈 **Dataset Schema:** an outline of the schema of DROID. +* 📖 **Contribution Guidelines:** guidelines for contributing data to DROID. + + + diff --git a/docs/software-setup/docker.md b/docs/software-setup/docker.md new file mode 100644 index 0000000..99a09c2 --- /dev/null +++ b/docs/software-setup/docker.md @@ -0,0 +1,156 @@ +--- +layout: default +title: Running Application through Docker +has_children: false +nav_order: 2 +parent: Software Setup +--- + + +This guide commences with outlining the configuration of your Franka robot arm. Following this we detail the configuration of the Oculus Quest. We then outline the software setup for the NUC which interfaces directly with the Franka control unit and finally the laptop which runs the GUI application and client software. + +
+ + Table of contents + + {: .text-delta } +1. TOC +{:toc} +
+ +# Configuring the Franka robot + +## Franka World Account + +A Franka World account is used to manage Franka robot arms and associated firmware updates. You may login to Franka World or register and account at the following [portal](https://franka.world/). + +Thankfully Franka Robotics have provided a tutorial on registering and synchronizing software for your Franka robot on Franka World. Please follow this tutorial to set up your robot arm: + + + +Importantly, after the above tutorial, it is necessary to ensure that the Franka Control Interface (FCI) feature is installed on your robot. Further information on this interface which Franka Robotics expose is found in the guide below: + + + +## Operating the Robot + +Please refer to the Franka Robotics [Getting Started Guide](https://frankaemika.github.io/docs/getting_started.html) to perform the initial setup and operation of your robot arm. At this point it is worthwhile noting the details of how to activate and deactivate FCI for your robot, these details can be found [here](https://frankaemika.github.io/docs/getting_started.html#preparing-the-robot-for-fci-usage-in-desk). + + +## Updating Inertia Parameters for Robotiq Gripper + +In order to accurately represent the robot model with the Robotiq gripper we need to update the end-effector configuration. From the Desk UI you may access this option under Settings > End-Effector as outlined [here](https://facebookresearch.github.io/fairo/polymetis/troubleshooting.html#end-effector-configuration). + +Please add the following [configuration file](https://github.com/frankaemika/external_gripper_example/blob/master/panda_with_robotiq_gripper_example/config/endeffector-config.json) via the UI. + +# Configuring the Oculus Quest + +The Oculus will be used to run an application that tracks the pose of hand-held controllers which we use to teleoperate the robot. + +The first step to setting up your Oculus Quest is to associate a Meta account with the device. You may create an account at the following [portal](https://secure.oculus.com/sign-up/). Once you've created a Meta account you also need to register as a Meta developer, a guide for accomplishing this can be found [here](https://developers.facebook.com/docs/development/register/). + +Once you have a meta developer account, you are ready to begin enabling developer mode on your Oculus device. Developer mode is required to run a custom application for the Oculus Quest which we use as part of the DROID platform. For instructions on enabling developer mode on your Oculus device please see the following [guide](https://developer.oculus.com/documentation/native/android/mobile-device-setup/). + +Later in this guide we will detail how to run the required application on the Oculus, for now the device setup is complete. + +# Configuring the NUC + +The NUC device is used to run the polymetis controller manager server. This server manages translating commands from the user client to the robot client. A high-level schematic outling the controller manager is given below, further details can also be found [here](https://facebookresearch.github.io/fairo/polymetis/overview.html): + +image + +In order to gain an understanding of the various components being installed it is worthwhile working through this section. If you are less concerned with understanding individual software dependencies and their function using the automated install script is more time efficient. + +## Booting with Ubuntu 22.04 + +We will install Ubuntu 22.04 through flashing a USB with Ubuntu 22.04 and using this flased USB drive as the install medium. + +You may use the following [application](https://etcher.balena.io/) to flash a USB drive with the Ubuntu OS image. Download this application on a device other than the laptop/workstation as we don't want to include any unnecessary applications on this device. Follow the official [Ubuntu Installation guide](https://ubuntu.com/tutorials/install-ubuntu-desktop#1-overview) to set up the USB flashdrive and install the Ubuntu OS (22.04). + +When installing Ubuntu, set the computer password `robot` and enable the `Log in automatically` setting. + +## Ubuntu Pro Token + +In order to simplify the process of performing a RT patch of the Ubuntu Kernel we leverage Ubuntu Pro. Generate an Ubuntu Pro token through following the section 3 called "Get your free Ubuntu pro subscription" from the following [guide](https://ubuntu.com/pro/tutorial). We will use this token to activate Ubuntu pro and activate an RT patched kernel on our machine. + +## Configure Parameters + +Complete all parameters in `./r2d2/misc/parameters.py`. + +Start by specifying static IP addresses for all the machines on the platform (NUC, laptop, control unit). + +Add the sudo password for the machine you are using (only relevant for the NUC machine). + +Set the type and serial number of your robot. The serial number for your robot can be found on the control box unit. + +If this is your first time setting up the platform you can ignore the camera ids as you will need to load the GUI to generate these. + +Set the Charuco board parameters to match the board you are using. + +Provide an Ubuntu Pro token (required to automate rt-patch of kernel on the NUC). + +## Run Setup Script + +To complete the device setup execute the setup script through running the following: + +```bash +./scripts/setup/nuc_setup.sh +``` + +# Configuring the Laptop/Workstation + +The laptop/workstation device manages the execution of the Oculus Quest application, camera data and user client code including a GUI application. Recalling the Polymetis diagram from earlier, all the user client code is run on this device. + +image + +## Booting with Ubuntu 22.04 + +We will install Ubuntu 22.04 through flashing a USB with Ubuntu 22.04 and using this flased USB drive as the install medium. + +You may use the following [application](https://etcher.balena.io/) to flash a USB drive with the Ubuntu OS image. Download this application on a device other than the laptop/workstation as we don't want to include any unnecessary applications on this device. Follow the official [Ubuntu Installation guide](https://ubuntu.com/tutorials/install-ubuntu-desktop#1-overview) to set up the USB flashdrive and install the Ubuntu OS (22.04). + +When installing Ubuntu, set the computer password `robot` and enable the `Log in automatically` setting. + +## Ubuntu Pro Token + +In order to simplify the process of performing a RT patch of the Ubuntu Kernel we leverage Ubuntu Pro. Generate an Ubuntu Pro token through following the section 3 called "Get your free Ubuntu pro subscription" from the following [guide](https://ubuntu.com/pro/tutorial). We will use this token to activate Ubuntu pro and activate an RT patched kernel on our machine. + +## Configure Parameters + +Complete all parameters in `./r2d2/misc/parameters.py`. + +Start by specifying static IP addresses for all the machines on the platform (NUC, laptop, control unit). + +Add the sudo password for the machine you are using (only relevant for the NUC machine). + +Set the type and serial number of your robot. The serial number for your robot can be found on the control box unit. + +If this is your first time setting up the platform you can ignore the camera ids as you will need to load the GUI to generate these. + +Set the Charuco board parameters to match the board you are using. + +Provide an Ubuntu Pro token (required to automate rt-patch of kernel on the NUC). + +## Run Setup Script + +To complete the device setup execute the setup script through running the following: + +```bash +./scripts/setup/laptop_setup.sh +``` + +# Testing/Validating Entire Setup + +In order to validate your device setup we will attempt to collect a trajectory. Start by running the NUC server machine through running the corresponding Docker container: + +```bash +cd .docker/nuc +docker compose -f docker-compose-nuc.yaml up +``` + +Next run the test script for collecting a trajectory on the laptop through running the test Docker container: + +```bash +cd .docker/laptop +docker compose -f docker-compose-laptop.yaml run laptop_setup python scripts/test/collect_trajectory.py +``` diff --git a/docs/software-setup/host-installation.md b/docs/software-setup/host-installation.md new file mode 100644 index 0000000..bd78aeb --- /dev/null +++ b/docs/software-setup/host-installation.md @@ -0,0 +1,289 @@ +--- +layout: default +title: Running Application on Host +has_children: false +nav_order: 1 +parent: Software Setup +--- + +This guide commences with outlining the configuration of your Franka robot arm. Following this we detail the configuration of the Oculus Quest. We then outline the software setup for the NUC which interfaces directly with the Franka control unit and finally the laptop which runs the GUI application and client software. + +
+ + Table of contents + + {: .text-delta } +1. TOC +{:toc} +
+ +# Configuring the Franka robot + +## Franka World Account + +A Franka World account is used to manage Franka robot arms and associated firmware updates. You may login to Franka World or register and account at the following [portal](https://franka.world/). + +Thankfully Franka Robotics have provided a tutorial on registering and synchronizing software for your Franka robot on Franka World. Please follow this tutorial to set up your robot arm: + + + +Importantly, after the above tutorial, it is necessary to ensure that the Franka Control Interface (FCI) feature is installed on your robot. Further information on this interface which Franka Robotics expose is found in the guide below: + + + +## Operating the Robot + +Please refer to the Franka Robotics [Getting Started Guide](https://frankaemika.github.io/docs/getting_started.html) to perform the initial setup and operation of your robot arm. At this point it is worthwhile noting the details of how to activate and deactivate FCI for your robot, these details can be found [here](https://frankaemika.github.io/docs/getting_started.html#preparing-the-robot-for-fci-usage-in-desk). + + +## Updating Inertia Parameters for Robotiq Gripper + +In order to accurately represent the robot model with the Robotiq gripper we need to update the end-effector configuration. From the Desk UI you may access this option under Settings > End-Effector as outlined [here](https://facebookresearch.github.io/fairo/polymetis/troubleshooting.html#end-effector-configuration). + +Please add the following [configuration file](https://github.com/frankaemika/external_gripper_example/blob/master/panda_with_robotiq_gripper_example/config/endeffector-config.json) via the UI. + +# Configuring the Oculus Quest + +The Oculus will be used to run an application that tracks the pose of hand-held controllers which we use to teleoperate the robot. + +The first step to setting up your Oculus Quest is to associate a Meta account with the device. You may create an account at the following [portal](https://secure.oculus.com/sign-up/). Once you've created a Meta account you also need to register as a Meta developer, a guide for accomplishing this can be found [here](https://developers.facebook.com/docs/development/register/). + +Once you have a meta developer account, you are ready to begin enabling developer mode on your Oculus device. Developer mode is required to run a custom application for the Oculus Quest which we use as part of the DROID platform. For instructions on enabling developer mode on your Oculus device please see the following [guide](https://developer.oculus.com/documentation/native/android/mobile-device-setup/). + +Later in this guide we will detail how to run the required application on the Oculus, for now the device setup is complete. + +# Configuring the NUC + +The NUC device is used to run the polymetis controller manager server. This server manages translating commands from the user client to the robot client. A high-level schematic outling the controller manager is given below, further details can also be found [here](https://facebookresearch.github.io/fairo/polymetis/overview.html): + +image + +## Booting with Ubuntu 18.04 + +We will install Ubuntu 18.04 through flashing a USB with Ubuntu 18.04 and using this flased USB drive as the install medium. + +You may use the following [application](https://etcher.balena.io/) to flash a USB drive with the Ubuntu OS image. Download this application on a device other than the NUC as we don't want to include any unnecessary applications on the NUC (e.g. personal laptop). Follow the official [Ubuntu Installation guide](https://ubuntu.com/tutorials/install-ubuntu-desktop#1-overview) to set up the USB flashdrive and install the Ubuntu OS (18.04) on the NUC. + +When installing Ubuntu, set the computer password `robot` and enable the `Log in automatically` setting. + +## Configuring Static IP Address + +To set the static IP for the NUC, enter Settings > Network and click the add wired connection option (through clicking the + option under the Wired heading). Click the IPv4 tab; under IPv4 method select manual. Set the Address to 172.16.0.2 and the netmask to 255.255.255.0. Click apply to create this static IP address. + +## Performing RT Patch of Kernel + +In order to ensure that real-time priorities set in the libfranka codebase are respected we need to perform a Real-Time (RT) patch of the default kernel. For this section we will be following the [official guide](https://frankaemika.github.io/docs/installation_linux.html#setting-up-the-real-time-kernel) provided by Franka Robotics. + +To ensure, you replicate the same setup as the original DROID platform implementation start by installing dependencies with: + +```bash +sudo apt-get install build-essential bc curl ca-certificates gnupg2 libssl-dev lsb-release libelf-dev bison flex dwarves zstd libncurses-dev +``` + +Following the installation of dependencies, install a kernel patch that has been tested with the DROID platform: + +```bash +curl -SLO [https://mirrors.edge.kernel.org/pub/linux/kernel/v5.x/linux-5.4.70.tar.xz](https://mirrors.edge.kernel.org/pub/linux/kernel/v5.x/linux-5.4.70.tar.xz) +curl -SLO [https://mirrors.edge.kernel.org/pub/linux/kernel/projects/rt/5.4/older/patch-5.4.70-rt40.patch.xz](https://mirrors.edge.kernel.org/pub/linux/kernel/projects/rt/5.4/older/patch-5.4.70-rt40.patch.xz) +xz -d *.xz +``` + +Follow the official Franka Robotics guide from the [Compiling the kernel](https://frankaemika.github.io/docs/installation_linux.html#compiling-the-kernel) section onwards, using the kernel patch that was installed above. + +## CPU Frequency Scaling + +Most CPUs are by default configured to use a lower operating frequency, we wish to override this setting in order to increase the operating frequenecy and as a result reduce the latency when interfacing with libfranka. Follow this [section](https://frankaemika.github.io/docs/troubleshooting.html#disabling-cpu-frequency-scaling) of the official Franka Robotics guides to disable CPU frequency scaling. + + +## Configuring Python Virtual Environment (Conda) + +We will use Conda as the package manager for our python virtual environment. You can install Conda from the following [link](https://docs.conda.io/projects/conda/en/latest/user-guide/install/linux.html). Once you've installed Conda, ensure that you have configured git on the NUC so you can pull software packages from GitHub. A guide on configuring git is provided [here](https://docs.github.com/en/get-started/getting-started-with-git/set-up-git#setting-up-git). + +Next, we will commence with setting up the Polymetis library. The following [guide](https://facebookresearch.github.io/fairo/polymetis/installation.html#for-advanced-users-developers) details how to build Polymetis, we will be following this guide. + +The first step of the linked guide requires you to clone the fairo repository. We have included a pinned version of the library with the R2D2 main repository as a git submodule. Clone the R2D2 repository and submodules with the following command: + +```bash +git clone git@github.com:AlexanderKhazatsky/R2D2.git +# sync and pull submodules +git submodule sync +git submodule update --remote --init --recursive +``` + +You should now find the fairo repository at `r2d2/fairo`, from this point continue with steps 2 and 3 of the polymetis guide. + +In step 4, when building libfranka from source, it is crucial to fix the version of libfranka you are using to one that is compatible with the robot you are using, see the below table for a list of robot hardware and libfranka version compatibility: + +| Robot | libfranka Version | +| --------- | -------- | +| Franka Emika Panda | 0.9.0 | +| Franka Research 3 | 0.10.0 | + +In order to install a specific libfranka version (e.g. 0.10.0) using the linked guide, you can run the `build_libfranka` script as follows: + +```bash +./scripts/build_libfranka.sh 0.10.0 +``` + +When building the polymetis from source with CMAKE, be sure to set all setting to `ON`: + +```bash +cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_FRANKA=ON -DBUILD_TESTS=ON -DBUILD_DOCS=ON +make -j +``` + +Now that Polymetis is built, we will add other dependencies to our conda virtual environment. + +Now that polymetis is built we will commence with installing the remaining dependencies for our python virtual environment. From the root directory of this repository, with the python virtual environment created during polymetis build activated run the following command to install remaining dependencies: + +```bash +pip install -e . + +# Done like this to avoid dependency issues +pip install dm-robotics-moma==0.5.0 --no-deps +pip install dm-robotics-transformations==0.5.0 --no-deps +pip install dm-robotics-agentflow==0.5.0 --no-deps +pip install dm-robotics-geometry==0.5.0 --no-deps +pip install dm-robotics-manipulation==0.5.0 --no-deps +pip install dm-robotics-controllers==0.5.0 --no-deps +``` + +The next step is to ensure the the project config files reference the robot you are using. First we will update the robot client config file and after this we will update the robot model config file. Please find links to the required config files below: + +| Robot | Config Files | +| --------- | -------- | +| Franka Emika Panda | [config files](https://drive.google.com/drive/folders/1wXTQQbFKjd9ed3yKxB4td9GzA_XrR7Xk) | +| Franka Research 3 | [config files](https://drive.google.com/drive/folders/178-MJTAVV0m5_RDs2ScUNcYameGDA0Eg) | + +We will start by updating the robot client config file. To do so go into `fairo/polymetis/polymetis/conf/robot_client` and delete the existing `franka_hardware.yaml` file. Replace this file with `franka_hardware[robot_name].yaml` from the linked config files folder. Rename this file to `franka_hardware.yaml`. Finally, edit this `franka_hardware.yaml` file and replace `executable_cfg.robot_ip` to match you Franka control box's IP address. + +Next we will update the robot model config file. To do so go into `fairo/polymetis/polymetis/conf/robot_model` and delete the existing `franka_panda.yaml` file. Replace this file with `franka_panda[robot_name].yaml` from the linked config files folder. Rename this file to `franka_panda.yaml`. + +Update the IP parameters in `droid/misc/parameters.py`, in particular set `robot_ip` to match the IP address of your robot and `nuc_ip` to match the IP address of your NUC. Also set the `sudo_password` to match your machine's sudo password (sudo access is required to launch the robot). Finally update the `robot_type` parameter to `panda` or `fr3` depending on which robot you are using. + +If you choose to install miniconda instead of anaconda in previous steps of this guide you will need to make the following edits: + +In r2d2/franka change the word anaconda to minicode in the scripts `launch_gripper.sh` and `launch_robot.sh`. Also change the paths to be absolute. Repeat for the `launch_server.sh` file in `scripts/server` + +## Optional: Configure Headless Server + +When you have validated your entire setup you may wish to make the NUC a headless server such that you don't need to manually run commands to start the control server. + +From the terminal enter `crontab -e` and add the ollowing line to the bottom of the file: + +``` +@reboot bash [YOUR PATH TO DROID]/scripts/server/launch_server.sh +``` + +You may remove any displays associated with your NUC once you have configured it to run as a headless server. + +# Configuring the Laptop/Workstation + +The laptop/workstation device manages the execution of the Oculus Quest application, camera data and user client code including a GUI application. Recalling the Polymetis diagram from earlier, all the user client code is run on this device. +image + +## Booting with Ubuntu 22.04 + +We will install Ubuntu 22.04 through flashing a USB with Ubuntu 22.04 and using this flased USB drive as the install medium. + +You may use the following [application](https://etcher.balena.io/) to flash a USB drive with the Ubuntu OS image. Download this application on a device other than the laptop/workstation as we don't want to include any unnecessary applications on this device. Follow the official [Ubuntu Installation guide](https://ubuntu.com/tutorials/install-ubuntu-desktop#1-overview) to set up the USB flashdrive and install the Ubuntu OS (22.04). + +When installing Ubuntu, set the computer password `robot` and enable the `Log in automatically` setting. + +## Configuring Static IP Address + +To set the static IP for the laptop, enter Settings > Network and click the add wired connection option (through clicking the + option under the Wired heading). Click the IPv4 tab; under IPv4 method select manual. Set the Address to 172.16.0.1 and the netmask to 255.255.255.0. Click apply to create this static IP address. + +## Configuring Python Virtual Environment (Conda) + +We will use Conda as the package manager for our python virtual environment. You can install Conda from the following [link](https://docs.conda.io/projects/conda/en/latest/user-guide/install/linux.html). Once you've installed Conda, ensure that you have configured git on the NUC so you can pull software packages from GitHub. A guide on configuring git is provided [here](https://docs.github.com/en/get-started/getting-started-with-git/set-up-git#setting-up-git). + +Clone the R2D2 repository and submodules with the following command: + +```bash +git clone git@github.com:AlexanderKhazatsky/R2D2.git +# sync and pull submodules +git submodule sync +git submodule update --remote --init --recursive +``` + +Next create and activate a conda environment called `robot` with python 3.7 through running the following commands: + +```bash +conda create -n "robot" python=3.7 +conda activate robot +``` + +Ensure that GCC is installed through running the following commands: + +```bash +sudo apt update +sudo apt install build-essential +``` + +Verify your installation through running (you should observe a version returned): + +```bash +gcc --version +``` + +Next we will install the ZED SDK and python API which is required to interface with ZED cameras. Follow the official guide outlined [here](https://www.stereolabs.com/docs/installation/linux), while adhering to the below instructions during your installation: + +* Ensure you have the robot conda environment activated +* Enter yes when prompted to install CUDA +* Enter yes to everything else during the installation procedure with the exception of optimizing ZED models this is optiona + +Once you have restarted your machine post installation, activate the robot conda environment and test that you can import pyzed through running: + +```bash +python -c "import pyzed" +``` + +The software for the Oculus application is included under `r2d2/oculus_reader` as a git submodule. Start by installing the oculus reader dependencies into the current virtual environment through running: + +```bash +pip install -e ./r2d2/oculus_reader +``` + +Next, install the android debug bridge software dependency required to interface with your Oculus Quest through running: + +```bash +sudo apt install android-tools-adb +``` + +Finally from the root directory of the project repository, with the python virtual environment activated run the following command to install remaining dependencies: + +```bash +pip install -e . + +# Done like this to avoid dependency issues +pip install dm-robotics-moma==0.5.0 --no-deps +pip install dm-robotics-transformations==0.5.0 --no-deps +pip install dm-robotics-agentflow==0.5.0 --no-deps +pip install dm-robotics-geometry==0.5.0 --no-deps +pip install dm-robotics-manipulation==0.5.0 --no-deps +pip install dm-robotics-controllers==0.5.0 --no-deps +``` + +Update the IP parameters in `droid/misc/parameters.py`, in particular set `robot_ip` to match the IP address of your robot and `nuc_ip` to match the IP address of your NUC. In addition, set the `robot_serial_number` to match your robot's serial number (found on your franka website, under Settings -> Franka World -> Control S/N). For the `robot_type variable`, enter 'fr3' or 'panda' depending on which Franka robot you are using. Update the Charuco board parameters to match the board you are using. Finally you will need to set the camera ids in this parameters file further details on how to accomplish this are provided later in the guide. + +If you choose to install miniconda instead of anaconda in previous steps of this guide you will need to make the following edits: + +In r2d2/franka change the word anaconda to minicode in the scripts `launch_gripper.sh` and `launch_robot.sh`. Also change the paths to be absolute. Repeat for the `launch_server.sh` file in `scripts/server` + + +# Testing/Validating Entire Setup + +In order to validate your device setup we will attempt to collect a trajectory. Start by running the NUC server machine through running the following commands: + +```bash +conda activate polymetis-local +python scripts/server/run_server.py +``` + +With the control server running on the NUC, run the script for testing trajectory collection with: + +```bash +conda activate robot +python scripts/test/collect_trajectory.py +``` diff --git a/docs/software-setup/software-setup.md b/docs/software-setup/software-setup.md new file mode 100644 index 0000000..b808e76 --- /dev/null +++ b/docs/software-setup/software-setup.md @@ -0,0 +1,13 @@ +--- +layout: default +title: Software Setup +has_children: true +nav_order: 3 +permalink: /docs/software-setup +--- + +There are two methods of running DROID, one can run the application software directly on the host machine or through Docker. + +Running DROID software directly on the host machine requires additional steps in the software installation process but is worthwhile in the case where machines are dedicated to the DROID setup as it forgoes the need to launch and manage Docker containers. + +Running DROID software through Docker requires less manual software installation steps and allows for machines to easily be repurposed for other sets of software as application software isn't dependent on host environment configuration. Running the application software through Docker does however require an understanding of Docker the management of Docker containers.