Do you want to model your DDS applications in Python? This article explains how to start using OpenSplice DDS with Python.
OpenSplice DDS comes with a Python DCPS API that provides Python classes allowing you model your DDS application using Python. The Python DCPS API is a native Python binding that supports full DDS functionality. The language binding consists of a Python interface and a C wrapper implementation of the C99 API (C API for DDS).
Using OpenSplice DDS with Python
Getting started with the Python language binding
In order to use the Python language binding you will need to install the following.
Linux
- Python 3.4 or later
- GCC 4.8 or later
- pip3 – you can install this using the command package “python3-pip” with most Linux package managers.
Windows
- Python 3.5 or 3.6
- pip – this is usually included in Python for windows
- Visual Studio 14 (2015) C compiler or later
Python modules
- Cython version 0.27 or later
- install using the command “pip3 install Cython”
On Windows if pip3 is not referenced on the PATH then you will find pip3 in the Scripts directory of your Python installation. This is usually under C:\Users\<username>\AppData\Local\Programs
Note: python or python3
When using older systems or older versions of Python the command “python” will run Python 2, and “python3” will run Python 3. However on more recent systems that only have Python 3 installed the command “python” will work. The same relates to pip and pip3.
Installing the Python DCPS API
Before using the OpenSplice DDS Python language binding you need to install OpenSplice.
Once you have done this you will find the Python DCPS API files in the $OSPL_HOME/tools/python where $OSPL_HOME is the path to the OpenSplice DDS installation directory.
There are two ways to installed the Python DCPS API
- From a Python wheel
- From the source
NOTE: Some versions of OpenSplice do not have the python wheel file included so you will need to install from source or create an installation wheel.
Installing from a Python wheel
If your version of OpenSplice includes the python wheel you should see a file or files ending in .whl in the $OSPL_HOME/tools/python directory.
If there are multiple wheels then for instance:
- Python 3.5 – use the .whl file including cp35
- Python 3.6 – use the .whl file including cp36
- etc.
You can install the package using pip.
For example, executing this command will install the wheel package for Python 3.4 on 64-bit Linux:
$pip3 install dds-6.10.4-cp34-cp34m-linux_x86_64.whl
Or for Python 3.5 on 64-bit Windows:
pip install dds-6.10.4-cp35-cp35m-win_amd64.whl
Installing from source (only if this is a development/HDE installation)
Ensure that the environment is set up for using OpenSplice by sourcing the release.com or running the release.bat file in the OpenSplice installation directory (depending on Operating system).
From the $OSPL_HOME/tools/python/src directory run the command:
$python3 setup.py install
RTS installation without Python API (Build Python wheel on development machine)
Some of the RTS deployment installations do not include the Python API at all. To install on the RTS environment you will need a Python wheel. This either comes with the installation or you will need to build the wheel on the development machine first nd install with the same instructions above.
# ensure build prerequisites are installled
sudo apt install build-essential python3 python3-pip
# upgrade/install python packages used in build
pip3 install –upgrade wheel pip setuptools Cython
# source ‘release.com’
source . ~/HDE/…/release.com
# change to the dds packages source directory and build the wheel
cd $OSPL_HOME/tools/python/src
python3 setup.py bdist_wheel
# resulting wheel will be on $OSPL_HOME/tools/python/src/dist/dds-*.whl
Documentation
For more details on using the OpenSplice Python language binding the Python DCPS API Guide is a good place to start. You can find this and all the other OpenSplice documentation on the OpenSplice documentation page.
The documentation is also included in the distribution. You will find it in the $OSPL_HOME/docs/pdf directory
Python Examples
The Python language binding comes with a number of examples to help you get started. You can find these in the $OSPL_HOME/tools/python/examples directory.
Inside the examples directory you will find a number of different files which the examples use to run. These are:
- py – These are runnable Python scripts that allow you to run the example.
- xml – An XML file that contains one or more Quality of Service (QoS) profiles for DDS entities
- idl – An interface description language file used to define topic(s).
What do the different Python examples do?
There are four different Python examples provided with the OpenSplice distribution. These are:
- qos_example.py – An example that demonstrates how to specify QoS settings using Python DCPS APIs. Also shows how to use a waitset.
- example1.py – Dynamic generation of Python Topic classes using IDL file and name. Uses a topic with a sequence.
- example2.py – Dynamic generation of Python Topic classes using Enumeration and nested modules.
- example3.py – Static generation of Python Topic classes using idlpp. Example is identical to example1.py for process.
- example4.py – Demonstrates finding DDS topics over-the-wire. Find topics registered by other processes, and read and write samples to those topics.
How do I run the Python examples?
To run the examples first you need to set up the OpenSplice environment variables. In a command prompt go to the $OSPL_HOME directory.
- On Windows: release.bat
- On Linux: source release.com
Go to the $OSPL_HOME/tools/python/examples directory.
If you are using single process memory mode you can just run the example using the command:
For examples 1,2 and 4
python example1.py
For example 3
idlpp -l python example3.idl
python example3.py
If you are using shared memory mode you will need to start the OpenSplice daemon before running the example. You can do this using the command:
ospl start
or starting it from the launcher.