transport#

Gazebo Transport

Maintainer: caguero AT openrobotics DOT org

GitHub open issues GitHub open pull requests Discourse topics Hex.pm

Build

Status

Test coverage

codecov

Ubuntu Noble

Build Status

Homebrew

Build Status

Windows

Build Status

Gazebo Transport, a component of Gazebo, provides fast and efficient asynchronous message passing, services, and data logging.

Table of Contents

Features

Install

Usage

Documentation

Testing

Folder Structure

Contributing

Code of Conduct

Versioning

License

Features

Gazebo Transport is an open source communication library that allows exchanging data between clients. In our context, a client is called a node. Nodes might be running within the same process in the same machine or in machines located in different continents. 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 as the data serialization format 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.

Install

See the installation tutorial.

Usage

See tutorials and the example directory in the source code.

Known issue of command line tools

In the event that the installation is a mix of Debian and from source, command line tools from gz-tools may not work correctly.

A workaround is to define the environment variable GZ_CONFIG_PATH to point to the location of the Gazebo library installation, where the YAML file for the package is found, such as

export GZ_CONFIG_PATH=/usr/local/share/gz

This issue is tracked here.

Documentation

Visit the documentation page.

Folder Structure

gz-transport
├── conf        Configuration file for the integration with the `gz` CLI tool.
├── docker      Dockerfile with gz-transport installed and scripts to build and run the code.
├── example     Example programs that use most of the Gazebo Transport API.
├── include     Header files that get installed.
├── log         All the code related with Gazebo Transport logging.
├── src         Source code of the core library.
├── test        A directory of integration, performance and regression tests.
└── tutorials   A set of tutorials about Gazebo Transport features.

Contributing

Please see CONTRIBUTING.md.

Code of Conduct

Please see CODE_OF_CONDUCT.md.

Versioning

This library uses Semantic Versioning. Additionally, this library is part of the Gazebo project which periodically releases a versioned set of compatible and complimentary libraries. See the Gazebo website for version and release information.

License

This library is licensed under Apache 2.0. See also the LICENSE file.

Gazebo Transport 14.X

Gazebo Transport 14.0.0 (2024-09-25)

  1. Baseline: this includes all changes from 13.4.0 and earlier.

  2. Miscellaneous documentation fixes

  3. Simplify the relay tutorial docker setup

  4. Replace deprecated File.exists with File.exist and tweak tutorial

  5. Update gz-transport14 badge URLs

  6. Ionic Changelog

  7. Replace IGN_IP with GZ_IP

  8. Add an explicit dependency on cppzmq-dev

  9. Enable 24.04 CI, require cmake 3.22.1

  10. Allow programmatic configuration of unicast relays.

  11. Delete copy ctor and copy-assignment for log::Batch

  12. Remove python3-distutils since it’s not needed on Jammy (#496)

  13. Find Python3 directly, not with GzPython

  14. gz_TEST: more output when tests fail

  15. Remove HIDE_SYMBOLS_BY_DEFAULT: replace by a default configuration in gz-cmake.

  16. Use HIDE_SYMBOLS_BY_DEFAULT

  17. Bumps in Ionic: gz-transport14

Gazebo Transport 13.X

Gazebo Transport 13.4.0 (2024-06-18)

  1. Add frequency to topic CLI.

Gazebo Transport 13.3.0 (2024-06-05)

  1. Adding option to ignore local messages

  2. Include Python tutorial in list of tutorials

  3. Remove python3-distutils since it’s not needed on Jammy

  4. Add package.xml

Gazebo Transport 13.2.0 (2024-04-09)

  1. Use relative install path for gz tool data

  2. No input service request from the command line

  3. Use std::shared_ptr for gz::transport::NodeShared

  4. Use a default timeout when requesting a service from CLI.

  5. Fix test failures when run under colcon test

Gazebo Transport 13.1.0 (2024-03-14)

  1. Oneway service request from the command line

  2. Re-enable tests of bash completion functions for gz

  3. Find Python3 directly, not with GzPython

  4. Fix issue #468

  5. Test refactoring part 2

  6. Update CI badges in README

  7. Support for bazel on garden

  8. Use subprocess rather than custom code

  9. Infrastructure

  10. Remove duplicated functionality from test_config

  11. Make empty constructor as peer to explicit

  12. Adds the subcommands for the log command for bash completion

  13. Adds the python bindings tutorial

Gazebo Transport 13.0.0 (2023-09-29)

  1. Fix Docker in Harmonic

  2. Documentation fixes

  3. Protect remoteSubscribers with mutex.

  4. Remove deprecations in Harmonic

  5. ign -> gz

  6. Infrastructure

  7. Python Bindings for Publisher, Subscriber and Service Request features.

  8. Fix topic/service list inconsistency

  9. Show subscribers info when running topic info

  10. List subscribed topics when running topic list

  11. ⬆️ Bump main to 13.0.0~pre1

Gazebo Transport 12.X

Gazebo Transport 12.2.1 (2023-09-26)

  1. Infrastructure

  2. Fix topic/service list inconsistency

  3. Backport Windows fix to ign-transport8

  4. Fix unused-result warning

  5. Fix compatibility with protobuf 22

  6. Fix compiler warning and signedness issue

  7. Fix filesystem headers for tests

  8. Fix typos

Gazebo Transport 12.2.0 (2023-04-19)

  1. CI workflow: use checkout v3

  2. Rename COPYING to LICENSE

  3. Support clang and std::filesystem

  4. Added Node::RequestRaw

  5. Pass std::function by value to Node::Subscribe

  6. Prevent invoking callbacks after a node unsubscribes to a topic

  7. Suppress some Windows warnings

  8. Fix include/ignition/…/parameters header files

  9. Fix CLI configuration install path to ignition

Gazebo Transport 12.1.0 (2023-01-11)

  1. Ignition to Gazebo renaming.

  2. Use new ignition-specific formatter.

  3. Remove warnings in Garden on Ubuntu 22.04.

Gazebo Transport 12.0.0 (2022-09-22)

  1. Improved windows instructions

  2. Improved instructions

  3. Fix table in “Nodes and topics tutorial”

  4. Update link

  5. Tweak section title.

  6. Fix Docker build and relay tutorial instructions

  7. Fix bench example compilation.

  8. Download examples matching the version number

  9. Tweak topic statistics tutorial

  10. Don’t use ignition/msgs.hh

  11. Remove left-over from Discovery_TEST

  12. Suppress protobuf related Windows warnings

  13. Remove problematic discovery test

  14. ign -> gz Provisional Finale: Source Migration : gz-transport

  15. ign -> gz migrations

  16. Use auto for loop iterators

  17. Update GoogleTest to latest version

  18. ign -> gz Partial Docs Migration and Project Name Followups : gz-transport

  19. Migrate ignition-transport

  20. Rename CMake project to gz

  21. ign -> gz Macro Migration : gz-transport

  22. [ign -> gz] CMake functions

  23. ign -> gz Environment Variable Migration

  24. ign -> gz Namespace Migration : gz-transport

  25. ign -> gz migration

  26. Use ign-utils instead of ign-cmake utilities

  27. Remove Bionic from future releases (Garden+)

  28. Bumps in garden: ign-transport12 use ign-math7

  29. Bumps in garden : ci_matching_branch/bump_garden_ign-transport12

Gazebo Transport 11.X

Gazebo Transport 11.4.1 (2023-09-01)

  1. Fix topic/service list inconsistency

  2. Backport Windows fix to ign-transport8

  3. Fix unused-result warning

  4. Fix compatibility with protobuf 22

  5. Fix compiler warning and signedness issue

  6. Rename COPYING to LICENSE

  7. Infrastructure

  8. Support clang and std::filesystem

Gazebo Transport 11.4.0 (2023-03-08)

  1. Added Node::RequestRaw

  2. Suppress some Windows warnings.

  3. All changes up to version 8.2.0.

Gazebo Transport 11.3.2 (2022-12-08)

  1. Fix include/ignition/…/parameters header files

Gazebo Transport 11.3.1 (2022-12-01)

  1. Fix CLI configuration install path to ignition

Gazebo Transport 11.3.0 (2022-10-31)

  1. Add parameters component

  2. Fix build for Debian Bullseye

Gazebo Transport 11.2.0 (2022-08-16)

  1. Remove problematic discovery test

  2. Change IGN_DESIGNATION to GZ_DESIGNATION

  3. Ignition -> Gazebo

  4. Bash completion for flags

Gazebo Transport 11.1.0 (2022-06-01)

  1. Add option to output messages in JSON format

  2. Use libexec to install lib binaries

  3. Use exec instead of popen to run ign-launch binary

  4. Focal CI: static checkers, doxygen linters, compiler warnings

  5. Add Ubuntu Jammy CI

  6. Corrected a typo in topic_main.cc

  7. Remove no username error messages

  8. Try USER variable to retrieve the username.

  9. Documented the default value of IGN_PARTITION

  10. Remove static on registrationCb and unregistrationCb.

  11. Make zmq check for post 4.3.1 not to include 4.3.1

  12. NetUtils: simplify logic in determineInterfaces

  13. Fix Homebrew warning (backport from Fortress) (#268)

Gazebo Transport 11.0.0 (2021-09-28)

  1. Windows fix

  2. Remove unnecessary copy and assignment operators

  3. Depend on gz-msgs8

  4. Infrastructure

Gazebo Transport 10.X

Gazebo Transport 10.2.0 (2022-03-25)

  1. Use exec instead of popen to run gz-launch binary

  2. Focal CI: static checkers, doxygen linters, compiler warnings

  3. Add option to output messages in JSON format

  4. Remove no username error messages

  5. Documented the default value of GZ_PARTITION

  6. Remove static on registrationCb and unregistrationCb.

  7. Make zmq check for post 4.3.1 not to include 4.3.1

  8. NetUtils: simplify logic in determineInterfaces

  9. Fix Homebrew warning (backport from Fortress)

Gazebo Transport 10.1.0 (2021-10-17)

  1. Fix Homebrew warning (backport from Fortress).

  2. Use standalone executables with gz tool.

  3. Make zmq check for post 4.3.1 not to include 4.3.1

  4. Remove unnecessary copy and assignment operators (#241).

Gazebo Transport 10.0.0 (2021-03-30)

  1. Depend on cli component of ignition-utils

  2. Add instructions to build and run examples

  3. Bump in edifice: gz-msgs7

  4. Configurable IP address and port for discovery

  5. Changes from Dome tutorial party

  6. Infrastructure and documentation

Gazebo Transport 9.X

Gazebo Transport 9.X.X

Gazebo Transport 9.1.1 (2021-01-05)

  1. Add errno output for discovery.

  2. Consider all network interfaces when checking HOST option.

  3. Remove tools/code_check and update codecov.

  4. Remove deprecated test.

  5. Master branch updates.

  6. Add windows installation.

Gazebo Transport 9.1.0 (2021-01-05)

  1. All changes up to version 8.2.0.

Gazebo Transport 9.0.0 (2020-09-29)

  1. Fix link in “development” tutorial.

  2. Remove contribute tutorial.

  3. Update link to the tutorials.

  4. Use private access modifier for pImpl variable in MsgIter class.

  5. Remove deprecations before 9.x.x release.

  6. Make CPPZMQ a PUBLIC dependency.

  7. Update codeowners.

  8. Removed markdown-header.

  9. Removed repeated installation instructions.

  10. Need ignition-msgs version 6

  11. Update link to repo.

  12. Fix download link.

  13. Workflow updates.

  14. Add .gitignore.

  15. Update BitBucket links.

Gazebo Transport 8.X

Gazebo Transport 8.X.X

Gazebo Transport 8.2.0 (2020-01-05)

  1. All changes up to version 7.5.1.

  2. Addition of topic statistics that can report number of dropped messages and publication, age, and reception statistics.

Gazebo Transport 8.5.0 (2024-01-05)

  1. Update github action workflows

  2. Adds the subcommands for the log command

  3. Fix topic/service list inconsistency

  4. Backport Windows fix to ign-transport8

  5. Fix compatibility with protobuf 22

  6. Fix compiler warning and signedness issue

  7. Support clang and std::filesystem

  8. Pass std::function by value to Node::Subscribe

Gazebo Transport 8.4.0 (2022-11-17)

  1. ign -> gz : Remove redundant namespace references.

  2. Backport Windows fix from main branch.

  3. ign -> gz Migrate Ignition Headers : gz-transport.

Gazebo Transport 8.3.0 (2022-07-27)

  1. Ignition -> Gazebo

  2. Bash completion for flags

  3. Focal CI: static checkers, doxygen linters, compiler warnings

  4. Remove no username error messages

  5. Documented the default value of GZ_PARTITION

  6. Remove static on registrationCb and unregistrationCb.

Gazebo Transport 8.2.1 (2021-10-27)

  1. Make zmq check for post 4.3.1 not to include 4.3.1

  2. Fix Homebrew warning (backport from Fortress)

  3. Infrastructure

  4. Remove deprecated test

  5. Add Windows Installation using conda-forge, and cleanup install docs

Gazebo Transport 8.2.0 (2020-01-05)

  1. All changes up to version 7.5.1.

  2. Addition of topic statistics that can report number of dropped messages and publication, age, and reception statistics.

Gazebo Transport 8.1.0 (2020-08-28)

  1. Fix mem leak.

  2. One NodeShared per process.

  3. Remove Windows warnings.

  4. Remove warnings on Homebrew.

  5. Fix ByteSize deprecation warnings for Protobuf 3.1+.

  6. Improve compiler support for c++ filesystem.

  7. Support playback of corrupt log files.

  8. Add signal handler to log playback.

  9. Added additional publishers and subscribers to the bench example program in order to simulate high network traffic conditions.

  10. Added topic subscription to the C interface.

  11. Added fast log playback, where messages are published without waiting.

Gazebo Transport 8.0.0 (2019-12-10)

  1. Upgrade to ignition-msgs5.

  2. Utilize protobuf messages for discovery.

  3. Ignore incompatible discovery messages and reduce console spam.

  4. Improve compiler support for c++ filesystem.

  5. This release includes all changes up to 7.5.0.

Gazebo Transport 7

Gazebo Transport 7.5.1 (2020-12-23)

  1. CI fixes

  2. Fix codecheck

  3. Prevent empty messages from spamming the console

Gazebo Transport 7.5.0 (2020-07-29)

  1. Disable flaky Mac OS X tests

  2. Prevent empty messages from spamming the console

  3. Modernize actions CI

  4. Helper function to get a valid topic name

  5. GitHub migration

  6. Fix ZMQ and Protobuf warnings

  7. Handle getpwduid_r error cases. This addresses issue #118. Solution was created in pull request #441 by Poh Zhi-Ee.

Gazebo Transport 7.4.0 (2020-03-09)

  1. Removed a sleep from NodeShared. The sleep was meant to guarantee message delivery during connect. This approach would fail if the delay between nodes was too large.

  2. Set default message buffer sizes to 1000, for both send and receive buffers.

  3. Added support for configuring message buffers via environment variables.

Gazebo Transport 7.3.0

  1. Write to disk from a background thread in log recorder

  2. Restore original Playback::Start and add overload with new parameter to fix ABI.

  3. Improve compiler support for c++ filesystem.

Gazebo Transport 7.2.1

  1. Updates to C interface subscription options.

Gazebo Transport 7.2.0

  1. Support playback of corrupt log files.

  2. Add signal handler to log playback.

  3. Ignore incompatible discovery messages and reduce console spam.

  4. Added additional publishers and subscribers to the bench example program in order to simulate high network traffic conditions.

  5. Added topic subscription to the C interface.

  6. Added fast log playback, where messages are published without waiting.

Gazebo Transport 7.1.0

  1. Added method for determining if a throttled publisher is ready to publish.

  2. Add intraprocess field to MessageInfo. The intraprocess field indicates whether the message is coming from a node within this process.

Gazebo Transport 7.0.0

  1. Fix fast constructor-destructor deadlock race condition.

  2. Added ability to specify partition information on a node through the CIface.

  3. Added ability to advertise a topic through the CIface.

  4. Added a -n argument to the echo command line tool, where -n can be used to specify the number of messages to echo and then exit. Made the gz.hh header file private (not installed).

  5. Added start of C interface, currently it supports only pub/sub.

  6. Introduce GZ_RELAY.

  7. Upgrade to ignition-msgs4.

Gazebo Transport 6

Gazebo Transport 6.X.X

  1. Ignore EPERM and ENOBUFS errors during discovery, generalize cmake for gz tool files

  2. Skip cmd*.rb generation on windows to fix build

Gazebo Transport 6.0.0

  1. Upgrade to proto3, c++17, ignition-cmake2 and ignition-msgs3.

Gazebo Transport 5

Gazebo Transport 5.X.X

  1. Added support for alternative clock sources during log recording.

  2. Exposed Log and log Playback time information.

  3. Added the ability to Seek within the log playback, which makes possible to jump to any valid time point of the reproduction.

  4. Added the ability to Step the advance of the playback from within the log replayer.

  5. Added the ability to Pause/Resume playback from the log replayer.

  6. Added support for topic remapping when running “gz log playback”. Note that the string “:=” is not allowed now as part of a partition, namespace or topic anymore.

  7. Added the ability to remap topic names.

  8. Prevent the log recorder from subscribing to topics that have already been added.

  9. Added log::Recorder::Topics that returns the set of added topics.

  10. Added log::Recorder::Filename that returns the name of the log file.

  11. Added a logging tutorial

  12. Added a migration guide for helping with the transition between major versions

  13. Converted gz-transport-log into a component

  14. Added inline versioned namespace to the log library

  15. Added inline versioned namespace to the main library

  16. Added –force option to ‘gz log record’

Gazebo Transport 4

Gazebo Transport 4.X.X

  1. Ignore subinterfaces when using determineInterfaces().

  2. Refactored Playback to return a PlaybackHandle from Start()

  3. Added command line tool for the logging features

  4. Added examples using logging features

  5. Added integration tests for recording

  6. Added ability to play back gz transport topics

  7. Added ability to record gz transport topics

  8. Added ability to query log messages by topic name and time received

  9. Added ability to get all messages from a log file

  10. Added ability to insert messages into a sqlite3 based log file

  11. Added TopicUtils::DecomposeFullyQualifiedTopic()

Gazebo Transport 4.0.0 (2018-01-XX)

  1. Basic authentication for topics.

  2. Upgrade to gz-cmake.

  3. Added a benchmark program to test latency and throughput.

  4. Support publication and receipt of raw serialized data.

  5. Use zero copy when publishing messages.

  6. Added publishing and receiving messages as raw bytes

  7. Updated service responder callbacks to return a boolean value. The existing functions have been deprecated.

  8. Hide ZMQ from public interfaces

Gazebo Transport 3

Gazebo Transport 3.X.X

Gazebo Transport 3.1.0 (2017-11-29)

  1. Documentation improvements

  2. Workaround for the ghost Msbuild warning in Jenkins plugin

  3. Added tests for gz.cc

  4. Remove manual setting of flags for dynamic linking of the Windows CRT library

  5. Add BUILD_TESTING CMake option and tests target

  6. Remove unused statement from Header::Unpack

  7. Port cmake fixes from sdformat

  8. Clean up DefaultFlags.cmake

  9. Add the new const methods to overloaded bool operator

  10. SubscriptionHandler.hh fix std::move compiler warning

  11. Fix gz topic|service fails on MacOS X if system integrity protection is enabled

Gazebo Transport 3.0.0

  1. Added optional message throttling when publishing messages.

  2. Support for an optional MessageInfo parameter in the user callbacks for receiving messages. This parameter provides some information about the message received (e.g.: topic name).

  3. Added Node::Publisher::HasConnections function that can be used to check if a Publisher has subscribers.

  4. Add gz topic –echo command line tool.

  5. Support a generic callback signature for receiving messages of any type.

  6. Node::Unadvertise(), Node::Publish() and Node::TopicsAdvertised() removed. Node::Advertise() returns a Node::Publisher object that can be used for publishing messages. When this object runs out of scope the topic is unadvertised.

  7. Create AdvertiseMessageOptions and AdvertiseServiceOptions classes.

  8. Subscription options added. The first option is to provide the ability to set the received message rate on the subscriber side.

  9. Added gz service –req <args …> for requesting services using the command line.

  10. Do not allow to advertise a topic that is currently advertised on the same node. See issue #54

  11. ZeroMQ updated from 3.2.4 to 4.0.4 on Windows.

Gazebo Transport 2.x

  1. Fix issue #55.

  2. Protobuf3 support added.

  3. ZeroMQ updated from 3.2.4 to 4.0.4 on Windows.

  4. Copyright added to tools/code_check.sh and tools/cpplint_to_cppcheckxml.py

  5. Fix case where std::bad_function_call could be thrown.

Gazebo Transport 2.0.0

  1. Move ZMQ initialization from constructor to separate function in NodeShared.

  2. Node::Advertise returns a publisher id that can be used to publish messages, as an alternative to remembering topic strings.

Gazebo Transport 1.x

Gazebo Transport 1.2.0

  1. Removed duplicate code in NetUtils, and improved speed of DNS lookup