diff --git a/Changelog.md b/Changelog.md index 453f5468b..0db89251a 100644 --- a/Changelog.md +++ b/Changelog.md @@ -1,6 +1,31 @@ ## Gazebo Transport 14.X -### Gazebo Transport 14.0.0 (2024-08-26) +### Gazebo Transport 14.0.0 (2024-09-25) + +1. **Baseline:** this includes all changes from 13.4.0 and earlier. + +1. Miscellaneous documentation fixes + * [Pull request #536](https://github.com/gazebosim/gz-transport/pull/536) + * [Pull request #539](https://github.com/gazebosim/gz-transport/pull/539) + * [Pull request #537](https://github.com/gazebosim/gz-transport/pull/537) + * [Pull request #534](https://github.com/gazebosim/gz-transport/pull/534) + * [Pull request #532](https://github.com/gazebosim/gz-transport/pull/533) + * [Pull request #532](https://github.com/gazebosim/gz-transport/pull/532) + * [Pull request #528](https://github.com/gazebosim/gz-transport/pull/528) + * [Pull request #527](https://github.com/gazebosim/gz-transport/pull/527) + * [Pull request #526](https://github.com/gazebosim/gz-transport/pull/526) + +1. Simplify the relay tutorial docker setup + * [Pull request #530](https://github.com/gazebosim/gz-transport/pull/530) + +1. Replace deprecated File.exists with File.exist and tweak tutorial + * [Pull request #529](https://github.com/gazebosim/gz-transport/pull/529) + +1. Update gz-transport14 badge URLs + * [Pull request #524](https://github.com/gazebosim/gz-transport/pull/524) + +1. Ionic Changelog + * [Pull request #523](https://github.com/gazebosim/gz-transport/pull/523) 1. Replace IGN_IP with GZ_IP * [Pull request #515](https://github.com/gazebosim/gz-transport/pull/515) diff --git a/README.md b/README.md index 3d2218584..1ae1e9284 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Build | Status -- | -- Test coverage | [![codecov](https://codecov.io/gh/gazebosim/gz-transport/tree/main/graph/badge.svg)](https://codecov.io/gh/gazebosim/gz-transport/tree/main) -Ubuntu Jammy | [![Build Status](https://build.osrfoundation.org/buildStatus/icon?job=gz_transport-ci-main-jammy-amd64)](https://build.osrfoundation.org/job/gz_transport-ci-main-jammy-amd64) +Ubuntu Noble | [![Build Status](https://build.osrfoundation.org/buildStatus/icon?job=gz_transport-ci-main-noble-amd64)](https://build.osrfoundation.org/job/gz_transport-ci-main-noble-amd64) Homebrew | [![Build Status](https://build.osrfoundation.org/buildStatus/icon?job=gz_transport-ci-main-homebrew-amd64)](https://build.osrfoundation.org/job/gz_transport-ci-main-homebrew-amd64) Windows | [![Build Status](https://build.osrfoundation.org/buildStatus/icon?job=gz_transport-main-win)](https://build.osrfoundation.org/job/gz_transport-main-win/) diff --git a/docker/Dockerfile b/docker/Dockerfile new file mode 100644 index 000000000..97aa41dec --- /dev/null +++ b/docker/Dockerfile @@ -0,0 +1,67 @@ +# Ubuntu 24.04 +FROM ubuntu:noble + +ENV TZ=America/Los_Angeles +ENV DEBIAN_FRONTEND=noninteractive +RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone + +# Tools I find useful during development +RUN apt-get update \ + && apt-get install -y \ + cmake \ + pkg-config \ + cppcheck \ + git \ + mercurial \ + build-essential \ + curl \ + libprotobuf-dev \ + protobuf-compiler \ + libprotoc-dev \ + libzmq3-dev \ + net-tools \ + uuid-dev \ + doxygen \ + ruby-ronn \ + libsqlite3-dev \ + python3-pybind11 \ + sudo \ + gnupg \ + lsb-release \ + wget \ + tzdata \ + && apt-get clean + +# Install gazebo dependencies +RUN /bin/sh -c 'echo "deb [trusted=yes] http://packages.osrfoundation.org/gazebo/ubuntu-stable `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-stable.list' \ + && /bin/sh -c 'wget http://packages.osrfoundation.org/gazebo.key -O - | apt-key add -' \ + && apt-get update \ + && apt-get install -y \ + libgz-cmake4-dev \ + libgz-math8-dev \ + libgz-msgs11-dev \ + libgz-utils3-cli-dev \ + && apt-get clean + +USER ubuntu +WORKDIR /tmp +# Gazebo transport +RUN git clone https://github.com/gazebosim/gz-transport.git -b gz-transport14 +RUN cd gz-transport \ + && mkdir build \ + && cd build \ + && cmake .. -DCMAKE_INSTALL_PREFIX=/tmp/gz-transport \ + && make -j4 install + +# Gazebo transport examples +RUN cd gz-transport/example \ + && mkdir build \ + && cd build \ + && cmake .. -DCMAKE_INSTALL_PREFIX=/tmp/gz-transport \ + && make -j4 + +WORKDIR /tmp/gz-transport/example/build + +# Customize your image here. +# E.g.: +# ENV PATH="/opt/sublime_text:$PATH" diff --git a/docker/build.bash b/docker/build.bash deleted file mode 100755 index 30c4e5a91..000000000 --- a/docker/build.bash +++ /dev/null @@ -1,44 +0,0 @@ -#!/usr/bin/env bash - -# -# Copyright (C) 2019 Open Source Robotics Foundation -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -# -# - -# Builds a Docker image. - -if [ $# -eq 0 ] -then - echo "Usage: $0 directory-name" - exit 1 -fi - -# get path to current directory -DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" - -if [ ! -d $DIR/$1 ] -then - echo "image-name must be a directory in the same folder as this script" - exit 2 -fi - -user_id=$(id -u) -image_name=$(basename $1) -image_plus_tag=$image_name:$(date +%Y_%b_%d_%H%M) - -docker build --rm -t $image_plus_tag --build-arg user_id=$user_id $DIR/$image_name -docker tag $image_plus_tag $image_name:latest - -echo "Built $image_plus_tag and tagged as $image_name:latest" diff --git a/docker/gz-transport/Dockerfile b/docker/gz-transport/Dockerfile deleted file mode 100644 index 45e3c390a..000000000 --- a/docker/gz-transport/Dockerfile +++ /dev/null @@ -1,93 +0,0 @@ -# Ubuntu 22.04 -FROM ubuntu:jammy - -ENV TZ=America/Los_Angeles -RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone - -# Tools I find useful during development -RUN apt-get update \ - && apt-get install -y \ - cmake \ - pkg-config \ - cppcheck \ - git \ - mercurial \ - build-essential \ - curl \ - libprotobuf-dev \ - protobuf-compiler \ - libprotoc-dev \ - libzmq3-dev \ - net-tools \ - uuid-dev \ - doxygen \ - ruby-ronn \ - libsqlite3-dev \ - python3-pybind11 \ - sudo \ - gnupg \ - lsb-release \ - wget \ - tzdata \ - && apt-get clean - -# Set USER and GROUP -ARG USER=developer -ARG GROUP=developer - -# Add a user with the same user_id as the user outside the container -# Requires a docker build argument `user_id`. - -RUN curl -SsL https://github.com/boxboat/fixuid/releases/download/v0.4/fixuid-0.4-linux-amd64.tar.gz | tar -C /usr/local/bin -xzf - && \ - chown root:root /usr/local/bin/fixuid && \ - chmod 4755 /usr/local/bin/fixuid && \ - mkdir -p /etc/fixuid && \ - printf "user: $USER\ngroup: $GROUP\n" > /etc/fixuid/config.yml - -RUN addgroup --gid 1000 $USER && \ - adduser --uid 1000 --ingroup $USER --home /home/$USER --shell /bin/sh --disabled-password --gecos "" $USER - -RUN adduser $USER sudo \ - && echo "$USER ALL=NOPASSWD: ALL" >> /etc/sudoers.d/$USER - -# Commands below run as the developer user. -USER $USER:$GROUP - -# When running a container start in the developer's home folder. -WORKDIR /home/$USER - -RUN export DEBIAN_FRONTEND=noninteractive \ - && sudo apt-get update \ - && sudo apt-get clean - -# Install gazebo dependencies -RUN sudo /bin/sh -c 'echo "deb [trusted=yes] http://packages.osrfoundation.org/gazebo/ubuntu-stable `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-stable.list' \ - && sudo /bin/sh -c 'wget http://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add -' \ - && sudo apt-get update \ - && sudo apt-get install -y \ - libgz-cmake4-dev \ - libgz-math8-dev \ - libgz-msgs11-dev \ - libgz-utils3-cli-dev \ - && sudo apt-get clean - -# Gazebo transport -RUN git clone https://github.com/gazebosim/gz-transport.git -b gz-transport14 \ - && cd gz-transport \ - && mkdir build \ - && cd build \ - && cmake .. -DCMAKE_INSTALL_PREFIX=/usr \ - && sudo make -j4 install \ - && cd ../.. - -# Gazebo transport examples -RUN cd gz-transport/example \ - && mkdir build \ - && cd build \ - && cmake .. \ - && make -j4 \ - && cd ../.. - -# Customize your image here. -# E.g.: -# ENV PATH="/opt/sublime_text:$PATH" diff --git a/docker/run.bash b/docker/run.bash deleted file mode 100755 index deb6fd50e..000000000 --- a/docker/run.bash +++ /dev/null @@ -1,91 +0,0 @@ -#!/usr/bin/env bash - -# -# Copyright (C) 2019 Open Source Robotics Foundation -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -# -# - -# Runs a docker container with the image created by build.bash -# Requires: -# docker -# nvidia-docker -# an X server -# Recommended: -# A joystick mounted to /dev/input/js0 or /dev/input/js1 - -if [ $# -lt 1 ] -then - echo "Usage: $0 [ ...]" - exit 1 -fi - -IMG=$(basename $1) - -ARGS=("$@") -WORKSPACES=("${ARGS[@]:1}") - -# Make sure processes in the container can connect to the x server -# Necessary so gazebo can create a context for OpenGL rendering (even headless) -XAUTH=/tmp/.docker.xauth -if [ ! -f $XAUTH ] -then - xauth_list=$(xauth nlist :0 | sed -e 's/^..../ffff/') - if [ ! -z "$xauth_list" ] - then - echo $xauth_list | xauth -f $XAUTH nmerge - - else - touch $XAUTH - fi - chmod a+r $XAUTH -fi - -DOCKER_OPTS= - -# Share your vim settings. -VIMRC=~/.vimrc -if [ -f $VIMRC ] -then - DOCKER_OPTS="$DOCKER_OPTS -v $VIMRC:/home/developer/.vimrc:ro" -fi - -for WS_DIR in ${WORKSPACES[@]} -do - WS_DIRNAME=$(basename $WS_DIR) - if [ ! -d $WS_DIR/src ] - then - echo "Other! $WS_DIR" - DOCKER_OPTS="$DOCKER_OPTS -v $WS_DIR:/home/developer/other/$WS_DIRNAME" - else - echo "Workspace! $WS_DIR" - DOCKER_OPTS="$DOCKER_OPTS -v $WS_DIR:/home/developer/workspaces/$WS_DIRNAME" - fi -done - -# Mount extra volumes if needed. -# E.g.: -# -v "/opt/sublime_text:/opt/sublime_text" \ - -docker run -it \ - -e DISPLAY \ - -e QT_X11_NO_MITSHM=1 \ - -e XAUTHORITY=$XAUTH \ - -v "$XAUTH:$XAUTH" \ - -v "/tmp/.X11-unix:/tmp/.X11-unix" \ - -v "/etc/localtime:/etc/localtime:ro" \ - -v "/dev/input:/dev/input" \ - --rm \ - --security-opt seccomp=unconfined \ - $DOCKER_OPTS \ - $IMG diff --git a/example/playback.cc b/example/playback.cc index 917dc88a1..bb9489020 100644 --- a/example/playback.cc +++ b/example/playback.cc @@ -21,6 +21,7 @@ /// Launch the gz-transport subscriber example if the log was created /// by recording the publisher example. +//! [complete] #include #include #include @@ -62,4 +63,7 @@ int main(int argc, char *argv[]) // Wait until the player stops on its own std::cout << "Playing all messages in the log file\n"; handle->WaitUntilFinished(); + + return 0; } +//! [complete] diff --git a/example/record.cc b/example/record.cc index c4586a54f..1a4045c50 100644 --- a/example/record.cc +++ b/example/record.cc @@ -20,6 +20,7 @@ /// Launch the gz-transport publisher example so this example has /// something to record. +//! [complete] #include #include #include @@ -65,4 +66,7 @@ int main(int argc, char *argv[]) recorder.Stop(); std::cout << "\nRecording finished!" << std::endl; + + return 0; } +//! [complete] diff --git a/log/src/cmd/cmdlog.rb.in b/log/src/cmd/cmdlog.rb.in index cc7120b11..624b1cca2 100644 --- a/log/src/cmd/cmdlog.rb.in +++ b/log/src/cmd/cmdlog.rb.in @@ -187,7 +187,7 @@ class Cmd case options['subcommand'] when 'record' - if options['force'] and File.exists?(options['file']) + if options['force'] and File.exist?(options['file']) begin File.delete(options['file']) rescue Exception => e diff --git a/log/test/integration/playback.cc b/log/test/integration/playback.cc index fb5f89c5a..1d1495857 100644 --- a/log/test/integration/playback.cc +++ b/log/test/integration/playback.cc @@ -568,7 +568,7 @@ TEST(playback, GZ_UTILS_TEST_DISABLED_ON_MAC(ReplayPauseResume)) ////////////////////////////////////////////////// /// \brief Record a log and then play it back calling the Step method to control /// the playback workflow. -TEST(playback, GZ_UTILS_TEST_DISABLED_ON_MAC(ReplayStep)) +TEST(playback, GZ_UTILS_TEST_ENABLED_ONLY_ON_LINUX(ReplayStep)) { std::vector topics = {"/foo", "/bar", "/baz"}; diff --git a/tutorials/01_intro.md b/tutorials/01_intro.md index 0088e0f66..3eab54fba 100644 --- a/tutorials/01_intro.md +++ b/tutorials/01_intro.md @@ -6,19 +6,22 @@ Next Tutorial: \ref installation Gazebo Transport is an open source communication library that allows sharing data between clients. In our context, a client is called a node. Nodes might -be running within the same process on the same machine or on separate machines located -around the world. Gazebo Transport is multi-platform (Linux, Mac OS X, and -Windows), so all the low level details, such as data alignment or endianness, are -hidden for you. +be running within the same process on the same machine or on separate machines +located around the world. Gazebo Transport is multi-platform (Linux, Mac OS X, +and Windows), so all the low level details, such as data alignment or +endianness, are hidden for you. -Gazebo Transport uses [Google Protocol buffers] -(https://developers.google.com/protocol-buffers/?hl=en) as the data type for -communicating between nodes. Users can define their own messages using the -Protobuf utils, and then exchange them between the nodes. Gazebo Transport -discovers, serializes and delivers messages to the destinations using a -combination of custom code and [ZeroMQ] (http://zeromq.org/). +Gazebo Transport uses +[Google Protocol buffers](https://developers.google.com/protocol-buffers/?hl=en) +as the data type for communicating between nodes. Users can define their own +messages using the Protobuf utils, and then exchange them between the nodes. +Gazebo Transport discovers, serializes and delivers messages to the +destinations using a combination of custom code and +[ZeroMQ](http://zeromq.org/). ## What programming language can I use with Gazebo Transport? -C++ is the native implementation and the only language that has all available library features. -Python implementation is a wrapper around C++ methods using `pybind11`. It does not support all features like C++, but contains the main features such as publication, subscription and service request. +C++ is the native implementation and the only language that has all available +library features. Python implementation is a wrapper around C++ methods using +`pybind11`. It does not support all features like C++, but contains the main +features such as publication, subscription and service request. diff --git a/tutorials/02_installation.md b/tutorials/02_installation.md index 981c1f55b..892073566 100644 --- a/tutorials/02_installation.md +++ b/tutorials/02_installation.md @@ -42,7 +42,7 @@ tap](https://github.com/osrf/homebrew-simulation). Gazebo Transport is straightforward to install on Mac OS X 10.9 (Mavericks) or higher. Installation on older versions requires changing the default standard library and rebuilding dependencies due to the use of c++11. For -purposes of this documentation, Assuming OS X 10.9 or greater is in +purposes of this documentation, assuming OS X 10.9 or greater is in use. Here are the instructions: Install homebrew, which should also prompt you to install the XCode @@ -84,7 +84,7 @@ which version you need. ## Ubuntu Linux For compiling the latest version of Gazebo Transport you will need an -Ubuntu distribution equal to 20.04 (Focal) or newer. +Ubuntu distribution equal to 24.04 (Noble) or newer. Make sure you have removed the Ubuntu pre-compiled binaries before installing from source: @@ -205,7 +205,7 @@ sudo make uninstall ### Prerequisites -First, follow the [gz-cmake](https://github.com/gazebosim/gz-cmake) tutorial for installing Conda, Visual Studio, CMake, etc., prerequisites, and creating a Conda environment. +First, follow the [source installation](https://gazebosim.org/docs/ionic/install_windows_src/) tutorial until step 5 included for installing Conda, Visual Studio, CMake, etc., prerequisites, and creating a Conda environment. Navigate to `condabin` if necessary to use the `conda` command (i.e., if Conda is not in your `PATH` environment variable. You can find the location of `condabin` in Anaconda Prompt, `where conda`). @@ -266,7 +266,7 @@ conda install libgz-cmake<#> libgz-msgs<#> libgz-tools<#> --channel conda-forge cmake --build . --config Release ``` - Try an example + Try an example (in the Release directory) ```bash responser ``` @@ -278,7 +278,7 @@ conda install libgz-cmake<#> libgz-msgs<#> libgz-tools<#> --channel conda-forge # Documentation -Visit the [documentation page](https://gazebosim.org/api/transport/12.0/index.html). +Visit the [documentation page](https://gazebosim.org/api/transport/14/index.html). ## Build documentation ```bash @@ -286,16 +286,9 @@ cd build make doc ``` -Upload documentation to gazebosim.org. -```bash -cd build -sh upload.sh +View the documentation by running the following command from the `build` directory. ``` - -If you're creating a new release, then tell gazebosim.org about - the new version. For example: -```bash -curl -k -X POST -d '{"libName":"transport", "version":"1.0.0", "releaseDate":"2017-10-09T12:10:13+02:00","password":"secret"}' http s://api.gazebosim.org/1.0/versions +firefox doxygen/html/index.html ``` # Testing diff --git a/tutorials/04_messages.md b/tutorials/04_messages.md index 85bc5ab00..4e6adc7fd 100644 --- a/tutorials/04_messages.md +++ b/tutorials/04_messages.md @@ -148,6 +148,20 @@ cmake --build . --config Release ## Running the examples +> **NOTE** +> It is essential to have a valid value of `GZ_PARTITION` environment variable +> and to have it set to the same value in all open terminals. As `GZ_PARTITION` +> is based on hostname and username, especially Windows and Mac users might +> have problems due to spaces in their username, which are not a valid character +> in `GZ_PARTITION`. gz-transport prints error `Invalid partition name` in such +> case. To resolve that, set `GZ_PARTITION` explicitly to a valid value: +> ```bash +> # Linux and Mac +> export GZ_PARTITION=test +> # Windows +> set GZ_PARTITION=test +> ``` + Open two new terminals and from your `build/` directory run the executables. From terminal 1: diff --git a/tutorials/05_services.md b/tutorials/05_services.md index 801a8fa8d..da4e0e955 100644 --- a/tutorials/05_services.md +++ b/tutorials/05_services.md @@ -609,6 +609,25 @@ cmake --build . --config Release ## Running the examples +> **NOTE** +> It is essential to have a valid value of `GZ_PARTITION` environment variable +> and to have it set to the same value in all open terminals. As `GZ_PARTITION` +> is based on hostname and username, especially Windows and Mac users might +> have problems due to spaces in their username, which are not a valid character +> in `GZ_PARTITION`. gz-transport prints error `Invalid partition name` in such +> case. To resolve that, set `GZ_PARTITION` explicitly to a valid value: +> ```bash +> # Linux and Mac +> export GZ_PARTITION=test +> # Windows +> set GZ_PARTITION=test +> ``` + +> **NOTE** +> On Windows, you can see firewall or antivirus prompts when running the examples. +> For them to work properly, you should allow all communication to the +> example programs. + Open three new terminals and from your ``build/`` directory run the executables. From terminal 1: @@ -661,7 +680,11 @@ directory run the executables. From terminal 1: ```{.sh} +# Linux and MacOS ./responser_oneway + +# Windows +.\Release\responser_oneway.exe ``` From terminal 2: @@ -678,11 +701,7 @@ In your responser terminal, you should expect an output similar to this one, showing that your service provider has received a request: ```{.sh} -# Linux and MacOS ./responser_oneway - -# Windows -.\Release\responser_oneway.exe Request received: [HELLO] ``` @@ -723,12 +742,8 @@ In your requesters' terminals, you should expect an output similar to this one, showing that you have received a response: ```{.sh} -# Linux and MacOS ./requester_no_input -# Windows -.\Release\requester_no_input.exe - Press to exit Response: [This is it! This is the answer. It says here...that a bolt of lightning is going to strike the clock tower at precisely 10:04pm, next diff --git a/tutorials/06_python_support.md b/tutorials/06_python_support.md index 81ebd2603..74204c2cd 100644 --- a/tutorials/06_python_support.md +++ b/tutorials/06_python_support.md @@ -9,7 +9,7 @@ In this tutorial, we are going to show the functionalities implemented in Python These features are brought up by creating bindings from the C++ implementation using pybind11. It is important to note that not all of C++ features are available yet, on this tutorial we will go over the most relevant features. For more information, -refer to the [__init__.py](https://github.com/gazebosim/gz-transport/blob/gz-transport13/python/src/__init__.py) +refer to the [__init__.py](https://github.com/gazebosim/gz-transport/blob/gz-transport14/python/src/__init__.py) file which is a wrapper for all the bindings. For this tutorial, we will create two nodes that communicate via messages. One node @@ -24,7 +24,7 @@ cd ~/gz_transport_tutorial ## Publisher -Download the [publisher.py](https://github.com/gazebosim/gz-transport/blob/gz-transport13/python/examples/publisher.py) file within the `gz_transport_tutorial` +Download the [publisher.py](https://github.com/gazebosim/gz-transport/blob/gz-transport14/python/examples/publisher.py) file within the `gz_transport_tutorial` folder and open it with your favorite editor: \snippet python/examples/publisher.py complete @@ -32,16 +32,16 @@ folder and open it with your favorite editor: ### Walkthrough ```{.py} - from gz.msgs10.stringmsg_pb2 import StringMsg - from gz.msgs10.vector3d_pb2 import Vector3d - from gz.transport13 import Node + from gz.msgs11.stringmsg_pb2 import StringMsg + from gz.msgs11.vector3d_pb2 import Vector3d + from gz.transport14 import Node ``` -The library `gz.transport13` contains all the Gazebo Transport elements that can be +The library `gz.transport14` contains all the Gazebo Transport elements that can be used in Python. The final API we will use is contained inside the class `Node`. -The lines `from gz.msgs10.stringmsg_pb2 import StringMsg` and `from gz.msgs10.vector3d_pb2 import Vector3d` -includes the generated protobuf code that we are going to use for our messages. +The lines `from gz.msgs11.stringmsg_pb2 import StringMsg` and `from gz.msgs11.vector3d_pb2 import Vector3d` +include the generated protobuf code that we are going to use for our messages. We are going to publish two types of messages: `StringMsg` and `Vector3d` protobuf messages. @@ -89,7 +89,7 @@ each topic. The method *publish()* sends a message to all the subscribers. ## Subscriber -Download the [subscriber.py](https://github.com/gazebosim/gz-transport/blob/gz-transport13/python/examples/subscriber.py) +Download the [subscriber.py](https://github.com/gazebosim/gz-transport/blob/gz-transport14/python/examples/subscriber.py) file into the `gz_transport_tutorial` folder and open it with your favorite editor: \snippet python/examples/subscriber.py complete @@ -97,12 +97,12 @@ file into the `gz_transport_tutorial` folder and open it with your favorite edit ### Walkthrough ```{.py} - from gz.msgs10.stringmsg_pb2 import StringMsg - from gz.msgs10.vector3d_pb2 import Vector3d - from gz.transport13 import Node + from gz.msgs11.stringmsg_pb2 import StringMsg + from gz.msgs11.vector3d_pb2 import Vector3d + from gz.transport14 import Node ``` -Just as before, we are importing the `Node` class from the `gz.transport13` library +Just as before, we are importing the `Node` class from the `gz.transport14` library and the generated code for the `StringMsg` and `Vector3d` protobuf messages. ```{.py} @@ -177,6 +177,20 @@ export PYTHONPATH=$PYTHONPATH:/lib/python ## Running the examples +> **NOTE** +> It is essential to have a valid value of `GZ_PARTITION` environment variable +> and to have it set to the same value in all open terminals. As `GZ_PARTITION` +> is based on hostname and username, especially Windows and Mac users might +> have problems due to spaces in their username, which are not a valid character +> in `GZ_PARTITION`. gz-transport prints error `Invalid partition name` in such +> case. To resolve that, set `GZ_PARTITION` explicitly to a valid value: +> ```bash +> # Linux and Mac +> export GZ_PARTITION=test +> # Windows +> set GZ_PARTITION=test +> ``` + Open two new terminals and directly run the Python scripts downloaded previously. From terminal 1: @@ -226,9 +240,9 @@ in several places (publisher and subscribers). We developed a couple of examples that demonstrate this particular issue. Take a look at a publisher and subscriber (whithin the same node) that have race -conditions triggered in the [data_race_without_mutex.py](https://github.com/gazebosim/gz-transport/blob/gz-transport13/python/examples/data_race_without_mutex.py) file. The proposed solution to this +conditions triggered in the [data_race_without_mutex.py](https://github.com/gazebosim/gz-transport/blob/gz-transport14/python/examples/data_race_without_mutex.py) file. The proposed solution to this issue is to use the `threading` library, you can see the same example with a mutex -in the [data_race_with_mutex.py](https://github.com/gazebosim/gz-transport/blob/gz-transport13/python/examples/data_race_with_mutex.py) file. +in the [data_race_with_mutex.py](https://github.com/gazebosim/gz-transport/blob/gz-transport14/python/examples/data_race_with_mutex.py) file. You can run any of those examples by just doing the following in a terminal: ```{.sh} @@ -251,8 +265,8 @@ of messages published per topic. We can declare the throttling option using the following code : ```{.py} - from gz.msgs10.stringmsg_pb2 import StringMsg - from gz.transport13 import Node, AdvertiseMessageOptions + from gz.msgs11.stringmsg_pb2 import StringMsg + from gz.transport14 import Node, AdvertiseMessageOptions # Create a transport node and advertise a topic with throttling enabled. node = Node() @@ -261,10 +275,9 @@ We can declare the throttling option using the following code : # Setting the throttling option opts = AdvertiseMessageOptions() opts.msgs_per_sec = 1 - pub = node.advertise(topic_name, StringMsg, opts); - if (!pub): + pub = node.advertise(topic_name, StringMsg, opts) + if not pub: print("Error advertising topic" + topic_name) - return False ``` ### Walkthrough @@ -280,7 +293,7 @@ it to set the publishing rate (the member `msgs_per_sec`), In our case, the rate specified is 1 msg/sec. ```{.py} - pub = node.advertise(topic_name, StringMsg, opts); + pub = node.advertise(topic_name, StringMsg, opts) ``` Next, we advertise the topic with message throttling enabled. To do it, we pass opts @@ -296,8 +309,8 @@ second from that particular topic. We can declare the throttling option using the following code : ```{.py} - from gz.msgs10.stringmsg_pb2 import StringMsg - from gz.transport13 import Node, SubscribeOptions + from gz.msgs11.stringmsg_pb2 import StringMsg + from gz.transport14 import Node, SubscribeOptions def stringmsg_cb(msg: StringMsg): print("Received StringMsg: [{}]".format(msg.data)) @@ -337,12 +350,12 @@ topic without having to modify the publisher and create a new log. We can declare the topic remapping option using the following code: ```{.py} - from gz.transport13 import Node, NodeOptions + from gz.transport14 import Node, NodeOptions # Create a transport node and remap a topic. nodeOpts = NodeOptions() - nodeOptions.add_topic_remap("/foo", "/bar"); - node = Node(nodeOptions); + nodeOpts.add_topic_remap("/example_stringmsg_topic", "/bar") + node = Node(nodeOpts) ``` You can modify the publisher example to add this option. @@ -367,7 +380,7 @@ The command `gz log playback` also supports the notion of topic remapping. Run ## Service Requester -Download the [requester.py](https://github.com/gazebosim/gz-transport/blob/gz-transport13/python/examples/requester.py) +Download the [requester.py](https://github.com/gazebosim/gz-transport/blob/gz-transport14/python/examples/requester.py) file into the `gz_transport_tutorial` folder and open it with your favorite editor: \snippet python/examples/requester.py complete @@ -375,11 +388,11 @@ file into the `gz_transport_tutorial` folder and open it with your favorite edit ### Walkthrough ```{.py} - from gz.msgs10.stringmsg_pb2 import StringMsg - from gz.transport13 import Node + from gz.msgs11.stringmsg_pb2 import StringMsg + from gz.transport14 import Node ``` -Just as before, we are importing the `Node` class from the `gz.transport13` +Just as before, we are importing the `Node` class from the `gz.transport14` library and the generated code for the `StringMsg` protobuf message. ```{.py} @@ -408,7 +421,7 @@ result and response of the request in some variables and printing them out. Unfortunately, this feature is not available on Python at the moment. However, we can use a service responser created in C++ and make a request to it from a -code in Python. Taking that into account, we will use the [response.cc](https://github.com/gazebosim/gz-transport/blob/gz-transport13/example/responser.cc) file as the service responser. +code in Python. Taking that into account, we will use the [response.cc](https://github.com/gazebosim/gz-transport/blob/gz-transport14/example/responser.cc) file as the service responser. ## Running the examples diff --git a/tutorials/07_security.md b/tutorials/07_security.md index 6ed4829fe..98f3d88c6 100644 --- a/tutorials/07_security.md +++ b/tutorials/07_security.md @@ -37,6 +37,20 @@ password. Also, every subscriber will only connect to secure publishers. ### Example +> **NOTE** +> It is essential to have a valid value of `GZ_PARTITION` environment variable +> and to have it set to the same value in all open terminals. As `GZ_PARTITION` +> is based on hostname and username, especially Windows and Mac users might +> have problems due to spaces in their username, which are not a valid character +> in `GZ_PARTITION`. gz-transport prints error `Invalid partition name` in such +> case. To resolve that, set `GZ_PARTITION` explicitly to a valid value: +> ```bash +> # Linux and Mac +> export GZ_PARTITION=test +> # Windows +> set GZ_PARTITION=test +> ``` + First, let's test unsecure communication. This example requires [gz-tools](https://github.com/gazebosim/gz-tools). diff --git a/tutorials/08_relay.md b/tutorials/08_relay.md index 24fe7e215..50649841c 100644 --- a/tutorials/08_relay.md +++ b/tutorials/08_relay.md @@ -29,25 +29,17 @@ Download the [build.bash](https://github.com/gazebosim/gz-transport/raw/gz-trans [Dockerfile](https://github.com/gazebosim/gz-transport/raw/gz-transport14/docker/gz-transport/Dockerfile) files. ```{.sh} -wget https://github.com/gazebosim/gz-transport/raw/gz-transport14/docker/build.bash -wget https://github.com/gazebosim/gz-transport/raw/gz-transport14/docker/run.bash -mkdir gz-transport && wget https://github.com/gazebosim/gz-transport/raw/gz-transport14/docker/gz-transport/Dockerfile -O gz-transport/Dockerfile -chmod +x build.bash run.bash +wget https://github.com/gazebosim/gz-transport/raw/gz-transport14/docker/gz-transport/Dockerfile -O Dockerfile ``` Now, it's time to build the Docker image: ``` -./build.bash gz-transport +docker build -t gz-transport-relay - < Dockerfile ``` Run your Docker container: ``` -./run.bash gz-transport -``` - -Inside the docker instance, go to the `example` directory: -``` -cd gz-transport/example/build +docker run -it --rm gz-transport-relay /bin/bash ``` Back on your host, make sure that you have Gazebo Tools and net-tools diff --git a/tutorials/10_logging.md b/tutorials/10_logging.md index 3e4e96aa7..d969ab127 100644 --- a/tutorials/10_logging.md +++ b/tutorials/10_logging.md @@ -28,54 +28,7 @@ cd ~/gz_transport_tutorial Download the [record.cc](https://github.com/gazebosim/gz-transport/raw/gz-transport14/example/record.cc) file within the `gz_transport_tutorial` folder and open it with your favorite editor: -```{.cpp} -#include -#include -#include - -#include -#include - -////////////////////////////////////////////////// -int main(int argc, char *argv[]) -{ - if (argc != 2) - { - std::cerr << "Usage: " << argv[0] << " OUTPUT.tlog\n"; - return -1; - } - - gz::transport::log::Recorder recorder; - - // Record all topics - const int64_t addTopicResult = recorder.AddTopic(std::regex(".*")); - if (addTopicResult < 0) - { - std::cerr << "An error occurred when trying to add topics: " - << addTopicResult << "\n"; - return -1; - } - - // Begin recording, saving received messages to the given file - const auto result = recorder.Start(argv[1]); - if (gz::transport::log::RecorderError::SUCCESS != result) - { - std::cerr << "Failed to start recording: " << static_cast(result) - << "\n"; - return -2; - } - - std::cout << "Press Ctrl+C to finish recording.\n Recording... " - << std::endl; - - // Wait until the interrupt signal is sent. - gz::transport::waitForShutdown(); - - recorder.Stop(); - - std::cout << "\nRecording finished!" << std::endl; -} -``` +\snippet example/record.cc complete ### Walkthrough @@ -130,50 +83,7 @@ Download the [playback.cc](https://github.com/gazebosim/gz-transport/raw/gz-tran file within the `gz_transport_tutorial` folder and open it with your favorite editor: -```{.cpp} -#include -#include -#include -#include - -////////////////////////////////////////////////// -int main(int argc, char *argv[]) -{ - if (argc != 2) - { - std::cerr << "Usage: " << argv[0] << " INPUT.tlog\n"; - return -1; - } - - gz::transport::log::Playback player(argv[1]); - - // Playback all topics - const int64_t addTopicResult = player.AddTopic(std::regex(".*")); - if (addTopicResult == 0) - { - std::cout << "No topics to play back\n"; - return 0; - } - else if (addTopicResult < 0) - { - std::cerr << "Failed to advertise topics: " << addTopicResult - << "\n"; - return -1; - } - - // Begin playback - const auto handle = player.Start(); - if (!handle) - { - std::cerr << "Failed to start playback\n"; - return -2; - } - - // Wait until the player stops on its own - std::cout << "Playing all messages in the log file\n"; - handle->WaitUntilFinished(); -} -``` +\snippet example/playback.cc complete ### Walkthrough @@ -238,6 +148,20 @@ cmake --build . --config Release ## Running the examples +> **NOTE** +> It is essential to have a valid value of `GZ_PARTITION` environment variable +> and to have it set to the same value in all open terminals. As `GZ_PARTITION` +> is based on hostname and username, especially Windows and Mac users might +> have problems due to spaces in their username, which are not a valid character +> in `GZ_PARTITION`. gz-transport prints error `Invalid partition name` in such +> case. To resolve that, set `GZ_PARTITION` explicitly to a valid value: +> ```bash +> # Linux and Mac +> export GZ_PARTITION=test +> # Windows +> set GZ_PARTITION=test +> ``` + Open two new terminals and from your `build/` directory run the recorder. From terminal 1: diff --git a/tutorials/23_topic_statistics.md b/tutorials/23_topic_statistics.md index 1f24806f6..92a214ff0 100644 --- a/tutorials/23_topic_statistics.md +++ b/tutorials/23_topic_statistics.md @@ -37,7 +37,7 @@ for both publishers and subscribers. Setting `GZ_TRANSPORT_TOPIC_STATISTICS` to Additionally, a node on the subscriber side of a pub/sub relationship must call `EnableStats`. For example: -``` +```c++ if (!node.EnableStats(topic, true)) { std::cout << "Unable to enable stats\n"; @@ -54,7 +54,7 @@ It is possible to change the statistics output topic from `/statistics` to one of your choosing by specifying a topic name when enabling topic statistics. For example: -``` +```c++ if (!node.EnableStats(topic, true, "/my_stats")) { std::cout << "Unable to enable stats\n"; @@ -64,7 +64,7 @@ if (!node.EnableStats(topic, true, "/my_stats")) You can also change the statistics publication rate from 1Hz by specifying the new Hz rate after the statistic's topic name: -``` +```c++ if (!node.EnableStats(topic, true, "/my_stats", 100)) { std::cout << "Unable to enable stats\n"; @@ -73,9 +73,39 @@ if (!node.EnableStats(topic, true, "/my_stats", 100)) ### Example +For running the example, build the binaries in the example directory: + +``` +git clone https://github.com/gazebosim/gz-transport -b gz-transport14 +cd gz-transport/example +cmake -S . -B build +# For UNIX +cmake --build build --parallel +# For Windows +cmake --build build --config release --parallel +``` + +#### Executing +> **NOTE** +> It is essential to have a valid value of `GZ_PARTITION` environment variable +> and to have it set to the same value in all open terminals. As `GZ_PARTITION` +> is based on hostname and username, especially Windows and Mac users might +> have problems due to spaces in their username, which are not a valid character +> in `GZ_PARTITION`. gz-transport prints error `Invalid partition name` in such +> case. To resolve that, set `GZ_PARTITION` explicitly to a valid value. + If you have the Gazebo Transport sources with the example programs built, -then you can test topic statistics by following these steps. +then you can test topic statistics by following these steps depending on the +platform: + +##### Linux or Mac + +1. Terminal 1: `GZ_PARTITION=test GZ_TRANSPORT_TOPIC_STATISTICS=1 ./example/build/publisher` +1. Terminal 2: `GZ_PARTITION=test GZ_TRANSPORT_TOPIC_STATISTICS=1 ./example/build/subscriber_stats` +1. Terminal 3: `GZ_PARTITION=test GZ_TRANSPORT_TOPIC_STATISTICS=1 gz topic -et /statistics` + +##### Windows -1. Terminal 1: `GZ_TRANSPORT_TOPIC_STATISTICS=1 ./example/build/publisher` -1. Terminal 2: `GZ_TRANSPORT_TOPIC_STATISTICS=1 ./example/build/subscriber_stats` -1. Terminal 3: `GZ_TRANSPORT_TOPIC_STATISTICS=1 gz topic -et /statistics` +1. Terminal 1: `set "GZ_PARTITION=test" && set "GZ_TRANSPORT_TOPIC_STATISTICS=1" && example\build\release\publisher.exe` +1. Terminal 2: `set "GZ_PARTITION=test" && set "GZ_TRANSPORT_TOPIC_STATISTICS=1" && example\build\subscriber_stats.exe` +1. Terminal 3: `set "GZ_PARTITION=test" && set "GZ_TRANSPORT_TOPIC_STATISTICS=1" && gz topic -et /statistics`