ros-mobile-robots · fjp · Mar 20, 2022 · Mar 20, 2022 · Mar 20, 2022 · Mar 20, 2022
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1 @@
+docs/hardware_setup/images/*.svg filter=lfs diff=lfs merge=lfs -text
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -34,5 +34,6 @@ jobs:
       - name: build documentation
         run: mkdocs build
       - name: deploy documentation
+        # Deploy only on main branch, not on feature branches or pull requests
         if: ${{ github.ref == 'refs/heads/main' }}
         run: mkdocs gh-deploy --force
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+venv
diff --git a/docs/components.md b/docs/components.md
@@ -8,6 +8,8 @@ tags: [2wd, differential drive, robot, ros, noetic, raspberry, pi, autonomous, s
 
 ## BOM for REMO Robot
 
+--8<-- "docs/links.md"
+
 The following figure shows a 3D-printed Remo robot together with its components that
 satisfy the requirements for the ROS Navigation Stack. These parts are introduced next:
 
@@ -20,28 +22,30 @@ Bill of Materials (BOM) for [REMO robot](packages/remo_description.md):
 
 | **Part**                | **Quantity** | **Cost** | **Store** | **Notes** |
 |:------------------------|:------------:| --- |  --- |  --- |
-| Raspberry Pi 4 B (4 Gb) | 1 | $55.0 | [Sparkfun](https://www.sparkfun.com/products/15447), [Amazon.com](https://amzn.to/3L6PZ14), [Amazon.de](https://amzn.to/2IchIAc) | |
-| SanDisk 64 GB SD Card Class 10 | 1 | $13.99 | [Amazon.com](https://amzn.to/4eSkqWv), [Amazon.de](https://amzn.to/3dcFmYE) | |
-| SLAMTEC RPLiDAR A2M8 (12 m) | 1 | $319.00 | [Robotshop](https://www.robotshop.com/en/rplidar-a2m8-360-laser-scanner.html), [Amazon.com](https://amzn.to/3VSEBLe), [Amazon.de](https://amzn.to/30MyImR) | Other, less expensive, LiDARs will work as well, e.g., RPLiDAR A1 |
-| Adafruit DC Motor (+ Stepper) FeatherWing  | 1 | $19.95 | [adafruit.com](https://www.adafruit.com/product/2927), [Amazon.de](https://amzn.to/3km5KF3) | |
-| Teensy 4.0 or 3.2 | 1 | $19.95 | [PJRC Teensy 4.0](https://www.pjrc.com/store/teensy40.html), [PJRC Teensy 3.2](https://www.pjrc.com/store/teensy32.html) | |
-| Hobby Motor with Encoder - Metal Gear (DG01D-E) | 2 | $5.95 | [Sparkfun](https://www.sparkfun.com/products/16413) | |
-| Powerbank (e.g 15000 mAh) | 1 | $15.99 | [Amazon.de](https://amzn.to/3kmkx2t) | This Powerbank from Goobay is close to the maximum possible size LxWxH: 135.5x70x18 mm |
-| Battery pack (for four or eight batteries) | 1 | $5.59 |  [Amazon.de](https://amzn.to/3kiX8PH) | |
-| USB cable pack | 1 | $6.99 | [Amazon](http://amzn.com/B01N337FQF/) | Type A to Micro, right angle |
+| Raspberry Pi 4 B (4 Gb) | 1 | $55.0 | [Sparkfun](https://www.sparkfun.com/products/15447), [Amazon.com][amazon_rpi_4_us], [Amazon.de][amazon_rpi_4_ger] | |
+| SanDisk 64 GB SD Card Class 10 | 1 | $13.99 | [Amazon.com][sandisk_64gb_us], [Amazon.de][sandisk_64gb_ger] | |
+| SLAMTEC RPLiDAR A2M12 (12 m) | 1 | $319.00 | [Robotshop](https://www.robotshop.com/en/rplidar-a2m8-360-laser-scanner.html), [Amazon.com][amazon_rplidar_a2m12_us], [Amazon.de][amazon_rplidar_a2m12_ger] | Other, less expensive, LiDARs will work as well, e.g., RPLiDAR A1 |
+| SLAMTEC RPLiDAR A1M8 (12 m) | 1 | $99.00 | [Robotshop](https://www.robotshop.com/en/rplidar-a1m8-360-laser-scanner.html), [Amazon.com][amazon_rplidar_a1m8_us], [Amazon.de][amazon_rplidar_a1m8_ger] | Cheaper alternative to RPLiDAR A2M8 |
+| Adafruit DC Motor (+ Stepper) FeatherWing  | 1 | $19.95 | [adafruit.com](https://www.adafruit.com/product/2927), [Amazon.us][amazon_ada2927_us], [Amazon.de][amazon_ada2927_ger] | |
+| Teensy 4.0 or 3.2 | 1 | $32.29 | [Amazon.com][amazon_teensy_4.0_us], [Amazon.de][amazon_teensy_4.0_ger], [PJRC Teensy 4.0](https://www.pjrc.com/store/teensy40.html) | |
+| Hobby Motor with Encoder - Metal Gear (DG01D-E) | 2 | $12.50 | [Amazon.com][amazon_hobby_motor_us], [Sparkfun](https://www.sparkfun.com/products/16413) | |
+| Powerbank (e.g 15'000 mAh, or 10'000 mAh) | 1 | $23.99 | [Anker 10K Amazon.com][amazon_anker_powerbank_pc10k_us], [Anker 10K Amazon.de][amazon_anker_powerbank_pc10k_ger], [Amazon.de](https://amzn.to/3kmkx2t) | The Powerbank from Goobay (and Anker) is close to the maximum possible size LxWxH: 135.5 x 71 x 18 mm |
+| Battery pack (for four or eight batteries) | 1 | $5.59 |  [Amazon.com][amazon_battery_holder_8x_aa_us], [Amazon.de][amazon_battery_holder_8x_aa_ger] | |
+| USB C to USB C cable | 1 | $6.99 | [Amazon.com][amazon_usb_c_cable_50cm_us], [Amazon.de][amazon_usb_c_cable_50cm_ger] | USB C to USB C for Powerbank to [SBC](https://en.wikipedia.org/wiki/Single-board_computer) |
 | Remo Base  | 1 | -- | 3D printable, see [`remo_description`](https://github.com/ros-mobile-robots/remo_description) | |
-| Caster ball | 1 | $6.30 | [Amazon.com](http://amzn.com/B01N2S7CX6/), [Amazon.de](https://amzn.to/3Ie7Non) | 25.4 mm (1-inch) diameter; Alternatively any smooth, durable 3/4" [ball bearing](https://amzn.to/3FyT2Nm) for the caster |
-| Wheels      | 2 | $3.50 | [Sparkfun](https://www.sparkfun.com/products/13259), [exp-tech.de](https://www.exp-tech.de/plattformen/robotik/sonstige/6536/wheel-65mm-rubber-tire-pair) | Wheels are often part of a [robotics kit](https://joy-it.net/en/products/robot05) or can be purchased separately |
-| Power supply | 1 | $7.50 | [Adafruit](http://bit.ly/af1995) | Micro USB, 5V, 2.5A |
+| Caster ball | 1 | $6.30 | [Amazon.com][amazon_caster_ball], [Amazon.de][amazon_caster_ball_ger] | 25.4 mm (1-inch) diameter; Alternatively any smooth, durable 3/4" [ball bearing][amazon_ball_bearing_ger] for the caster |
+| Wheels      | 2 | $3.50 | [Amazon.com][amazon_wheels_us], [Amazon.de][amazon_wheels_ger], [Sparkfun](https://www.sparkfun.com/products/13259), [exp-tech.de](https://www.exp-tech.de/plattformen/robotik/sonstige/6536/wheel-65mm-rubber-tire-pair) | Wheels are often part of a [robotics kit](https://joy-it.net/en/products/robot05) or can be purchased separately |
+| Power supply | 1 | $7.50 | [Amazon.com][amazon_power_supply_us], [Amazon.de][amazon_power_supply_ger] | USB C, 5V, 3.5A |
 
 ### USB Wi-Fi Dongle (optional)
 
 For improved connectivity use a Wi-Fi USB dongle.
 
 |  **Part** | **Quantity** | **Cost** | **URL** | **Notes** |
 | --- | --: | --: | --- | --- |
-| WiFi Dongle - TP-Link Archer T2U Nano | 1 | $17.99 | [Amazon](https://amzn.to/4f2F3PV) | RTL8811AU chipset |
-| WiFi Dongle - TP-Link Archer T2U Plus | 1 | $19.99 | [Amazon](https://amzn.to/4cuxwaS) | RTL8811AU chipset |
+| WiFi Dongle - TP-Link Archer T2U Nano | 1 | $17.99 | [Amazon.us][amazon_wifi_t2u_nano_us], [Amazon.de][amazon_wifi_t2u_nano_ger] | RTL8811AU chipset |
+| WiFi Dongle - TP-Link Archer T3U | 1 | $18.99 | [Amazon.us][amazon_wifi_t3u_us], [Amazon.de][amazon_wifi_t3u_ger] | RTL8812AU chipset |
+| WiFi Dongle - TP-Link Archer T3U Plus | 1 | $19.99 | [Amazon.us][amazon_wifi_t3u_plus_us], [Amazon.de][amazon_wifi_t3u_plus_ger] | RTL8811AU chipset |
 
 
 ### Camera Modules (optional)
@@ -51,7 +55,7 @@ Get a camera in case you plan to do applications such as object detection, visua
 
 | **Part**                | **Quantity** | **Cost** | **Store** | **Notes** |
 |:------------------------|:------------:| --- |  --- |  --- |
-| Raspi Camera Module V2, 8 MP, 1080p | 1 | $ | [Amazon.com](https://amzn.to/4cPB9YH), [Amazon.de](https://amzn.to/2FdVDQF) | |
+| Raspi Camera Module V2, 8 MP, 1080p | 1 | $ | [Amazon.com][amazon_rpi_cam_v2_us], [Amazon.de][amazon_rpi_cam_v2_ger] | |
 | OAK-1 | 1 | $149 | [OpenCV.ai](https://store.opencv.ai/products/oak-1) | |
 | OAK-D | 1 | $199 | [OpenCV.ai](https://store.opencv.ai/products/oak-d) | |
 | OAK-D Lite | 1 | -- | [OpenCV.ai](https://store.opencv.ai/products/oak-d-lite) | Will be released |

diff --git a/docs/hardware_setup/3D_print.md b/docs/hardware_setup/3D_print.md
@@ -0,0 +1,101 @@
+# 3D Printing
+
+This page provides help to 3D print the parts of Remo robot. It contains information
+about configuring your slicer, suggestions to orient the parts and where support material is recommended to avoid
+failing prints and wasted PLA material.
+
+The table below gives an overview of the required parts of Remo and the average printing time:
+
+!!! note
+    Remo robot is a modular robotics platform which means you don't have to print all parts.
+    It is often possible to choose between different variants. For example:
+
+    - SBC Deck
+    - LiDAR Platform
+    - Camera Mount
+
+
+| Qt | Part                                                |  File                                                | Material | Time  | Notes                                 |
+|:--:|:----------------------------------------------------|:-----------------------------------------------------|:---------|:-----:|:--------------------------------------|
+| 1  | [Chassis](#chassis)                                 | `chassis.stl`                                        | PLA      |       |                                       |
+| 1  | [Caster wheel](#caster-wheel)                       | `caster_base_65mm.stl` and `caster_shroud_65mm.stl`  | PLA      |       | Print both parts of the caster wheel  |
+| 1  | [SBC Decks](#sbc-decks)                             | `raspberry_pi_deck.stl` or `jetson_nano_deck.stl`    | PLA      |       | Select one depending on used SBC      |
+| 1  | [LiDAR Platform](#lidar-platform)                   | `platfom_rplidar_a2.stl` or `platfom_rplidar_a1.stl` | PLA      |       | Select one dependin on used LiDAR     |
+| 1  | [SLAMTEC USB to Serial holder](#lidar-platform)     | `slamtec_holder.stl` or `jetson_nano_deck.stl`       | PLA      |       |                                       |
+| 1  | [Camera Mount](#camera-mount)                       | `camera_mount.stl`                                   | PLA      |       |                                       |
+
+## Chassis
+
+<script src="https://embed.github.com/view/3d/ros-mobile-robots/remo_description/main/meshes/remo/chassis.stl"></script>
+
+
+## Caster Wheel
+
+| Qty | Part | 3D View |
+|:---:|:-----|:-------:|
+| 1   | [`caster_base_65mm.stl`](https://github.com/ros-mobile-robots/remo_description/blob/main/meshes/remo/caster/caster_base_65mm.stl) | <script src="https://embed.github.com/view/3d/ros-mobile-robots/remo_description/main/meshes/remo/caster/caster_base_65mm.stl"></script> |
+
+## SBC Decks
+
+Currently there are two different decks you can print, depending on which SBC you are will use:
+
+=== "RPi Deck"
+
+    | Qty | Part | 3D View |
+    |:---:|:-----|:-------:|
+    | 1   | [`platfom_rplidar_a2.stl`](https://github.com/ros-mobile-robots/remo_description/blob/main/meshes/remo/deck/raspberry_pi_deck.stl) | <script src="https://embed.github.com/view/3d/ros-mobile-robots/remo_description/main/meshes/remo/deck/raspberry_pi_deck.stl"></script> |
+
+
+
+=== "Jetson Nano Deck"
+
+    | Qty | Part | 3D View |
+    |:---:|:-----|:-------:|
+    | 1   | [`jetson_nano_deck.stl`](https://github.com/ros-mobile-robots/remo_description/blob/main/meshes/remo/deck/jetson_nano_deck.stl) | <script src="https://embed.github.com/view/3d/ros-mobile-robots/remo_description/main/meshes/remo/deck/jetson_nano_deck.stl"></script> |
+
+
+## LiDAR Platform
+
+
+=== "RPLiDAR A2 M8"
+
+    | Qty | Part | 3D View |
+    |:---:|:-----|:-------:|
+    | 1   | [`platfom_rplidar_a2.stl`](https://github.com/ros-mobile-robots/remo_description/blob/main/meshes/remo/lidar_platform/platfom_rplidar_a2.stl) | <script src="https://embed.github.com/view/3d/ros-mobile-robots/remo_description/main/meshes/remo/lidar_platform/platfom_rplidar_a2.stl"></script> |
+
+    | Qty | Part | 3D View |
+    |:---:|:-----|:-------:|
+    | 1   | [`slamtec_holder.stl`](https://github.com/ros-mobile-robots/remo_description/blob/main/meshes/remo/lidar_platform/slamtec_holder.stl) | <script src="https://embed.github.com/view/3d/ros-mobile-robots/remo_description/main/meshes/remo/lidar_platform/slamtec_holder.stl"></script> |
+
+
+=== "RPLiDAR A1 M8"
+
+    To be announced.
+
+
+## Camera Mount
+
+| Qty | Part | 3D View |
+|:---:|:-----|:-------:|
+| 1   | [`camera_mount.stl`](https://github.com/ros-mobile-robots/remo_description/blob/main/meshes/remo/camera_mount/camera_mount.stl) | <script src="https://embed.github.com/view/3d/ros-mobile-robots/remo_description/main/meshes/remo/camera_mount/camera_mount.stl"></script> |
+
+
+You can choose between the following camera adjustment mounts:
+
+=== "Raspi Camera v2"
+
+    | Qty | Part | 3D View |
+    |:---:|:-----|:-------:|
+    | 1   | [`Raspberry_pi_CAM_holder.stl`](https://github.com/ros-mobile-robots/remo_description/blob/main/meshes/remo/camera_mount/Raspberry_pi_CAM_holder.stl) | <script src="https://embed.github.com/view/3d/ros-mobile-robots/remo_description/main/meshes/remo/camera_mount/Raspberry_pi_CAM_holder.stl"></script> |
+
+=== "OAK 1"
+
+    | Qty | Part | 3D View |
+    |:---:|:-----|:-------:|
+    | 1   | [`OAK-1_adjustment_mount.stl`](https://github.com/ros-mobile-robots/remo_description/blob/main/meshes/remo/camera_mount/OAK-1_adjustment_mount.stl) | <script src="https://embed.github.com/view/3d/ros-mobile-robots/remo_description/main/meshes/remo/camera_mount/OAK-1_adjustment_mount.stl"></script> |
+
+=== "OAK D"
+
+    | Qty | Part | 3D View |
+    |:---:|:-----|:-------:|
+    | 1   | [`OAK-D_adjustment_mount.stl`](https://github.com/ros-mobile-robots/remo_description/blob/main/meshes/remo/camera_mount/OAK-D_adjustment_mount.stl) | <script src="https://embed.github.com/view/3d/ros-mobile-robots/remo_description/main/meshes/remo/camera_mount/OAK-D_adjustment_mount.stl"></script> |
diff --git a/docs/hardware_setup/assembly.md b/docs/hardware_setup/assembly.md
@@ -0,0 +1,15 @@
+# Assembly
+
+The following video gives an overview of the robot's components and how it will be assembled:
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/6aAEbtfVbAk" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
+More detailed assembly instructions are found in the next few sections:
+
+## Frame
+
+![assembly frame](https://media.githubusercontent.com/media/ros-mobile-robots/ros-mobile-robots.github.io/feature/hardware-setup/docs/hardware_setup/images/drawing_frame_group.svg)
+
+## Bread Board
+
+![bread board](https://media.githubusercontent.com/media/ros-mobile-robots/ros-mobile-robots.github.io/feature/hardware-setup/docs/hardware_setup/images/bread_board.svg)
diff --git a/docs/hardware_setup/electronics.md b/docs/hardware_setup/electronics.md
@@ -0,0 +1,17 @@
+# Electronics
+
+The bread board view from [Fritzing](https://fritzing.org/) shows the connection schematic. Both models (DiffBot and Remo) use
+slgithly different hardware (e.g. motor driver) which you can see in the following:
+
+=== "Remo"
+
+    [![Remo Fritzing]][Remo Fritzing]
+
+      [Remo Fritzing]: /fritzing/remo_architecture.svg
+
+
+=== "DiffBot"
+
+    [![DiffBot Fritzing]][DiffBot Fritzing]
+
+      [DiffBot Fritzing]: /fritzing/diffbot_architecture.svg
diff --git a/docs/hardware_setup/images/bread_board.svg b/docs/hardware_setup/images/bread_board.svg
diff --git a/docs/hardware_setup/images/drawing_frame_group.svg b/docs/hardware_setup/images/drawing_frame_group.svg
diff --git a/docs/hardware_setup/install.md b/docs/hardware_setup/install.md
@@ -0,0 +1,9 @@
+# Installation
+
+After completing the hardware setup, the next steps that follows consist of
+
+- Preparing the software on the [processing units](../processing_units/index.md)
+- Installing the [ROS software packages](../packages/index.md)
+
+
+If you want to learn more about the theory behind robotics visit [Robotics Theory](../theory/index.md) pages.
diff --git a/docs/hardware_setup/overview.md b/docs/hardware_setup/overview.md
@@ -0,0 +1,31 @@
+# Hardware Setup Overview
+
+The following pages guide you on how to setup the hardware of your robot (either DiffBot or Remo).
+
+- [**3D Printing**](3D_print.md) is only relevant for Remo robot (not DiffBot). 
+  Here you will learn which parts to print and some suggestions to configure your slicer.
+- [**Electronics**](electronics.md) provides instructions to connect the single board computer (e.g. Raspberry Pi), microcontroller (e.g. Teensy) as well as
+  the other components such as the motor driver, motors and laser scanner.
+
+    ??? info "Preview of connection schematic"
+        The bread board view from [Fritzing](https://fritzing.org/) shows the connection schematic. Both models (DiffBot and Remo) use
+        slgithly different hardware (e.g. motor driver) which you can see in the following:
+
+        === "Remo"
+
+            [![Remo Fritzing]][Remo Fritzing]
+
+            [Remo Fritzing]: /fritzing/remo_architecture.svg
+
+
+        === "DiffBot"
+
+            [![DiffBot Fritzing]][DiffBot Fritzing]
+
+            [DiffBot Fritzing]: /fritzing/diffbot_architecture.svg
+
+
+- [**Assembly**](assembly.md) give instructions to assemble Remo robot.
+
+
+
diff --git a/docs/index.md b/docs/index.md
@@ -16,7 +16,7 @@ The project is split into multiple parts, to adress the following main aspects o
 
 - [Bill of Materials (BOM)](./components.md) and the theory behind the parts.
 - [Theory of (mobile) robots](./theory/index.md).
-- [Assembly](/projects/diffbot/assembly/) of the robot platform and the components.
+- [Assembly](./hardware_setup/assembly.md) of the robot platform and the components.
 - Setup of ROS (Noetic or Melodic) on either Raspberry Pi 4 B or Jetson Nano, 
   which are both [Single Board Computers (SBC)](https://en.wikipedia.org/wiki/Single-board_computer) and are the brain of the robot.
 - [Modeling the Robot](/projects/diffbot/URDF) in Blender and URDF to simulate it in Gazebo.

diff --git a/docs/links.md b/docs/links.md
@@ -0,0 +1,54 @@
+[amazon_rpi_4_ger]: https://amzn.to/3J0TXuF
+[amazon_rpi_4_us]: https://amzn.to/4ofMRkV
+
+[sandisk_64gb_ger]: https://amzn.to/4nFmYuR
+[sandisk_64gb_us]: https://amzn.to/4n2UoCL
+
+[amazon_rplidar_a2m12_ger]: https://amzn.to/4hnsd0d
+[amazon_rplidar_a2m12_us]: https://amzn.to/46KPgyj
+
+[amazon_rplidar_a1m8_ger]: https://amzn.to/4q8tXyk
+[amazon_rplidar_a1m8_us]: https://amzn.to/43dKAyu
+
+[amazon_ada2927_ger]: https://amzn.to/3km5KF3
+[amazon_ada2927_us]: https://amzn.to/48nkoVN
+
+[amazon_teensy_4.0_ger]: https://amzn.to/3KGcLzU
+[amazon_teensy_4.0_us]: https://amzn.to/3KJamEz
+
+[amazon_hobby_motor_us]: https://amzn.to/46W69EU
+
+[amazon_anker_powerbank_pc10k_ger]: https://amzn.to/3B4ObUA
+[amazon_anker_powerbank_pc10k_us]: https://amzn.to/4nTkzwP
+
+[amazon_battery_holder_8x_aa_ger]: https://amzn.to/42vNJJY
+[amazon_battery_holder_8x_aa_us]: https://amzn.to/4pXCvYx
+
+[amazon_usb_c_cable_50cm_ger]: https://amzn.to/4ohAW6h
+[amazon_usb_c_cable_50cm_us]: https://amzn.to/4q4ahve
+
+[amazon_caster_ball_ger]: https://amzn.to/46KKFvZ
+[amazon_caster_ball_us]: https://amzn.to/3J5Scwf
+
+[amazon_ball_bearing_ger]: https://amzn.to/476Af8T
+
+[amazon_wheels_ger]: https://amzn.to/3KIjWHR
+[amazon_wheels_us]: https://amzn.to/3J1rGUK
+
+[amazon_power_supply_ger]: https://amzn.to/4q4Cj9Q
+[amazon_power_supply_us]: https://amzn.to/46Lfwsm
+
+[amazon_wifi_t2u_nano_ger]: https://amzn.to/3KBjY4l
+[amazon_wifi_t2u_nano_us]: https://amzn.to/4nKckDp
+
+[amazon_wifi_t3u_ger]: https://amzn.to/48paHGe
+[amazon_wifi_t3u_us]: https://amzn.to/3KPSdox
+
+[amazon_wifi_t3u_plus_ger]: https://amzn.to/478WD1w
+[amazon_wifi_t3u_plus_us]: https://amzn.to/4nN7Vzw
+
+[amazon_rpi_cam_v2_ger]: https://amzn.to/3IG7FDb
+[amazon_rpi_cam_v2_us]: https://amzn.to/4h1dkjI
+
+[amazon_rpi2]: https://amzn.to/3L6PZ14?tag=yourtrackingid-20
+[amazon_sdcard]: https://amzn.to/4eSkqWv?tag=yourtrackingid-20
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		docs/hardware_setup/images/*.svg filter=lfs diff=lfs merge=lfs -text