Skip to content

Commit a20006b

Browse files
author
Andrei Terechko
committed
Added pcap-based traffic analysis tools for performance profiling
1 parent 4673880 commit a20006b

17 files changed

Lines changed: 1118 additions & 6 deletions

File tree

‎.gitignore‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
**/__pycache__/
2+
.cache
13
build
24
install
3-
log
5+
log

‎README.md‎

Lines changed: 44 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,30 @@
11
# ROS2-DDS-TSN integration demo
22
This repository demonstrates basic advantages of integrating the [Data Distribution Service (DDS)](https://en.wikipedia.org/wiki/Data_Distribution_Service) and [Time-Sensitive Networking (TSN) Ethernet](https://en.wikipedia.org/wiki/Time-Sensitive_Networking). The demo is based on the [Gazebo plugin `gazebo_ros_diff_drive`](http://gazebosim.org/tutorials?tut=ros2_installing&cat=connect_ros#TestingGazeboandROS2integration), modeling a differential drive vehicle in the [Robot Operating System (ROS) 2](https://www.ros.org/) environment, as well as on the GNU/Linux [VLAN](https://tsn.readthedocs.io/vlan.html) and [traffic control](https://tldp.org/HOWTO/Traffic-Control-HOWTO/intro.html) framework.
33

4+
The structure of this repository is as follows:
5+
- `dds_tsn_demo`: the ROS2 application implementation for the demo;
6+
- `scripts`: script to bring up VLAN interface with QoS configuration on Linux;
7+
- `tools`: a traffic analysis framework and tools to analyze `.pcapng` files for a specific protocol;
8+
- `images`: system block diagram of the demo.
9+
- `licenses`: license files
10+
411
The demo video below shows the challenging [moose test](https://en.wikipedia.org/wiki/Moose_test) in the Gazebo simulator, where the white ego vehicle performs a time-critical evasive maneuver. Three different scenarios are shown:
512
1. successful driving without intereference,
613
1. collisions due to network interference without TSN features,
714
1. TSN features enable a successful drive with network interference.
815

916
https://user-images.githubusercontent.com/88086083/140656406-81919e7b-8d37-4a7a-a331-be7cd32f6673.mp4
1017

11-
As illustrated below, this demo uses three machines connected to a TSN Ethernet switch, imitating a robot sharing Ethernet links for streams with different criticality levels. `Machine C` runs the Gazebo simulation. The control of the modeled vehicle runs on an embedded controller `machine A` and publishes the safety-critical topic `/command` based on the data from the `/odometry` topic. An interference `machine B` floods the egress of `port 3` and interfere with the control traffic in the `/command` topic. This interference is likely to trigger a collision in the simulation. Interference may originate from a bug in `machine B`, see the bug icon, or from a network design sharing an Ethernet link between traffic streams with different criticality levels, see the fire icon. Fortunately, if we link the safety-critical DDS topic `/command` to a TSN stream with a high priority using [IEEE 802.1Q Priority-Based Scheduling (`PBS`)](https://en.wikipedia.org/wiki/Time-Sensitive_Networking#Scheduling_and_traffic_shaping), then the vehicle completes the moose test successfully. Furthermore, we can de-burst the interference traffic using the TSN's protocol [IEEE 802.1Qav Credit-Based Shaper (`CBS`)](https://en.wikipedia.org/wiki/Time-Sensitive_Networking#AVB_credit-based_scheduler) to ensure its egress bandwidth is limited.
18+
As illustrated below, this demo uses three machines connected to a TSN Ethernet switch, imitating a robot sharing Ethernet links for streams with different criticality levels.
19+
The components in grey are used for performance measurement, which we descrbe in deatail in the measurement section below.
20+
`Machine C` runs the Gazebo simulation. The control of the modeled vehicle runs on an embedded controller `machine A` and publishes the safety-critical topic `/command` based on the data from the `/odometry` topic.
21+
An interference `machine B` floods the egress of `port 3` and interfere with the control traffic in the `/command` topic.
22+
This interference is likely to trigger a collision in the simulation.
23+
Interference may originate from a bug in `machine B`, see the bug icon, or from a network design sharing an Ethernet link between traffic streams with different criticality levels, see the fire icon.
24+
Fortunately, if we link the safety-critical DDS topic `/command` to a TSN stream with a high priority using
25+
[IEEE 802.1Q Priority-Based Scheduling (`PBS`)](https://en.wikipedia.org/wiki/Time-Sensitive_Networking#Scheduling_and_traffic_shaping), then the vehicle completes the moose test successfully.
26+
Furthermore, we can de-burst the interference traffic using the TSN's protocol
27+
[IEEE 802.1Qav Credit-Based Shaper (`CBS`)](https://en.wikipedia.org/wiki/Time-Sensitive_Networking#AVB_credit-based_scheduler) to ensure its egress bandwidth is limited.
1228

1329
<p align="center"><img src="images/dds_tsn_mini_demo.png" alt="simplified demo architecture" width="700" class="center"/></p>
1430

@@ -138,6 +154,31 @@ iperf3 -c MACHINE_C_VLAN_INTERFACE -u -S 0x14 -t20
138154
1. Now start the interference as described in step 4.
139155
1. The vehicle should be able to successfully finish the moose test in the Gazebo simulation thanks to prioritized vehicle control traffic.
140156
157+
## How to measure TSN performance
158+
159+
To accurately measure the TSN performance of the network, consider [installing gPTP time synchronization on machines A and C](https://tsn.readthedocs.io/timesync.html). Furthermore, check if your network interfaces perform hardware time stamping with `sudo ethtool -T <network_interface>`.
160+
The measurement setup is shown in the block diagram above in grey, where *HW TS* stands for hardware timestamping.
161+
162+
Commands to be run on each machine is introduced below; for more information on `step 1` and `step 2`, see [traffic_analysis README](tools/traffic_analysis/README.md):
163+
164+
1. Run tshark with timestaping on machine A and C during the dds-tsn demo. After the demo is over move the `machine_a.pcapng` file to machine C.
165+
```bash
166+
# on machine A
167+
tshark -i <interface> --time-stamp-type adapter_unsynced -w machine_a.pcapng
168+
# on machine C
169+
tshark -i <interface> --time-stamp-type adapter_unsynced -w machine_c.pcapng
170+
```
171+
1. On machine C, run `traffic_analysis.py` script on both `.pcapng` files, save the results to a `.csv` file. Use the UDP source port (here 46278) to filter for UDP datagram only related to the `/cmd_vel` topic of Gazebo:
172+
```bash
173+
$ python3 tools/traffic_analysis/traffic_analysis.py -p machine_a.pcapng -c rtps.data machine_a.csv -f 'udp.srcport == 46278'
174+
$ python3 tools/traffic_analysis/traffic_analysis.py -p machine_c.pcapng -c rtps.data machine_c.csv -f 'udp.srcport == 46278'
175+
```
176+
1. Merge both .csv files with [rtps_csv_merge.py](tools/rtps_csv_merge/rtps_csv_merge.py):
177+
```bash
178+
$ python3 tools/rtps_csv_merge/rtps_csv_merge.py machine_a.csv machine_c.csv merged.csv
179+
```
180+
The generated `merged.csv` will then contain the HW timestamp from both the sending and the receiving side for a specific RTPS sequence number. This can be used for further processing.
181+
141182
## How to check the code style using Clang-Tidy
142183
The following steps have been tested on a Ubuntu 20.04 machine with ROS Foxy.
143184
1. Install `ament_clang_tidy` for ROS Foxy:
@@ -171,17 +212,16 @@ The following steps have been tested on a Ubuntu 20.04 machine with ROS Foxy.
171212
172213
## Useful links
173214
1. [Free S32G webinar on DDS-TSN integration in the Autoware.auto Autonomous Valet Parking application](https://www.nxp.com/design/training/dds-and-tsn-where-software-and-hardware-meet-for-dependable-communication-using-rti-connext-drive-and-nxp-s32g-processor:TIP-DDS-AND-TSN-WHERE-SOFTWARE-AND-HARDWARE-MEET)
215+
1. [Driving Interoperability and Performance in Automotive Systems with DDS and TSN](https://www.nxp.com/webapp/Download?colCode=DDSTSNWP) - DDS-TSN white paper co-authored by NXP and RTI
174216
1. https://tsn.readthedocs.io/index.html - hands-on tutorial on TSN and VLAN support in GNU/Linux
175217
1. https://arxiv.org/pdf/1808.10821.pdf - excellent description of the GNU/Linux traffic control and its application in robotics
176218
1. https://wiki.archlinux.org/title/VLAN - VLAN support in GNU/Linux
177219
1. https://tldp.org/HOWTO/Adv-Routing-HOWTO/index.html - Linux Advanced Routing & Traffic Control HOWTO
178220
1. https://en.wikipedia.org/wiki/Type_of_service - Type of Service field in the IP header
179221
180222
## TODO:
181-
1. Add a short demo video with and without DDS-TSN and embed it into the README
182223
1. Change the name of the topics in the C++ and .world to match the illustration in README
183224
1. Describe the CBS configuration of the TSN switch
184-
1. Describe the CB configuration of the TSN switch
185225
186226
## License
187-
This software is distributed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).
227+
This software is distributed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). License files of other software is located in the `licenses` directory.

SCR-1.1.txt renamed to SCR-1.2.txt

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
NXP Software Content Register
22

3-
Version: 1.0
3+
Version: 1.2
44
Outgoing License: Apache-2.0
55
License File: LICENSE
66
Type of content: Source code
77
Description and comments: Example project of DDS-TSN integration
88
Release Location: GitHub
99
Origin: Code written by NXP
1010
ROS 2 (Apache-2.0) - https://github.com/ros2
11+
Pyshark (MIT) - https://pypi.org/project/pyshark
12+
tabulate (MIT) - https://pypi.org/project/tabulate

‎images/dds_tsn_mini_demo.png‎

-40.5 KB
Loading

‎licenses/pyshark/LICENSE.txt‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) 2014 Dor Green
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎licenses/pyshark/PSF-3.10.2.txt‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
PSF LICENSE AGREEMENT FOR PYTHON 3.10.2
2+
3+
1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and
4+
the Individual or Organization ("Licensee") accessing and otherwise using Python
5+
3.10.2 software in source or binary form and its associated documentation.
6+
7+
2. Subject to the terms and conditions of this License Agreement, PSF hereby
8+
grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
9+
analyze, test, perform and/or display publicly, prepare derivative works,
10+
distribute, and otherwise use Python 3.10.2 alone or in any derivative
11+
version, provided, however, that PSF's License Agreement and PSF's notice of
12+
copyright, i.e., "Copyright © 2001-2022 Python Software Foundation; All Rights
13+
Reserved" are retained in Python 3.10.2 alone or in any derivative version
14+
prepared by Licensee.
15+
16+
3. In the event Licensee prepares a derivative work that is based on or
17+
incorporates Python 3.10.2 or any part thereof, and wants to make the
18+
derivative work available to others as provided herein, then Licensee hereby
19+
agrees to include in any such work a brief summary of the changes made to Python
20+
3.10.2.
21+
22+
4. PSF is making Python 3.10.2 available to Licensee on an "AS IS" basis.
23+
PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF
24+
EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR
25+
WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE
26+
USE OF PYTHON 3.10.2 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.
27+
28+
5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 3.10.2
29+
FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
30+
MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 3.10.2, OR ANY DERIVATIVE
31+
THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
32+
33+
6. This License Agreement will automatically terminate upon a material breach of
34+
its terms and conditions.
35+
36+
7. Nothing in this License Agreement shall be deemed to create any relationship
37+
of agency, partnership, or joint venture between PSF and Licensee. This License
38+
Agreement does not grant permission to use PSF trademarks or trade name in a
39+
trademark sense to endorse or promote products or services of Licensee, or any
40+
third party.
41+
42+
8. By copying, installing or otherwise using Python 3.10.2, Licensee agrees
43+
to be bound by the terms and conditions of this License Agreement.

‎licenses/tabulate/LICENSE.txt‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) 2014 Dor Green
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎licenses/tabulate/PSF-3.10.2.txt‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
PSF LICENSE AGREEMENT FOR PYTHON 3.10.2
2+
3+
1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and
4+
the Individual or Organization ("Licensee") accessing and otherwise using Python
5+
3.10.2 software in source or binary form and its associated documentation.
6+
7+
2. Subject to the terms and conditions of this License Agreement, PSF hereby
8+
grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
9+
analyze, test, perform and/or display publicly, prepare derivative works,
10+
distribute, and otherwise use Python 3.10.2 alone or in any derivative
11+
version, provided, however, that PSF's License Agreement and PSF's notice of
12+
copyright, i.e., "Copyright © 2001-2022 Python Software Foundation; All Rights
13+
Reserved" are retained in Python 3.10.2 alone or in any derivative version
14+
prepared by Licensee.
15+
16+
3. In the event Licensee prepares a derivative work that is based on or
17+
incorporates Python 3.10.2 or any part thereof, and wants to make the
18+
derivative work available to others as provided herein, then Licensee hereby
19+
agrees to include in any such work a brief summary of the changes made to Python
20+
3.10.2.
21+
22+
4. PSF is making Python 3.10.2 available to Licensee on an "AS IS" basis.
23+
PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF
24+
EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR
25+
WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE
26+
USE OF PYTHON 3.10.2 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.
27+
28+
5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 3.10.2
29+
FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
30+
MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 3.10.2, OR ANY DERIVATIVE
31+
THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
32+
33+
6. This License Agreement will automatically terminate upon a material breach of
34+
its terms and conditions.
35+
36+
7. Nothing in this License Agreement shall be deemed to create any relationship
37+
of agency, partnership, or joint venture between PSF and Licensee. This License
38+
Agreement does not grant permission to use PSF trademarks or trade name in a
39+
trademark sense to endorse or promote products or services of Licensee, or any
40+
third party.
41+
42+
8. By copying, installing or otherwise using Python 3.10.2, Licensee agrees
43+
to be bound by the terms and conditions of this License Agreement.

‎tools/rtps_csv_merge/README.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# RTPS CSV merging tool
2+
3+
`rtps_csv_merge.py` computes transmission latency of RTPS packets from a sending machine to a receiving machine. The two CSV files with RTPS packet information from the sending and receiving machines have to be first computed with `traffic_analysis.py` from the `tshark` sniffs. Then, `rtps_csv_merge.py` reads the CSV files and computes timestamp differences of RTPS packets with the same sequence ID from the two input CSV files.
4+
5+
The source packets come from:
6+
* `tshark` sniff on the sending side (extracted with `traffic_analysis.py` CSV export)
7+
* `tshark` sniff on tne receiving side (extracted with `traffic_analysis.py` CSV export)
8+
9+
The time difference calculation: `recv-send-difference = recv timestam - send timestamp`
10+
11+
It will merge two timestamps based on the sequence ID of the sample packet and skip IDs which aren't available in both source packets.
12+
13+
Usage:
14+
```
15+
$ python3 rtps_csv_merge.py -h
16+
usage: rtps_csv_merge.py [-h] input_send input_recv output_file
17+
18+
merges 3 CSVs with different timestamp sources
19+
20+
positional arguments:
21+
input_send input CSV file of sending side
22+
input_recv input CSV file of receiving side
23+
output_file output CSV file
24+
25+
optional arguments:
26+
-h, --help show this help message and exit
27+
```
28+
29+
The resulting CSV will have the following content:
30+
```
31+
<RTPS/DDS-sequence-ID>;<send-timestamp>;<recv-timestamp>;<recv-send-difference>
32+
```
33+
34+
## Example
35+
To sniff the network interface, generate the `.pcapng` file and the `.csv` file in one go, follow instructions [here](../traffic_analysis/README.md).
36+
37+
Assume you already have two `.pcapng` files available in the `traffic_analysis` directory captured from the ROS2 publisher and the subscriber respectively.
38+
1. First generate the `.csv` file for each `.pcapng` file
39+
```bash
40+
cd dds-tsn/tools/traffic_analysis
41+
python3 traffic_analysis.py -p publisher.pcapng -c rtps.data ../rtps_csv_merge/publisher.csv -f 'udp.srcport == 46278'
42+
python3 traffic_analysis.py -p subscriber.pcapng -c rtps.data ../rtps_csv_merge/subscriber.csv -f 'udp.srcport == 46278'
43+
```
44+
1. Merge the timestamps and generate the output CSV file:
45+
```bash
46+
cd dds-tsn/tools/rtps_csv_merge
47+
python3 rtps_csv_merge.py publisher.csv subscriber.csv merged.csv
48+
```

0 commit comments

Comments
 (0)