Skip to content

Commit

Permalink
Merge pull request #263 from budrus/iox-#136-gitter_badge
Browse files Browse the repository at this point in the history 
Iox #136 gitter badge
  • Loading branch information
Michael Pöhnl authored Sep 2, 2020
2 parents 9b20d9d + c2e6844 commit 0e37f5e
Show file tree
Hide file tree
Showing 8 changed files with 226 additions and 200 deletions.
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -179,8 +179,8 @@ Results will be available on this [Helix QAC dashboard](https://qaverify.program
of the maintainers, if you're interested in getting access.

It is possible that not the whole codebase follows these rules, things are work in progress. But this is where we want
go. As of now we don't have any continous integration checks implemented but will rely on reviews during the pull
requests. We're planning to introduce continous integration checks in the near future.
go. As of now we don't have any continuos integration checks implemented but will rely on reviews during the pull
requests. We're planning to introduce continuos integration checks in the near future.

### Header

Expand Down
8 changes: 2 additions & 6 deletions PLANNED_FEATURES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,5 @@ This list contains rather high-prio features that will most likely be implemente
* Request-response communication
* Support for multiple publishers on the same topic

## Out of scope

These are feature that are not in the focus of iceoryx. However if you have ideas or wishes and find them on this list,
feel free to start the discussion by raising a feature request anyway.

* Make iceoryx run on microcontrollers
If you have ideas or wishes and don't find them on this list,
feel free to start the discussion by raising a feature request.
231 changes: 46 additions & 185 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,45 +1,75 @@
# iceoryx - an IPC middleware for POSIX-based systems
# iceoryx - true zero-copy inter-process-communication

<p align="center">
<img src="https://user-images.githubusercontent.com/8661268/70233652-4aa6d180-175f-11ea-8524-2344e0d3935c.png" width="50%">
</p>

[![Build & Test](https://github.com/eclipse/iceoryx/workflows/Build%20&%20Test/badge.svg?branch=master)](https://github.com/eclipse/iceoryx/actions)
[![Gitter](https://badges.gitter.im/eclipse/iceoryx.svg)](https://gitter.im/eclipse/iceoryx)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

## Introduction

Great that you've made it to this little Eclipse project! Let's get you started by providing a quick background
tour, introducing the project scope and guide you through the examples.
tour, introducing the project scope and all you need for installation and a first running example.

So first off: What is iceoryx?

iceoryx is an inter-process-communication (IPC) middleware for various operating systems (currently we support Linux, MacOS and QNX).
It has its origins in the automotive industry, where large amounts of data have to be transferred between different processes
when it comes to driver assistance or automated driving systems. However, the efficient communication mechanisms can also be applied
to a wider range of use cases, e.g. in the field of robotics or game development.

<p align="center">
<img src="https://user-images.githubusercontent.com/8661268/74612998-b962bc80-510a-11ea-97f0-62f41c5d287b.gif" width="100%">
</p>

Iceoryx is an inter-process communication (IPC) middleware for [POSIX](https://en.wikipedia.org/wiki/POSIX) based
operating systems. It features shared memory capabilities that allow a true zero-copy data transfer. For more information have a look at the [1000 words iceoryx introduction in the eclipse newsletter.](https://www.eclipse.org/community/eclipse_newsletter/2019/december/4.php)
iceoryx uses a true zero-copy, shared memory approach that allows to transfer data from publishers to subscribers without a single copy.
This ensures data transmissions with constant latency, regardless of the size of the payload. For more information have a look at the
[1000 words iceoryx introduction](https://www.eclipse.org/community/eclipse_newsletter/2019/december/4.php)

Originating from the automotive domain, it is crucial to transfer a huge amount of data between multiple processes to
realize driver assistance systems or automated driving applications. Moreover, the same efficient communication
mechanism can be applied to a broader range of use cases, e.g. in the field of robotics or game development.
<p align="center">
<img src="https://user-images.githubusercontent.com/55156294/91751530-35af7f80-ebc5-11ea-9aed-eed590b229df.png" width="80%">
</p>

It's all about the API!
You're right, middleware is a cluttered term and can somehow be all or nothing, so let's talk about the [goals and non-goals](doc/goals-non-goals.md) of iceoryx.

It's all about the API?!

Don't get too frighten of the API when strolling through the codebase. Think of iceoryx's API as a "plumbing" one
("plumbing" as defined in Git, which means low-level). We're not using the "plumbing" API ourselves, but instead a typed API.
An example for a "porcelain" API would be [ROS2](https://www.ros.org/). Others are listed in the next section.
The normal use case is that iceoryx is integrated as high-performance IPC transport layer in a bigger framework with additional API layers.
An example for such a "porcelain" API would be [ROS2](https://www.ros.org/). Others are listed in the next section.

### Where is Eclipse iceoryx used?
### Where is Eclipse iceoryx already used?

|Framework | Description |
|---|---|
| [ROS2](https://github.com/ros2/rmw_iceoryx) | Eclipse iceoryx can be used inside the [robot operating system](https://www.ros.org/) with rmw_iceoryx |
| [eCAL](https://github.com/continental/ecal) | Open-source middleware from [Continental AG](https://www.continental.com/) supporting pub/sub and various message protocols |
| [ROS2](https://github.com/ros2/rmw_iceoryx) | Eclipse iceoryx can be used inside the [robot operating system](https://www.ros.org/) with [rmw_iceoryx](https://github.com/ros2/rmw_iceoryx.git) |
| [eCAL](https://github.com/continental/ecal) | Open-source framework from [Continental AG](https://www.continental.com/) supporting pub/sub and various message protocols |
| [RTA-VRTE](https://www.etas.com/en/products/rta-vrte.php) | [Adaptive AUTOSAR](https://www.autosar.org/standards/adaptive-platform/) platform software framework for vehicle computer from [ETAS GmbH](https://www.etas.com) |
| [Cyclone DDS](https://github.com/eclipse-cyclonedds/cyclonedds) | Performant and robust open-source DDS implementation maintained by [ADLINK Technology Inc.](https://www.adlinktech.com/) |

## Build and install

You can find the build and installation guidelines [here](doc/installation-guide.md).

## Examples

After you've built all the necessary things, you can continue playing around with the [examples](./iceoryx_examples).

## Build and run in a Docker environment

If you want to avoid installing anything on your host machine but you have Docker installed, it is possible to use it to build and run iceoryx applications.

Please see the dedicated [README.md](tools/docker/README.md) for information on how to do this.

## Documentation

* [Concepts](doc/conceptual-guide.md)
* [Usage Guide](doc/usage-guide.md)
* [Ice0ryx Utils Hacker Guide](iceoryx_utils/README.md)

### Targeted quality levels & platforms

> [Quality level](./CONTRIBUTING.md#quality-levels) are 5..1, where 1 is highest
Expand All @@ -55,174 +85,13 @@ An example for a "porcelain" API would be [ROS2](https://www.ros.org/). Others a
| iceoryx_utils | 1 | 4 | |
| iceoryx_introspection | 5 | 5 | |

### Scope

Who can benefit of using iceoryx? What's in for those folks?

#### User personas

**Andrew, the HAD developer**
Andrew is a software developer at a startup working on autonomous cars. Currently their project is using ROS, because
it's easy to get the car driving. After some months, he's realizing that sending gigabytes around, leads to high runtime
demands with ROS. A college mentions iceoryx during lunch, which might be interesting because it has a zero-copy
mechanism and offers a ROS RMW implementation. Soon after giving iceoryx a try, Andrew is thrilled about it. He cannot only feel
the runtime performance boost, but also still keep using his beloved ROS visualization tools!

**Martha, the indie game developer**
Martha always had troubles with those silly game engines. Some are slow but free, others are fast but too expensive.
It's a hard life if you're independent. When a friend who works in the automotive industry mentions he has just started
using iceoryx, which offers fast shared memory communication she listens up. Iceoryx is solely passing pointers around
and does avoid copies to the utmost? "I'll definitely try iceoryx in my new project and see if I can speed up the
performance with my low cost engine" she thinks while wandering home at night after the meetup with her friend.

**Robby, the lonely robot**
Robby is autonomous robot built during a research project at a university. He has a great set of features and can
astonish the crowds by creating a detailed map of the university building in under an hour. However, they made him use
that slow self-made IPC to communicate with his sensors because his parents wanted to get started fast. Though that
makes it hard for him to react in real-time to dangerous incidents like flying coffee cups. When strolling through
the interwebs on a lonely evening, he finds out about iceoryx: Free-to-use, high-performance data transfer with low
runtime overhead, real-time support! Brilliant! Maybe even Robby's biggest wish for a network binding will come true,
so he can stream his favorite [video](https://www.youtube.com/watch?v=g5NkgZXWl0w) even faster!

## Installation

iceoryx_utils and iceoryx_posh are deployed as independent cmake packages. Posh is using some functions from utils and is depending on it. You are able to build posh and utils and integrate in into existing cmake projects.

### Prerequisites

#### Mac OS

Before installing iceoryx you need a XCode installation, git and optional an installed ncurses library for
the introspection client. To install ncurses locally into your build folder follow these steps
```
cd iceoryx
ICEORYX_DIR=$PWD
mkdir -p build
cd build
git clone https://github.com/mirror/ncurses.git
cd ncurses
git checkout v6.2
./configure --prefix=$ICEORYX_DIR/build/dependencies/ --exec-prefix=$ICEORYX_DIR/build/dependencies/ --with-termlib
make -j12
make install
```

If you would like to use our Cyclone DDS Gateway you have to install Cyclone DDS first, see
[https://github.com/eclipse-cyclonedds/cyclonedds](https://github.com/eclipse-cyclonedds/cyclonedds).

#### Linux

Although we strive to be fully POSIX-compliant, we recommend using Ubuntu 18.04 and at least GCC 7.5.0 for development.

You will need to install the following packages:
```
sudo apt install cmake libacl1-dev libncurses5-dev pkg-config
```

Additionally, there is an optional dependency to the MIT licensed cpptoml library, which is used to parse a RouDi config file for the mempool config.
[cpptoml](https://github.com/skystrife/cpptoml)

### Build with CMake (all supported platforms)

**NOTE:** Requires CMake version 3.5 or higher.

The `CMakeLists.txt` from `iceoryx_meta` can be used to easily develop iceoryx with an IDE.

1. Clone the repository
```
git clone https://github.com/eclipse/iceoryx.git
```
2. Generate the necessary build files
```bash
cd iceoryx
cmake -Bbuild -Hiceoryx_meta -DTOML_CONFIG=ON
# when you have installed external dependencies like ncurses you have to add them
# to your prefix path
cmake -Bbuild -Hiceoryx_meta -DTOML_CONFIG=ON -DCMAKE_PREFIX_PATH=$(PWD)/build/dependencies/
```
3. Compile the source code
```
cmake --build build
```
#### With the following CMake switches you can add additional features
| switch | description |
|:---------|:-------------|
| `dds_gateway` | builds the iceoryx dds gateway using the cyclonedds dds stack, cyclonedds will be fetched and built as part of the build, see [cyclonedds](https://github.com/eclipse-cyclonedds/cyclonedds) for details |
| `examples` | builds all examples |
| `introspection` | the console introspection client which requires an installed ncurses library with terminfo support |
| `test` | enables module-, integration- and component-tests |
| `TOML_CONFIG` | activates config file support by using toml, if this is deactivated the central broker `RouDi` is not being build |
#### With the following CMake switches you can customize the iceoryx_posh build
| switch | description |
|:---------|:-------------|
| `IOX_MAX_PORT_NUMBER` | the maximum number of ports `RouDi` can distribute to the clients |
| `IOX_MAX_INTERFACE_NUMBER` | the maximum number for interface ports, which are used for e.g. gateways |
| `IOX_MAX_SUBSCRIBERS_PER_PUBLISHER` | the maximum number of subscriber a publisher can deliver chunks |
| `IOX_MAX_CHUNKS_ALLOCATE_PER_SENDER` | the maximum number of chunks a sender can hold at a given time |
| `IOX_MAX_HISTORY_CAPACITY_OF_CHUNK_DISTRIBUTOR` | the maximum number chunks available for the chunk history |
| `IOX_MAX_CHUNKS_HELD_PER_RECEIVER` | the maximum number of chunks a receiver can hold at a given time |
Have a look at `iceoryx_posh/cmake/iceoryx_posh_deployment.cmake` for the default values of this constants.
### Build with the build script (only Linux and QNX)
As an alternative we provide our build-test script which we use to integrate iceoryx into our infrastructure.
1. Clone the repository
```
git clone https://github.com/eclipse/iceoryx.git
```
2. Build everything
```
cd iceoryx
./tools/iceoryx_build_test.sh
```
With the following arguments you can add additional features:
| switch | description |
|:---------|:-------------|
| `clean` | Removes the build directory and performs a clean build. If you have installed ncurses locally into your build directory you have to reinstall it first. |
| `test` | Enables module-, integration- and component-tests. The Googletest-Framework will be automatically fetched from github and the test will be executed and the end of the script. |
### Build with colcon
Alternatively, iceoryx can be built with [colcon](https://colcon.readthedocs.io/en/released/user/installation.html) to provide a smooth integration for ROS2 developers.
```
mkdir -p iceoryx_ws/src
cd $_
git clone https://github.com/eclipse/iceoryx.git
cd ..
colcon build
```
This build method makes the most sense in combination with [rmw_iceoryx](https://github.com/ros2/rmw_iceoryx.git)
Congrats! You've build all the necessary things to continue playing around with the examples.
### Build and run in a Docker environment
If you want to avoid installing anything on your host machine but you have Docker installed, it is possible to use it to build and run iceoryx applications.
Please see the dedicated [README.md](tools/docker/README.md) for information on how to do this.
## Documentation
## Contribute

* [Concepts](doc/conceptual-guide.md)
* [Usage Guide](doc/usage-guide.md)
* [Ice0ryx Utils Hacker Guide](iceoryx_utils/README.md)
Please refer to the [CONTRIBUTING.md](./CONTRIBUTING.md) for a quick read-up about what to consider if you want to contribute.

## Examples
## Planned features

You can find our examples [here](./iceoryx_examples).
Get to know the upcoming features and the project scope in [PLANNED_FEATURES.md](./PLANNED_FEATURES.md).

## Innovations enabled by iceoryx

Expand All @@ -234,14 +103,6 @@ You can find our examples [here](./iceoryx_examples).

Is something missing or you've got ideas for other nifty examples? Jump right away to the next section!

## Contribute
Please refer to the [CONTRIBUTING.md](./CONTRIBUTING.md) for a quick read-up about what to consider if you want to contribute.
### Planned features
Get to know the upcoming features and the project scope in [PLANNED_FEATURES.md](./PLANNED_FEATURES.md).
## Maintainers

* Michael Pöhnl ([email protected])
Expand Down
4 changes: 2 additions & 2 deletions doc/conceptual-guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ A single segment may be mapped to multiple processes, however the addresses to w
![](fig/shared-memory-mapping.svg)

The POSIX API provides the [utilities](http://man7.org/linux/man-pages/man7/shm_overview.7.html) for working with
shared memory segements.
shared memory segments.

## Organization
An iceoryx system utilizes one "management" segment for administration purposes and any number of "user" segments for
Expand Down Expand Up @@ -145,7 +145,7 @@ Memory chunks are returned to the pool once all attached `ReceiverPort`s indicat
### A Note on Pointers
As already discussed, shared memory segments may be mapped to different memory areas in the virtual address space of a
process.
To deal with this, iceoryx utilises specialized pointer types: the `iox::RelativePointer` and
To deal with this, iceoryx utilizes specialized pointer types: the `iox::RelativePointer` and
the `iox::RelocatablePointer`.

Using these types, the difference in memory mapping is not a factor when it comes to locating a memory chunk.
Expand Down
44 changes: 44 additions & 0 deletions doc/goals-non-goals.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@

# Contents
- [Goals](#goals)
- [Non-Goals](#non-goals)
- [User personas](#user-personas)

# Goals
* High-performance inter-process-communication for various operating systems
* Service discovery functionality with dynamic connections
* Data agnostic, there are no restrictions on payload data
* Compatibility with AUTOSAR Adaptive and ROS2 communication patterns
* Providing the building blocks for being able to build gateways to network protocols
* Automotive-grade SW quality
* Modern C++

# Non-Goals
* Providing a data model and things like IDL or code generators
* Shrinking it down for being able to run on µControllers (e.g. with < 1MB of memory)
* Full compliance with the DDS standard

# User personas

**Andrew, the HAD developer**
Andrew is a software developer at a startup working on autonomous cars. Currently their project is using ROS, because
it's easy to get the car driving. After some months, he's realizing that sending gigabytes around, leads to high runtime
demands with ROS. A college mentions iceoryx during lunch, which might be interesting because it has a zero-copy
mechanism and offers a ROS RMW implementation. Soon after giving iceoryx a try, Andrew is thrilled about it. He cannot only feel
the runtime performance boost, but also still keep using his beloved ROS visualization tools!

**Martha, the indie game developer**
Martha always had troubles with those silly game engines. Some are slow but free, others are fast but too expensive.
It's a hard life if you're independent. When a friend who works in the automotive industry mentions he has just started
using iceoryx, which offers fast shared memory communication she listens up. Iceoryx is solely passing pointers around
and does avoid copies to the utmost? "I'll definitely try iceoryx in my new project and see if I can speed up the
performance with my low cost engine" she thinks while wandering home at night after the meetup with her friend.

**Robby, the lonely robot**
Robby is autonomous robot built during a research project at a university. He has a great set of features and can
astonish the crowds by creating a detailed map of the university building in under an hour. However, they made him use
that slow self-made IPC to communicate with his sensors because his parents wanted to get started fast. Though that
makes it hard for him to react in real-time to dangerous incidents like flying coffee cups. When strolling through
the interwebs on a lonely evening, he finds out about iceoryx: Free-to-use, high-performance data transfer with low
runtime overhead, real-time support! Brilliant! Maybe even Robby's biggest wish for a network binding will come true,
so he can stream his favorite [video](https://www.youtube.com/watch?v=g5NkgZXWl0w) even faster!
Loading

0 comments on commit 0e37f5e

Please sign in to comment.