Sync changes between Harmonic and Ionic directories (#551)

* Fix anchor links

Signed-off-by: Addisu Z. Taddese <[email protected]>

* Sync changes between Harmonic and Ionic directories

Signed-off-by: Addisu Z. Taddese <[email protected]>

---------

Signed-off-by: Addisu Z. Taddese <[email protected]>

Author: azeey

harmonic/GUI_tutorial.md

@@ -119,7 +119,7 @@ Along the bottom edge of the scene, you'll notice several buttons:
 
 ![Playback buttons](tutorials/gui/playback.png)
 
-From left to right, the options are `Play`, `Steps` and `RTF` (real time factor).
+From left to right, the options are `Play`, `Steps`, `Reset`,  `RTF` (real time factor).
 
 Pressing `Play` will start the simulation.
 You can use the same button to pause the simulation as well.
@@ -129,6 +129,8 @@ You can customize step size by hovering over the button.
 
 ![hover steps](tutorials/gui/hover_steps.png)
 
+Pressing `Reset` will clear any unsaved modification to the scene. Clicking it will remove the newly inserted shapes `box_0`, `sphere_0` and `capsule_0`.
+
 At the furthest right end of the scene, you can expand `RTF` to see not only the percentage value that compares real time with sim time, but also those individual values themselves, as well as iteration count.
 
 ![RTF expanded](tutorials/gui/rtf_expanded.png)

harmonic/Model_insertion_fuel.md

@@ -32,31 +32,31 @@ Check that the file size on the right is reasonable for your application before
 
 There are a few different ways to spawn a model into the simulation. 
 
-1. **Spawn from 'Fuel Resource' using the Resource Spawner plugin.**
+1. **Spawn from 'Fuel resources' using the Resource Spawner plugin.**
 
     Select the Resource Spawner plugin from the plugin menu (top right corner).
     The plugin will appear in the right panel, you might need to scroll down to be able to see the plugin. 
-    Wait until the resource are loaded under the 'Fuel Resource' panel. 
+    Wait until the resources are loaded under the 'Fuel resources' panel. 
     Select a resource owner (e.g. openrobotics), you can now search for the model name in the right panel. 
     Click on the cloud icon to download the model. 
     When the model has been downloaded, you can click on the model and insert it into your simulation scene. 
 
-    ![Resource Spawner - Fuel Resource](tutorials/fuel_insert/resource_spawner_cloud.png)
+    ![Resource Spawner - Fuel resources](tutorials/fuel_insert/resource_spawner_cloud.png)
 
 
 2. **Download model files from Fuel and spawn from local sources using the Resource Spawner plugin.**
 
     - Download the model files from [app.gazebosim.org/fuel/models](https://app.gazebosim.org/fuel/models).
-    - Extract the files and places them under your local model directory (e.g. `~/my-local-models/model-name`). 
+    - Extract the files and place them under your local model directory (e.g. `~/my-local-models/model-name`). 
     The folder should contain `materials`, `meshes` as well as the `model.config` and the `model.sdf` files. 
     - Add your model directory as a resource with `export GZ_SIM_RESOURCE_PATH=~/my-local-models/`
     - Open the Gazebo Simulator and add the Resource Spawner Plugin, the model should now show up under your local resources. 
 
-    ![Resource Spawner - Fuel Resource](tutorials/fuel_insert/resource_spawner_local.png)
+    ![Resource Spawner - Fuel resources](tutorials/fuel_insert/resource_spawner_local.png)
 
 3. **Copying the SDF snippet and adding it to your custom world SDF file.**
 
-    With the `<>` button you can directly copy a SDF snippet to paste into your world SDF file. 
+    With the `<>` button you can directly copy an SDF snippet to paste into your world SDF file. 
     The SDF snippet will look something like this: 
 
     ```
@@ -72,10 +72,10 @@ There are a few different ways to spawn a model into the simulation.
     
     ![spawn](tutorials/fuel_insert/husky.gif)
 
-4. **Downloading the code to permanently add a Fuel model to your custum SDF file.**
+4. **Downloading the code to permanently add a Fuel model to your custom SDF file.**
 
     If you prefer to add a Fuel model permanently to an `sdf` file, you can just as easily download the code by clicking the download-arrow icon to the right of the model's image.
-    Kook at the tutorial on [SDF Worlds](sdf_worlds) for more information on how to construct a custom world SDF file.
+    Look at the tutorial on [SDF Worlds](sdf_worlds) for more information on how to construct a custom world SDF file.
 
 Now you can add more models, or even load in any one of the plugins you learned about to interact with the model the same way you could with the shapes in the previous tutorial.
 

harmonic/install_ubuntu_src.md

@@ -29,32 +29,17 @@ sudo apt install python3-pip lsb-release gnupg curl
 
 ## vcstool and colcon from pip
 
-PIP is available on all platforms:
+PIP is available on all platforms. Using a PIP workspace to install the tools:
 
 ```bash
-pip install vcstool || pip3 install vcstool
+python3 -m venv $HOME/vcs_colcon_installation
+. $HOME/vcs_colcon_installation/bin/activate
+pip3 install vcstool colcon-common-extensions
 ```
 
-```bash
-pip install -U colcon-common-extensions || pip3 install -U colcon-common-extensions
-```
-
-Check that no errors were printed while installing with PIP. If your system is not recognising the commands, and you're using a system that is compatible with Debian or Ubuntu packages, see the instructions below to install using `apt`.
-
-After installing `vcstool` and `colcon` with PIP, you may need to add their executables to your `$PATH`.
-Check where the installation of these packages took place:
-
-```bash
-pip show vcstool || pip3 show vcstool | grep Location
-
-pip show colcon-common-extensions || pip3 show colcon-common-extensions | grep Location
-```
-
-If your install path is prefixed with `$HOME/.local`, you'll probably need to add the executables within this directory to your `$PATH` in order to avoid "command not found" errors when using `vcstool` and `colcon` later on:
-
-```bash
-export PATH=$PATH:$HOME/.local/bin/
-```
+`vcs` and `colcon` are now available from the PIP workspace in the current
+terminal. For using them in other terminals run the `activate` script as
+done above.
 
 ## vcstool and colcon from apt
 
@@ -143,14 +128,23 @@ colcon graph
 If that is the case, then you are ready
 to build the whole set of libraries:
 
+:::{warning}
+
+Compilation can take up to 16Gb of RAM memory. Use MAKEFLAGS with
+colcon as detailed in its instructions to reduce the number of
+compilation threads if needed.
+
+:::
+
+
 ```bash
 colcon build --merge-install
 ```
 
 To speed up the build process, you could also disable tests by using
 
 ```bash
-colcon build --cmake-args -DBUILD_TESTING=OFF --merge-install
+colcon build --cmake-args ' -DBUILD_TESTING=OFF' --merge-install
 ```
 
 To use debuggers activate debug symbols. Gazebo will run slower, but you'll be able to use GDB:
@@ -228,7 +222,7 @@ To perform QML debugging you'll need:
 You will need to build Gazebo with:
 
 ```bash
-colcon build --cmake-args -DQT_QML_DEBUG --merge-install
+colcon build --cmake-args ' -DQT_QML_DEBUG' --merge-install
 ```
 
 > **Note:** Advanced users may note that only the `gz-sim` project needs this flag.

harmonic/install_windows_src.md

@@ -15,10 +15,22 @@ without any failures when using their functionalities.
 
 ## Install dependencies
 
-1. Install a conda distribution. As Gazebo uses all dependencies from the conda-forge channel,
-   we suggest to install miniforge following [the official miniforge installation docs](https://github.com/conda-forge/miniforge#windows)
-   You will likely want to check the box to add `conda` to your `PATH`
-   during the installation process so that you won't have to do this step manually.
+1. If you do not have the conda package manager installed in your system, install a conda distribution.
+   As Gazebo uses all dependencies from the conda-forge channel, we suggest to install miniforge following [the official miniforge installation docs](https://github.com/conda-forge/miniforge#windows) by executing the following commands in a "Command Prompt" terminal:
+   ```cmd
+   curl.exe -L -O https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe
+   start /wait "" Miniforge3-Windows-x86_64.exe /InstallationType=JustMe /RegisterPython=0 /S /D=%UserProfile%\Miniforge3
+   %UserProfile%\Miniforge3\condabin\conda init
+   %UserProfile%\Miniforge3\condabin\conda config --set auto_activate_base false
+   del Miniforge3-Windows-x86_64.exe
+   ```
+   If you followed this step correctly, you should be able to access `conda` in any new "Command Prompt" terminal you open.
+   To verify that, check that if you open a new terminal and execute `conda info`, the output begins with:
+   ```cmd
+     active environment : None
+            shell level : 0
+     [..]
+   ```
 
 2. Install [Visual Studio 2019 or 2022](https://visualstudio.microsoft.com/downloads/).
    The Community version is free for students, open-source developers, and personal
@@ -27,21 +39,24 @@ without any failures when using their functionalities.
    cmake via Conda. All other checkboxes can be left unchecked.
 
 3. Open a Visual Studio Command Prompt (search for "x64 Native Tools Command Prompt
-   for VS" in the Windows search field near the Windows button). Optionally,
+   for VS" in the Windows search field near the Windows button) or Developer PowerShell
+   for VS (search for "developer powershell"). Optionally,
    right-click and pin to the task bar for quick access in the future.
 
-   If you did not add Conda to your `PATH` environment variable during Conda installation,
-   you may need to navigate to the location of `condabin` in order to use the `conda` command.
-   To find `condabin`, search for "Anaconda Prompt" in the Windows search field near the
-   Windows button, open it, run `where conda`, and look for a line containing the directory `condabin`.
+   If you chose PowerShell, you need to do a few steps to be able to use Conda and Gazebo in it:
+   ```bash
+   conda init powershell
+   # Restart the PowerShell
+   Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser
+   ```
 
-4. Navigate to your `condabin`, if necessary, and then create and activate a Conda environment:
+4. Create and activate a Conda environment:
    ```bash
    conda create -n gz-ws
    conda activate gz-ws
    ```
    Once you have activated an environment, a prefix like `(gz-ws)` will be prepended to
-   your prompt, and you can use the `conda` command outside of the `condabin` directory.
+   your prompt.
 
    You can use `conda info --envs` to see all of your environments.
 
@@ -65,8 +80,8 @@ without any failures when using their functionalities.
    conda install cmake git vcstool curl pkg-config ^
    colcon-common-extensions dartsim eigen freeimage gdal gts ^
    glib dlfcn-win32 ffmpeg ruby tinyxml2 tinyxml ^
-   libprotobuf urdfdom zeromq cppzmq ogre=1.10 ogre-next jsoncpp ^
-   libzip qt pybind11 --channel conda-forge
+   protobuf urdfdom zeromq cppzmq ogre=1.10 ogre-next jsoncpp ^
+   libzip qt pybind11 boost --channel conda-forge
    ```
    This can take tens of minutes (or less when using libmamba solver).
 
@@ -104,7 +119,7 @@ colcon graph
 If that is the case, then you are ready to build the whole set of libraries:
 
 ```bash
-colcon build --cmake-args -DBUILD_TESTING=OFF --merge-install --packages-up-to gz-sim8 gz-tools2
+colcon build --cmake-args -DBUILD_TESTING=OFF -DSKIP_SWIG=ON --merge-install --packages-up-to gz-sim8 gz-tools2
 ```
 Tests are turned off as they are not currently supported on Windows.
 
@@ -129,13 +144,16 @@ If there are no errors, all the binaries should be ready to use.
 The workspace needs to be sourced every time a new terminal is used (
 and Conda environment activated before that).
 
-Run the following command to source the workspace:
+The overall instructions for setting up a new terminal to use the built
+workspace are:
 
 ```bash
 # CMD
+conda activate gz-ws
 call install\setup.bat
 
 # PowerShell
+conda activate gz-ws
 .\install\setup.ps1
 ```
 

harmonic/moving_robot.md

@@ -88,7 +88,26 @@ The last command will display all messages sent on `/keyboard/keypress` topic.
 
 In the Gazebo window press different keys and you should see data (numbers) on the terminal where you run the `gz topic -e -t /keyboard/keypress` command.
 
-![KeyPublisher](tutorials/moving_robot/keypublisher_data.png)
+```
+$ gz topic -e -t /keyboard/keypress
+data: 68
+
+data: 85
+
+data: 72
+
+data: 74
+
+data: 81
+
+data: 16777235
+
+data: 16777234
+
+data: 16777237
+
+data: 16777236
+```
 
 We want to map these keystrokes into messages of type `Twist` and publish them to the `/cmd_vel` topic which our model listens to.
 The `TriggeredPublisher` plugin will do this.

harmonic/ros2_integration.md

@@ -76,7 +76,7 @@ Launching with composition:
 ros2 launch ros_gz_bridge ros_gz_bridge.launch.py bridge_name:=ros_gz_bridge config_file:=<path_to_your_YAML_file> use_composition:=True create_own_container:=True
 ```
 Alternatively, if an existing container is already running, you can pass its name
-when launching the bridge using the `container_name` parameter. More info about composition can be viewed [here](ros2_overview#composition)
+when launching the bridge using the `container_name` parameter. More info about composition can be viewed [here](ros2_overview.md#composition)
 
 Check [this block](https://github.com/gazebosim/ros_gz/blob/jazzy/ros_gz_bridge/launch/ros_gz_bridge.launch.py#L27-L34)
 from the source code to know all the different parameters accepted by this

harmonic/ros2_launch_gazebo.md

@@ -137,4 +137,4 @@ ros2 launch ros_gz_sim ros_gz_sim.launch.py world_sdf_file:=empty.sdf bridge_nam
 In the above launch files you may notice that the `create_own_container` argument for `ros_gz_bridge` is hardcoded to `False`. This has been done to prevent two duplicate containers from getting created (one for `gz_server` and another one for `ros_gz_bridge`), and instead make `ros_gz_bridge` use the container created by `gz_server`. More info about this can be viewed [here](https://github.com/gazebosim/ros_gz/pull/620#issue-2595570189)
 
 More info about `ros_gz_bridge` can be viewed [here](ros2_integration).
-More info about composition can be viewed [here](ros2_overview#composition).
+More info about composition can be viewed [here](ros2_overview.md#composition).

harmonic/sensors.md

@@ -322,17 +322,18 @@ You can download the finished node for this demo from [here](https://github.com/
 #### The lidar_node
 
 ```cpp
-gz::transport::Node node;
 std::string topic_pub = "/cmd_vel";
-gz::msgs::Twist data;
+gz::transport::Node node;
 auto pub = node.Advertise<gz::msgs::Twist>(topic_pub);
 ```
 
-We declare a `node` which will publish to `cmd_vel` topic and defined the message type `Twist`. Then advertise our node.
+We declare a `node` which will publish to `cmd_vel` topic. Then advertise our node.
 
 ```cpp
 void cb(const gz::msgs::LaserScan &_msg)
 {
+  gz::msgs::Twist data;
+
   bool allMore = true;
   for (int i = 0; i < _msg.ranges_size(); i++)
   {
@@ -362,11 +363,11 @@ If so we publish a message to our car to move forward. Otherwise we make the rob
 ```cpp
 int main(int argc, char **argv)
 {
-    std::string topic = "/lidar";
+    std::string topic_sub = "/lidar";
     // Subscribe to a topic by registering a callback.
-    if (!node.Subscribe(topic, cb))
+    if (!node.Subscribe(topic_sub, cb))
     {
-        std::cerr << "Error subscribing to topic [" << topic << "]" << std::endl;
+        std::cerr << "Error subscribing to topic [" << topic_sub << "]" << std::endl;
         return -1;
     }
 

harmonic/troubleshooting.md

@@ -19,6 +19,23 @@ GZ_CONFIG_PATH=<path_to_install_dir>/share/gz/
 
 ## macOS
 
+###  Maximum number of open files reached `ulimit` error
+When installing using homebrew, you may see the following error message:
+
+```bash
+Error: The maximum number of open files on this system has been reached. Use 'ulimit -n' to increase this limit.
+```
+
+As suggested in the error message, run the command below and check the output. The default value is set to `256` which is too low.
+```bash
+ulimit -n
+```
+
+Run the following command to increase the open files `ulimit` and then proceed with the homebrew install:
+```bash
+ulimit -n 10240
+```
+
 ### Unable to find `urdf_model.h` error
 After installing all the dependencies and starting the build process, you may encounter an error that looks like this:
 
@@ -233,3 +250,36 @@ foreach {
 }
 popd
 ```
+
+### Many errors from setuptools when running colcon
+When calling `colcon` to build the packages, you may face a wall of Python errors similar to this one:
+
+```
+> colcon graph
+Traceback (most recent call last):
+  File "<string>", line 1, in <module>
+ModuleNotFoundError: No module named 'setuptools.extern'
+[10.385s] colcon.colcon_core.package_identification ERROR Exception in package identification extension 'python_setup_py' in 'conda\Lib\site-packages\adodbapi': Command '['D:\\programovani\\gz-ws\\conda\\python.exe', '-c', "import sys;from setuptools.extern.packaging.specifiers import SpecifierSet;from distutils.core import run_setup;dist = run_setup(    'setup.py', script_args=('--dry-run',), stop_after='config');skip_keys = ('cmdclass', 'distclass', 'ext_modules', 'metadata');data = {    key: value for key, value in dist.__dict__.items()     if (        not key.startswith('_') and         not callable(value) and         key not in skip_keys and         key not in dist.display_option_names    )};data['metadata'] = {    k: v for k, v in dist.metadata.__dict__.items()     if k not in ('license_files', 'provides_extras')};sys.stdout.buffer.write(repr(data).encode('utf-8'))"]' returned non-zero exit status 1.
+```
+
+The messages are quite cryptic and do not point at the root cause. The root cause is that you have probably created a conda env directory in the same directory where you have the `src` directory containing the Gazebo sources (you have probably used `conda create --prefix ...` to create the env directory at a non-default destination).
+
+The solution is to move the conda env directory one level up.
+
+E.g., this is the problematic folder structure:
+
+```
+gz-ws\
+  conda\  # The conda env
+  src\    # The Gazebo sources
+    gz-sim\
+```
+
+To fix it, change the structure to something like this:
+
+```
+gz-ws\
+  src\
+    gz-sim\
+conda\
+```