linecode / ign-transport

Transport library for component communication based on publication/subscription and service calls.

Ignition Transport

Maintainer: caguero AT openrobotics DOT org

Build	Status
Test coverage
Ubuntu Bionic
Homebrew
Windows

Ignition Transport, a component of Ignition Robotics, provides fast and efficient asyncronous message passing, services, and data logging.

Table of Contents

Features

Install

Usage

Documentation

Testing

Folder Structure

Contributing

Code of Conduct

Versioning

License

Features

Ignition 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. Ignition 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.

Ignition 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. Ignition 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 ign-tools may not work correctly.

A workaround for a single package is to define the environment variable IGN_CONFIG_PATH to point to the location of the Ignition library installation, where the YAML file for the package is found, such as

export IGN_CONFIG_PATH=/usr/local/share/ignition

However, that environment variable only takes a single path, which means if the installations from source are in different locations, only one can be specified.

Another workaround for working with multiple Ignition libraries on the command line is using symbolic links to each library's YAML file.

mkdir ~/.ignition/tools/configs -p
cd ~/.ignition/tools/configs/
ln -s /usr/local/share/ignition/fuel4.yaml .
ln -s /usr/local/share/ignition/transport7.yaml .
ln -s /usr/local/share/ignition/transportlog7.yaml .
...
export IGN_CONFIG_PATH=$HOME/.ignition/tools/configs

This issue is tracked here.

Documentation

Visit the documentation page.

Build documentation

cd build
make doc

Upload documentation to ignitionrobotics.org.

cd build
sh upload.sh

If you're creating a new release, then tell ignitionrobotics.org about the new version. For example:

curl -k -X POST -d '{"libName":"transport", "version":"1.0.0", "releaseDate":"2017-10-09T12:10:13+02:00","password":"secret"}' https://api.ignitionrobotics.org/1.0/versions

Testing

Tests can be run by building the test target. From your build directory you can run:

$ make test

Folder Structure

ign-transport
├── conf        Configuration file for the integration with the `ign` CLI tool.
├── example     Example programs that use most of the Ignition Transport API.
├── include     Header files that get installed.
├── log         All the code related with Ignition Transport logging.
├── src         Source code of the core library.
├── test        A directory of integration, performance and regression tests.
├── tools       Scripts for continuous integration testing.
└── tutorials   A set of tutorials about Ignition 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 Ignition Robotics project which periodically releases a versioned set of compatible and complimentary libraries. See the Ignition Robotics website for version and release information.

License

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