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
@@ -20,19 +20,19 @@ 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 |
+| Raspberry Pi 4 B (4 Gb) | 1 | $55.0 | [Sparkfun](https://www.sparkfun.com/products/15447), [Amazon.com](https://amzn.to/4e0GdKz), [Amazon.de](https://amzn.to/2IchIAc) | |
+| SanDisk 64 GB SD Card Class 10 | 1 | $13.99 | [Amazon.com](https://amzn.to/3XGHNvl), [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/4eoG0kq), [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 |
+| Teensy 4.0 or 3.2 | 1 | $19.95 | [Amazon.com](https://amzn.to/3MM9E7j), [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 | [Amazon.com](https://amzn.to/3zhOtXu), [Sparkfun](https://www.sparkfun.com/products/16413) | |
+| Powerbank (e.g 15'000 mAh, or 10'000 mAh) | 1 | $23.99 | [Amazon.de](https://amzn.to/3kmkx2t), [Anker Amazon.com](https://amzn.to/3zkreMy), [Anker Amazon.de](https://amzn.to/3B4ObUA) | 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](https://amzn.to/47rP6ud), [Amazon.de](https://amzn.to/3kiX8PH) | |
+| USB cable pack | 1 | $6.99 | [Amazon.com](https://amzn.to/3z8ATpw), [Amazon.de](https://amzn.to/4ghEqm5) | Type A to Micro, right angle |
 | 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](https://amzn.to/3ZGCihZ), [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 | [Amazon.com](https://amzn.to/4grj5qb), [Amazon.de](https://amzn.to/3XEjXR4), [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](https://amzn.to/3MGWTLh), [Adafruit](http://bit.ly/af1995) | Micro USB, 5V, 2.5A |
 
 ### USB Wi-Fi Dongle (optional)
 

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/packages/diffbot_base/index.md b/docs/packages/diffbot_base/index.md
@@ -58,8 +58,12 @@ The previous approach (high-level PID) is documented in [High-Level Approach](hi
 ## Developing a low-level controller firmware and a high-level ROS Control hardware interface for a differential drive robot
 
 In the following two sections, the base controller, mentioned in the Navigation
-Stack, will be developed. For DiffBot/Remo, this platform-specific node is split
-into two software components.
+Stack, will be developed.
+
+![Navigation Stack]({{ asset_dir }}/navigation/navigation_stack.png)
+
+For DiffBot/Remo, this platform-specific node is split into two software
+components.
 
 The first component is the high-level `diffbot::DiffBotHWInterface` that
 inherits from `hardware_interface::RobotHW`, acting as an interface between
@@ -73,45 +77,47 @@ simulation and the real robot.
 An overview of ROS Control in simulation and the real world is given in the
 following figure (http://gazebosim.org/tutorials/?tut=ros_control):
 
-<figure>
-    <a href="{{ asset_dir }}/packages/diffbot_base/roscontrol-sim-reality.svg"><img src="{{ asset_dir }}/packages/diffbot_base/roscontrol-sim-reality.svg"></a>
-    <figcaption>ROS Control in Simulation and Reality</figcaption>
+<figure markdown>
+  ![ROS Control simulation and reality]({{ asset_dir }}/packages/diffbot_base/ros-control-simulation-and-reality.svg)
+  <figcaption>ROS Control in Simulation and Reality</figcaption>
 </figure>
 
 The second component is the low-level base controller that measures angular
 wheel joint positions and velocities and applies the commands from the
 high-level interface to the wheel joints. The following figure shows the
 communication between the two components:
 
-<figure>
-    <a href="{{ asset_dir }}/packages/diffbot_base/block-diagram-low-high-level.svg"><img src="{{ asset_dir }}/packages/diffbot_base/block-diagram-low-high-level.svg"></a>
-    <figcaption>Block diagram of the low-level controller and the high-level hardware interface</figcaption>
+<figure markdown>
+  ![Block diagram of low-level controller and high-level hardware interface]({{ asset_dir }}/packages/diffbot_base/block-diagram-low-level-base_controller-high-level-hardware_interface.svg)
+  <figcaption>Block diagram of the low-level controller and the high-level hardware interface (ROS
+Control)</figcaption>
 </figure>
 
 The low-level base controller uses two PID controllers to compute PWM signals
 for each motor based on the error between measured and target wheel velocities.
 `RobotHW` receives measured joint states (angular position (rad) and angular
 velocity (rad/s)) from which it updates its joint values. With these measured
-velocities and the desired command velocity (`geometry_msgs/Twist` message on the
-`cmd_vel` topic), from the Navigation Stack, the `diff_drive_controller` computes
-the target angular velocities for both wheel joints using the mathematical
-equations of a differential drive robot. This controller works with continuous
-wheel joints through a `VelocityJointInterface` class. The computed target
-commands are then published within the high-level hardware interface inside the
-robots `RobotHW::write` method. Additionally, the controller computes and
-publishes the odometry on the odom topic (`nav_msgs/Odometry`) and the transform
-from `odom` to `base_footprint`.
+velocities and the desired command velocity (`geometry_msgs/Twist` message on
+the `cmd_vel` topic), from the Navigation Stack, the `diff_drive_controller`
+computes the target angular velocities for both wheel joints using the
+mathematical equations of a differential drive robot. This controller works with
+continuous wheel joints through a `VelocityJointInterface` class. The computed
+target commands are then published within the high-level hardware interface
+inside the robot's `RobotHW::write` method. Additionally, the controller
+computes and publishes the odometry on the odom topic (`nav_msgs/Odometry`) and
+the transform from `odom` to `base_footprint`.
 
 
-Having explained the two components of the base
-controller, the low-level firmware is implemented first. The high-level hardware
-interface follows the next section.
+Having explained the two components of the base controller, the low-level
+firmware is implemented first. The high-level hardware interface follows the
+next section.
 
-But before this an introduction to the PID controllers are given in [PID Controllers](pid.md).
+But before this an introduction to the PID controllers are given in [PID
+Controllers](pid.md).
 
 ### diffbot_base Package
 
-The `diffbot_base` package is created with `catkin-tools`:
+The `diffbot_base` package was created with `catkin-tools`:
 
 ```console
 fjp@diffbot:/home/fjp/catkin_ws/src$ catkin create pkg diffbot_base --catkin-deps diff_drive_controller hardware_interface roscpp sensor_msgs rosparam_shortcuts
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