README.md 6.86 KB
Newer Older
1
# **Manual TeSSLaBridge Version 1.0.0**
Marian Begemann's avatar
Marian Begemann committed
2

Hannes Kallwies's avatar
Hannes Kallwies committed
3
TeSSLaBridge is a ROS 2 dashing package that connects TeSSLa and ROS2. 
4
It is developed by the **Institute for Software Engineering and Programming Languages** of the **University of Lübeck, Germany**. 
Marian Begemann's avatar
Marian Begemann committed
5

Marian Begemann's avatar
Marian Begemann committed
6
Project contributors: Marian Johannes Begemann, Malte Schmitz, Hannes Kallwies, Daniel Thoma, Martin Leucker
Marian Begemann's avatar
Marian Begemann committed
7
8


9
10
<a name="link-overview"></a>
##### Overview
Hannes Kallwies's avatar
Hannes Kallwies committed
11
- [Installation](#link-install-guide)
12
  - [Install ROS2 Dashing](#link-install-ros)
Hannes Kallwies's avatar
Hannes Kallwies committed
13
  - [Install TeSSLa dependencies](#link-install-tessla)
14
  - [Install TeSSLaBridge](#link-install-bridge)
Hannes Kallwies's avatar
Hannes Kallwies committed
15
- [Usage](#usage)
Hannes Kallwies's avatar
Hannes Kallwies committed
16
17
  - [Important files](#important-files)
  - [How to use the TeSSLaBridge](#how-to-use)
Marian Begemann's avatar
Marian Begemann committed
18

19
<a name="link-install-guide"></a>
Hannes Kallwies's avatar
Hannes Kallwies committed
20
21
22
23
24
25
26
## **Installation**

**Required Software:**

  * Ubuntu 18.04 LTS (reference system)
  * ROS 2 Dashing Diademata
  * TeSSLa
Hannes Kallwies's avatar
Hannes Kallwies committed
27
  * Python 3.6
Hannes Kallwies's avatar
Hannes Kallwies committed
28
29
  * Java
  * Rust/Cargo
Marian Begemann's avatar
Marian Begemann committed
30

31
32
33
34
<a name="link-install-ros"></a>
### Install ROS2 Dashing
Install ROS2 desktop of the Dashing version:
(https://docs.ros.org/en/dashing/Installation/Ubuntu-Install-Debians.html)
Marian Begemann's avatar
Marian Begemann committed
35

36
37
38
39
40
41
42
43
Set locale
```
locale  # check for UTF-8

sudo apt update && sudo apt install locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8
Marian Begemann's avatar
Marian Begemann committed
44

45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
locale  # verify settings
```
Setup Sources
```
sudo apt update && sudo apt install curl gnupg2 lsb-release
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key  -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
```
Install ROS 2 packages
```
sudo apt update
sudo apt install ros-dashing-desktop
echo 'source /opt/ros/dashing/setup.bash' >> ~/.bashrc
```
Install argcomplete (optional)
Marian Begemann's avatar
Marian Begemann committed
60
```
61
62
63
64
65
66
67
sudo apt install -y python3-pip
pip3 install -U argcomplete
```
Test if installation were successful but running this commands in a new terminal each:
```
ros2 run demo_nodes_cpp talker
ros2 run demo_nodes_py listener
Marian Begemann's avatar
Marian Begemann committed
68
69
```

70
71
72
73
Install colcon
```
sudo apt install python3-colcon-common-extensions
```
Marian Begemann's avatar
Marian Begemann committed
74

75
<a name="link-install-tessla"></a>
Hannes Kallwies's avatar
Hannes Kallwies committed
76
### Install TeSSLa dependencies
77
78
```
sudo apt install default-jdk
Hannes Kallwies's avatar
Hannes Kallwies committed
79
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
80
```
Marian Begemann's avatar
Marian Begemann committed
81

82
83
<a name="link-install-bridge"></a>
### Install TeSSLaBridge
Marian Begemann's avatar
Marian Begemann committed
84

85
86
place the project folder in your home directory (also required for using the scripts)
```
Hannes Kallwies's avatar
Hannes Kallwies committed
87
git clone https://git.tessla.io/ros/tesslarosbridge.git
Hannes Kallwies's avatar
Hannes Kallwies committed
88
cd tesslarosbridge
89
90
91
colcon build --symlink-install
```

Hannes Kallwies's avatar
Hannes Kallwies committed
92
93
94
95
96
### (Optional:) Start the counter example to verify that everything works

Note: This performs only a dry run of the pre-compiled TeSSLa Bridge for the example.
The steps for building your own TeSSLa/ROS monitor follow below.

97
```
Hannes Kallwies's avatar
Hannes Kallwies committed
98
bash scripts/start_example_counter_with_reset.sh
99
100
```

Hannes Kallwies's avatar
Hannes Kallwies committed
101
102
103
104
105
<a name="usage"></a>
## Usage

This section describes the general usage of the TeSSLa/ROS bridge.

Hannes Kallwies's avatar
Hannes Kallwies committed
106
The project is currently configured to run a simple example, consisting of a counter-with-reset node ([src/tesslabridge/tesslabridge/examples/counter_with_reset.py](https://git.tessla.io/ros/tesslarosbridge/-/blob/main/src/tesslabridge/tesslabridge/examples/counter_with_reset.py)) and a corresponding monitor ([config_tessla/counter_with_reset.tessla](https://git.tessla.io/ros/tesslarosbridge/-/blob/main/config_tessla/counter_with_reset.tessla)).
Hannes Kallwies's avatar
Hannes Kallwies committed
107
108
109

For a detailed description of the example see [this article on tessla.io](https://www.tessla.io/blog/rosBridge/).

110
<a name="important-files"></a>
Hannes Kallwies's avatar
Hannes Kallwies committed
111
112
113
114
115
116
117
118
119
### Important files

- `src/tesslabridge/config` - The yaml files which provide parameters
- `scripts/` - Scripts to build the project and start the examples with the correct configuration
- `config_tessla/` the *.tessla files 

#### Annotations 

The TeSSLa specification for the monitor is placed in the folder `config_tessla`.
Marian Begemann's avatar
Marian Begemann committed
120

Hannes Kallwies's avatar
Hannes Kallwies committed
121
In the file `TeSSLaROSBridge.tessla` two annotations are defined which can be used in the specification for connecting the TeSSLa monitor with ROS topics:
Marian Begemann's avatar
Marian Begemann committed
122

Hannes Kallwies's avatar
Hannes Kallwies committed
123
@RosSubscription is used for input streams to subscribe ROS topics:
Marian Begemann's avatar
Marian Begemann committed
124

125
126
127
```
def @RosSubscription(name: String, ros_type: String, qos_profile: String)
```
Hannes Kallwies's avatar
Hannes Kallwies committed
128
129
- `name`: The full name of the ROS topic to subscribe to
- `ros_type`: The type of the ROS topic
130
131
  - int64
  - bool
Marian Begemann's avatar
Marian Begemann committed
132
133
  - float64
  - String
Hannes Kallwies's avatar
Hannes Kallwies committed
134
- `qos-profile`: The Quality of Service Profile of ROS
Marian Begemann's avatar
Marian Begemann committed
135
136
137
  - int e.g. 10 - for other topics
  - "qos_profile_sensor_data" - for sensor topics

Hannes Kallwies's avatar
Hannes Kallwies committed
138
139
140

@RosPublisher is used for output streams to publish to ROS topics:

Marian Begemann's avatar
Marian Begemann committed
141
```
Hannes Kallwies's avatar
Hannes Kallwies committed
142
def @RosPublisher(name: String, ros_type: String, qos_profile: String)
Marian Begemann's avatar
Marian Begemann committed
143
```
Hannes Kallwies's avatar
Hannes Kallwies committed
144
145
146
147
148
149
150
151
152
- `name`: The full name of the ROS topic to subscribe to
- `ros_type`: The type of the ROS topic
  - int64
  - bool
  - float64
  - String
- `qos-profile`: The Quality of Service Profile of ROS
  - int e.g. 10 - for other topics
  - "qos_profile_sensor_data" - for sensor topics
153

Hannes Kallwies's avatar
Hannes Kallwies committed
154
155

Example usage can be found in the sample specification `counter_with_reset.tessla`:
156
```
Hannes Kallwies's avatar
Hannes Kallwies committed
157
include "TeSSLaROSBridge.tessla"
Marian Begemann's avatar
Marian Begemann committed
158

159
160
@RosSubscription("/counter", "int64", "10")
in x: Events[Int]
Marian Begemann's avatar
Marian Begemann committed
161

Marian Begemann's avatar
Marian Begemann committed
162
def reset = x > 10
Marian Begemann's avatar
Marian Begemann committed
163

164
165
166
@RosPublisher("/reset_counter", "bool", "10")
out reset
```
Marian Begemann's avatar
Marian Begemann committed
167

168
<a name="how-to-use"></a>
Hannes Kallwies's avatar
Hannes Kallwies committed
169
### How to use the TeSSLaBridge
Marian Begemann's avatar
Marian Begemann committed
170

Hannes Kallwies's avatar
Hannes Kallwies committed
171
#### Configure build
Marian Begemann's avatar
Marian Begemann committed
172

Hannes Kallwies's avatar
Hannes Kallwies committed
173
174
* Write your TeSSLa specification and use annotations as described above.
  * See `config_tessla/counter_with_reset.tessla` as example.
Marian Begemann's avatar
Marian Begemann committed
175

Hannes Kallwies's avatar
Hannes Kallwies committed
176
177
* Choose the Tessla specification to use in the build process by naming it in `scripts/build_project.sh` line 17 (without .tessla ending)
  * E.g. `tessla_specifiaction_file="counter_with_reset"`.
Marian Begemann's avatar
Marian Begemann committed
178

Hannes Kallwies's avatar
Hannes Kallwies committed
179
180
181
* Configure the usage of a trace file: `src/tesslabridge/config/tessla_bridge.yaml`
  * E.g. `use_trace: true`
  * E.g. `trace_path: "/tmp/tessla.output"`
Marian Begemann's avatar
Marian Begemann committed
182

Hannes Kallwies's avatar
Hannes Kallwies committed
183
#### Build & Run Project
Marian Begemann's avatar
Marian Begemann committed
184

Hannes Kallwies's avatar
Hannes Kallwies committed
185
After installation and configuration, the example can be started by using two scripts:
Marian Begemann's avatar
Marian Begemann committed
186

Hannes Kallwies's avatar
Hannes Kallwies committed
187
1) `scripts/build_project.sh`
Marian Begemann's avatar
Marian Begemann committed
188
   * Build the project based on the *.tessla file specified as parameter in line 1. 
Hannes Kallwies's avatar
Hannes Kallwies committed
189
190
191
192
193
194
195
   * Creates JSON with annotation information for *.tessla file
   * Builds the TeSSLa monitor via translation to Rust
   * Creates tessla lib code for TeSSLa/ROS Bridge interface
   * Adjusts config paths for the TeSSLa/ROS Bridge
   * Builds the TeSSLa/ROS Bridge project

2) `scripts/start_TeSSLaBridge_standalone.sh`
Marian Begemann's avatar
Marian Begemann committed
196
   * sources the project
Hannes Kallwies's avatar
Hannes Kallwies committed
197
198
199
   * start corressponding ROS2 launch script for the TeSSLa bridge

For the counter example, use `start_example_counter_with_reset_rust.sh` which satarts the TeSSLa Bridge and the observed counter node ([src/tesslabridge/tesslabridge/examples/counter_with_reset.py](https://git.tessla.io/ros/tesslarosbridge/-/blob/main/src/tesslabridge/tesslabridge/examples/counter_with_reset.py)) in parallel.
Marian Begemann's avatar
Marian Begemann committed
200

Hannes Kallwies's avatar
Hannes Kallwies committed
201
#### **TIME**
Marian Begemann's avatar
Marian Begemann committed
202

Marian Begemann's avatar
Marian Begemann committed
203
The current time is created by the tesslabridge, when it passes a recived messages to the tessla interface.
Marian Begemann's avatar
Marian Begemann committed
204

Marian Begemann's avatar
Marian Begemann committed
205
make_step is called once every second by the tesslabridge to keep tessla processing even if no new data is supplied by the ros topics.
Marian Begemann's avatar
Marian Begemann committed
206
207