Great that you've made it to this little Eclipse project! Let's get yout started by providing a quick background tour, introducing the project scope and guide you through the examples.
So first off: What is iceoryx?
Iceoryx is an inter-process communication (IPC) middleware for POSIX based operating systems. It features shared memory capabilities which allow a true zero-copy data transfer.
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.
It's all about the API!
Don't get too frighted 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. Examples for a "porcelain" API would be e.g. Adaptive Autosar Foundation (see AUTOSAR_EXP_ARAComAPI.pdf) or ROS.
Who can benefit of using iceoryx? What's in for those folks?
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 can not 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 soley 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 autonmous 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-performace data transfer with low runtime overhead, real-time support! Brilliant! Maybe even Robbys biggest wish for a network binding will come true, so he can stream his favorite video even faster!
Either download our pre-built daemon (called RouDi) and our runtime lib or build everything yourself.
wget iceoryx.deb
dpkg -i iceoryx.deb
You've sucessfully installed iceoryx! Continue with the section examples to see how to get started developing applications using iceoryx.
Great that you want start developing iceoryx! In order to get started please consider the next sections.
Altough we strive to be fully POSIX-compliant, we recommend to use Ubuntu 18.04 and at least GCC 7.4.0 for development.
You will need to install the following packages:
sudo apt-get install cmake libacl1-dev libncurses5-dev pkg-config
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 existong cmake projects.
For the first start we advise to use our build-test script for building everything.
git clone https://github.com/eclipse/iceoryx.git
./tools/iceoryx_build-test.sh
In default-mode the script is not building the provided test. For a clean build just add "clean" as first argument to the script.
To build iceoryx with tests, just add "test" as first argument to the script.
./tools/iceoryx_build-test.sh test
The Googletest-Framework will be automatically fetched from github and the test will be executed and the end of the script.
Congrats! You've build all the necessary things to continue playing around with the examples.
Great that your still here, time for code! The following examples give you a quick and easy introduction into the inner workings of iceoryx. We hope you enjoy our sightseeing tour!
| Name | Description | Technologies |
|---|---|---|
| icedelivery | Transfer data between POSIX applications | SoA, service description |
| ros-on-ice | See how iceoryx can be used inside the robot operating system (will come) | ROS, RMW |
Is something missing or you've got ideas for other nifty examples? Jump right away to the next section!
Please refer to the CONTRIBUTING.md for a quick read-up about what to consider if you want to contribute.
Get to know the upcoming features and the project scope in PLANNED_FEATURES.md.
- Michael Pöhnl (michael.poehnl@de.bosch.com)
- Christian Eltzschig (christian.eltzschig2@de.bosch.com)
- Dietrich Krönke (dietrich.kroenke2@de.bosch.com)
- Mathias Kraus (mathias.kraus2@de.bosch.com)
- Matthias Killat (matthias.killat2@de.bosch.com)
- Martin Hintz (martin.hintz@de.bosch.com)
- Simon Hoinkis (simon.hoinkis2@de.bosch.com)