Skip to content

Commit 8039663

Browse files
IkerLuengoIkerLuengo
committed
Update readme
Signed-off-by: Iker Luengo <ikerluengo@eprosima.com>
1 parent bc619d5 commit 8039663

1 file changed

Lines changed: 179 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,180 @@
11
# Python binding for Fast DDS Statistics Backend
2+
3+
<a href="http://www.eprosima.com"><img src="https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcSd0PDlVz1U_7MgdTe0FRIWD0Jc9_YH-gGi0ZpLkr-qgCI6ZEoJZ5GBqQ" align="left" hspace="8" vspace="2" width="100" height="100" ></a>
4+
5+
[![License](https://img.shields.io/github/license/eProsima/Fast-DDS-python.svg)](https://opensource.org/licenses/Apache-2.0)
6+
[![Releases](https://img.shields.io/github/v/release/eProsima/Fast-DDS-python?sort=semver)](https://github.com/eProsima/Fast-DDS-python/releases)
7+
[![Issues](https://img.shields.io/github/issues/eProsima/Fast-DDS-python.svg)](https://github.com/eProsima/Fast-DDS-python/issues)
8+
[![Forks](https://img.shields.io/github/forks/eProsima/Fast-DDS-python.svg)](https://github.com/eProsima/Fast-DDS-python/network/members)
9+
[![Stars](https://img.shields.io/github/stars/eProsima/Fast-DDS-python.svg)](https://github.com/eProsima/Fast-DDS-python/stargazers)
10+
11+
12+
*eProsima Fast DDS Python* is a Python binding for the [*eProsima Fast DDS*](https://github.com/eProsima/Fast-DDS) C++ library. This is a work in progress, but ultimately the goal is having the complete *Fast DDS* API available in Python.
13+
14+
## Installation guide
15+
16+
This tutorial shows how to build *Fast DDS Python* using [colcon](https://colcon.readthedocs.io), a command line tool to build sets of software packages.
17+
To do so, `colcon` and `vcstool` need to be installed:
18+
19+
```bash
20+
pip install -U colcon-common-extensions vcstool
21+
```
22+
23+
### Dependencies
24+
25+
*Fast DDS Python* depends on [Fast DDS](https://github.com/eProsima/Fast-DDS) and [Fast CDR](https://github.com/eProsima/Fast-CDR).
26+
For simplicity, this tutorial will build these dependencies alongside the binding itself.
27+
More advanced users can build or link to this packages separately.
28+
Install *Fast DDS* dependencies running:
29+
30+
```bash
31+
sudo apt update
32+
sudo apt install -y \
33+
libasio-dev \
34+
libtinyxml2-dev
35+
```
36+
37+
### Build and install
38+
39+
```bash
40+
# Change directory to the location where the colcon workspace will be created
41+
cd <path_to_ws>
42+
# Create workspace directory
43+
mkdir -p fastdds_statistics_backend_ws/src
44+
cd fastdds_statistics_backend_ws
45+
# Get workspace setup file
46+
wget https://raw.githubusercontent.com/eProsima/Fast-DDS-python/main/fastdds_python.repos
47+
# Download repositories
48+
vcs import src < fastdds_python.repos
49+
# Build the workspace
50+
colcon build
51+
```
52+
53+
## Limitations
54+
55+
This project is on the very early stages of development, and there are many features not available yet. These include, but are not restricted to:
56+
57+
* QoS modification is not supported on python. If you need to use non-default QoS, please use XML configuration files.
58+
* Status listeners are not available. Even though python will not complain if you add a listener to an entity, the listener will not be triggered.
59+
60+
61+
## Python example
62+
63+
The *Fast DDS* functionality is contained in the `fastdds_wrapper` module, so you will need to include that module in your script. You will also need to create the python binding for your data type and include its module. This example will guide you through these steps in a simple example.
64+
65+
### Generate a data type
66+
67+
Create an IDL file with the description of your data type and save it as `HelloWorld.idl`:
68+
69+
```
70+
struct HelloWorld
71+
{
72+
unsigned long index;
73+
string message;
74+
};
75+
```
76+
77+
Use [*Fast DDS gen*](https://github.com/eProsima/Fast-DDS-Gen) to generate the necessary files from this IDL. If you installed *Fast DDS Python* using the `fastdds_python.repos` file, you will find *Fast DDS Gen* in the `src` file. Do not forget to use the `-python` option to create the files needed for the python binding:
78+
79+
```bash
80+
fastddsgen -python HelloWorld.idl
81+
```
82+
83+
Now use the generated CMakeFile to compile the data type and create the python binding:
84+
85+
```bash
86+
mkdir HelloWorld_build
87+
cd HelloWorld_build
88+
cmake ..
89+
cmake --build .
90+
```
91+
92+
This will create a `HelloWorld.py` file with a `HelloWorld` module that you will need to add to your script.
93+
94+
### Creating the DataWriter
95+
96+
Import the `fastdds_wrapper` and the `HelloWorld` modules and follow the usual steps to create a DataWriter:
97+
98+
```python
99+
import fastdds_wrapper
100+
import HelloWorld
101+
102+
domain = 5;
103+
factory = fastdds_wrapper.DomainParticipantFactory.get_instance()
104+
participant_qos = fastdds_wrapper.DomainParticipantQos()
105+
factory.get_default_participant_qos(participant_qos)
106+
participant = factory.create_participant(domain, participant_qos)
107+
108+
topic_data_type = HelloWorld.HelloWorldPubSubType()
109+
topic_data_type.setName("HelloWorldDataType")
110+
type_support = fastdds_wrapper.TypeSupport(topic_data_type)
111+
participant.register_type(type_support)
112+
113+
topic_qos = fastdds_wrapper.TopicQos()
114+
participant.get_default_topic_qos(topic_qos)
115+
topic = self.participant.create_topic("myTopic", topic_data_type.getName(), topic_qos)
116+
117+
publisher_qos = fastdds_wrapper.PublisherQos()
118+
participant.get_default_publisher_qos(publisher_qos)
119+
publisher = participant.create_publisher(publisher_qos)
120+
121+
writer_qos = fastdds_wrapper.DataWriterQos()
122+
publisher.get_default_datawriter_qos(writer_qos)
123+
writer = self.publisher.create_datawriter(topic, writer_qos)
124+
```
125+
126+
### Publishing a sample
127+
128+
You can publish a sample the same way you would do it in C++:
129+
130+
```python
131+
data = HelloWorld.HelloWorld()
132+
data.message("Hello World")
133+
data.index(0)
134+
writer.write(data)
135+
```
136+
137+
### Creating the DataReader
138+
139+
Import the `fastdds_wrapper` and the `HelloWorld` modules and follow the usual steps to create a DataReader:
140+
141+
```python
142+
import fastdds_wrapper
143+
import HelloWorld
144+
145+
domain = 5;
146+
factory = fastdds_wrapper.DomainParticipantFactory.get_instance()
147+
participant_qos = fastdds_wrapper.DomainParticipantQos()
148+
factory.get_default_participant_qos(participant_qos)
149+
participant = factory.create_participant(domain, participant_qos)
150+
151+
topic_data_type = HelloWorld.HelloWorldPubSubType()
152+
topic_data_type.setName("HelloWorldDataType")
153+
type_support = fastdds_wrapper.TypeSupport(topic_data_type)
154+
participant.register_type(type_support)
155+
156+
topic_qos = fastdds_wrapper.TopicQos()
157+
participant.get_default_topic_qos(topic_qos)
158+
topic = participant.create_topic("myTopic", topic_data_type.getName(), topic_qos)
159+
160+
subscriber_qos = fastdds_wrapper.SubscriberQos()
161+
participant.get_default_subscriber_qos(subscriber_qos)
162+
subscriber = participant.create_subscriber(subscriber_qos)
163+
164+
reader_qos = fastdds_wrapper.DataReaderQos()
165+
subscriber.get_default_datareader_qos(reader_qos)
166+
reader = subscriber.create_datareader(topic, reader_qos)
167+
```
168+
169+
### Reading a sample
170+
171+
You can read a sample the same way you would do it in C++:
172+
173+
```python
174+
info = fastdds_wrapper.SampleInfo()
175+
data = HelloWorld.HelloWorld()
176+
reader.take_next_sample(data, info)
177+
178+
print("Received {message} : {index}".format(message=data.message(), index=data.index()))
179+
```
180+

0 commit comments

Comments
 (0)