diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..c93f9e57 --- /dev/null +++ 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 index 5a690020..c618af69 100644 --- 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 new file mode 100644 index 00000000..5ceb3864 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +venv diff --git a/docs/components.md b/docs/components.md index 63e48299..c7692288 100644 --- 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 new file mode 100644 index 00000000..78543921 --- /dev/null +++ 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 + + + + +## 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) | | + +## 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) | | + + + +=== "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) | | + + +## 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) | | + + | 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) | | + + +=== "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) | | + + +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) | | + +=== "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) | | + +=== "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) | | \ No newline at end of file diff --git a/docs/hardware_setup/assembly.md b/docs/hardware_setup/assembly.md new file mode 100644 index 00000000..c11e01cc --- /dev/null +++ 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: + + + +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 new file mode 100644 index 00000000..d1bd4d61 --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/hardware_setup/images/bread_board.svg b/docs/hardware_setup/images/bread_board.svg new file mode 100644 index 00000000..74f63948 --- /dev/null +++ b/docs/hardware_setup/images/bread_board.svg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0bbaba3a1c1a353d05f455d5f687e08b3e3bf245a4ea03cadf1c238731345f63 +size 507470 diff --git a/docs/hardware_setup/images/drawing_frame_group.svg b/docs/hardware_setup/images/drawing_frame_group.svg new file mode 100644 index 00000000..55bb8cfd --- /dev/null +++ b/docs/hardware_setup/images/drawing_frame_group.svg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:55ccc409c0b906ae48beaa608dd05f500d07faacb6c3132a8a68bd98d88988bb +size 4891526 diff --git a/docs/hardware_setup/install.md b/docs/hardware_setup/install.md new file mode 100644 index 00000000..e03cef38 --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/hardware_setup/overview.md b/docs/hardware_setup/overview.md new file mode 100644 index 00000000..19a3a9db --- /dev/null +++ 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 index 03782a38..7e96ab7d 100644 --- 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 index 8669c41b..74718e39 100644 --- 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,9 +77,9 @@ 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): -
- -
ROS Control in Simulation and Reality
+
+ ![ROS Control simulation and reality]({{ asset_dir }}/packages/diffbot_base/ros-control-simulation-and-reality.svg) +
ROS Control in Simulation and Reality
The second component is the low-level base controller that measures angular @@ -83,35 +87,37 @@ 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: -
- -
Block diagram of the low-level controller and the high-level hardware interface
+
+ ![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) +
Block diagram of the low-level controller and the high-level hardware interface (ROS +Control)
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 diff --git a/docs/packages/index.md b/docs/packages/index.md index c67a13d0..41b668ba 100644 --- a/docs/packages/index.md +++ b/docs/packages/index.md @@ -1,117 +1,53 @@ -# Diffbot ROS Packages - -The following describes the easiest way to make use of diffbot's ROS packages inside the [ros-mobile-robots/diffbot](https://github.com/ros-mobile-robots/diffbot) -repository. - -The following steps will be performed on both, the workstation/development PC and the single board computer (SBC). - -## Git: clone diffbot repository - -After setting up ROS on your workstation PC and the SBC (either [Raspberry Pi 4B](https://ros-mobile-robots.com/rpi-setup/) or [Jetson Nano](https://ros-mobile-robots.com/jetson-nano-setup/)), -create a ros workspace in your users home folder and clone the [`diffbot` repository]({{ diffbot_repo_url }}): - -``` -mkdir -p ros_ws/src -git clone https://github.com/ros-mobile-robots/diffbot.git -``` - -## Obtain (system) Dependencies - -The `diffbot` repository relies on two sorts of dependencies: - -- Source (non binary) dependencies from other (git) repositories. -- System dependencies available in the (ROS) Ubuntu package repositories. Also refered to as pre built binaries. - - -### Source Dependencies - -Let's first obtain source dependencies from other repositories. -To do this the recommended tool to use is [`vcstool`](http://wiki.ros.org/vcstool) -(see also https://github.com/dirk-thomas/vcstool for additional documentation and examples.). - -!!! note - [`vcstool`](http://wiki.ros.org/vcstool) replaces [`wstool`](http://wiki.ros.org/wstool). - -Inside the cloned `diffbot` repository, -make use of the `import` command and the `diffbot.repos` file containing the required source repositories: - -``` -vcs import < diffbot.repos -``` - -This will clone all repositories which are stored in the `diffbot.repos` that get passed in via stdin in YAML format. - -!!! note - The file `diffbot.repos` contains relative paths and will clone the listed repositories in the parent folder from where - the `vcs import` command is called. When it is called from inside the `diffbot` repository, which should be located - in the `src` folder of a catkin workspace, then the other repositories are also cloned in the `src` folder. - -For the SBC not all dependencies in `diffbot.repos` are needed. -Instead the `diffbot_robot.repos` is here to clone the [`rplidar_ros`](https://github.com/Slamtec/rplidar_ros) repository. - -``` -vcs import < diffbot_robot.repos -``` - -Now that additional packages are inside the catkin workspace it is time to install the system dependencies. - -### System Dependencies - -All the needed ROS system dependencies which are required by diffbot's packages can be installed using -[`rosdep`](http://wiki.ros.org/rosdep) command, which was installed during the ROS setup. -To install all system dependencies use the following command: - -``` -rosdep install --from-paths src --ignore-src -r -y -``` - -!!! info - On the following packages pages it is explained that the dependencies of a ROS package are defined inside its `package.xml`. - - -After the installation of all dependencies finished (which can take a while), it is time to build the catkin workspace. -Inside the workspace use [`catkin-tools`](https://catkin-tools.readthedocs.io/en/latest/) to build the packages inside the `src` folder. - -!!! note - The first time you run the following command, make sure to execute it inside your catkin workspace and not the `src` directory. - -``` -catkin build -``` - -Now source the catkin workspace either using the [created alias](../ros-setup.md#environment-setup) or the full command for the bash shell: - -``` -source devel/setup.bash -``` - -## Examples - -Now you are ready to follow the examples listed in the readme. - -!!! info - TODO extend documentation with examples - - -## Optional Infos - -### Manual Dependency Installation - -To install a package from source clone (using git) or download the source files from where they are located (commonly hosted on GitHub) into the `src` folder of a ros catkin workspace and execute the [`catkin build`](https://catkin-tools.readthedocs.io/en/latest/verbs/catkin_build.html) command. Also make sure to source the workspace after building new packages with `source devel/setup.bash`. - -```console -cd /homw/fjp/git/diffbot/ros/ # Navigate to the workspace -catkin build # Build all the packages in the workspace -ls build # Show the resulting build space -ls devel # Show the resulting devel space -``` - -!!! note - - Make sure to clone/download the source files suitable for the ROS distribtion - you are using. If the sources are not available for the distribution you are - working with, it is worth to try building anyway. Chances are that the package - you want to use is suitable for multiple ROS distros. For example if a package - states in its docs, that it is only available for - [kinetic](http://wiki.ros.org/kinetic) it is possible that it will work with a - ROS [noetic](http://wiki.ros.org/noetic) install. +# ROS Software Packages + +After having verified that the hardware requirements for the Navigation Stack +are met, an overview of Remo's software follows. + +## Software requirements for the ROS Navigation Stack + +The [`diffbot`](https://github.com/ros-mobile-robots/diffbot/) and +[`remo_description`](https://github.com/ros-mobile-robots/remo_description) +repositories contain the following ROS packages: + +- `diffbot_base`: This package contains the platform-specific code for the base +controller component required by the ROS Navigation Stack. It consists of the +firmware based on rosserial for the Teensy MCU and the C++ node running on the +SBC that instantiates the ROS Control hardware interface including the +`controller_manager` control loop for the real robot. The low-level +`base_controller` component reads the encoder ticks from the hardware, +calculates angular joint positions and velocities, and publishes them to the ROS +Control hardware interface. Using this interface makes it possible to use the +`diff_drive_controller` package from [ROS +Control](http://wiki.ros.org/diff_drive_controller). It provides a controller +(`DiffDriveController`) for a differential drive mobile base that computes +target joint velocities from commands received by either a teleop node or the +ROS Navigation Stack. The computed target joint velocities are forwarded to the +low-level base controller, where they are compared to the measured velocities to +compute suitable motor PWM signals using two separate PID controllers, one for +each motor. +- `diffbot_bringup`: Launch files to bring up the hardware driver nodes (camera, +lidar, microcontroller, and so on) as well as the C++ nodes from the +`diffbot_base` package for the real robot. +- `diffbot_control`: Configurations for `DiffDriveController` and +`JointStateController` of ROS Control used in the Gazebo simulation and the real +robot. The parameter configurations are loaded onto the parameter server with +the help of the launch files inside this package. +- `remo_description`: This package contains the URDF description of Remo +including its sensors. It allows you to pass arguments to visualize different +camera and SBC types. It also defines the `gazebo_ros_control` plugin. Remo's +description is based on the description at +https://github.com/ros-mobile-robots/mobile_robot_description, which provides a +modular URDF structure that makes it easier to model your own differential drive +robot. +- `diffbot_gazebo`: Simulation-specific launch and configuration files for Remo +and Diffbot, to be used in the Gazebo simulator. +- `diffbot_msgs`: Message definitions specific to Remo/Diffbot, for example, the +message for encoder data is defined in this package. +- `diffbot_navigation`: This package contains all the required configuration and +launch files for the ROS Navigation Stack to work. +- `diffbot_slam`: Configurations for simultaneous localization and mapping using +implementations such as gmapping to create a map of the environment. + +After this overview of the ROS packages of a differential robot that fulfill the +requirements of the Navigation Stack, the next pages explain those packages in +more detail. \ No newline at end of file diff --git a/docs/packages/packages-setup.md b/docs/packages/packages-setup.md new file mode 100644 index 00000000..c67a13d0 --- /dev/null +++ b/docs/packages/packages-setup.md @@ -0,0 +1,117 @@ +# Diffbot ROS Packages + +The following describes the easiest way to make use of diffbot's ROS packages inside the [ros-mobile-robots/diffbot](https://github.com/ros-mobile-robots/diffbot) +repository. + +The following steps will be performed on both, the workstation/development PC and the single board computer (SBC). + +## Git: clone diffbot repository + +After setting up ROS on your workstation PC and the SBC (either [Raspberry Pi 4B](https://ros-mobile-robots.com/rpi-setup/) or [Jetson Nano](https://ros-mobile-robots.com/jetson-nano-setup/)), +create a ros workspace in your users home folder and clone the [`diffbot` repository]({{ diffbot_repo_url }}): + +``` +mkdir -p ros_ws/src +git clone https://github.com/ros-mobile-robots/diffbot.git +``` + +## Obtain (system) Dependencies + +The `diffbot` repository relies on two sorts of dependencies: + +- Source (non binary) dependencies from other (git) repositories. +- System dependencies available in the (ROS) Ubuntu package repositories. Also refered to as pre built binaries. + + +### Source Dependencies + +Let's first obtain source dependencies from other repositories. +To do this the recommended tool to use is [`vcstool`](http://wiki.ros.org/vcstool) +(see also https://github.com/dirk-thomas/vcstool for additional documentation and examples.). + +!!! note + [`vcstool`](http://wiki.ros.org/vcstool) replaces [`wstool`](http://wiki.ros.org/wstool). + +Inside the cloned `diffbot` repository, +make use of the `import` command and the `diffbot.repos` file containing the required source repositories: + +``` +vcs import < diffbot.repos +``` + +This will clone all repositories which are stored in the `diffbot.repos` that get passed in via stdin in YAML format. + +!!! note + The file `diffbot.repos` contains relative paths and will clone the listed repositories in the parent folder from where + the `vcs import` command is called. When it is called from inside the `diffbot` repository, which should be located + in the `src` folder of a catkin workspace, then the other repositories are also cloned in the `src` folder. + +For the SBC not all dependencies in `diffbot.repos` are needed. +Instead the `diffbot_robot.repos` is here to clone the [`rplidar_ros`](https://github.com/Slamtec/rplidar_ros) repository. + +``` +vcs import < diffbot_robot.repos +``` + +Now that additional packages are inside the catkin workspace it is time to install the system dependencies. + +### System Dependencies + +All the needed ROS system dependencies which are required by diffbot's packages can be installed using +[`rosdep`](http://wiki.ros.org/rosdep) command, which was installed during the ROS setup. +To install all system dependencies use the following command: + +``` +rosdep install --from-paths src --ignore-src -r -y +``` + +!!! info + On the following packages pages it is explained that the dependencies of a ROS package are defined inside its `package.xml`. + + +After the installation of all dependencies finished (which can take a while), it is time to build the catkin workspace. +Inside the workspace use [`catkin-tools`](https://catkin-tools.readthedocs.io/en/latest/) to build the packages inside the `src` folder. + +!!! note + The first time you run the following command, make sure to execute it inside your catkin workspace and not the `src` directory. + +``` +catkin build +``` + +Now source the catkin workspace either using the [created alias](../ros-setup.md#environment-setup) or the full command for the bash shell: + +``` +source devel/setup.bash +``` + +## Examples + +Now you are ready to follow the examples listed in the readme. + +!!! info + TODO extend documentation with examples + + +## Optional Infos + +### Manual Dependency Installation + +To install a package from source clone (using git) or download the source files from where they are located (commonly hosted on GitHub) into the `src` folder of a ros catkin workspace and execute the [`catkin build`](https://catkin-tools.readthedocs.io/en/latest/verbs/catkin_build.html) command. Also make sure to source the workspace after building new packages with `source devel/setup.bash`. + +```console +cd /homw/fjp/git/diffbot/ros/ # Navigate to the workspace +catkin build # Build all the packages in the workspace +ls build # Show the resulting build space +ls devel # Show the resulting devel space +``` + +!!! note + + Make sure to clone/download the source files suitable for the ROS distribtion + you are using. If the sources are not available for the distribution you are + working with, it is worth to try building anyway. Chances are that the package + you want to use is suitable for multiple ROS distros. For example if a package + states in its docs, that it is only available for + [kinetic](http://wiki.ros.org/kinetic) it is possible that it will work with a + ROS [noetic](http://wiki.ros.org/noetic) install. diff --git a/docs/git-setup.md b/docs/processing_units/git-setup.md similarity index 100% rename from docs/git-setup.md rename to docs/processing_units/git-setup.md diff --git a/docs/hardware-interfaces.md b/docs/processing_units/hardware-interfaces.md similarity index 100% rename from docs/hardware-interfaces.md rename to docs/processing_units/hardware-interfaces.md diff --git a/docs/processing_units/index.md b/docs/processing_units/index.md new file mode 100644 index 00000000..b843eac7 --- /dev/null +++ b/docs/processing_units/index.md @@ -0,0 +1,53 @@ +# Processing Units + +Our robot consists of components which are connected as shown in the block diagram below: + +[![Block Diagram Remo]][Block Diagram Remo] + + [Block Diagram Remo]: {{ asset_dir }}/processing_units/block-diagram-remo.svg + +The Teensy 3.2 microcontroller board is connected to the encoder and optional IMU +sensor as well as the motor driver actuator. It communicates to the Raspberry Pi 4 B via +USB over the `rosserial` protocol. The motor driver and the optional IMU exchange +data over I2C with the microcontroller. The RPLIDAR has a serial-to-USB converter and +is therefore connected to one of the USB ports of the SBC. The motor encoder sensors +are interfaced through the GPIO pins of the microcontroller. The following shows the +connection diagram of the components: + + +[![Remo Fritzing]][Remo Fritzing] + + [Remo Fritzing]: /fritzing/remo_architecture.svg + + +## Overview of ROS nodes and topics for the Remo robot + +The following launch file will bring up the hardware nodes, load the robot description +onto the parameter server, start `diff_drive_controller`, and begin to publish the +transformations using `tf`. Run this launch file on the robot's SBC: + +```console +roslaunch diffbot_bringup bringup.launch model:=remo +``` + +On the development PC, you can use the teleop node to steer the robot. To do this, run +the following: + +```console +roslaunch diffbot_bringup keyboard_teleop.launch +``` + +Issuing the rosnode list command shows the following list of started nodes: + +```console +/diffbot/controller_spawner +/diffbot/diffbot_base +/diffbot/robot_state_publisher +/diffbot/rosserial_base_controller +/diffbot_teleop_keyboard +/rosout +``` + +[![ROS nodes and topics of Remo]][ROS nodes and topics of Remo] + + [ROS nodes and topics of Remo]: {{ asset_dir }}/processing_units/ros-nodes-remo.svg \ No newline at end of file diff --git a/docs/jetson-nano-setup.md b/docs/processing_units/jetson-nano-setup.md similarity index 100% rename from docs/jetson-nano-setup.md rename to docs/processing_units/jetson-nano-setup.md diff --git a/docs/ros-network-setup.md b/docs/processing_units/ros-network-setup.md similarity index 100% rename from docs/ros-network-setup.md rename to docs/processing_units/ros-network-setup.md diff --git a/docs/ros-setup.md b/docs/processing_units/ros-setup.md similarity index 98% rename from docs/ros-setup.md rename to docs/processing_units/ros-setup.md index 69c5ba3c..6ffeb73d 100644 --- a/docs/ros-setup.md +++ b/docs/processing_units/ros-setup.md @@ -3,7 +3,7 @@ The robot setup is supposed to run on Ubuntu Mate 20.04 Focal Fossa. [ROS Noetic](http://wiki.ros.org/noetic) is intended to run with this Ubuntu version. To install ROS follow the [installation instructions](http://wiki.ros.org/noetic/Installation/Ubuntu). !!! info - In the 1.4 Installation step](http://wiki.ros.org/noetic/Installation/Ubuntu#Installation-1) you have to choose + In the [1.4 Installation step](http://wiki.ros.org/noetic/Installation/Ubuntu#Installation-1) you have to choose how much of ROS you want to install. For the development pc you can go with the `sudo apt install ros-noetic-desktop-full` command. For the robot install the `ros-noetic-robot` Ubuntu package. Other system dependencies will be installed with the [`rosdep`](http://wiki.ros.org/rosdep) command, explained in the following section. diff --git a/docs/rpi-setup.md b/docs/processing_units/rpi-setup.md similarity index 100% rename from docs/rpi-setup.md rename to docs/processing_units/rpi-setup.md diff --git a/docs/packages/diffbot_base/scripts/teensy-mcu.md b/docs/processing_units/teensy-mcu.md similarity index 100% rename from docs/packages/diffbot_base/scripts/teensy-mcu.md rename to docs/processing_units/teensy-mcu.md diff --git a/docs/resources/packages/diffbot_base/block-diagram-low-high-level.svg b/docs/resources/packages/diffbot_base/block-diagram-low-high-level.svg deleted file mode 100644 index 366cef8c..00000000 --- a/docs/resources/packages/diffbot_base/block-diagram-low-high-level.svg +++ /dev/null @@ -1 +0,0 @@ -ROS Navigation StackRealityInput/OutputHardwareController ManagerLoads, unloads, and calls updates to controllersjoint_state_controllerdiff_drive_controllerEncodersActuatorsMotors, Servos, etc.Embedded Controllerse.g., Teensy, operates PID controllers to follow set pointsubscribe/wheel_cmd_velocitiesdiffbot_msgs/WheelsCmdpublish/measured_joint_statessensor_msgs/JointStateJoint Statesangular positions / velocitiespublish/wheel_cmd_velocitiessubscribe/measured_joint_stateshardware_interface::RobotHWProvides position, velocity, and effort interfacesbetweenhardwareand ros_controlread()write()High-levelHardwareInterfaceLow-levelBaseControllerupdate joint interface valuesROS Interface/joint_statesfor robot_state_publisherROS Interface/cmd_vel \ No newline at end of file diff --git a/docs/resources/packages/diffbot_base/block-diagram-low-level-base_controller-high-level-hardware_interface.svg b/docs/resources/packages/diffbot_base/block-diagram-low-level-base_controller-high-level-hardware_interface.svg new file mode 100644 index 00000000..e08a6e1e --- /dev/null +++ b/docs/resources/packages/diffbot_base/block-diagram-low-level-base_controller-high-level-hardware_interface.svg @@ -0,0 +1 @@ +ROS Navigation StackRealityInput/OutputHardwareController ManagerLoads, unloads, and calls updates to controllersjoint_state_controllerdiff_drive_controllerEncodersActuatorsMotors, Servos, etc.Embedded Controllerse.g., Teensy, operates PID controllers to follow set pointsubscribe/wheel_cmd_velocitiesdiffbot_msgs/WheelsCmdpublish/measured_joint_statessensor_msgs/JointStateJoint Statesangular positions / velocitiespublish/wheel_cmd_velocitiessubscribe/measured_joint_stateshardware_interface::RobotHWProvides position, velocity, and effort interfacesbetweenhardwareand ros_controlread()write()High-levelHardwareInterfaceLow-levelBaseControllerupdate joint interface valuesROS Interface/joint_statesfor robot_state_publisherROS Interface/cmd_vel \ No newline at end of file diff --git a/docs/resources/packages/diffbot_base/ros-control-simulation-and-reality.svg b/docs/resources/packages/diffbot_base/ros-control-simulation-and-reality.svg new file mode 100644 index 00000000..e325a584 --- /dev/null +++ b/docs/resources/packages/diffbot_base/ros-control-simulation-and-reality.svg @@ -0,0 +1 @@ +SimulationHardwareHardware ResourceInterface LayerEncodersActuatorsRealityInput/OutputGazeboSimulatorhardware_interface::RobotHWSimProvides position, velocity, and effort interfacesbetweenGazeboand ros_controlwriteSim()readSim()read()write()Joint State Interfacee.g.JointStateInterfaceJoint Command Interfacee.g.VelocityJointInterfaceController Managerjoint_state_controllerdiff_drive_controllerROS Interface/joint_statesROS Interface/cmd_velEmbedded controllersLoads, unloads, and calls updates to controllershardware_interface::RobotHWProvides position, velocity, and effort interfacesbetweenhardwareand ros_control \ No newline at end of file diff --git a/docs/resources/packages/diffbot_base/roscontrol-sim-reality.svg b/docs/resources/packages/diffbot_base/roscontrol-sim-reality.svg deleted file mode 100644 index 4921a39c..00000000 --- a/docs/resources/packages/diffbot_base/roscontrol-sim-reality.svg +++ /dev/null @@ -1 +0,0 @@ -GazeboSimulatorSimulationHardwareHardware ResourceInterface LayerEncodersActuatorsRealityInput/Outputhardware_interface::RobotHWSimProvides position, velocity, and effort interfacesbetweenGazeboand ros_controlwriteSim()readSim()read()write()Joint State Interfacee.g.JointStateInterfaceJoint Command Interfacee.g.VelocityJointInterfaceController Managerjoint_state_controllerdiff_drive_controllerROS Interface/joint_statesROS Interface/cmd_velEmbedded controllersLoads, unloads, and calls updates to controllershardware_interface::RobotHWProvides position, velocity, and effort interfacesbetweenhardwareand ros_control \ No newline at end of file diff --git a/docs/resources/processing_units/block-diagram-remo.svg b/docs/resources/processing_units/block-diagram-remo.svg new file mode 100644 index 00000000..5d5172a5 --- /dev/null +++ b/docs/resources/processing_units/block-diagram-remo.svg @@ -0,0 +1 @@ +Microcontroller boardTeensySingle Board ComputerRaspberry Pi 4BLaser ScannerRPLidarA2 M8Wi-Fi Dongle (optional) I2CUSBMotor DriverAdafruit FeatherWingMotor Left + EncoderMotor Right + EncoderSerial/USBIMU (optional)I2CUSBCameraRaspiCamera v2CSI \ No newline at end of file diff --git a/docs/resources/processing_units/ros-nodes-remo.svg b/docs/resources/processing_units/ros-nodes-remo.svg new file mode 100644 index 00000000..a197bcb4 --- /dev/null +++ b/docs/resources/processing_units/ros-nodes-remo.svg @@ -0,0 +1 @@ +Navigation Stackdiffbot_basehigh-level hardware interfacebased on ROS Controldiffbot_base_controllerlow-level base controllerrunning on Teensy with rosserialkeyboard_teleopmobile_base_controller/cmd_velgeometry_msgs/TwistRemo Robottfmeasured_joint_statessensor_msgs/JointStatewheel_cmd_velocitiesdiffbot/WheelsCmdMotor PWM signalsEncoder Hall sensor signalsrobot_state_publisherjoint_statessensor_msgs/JointStaterplidarNodecontroller_spawnerdiff_drive_controllerjoint_state_controllerscansensor_msgs/LaserScanresetstd_msgs/Empty \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 1c2c8bdf..1dea0c1a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -69,9 +69,11 @@ markdown_extensions: generic: true - pymdownx.tasklist: custom_checkbox: true + - pymdownx.magiclink plugins: - search + - glightbox - macros - mkdocs-jupyter: execute: False @@ -83,6 +85,47 @@ nav: - Getting Started: - Technical Requirements: technical_requirements.md - Components: components.md + - Hardware Setup: + - hardware_setup/overview.md + - 3D Printing: hardware_setup/3D_print.md + - Electronics: hardware_setup/electronics.md + - Assembly: hardware_setup/assembly.md + - Install: hardware_setup/install.md + - Processing Units: + - processing_units/index.md + - Single Board Computer: + - Raspberry Pi Setup: processing_units/rpi-setup.md + - Jetson Nano Setup: processing_units/jetson-nano-setup.md + - Git Setup: processing_units/git-setup.md + - ROS Setup: processing_units/ros-setup.md + - Microcontroller: processing_units/teensy-mcu.md + - Hardware Interfaces: processing_units/hardware-interfaces.md + - ROS Network Setup: processing_units/ros-network-setup.md + - ROS Software Packages: + - packages/index.md + - Packages Setup: packages/packages-setup.md + - Robot Package: diffbot_robot.md + - Robot Description: + - Robot Description: robot-description.md + - Remo Description: packages/remo_description.md + - Simulation: diffbot_gazebo.md + - Control: diffbot_control.md + - Base Hardware Interface: + - packages/diffbot_base/index.md + - PID Controllers: packages/diffbot_base/pid.md + - Low-Level PID Approach: packages/diffbot_base/low-level.md + - High-Level PID Approach: packages/diffbot_base/high-level.md + - Messages: diffbot_msgs.md + - Motor Driver: grove_motor_driver.md + - Motor and Encoder: DG01D-E-motor-with-encoder.md + - Navigation: diffbot_navigation.md + - SLAM: diffbot_slam.md + - Move Base Flex: diffbot_mbf.md + - Hardware Bringup: diffbot_bringup.md + - Rasperry Pi Camera: packages/raspicam_node.md + - Inertial Measurement Unit: + - Robot Localization: packages/imu/robot_localization.md + - BNO055 Driver: packages/imu/driver-bno055.md - Robotics Theory: - theory/index.md - Preliminaries: @@ -128,37 +171,4 @@ nav: - Motion and Odometry: theory/motion-and-odometry.md - Power Supply: power-supply.md - Laser Range Scanner: laser-range-scanner.md - - Processing Units: - - Single Board Computer: - - Raspberry Pi Setup: rpi-setup.md - - Jetson Nano Setup: jetson-nano-setup.md - - Git Setup: git-setup.md - - ROS Setup: ros-setup.md - - Microcontroller: packages/diffbot_base/scripts/teensy-mcu.md - - Hardware Interfaces: hardware-interfaces.md - - ROS Network Setup: ros-network-setup.md - - Packages: - - packages/index.md - - Robot Package: diffbot_robot.md - - Robot Description: - - Robot Description: robot-description.md - - Remo Description: packages/remo_description.md - - Simulation: diffbot_gazebo.md - - Control: diffbot_control.md - - Base Hardware Interface: - - packages/diffbot_base/index.md - - PID Controllers: packages/diffbot_base/pid.md - - Low-Level PID Approach: packages/diffbot_base/low-level.md - - High-Level PID Approach: packages/diffbot_base/high-level.md - - Messages: diffbot_msgs.md - - Motor Driver: grove_motor_driver.md - - Motor and Encoder: DG01D-E-motor-with-encoder.md - - Navigation: diffbot_navigation.md - - SLAM: diffbot_slam.md - - Move Base Flex: diffbot_mbf.md - - Hardware Bringup: diffbot_bringup.md - - Rasperry Pi Camera: packages/raspicam_node.md - - Inertial Measurement Unit: - - Robot Localization: packages/imu/robot_localization.md - - BNO055 Driver: packages/imu/driver-bno055.md - Insiders: insiders/index.md