Skip to content

Commit b8c1597

Browse files
jrharbin-yorkjrharbin-york
committed
Redo documentation and readme
1 parent 7694f68 commit b8c1597

File tree

8 files changed

+171
-146
lines changed

8 files changed

+171
-146
lines changed

‎README.md‎

Lines changed: 9 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -8,108 +8,18 @@ SESAME deliverable documents
88
- D6.6: Simulation-Based Testing Methodology for EDDIs
99
- D6.7: Tools for Automated Quality Assurance of EDDI-Supported MRS
1010

11-
This online guide complements D6.7 in reference to providing
12-
source code and instructions for the platform.
13-
14-
# Documentation
15-
16-
[Documentation for the platform](./documentation/index.md)
17-
18-
19-
```
20-
apt-get install ros-melodic-turtlebot3-*
21-
apt-get install ros-melodic-turtlesim-*
22-
apt-get install ros-melodic-rosbridge-server
23-
```
24-
25-
## Patching for jrosbridge
26-
27-
This applies when using the ROS interface for the testing platform.
28-
29-
Because of a problem with jrosbridge (that is used for connecting the
30-
ROS interface to the testing platform), it is necessary to patch a
31-
certain system package for jrosbridge to work on recent Ubuntu versions.
32-
For more information on why this is necessary, please see
33-
[here](https://github.com/RobotWebTools/rosbridge_suite/issues/488)
34-
35-
Please go to the directory **REPO_BASE_PATH/patches** and run the
36-
commands below. (Note this assumes the Python version used for the
37-
rosbridge python components is Python 2.7, it may be a later version
38-
in ROS versions beyond ROS Melodic).
39-
40-
```
41-
42-
export PATCH_DIR=/usr/lib/python2.7/dist-packages/autobahn/websocket
43-
sudo cp ./python_protocol_patch.py $PATCH_DIR
44-
cd $PATCH_DIR
45-
sudo cp protocol.py protocol.py.orig
46-
sudo patch < python_protocol_patch.py
47-
```
48-
49-
To restore everything its previous state, please use the following
50-
commands:
11+
The integrated methodology:
5112

52-
```
53-
PATCH_DIR=/usr/lib/python2.7/dist-packages/autobahn/websocket
54-
cd $PATCH_DIR
55-
sudo cp protocol.py.orig protocol.py
56-
```
13+
![Integrated methodology figure](./documentation/readme-images/overall-alg-structure.png)
5714

58-
## Running the TurtleSim Case Study
15+
The testing architecture:
5916

60-
- Ensure the Turtlesim example itself runs properly as described
61-
[here](http://wiki.ros.org/turtlesim):
17+
![Testing architecture](./documentation/readme-images/methodology-simtesting.png)
6218

63-
- Pull the latest from the "development-release-aug2022" branch
64-
65-
- In the parent Eclipse:
66-
67-
- Ensure the variable **REPO_BASE_PATH** in the project
68-
uk.ac.york.testing.evolutionary.utilities file, PathDefinitions.java
69-
is set to the absolute path of the root directory in which you checked
70-
out this repository
71-
72-
- The same for **REPO_BASE_PATH** in the project
73-
uk.ac.york.testing.generator, file ModelPathDefinitions.java (again,
74-
this should be set to the absolute path of the root directory in which
75-
you checked out this repository)
76-
77-
- Then for all the listed SESAME projects (except for
78-
uk.ac.york.sesame.testing.generator), right-click on each of them,
79-
select "Run As"... "Maven Install". This makes sure updated JARs are
80-
built for all of them.
81-
82-
- Enter the child Eclipse by right-clicking on selecting the
83-
uk.ac.york.sesame.testing.generator project, and selecting
84-
85-
- Create a new "testTurtle" Java project and copy the models and code
86-
files for the development branch from:
87-
[runtime-EclipseApplication/testTurtle](https://github.com/sesame-project/simulationBasedTesting/tree/development-release-aug2022/runtime-EclipseApplication/testTurtle)
88-
into this project, including "src", "models" and "pom.xml". If you
89-
checked out the development-release-aug2022 branch, this can be found
90-
under your local system on
91-
$REPO_BASE_PATH/runtime-EclipseApplication/testTurtle.
92-
93-
- Copy the ROS launch file
94-
[test.launch](https://github.com/sesame-project/simulationBasedTesting/blob/development-release-aug2022/temp-launch-scripts/launch-scripts/test.launch)
95-
into: $HOME/catkin_ws/src/turtle_custom_launch/launch/test.launch
96-
97-
- Change the MRS launch file path path to your filesystem in
98-
testTurtle.model (in "TestingSpace", "MRS", "Launch File Location") to
99-
the correct path on your system.
100-
101-
- Try generating the code based upon the model testTurtle.model
102-
103-
- Execute the new test runner for ExptRunner_firstExperiment. This
104-
should start the simulator.
105-
106-
- When it starts, select the "Reading from keyboard" xterm and
107-
use the arrow keys to drive it; when fuzzing is active the
108-
velocities will be replaced by random values.
19+
# Documentation
10920

110-
Try cleaning and rebuilding the project in case of any problems.
21+
Documentation and installation instructions for the platform can be found here:
22+
[Documentation for the SESAME simulation-based testing platform](./documentation/index.md)
11123

112-
If you reload the child Eclipse, you may find that you get "Problems
113-
encountered..." on loading the model. In this case, right-click on the
114-
project, select "Generate SESAME Code" and then when the wizard
115-
pops up, choose "Cancel". This will re-register the metamodels.
24+
This online guide complements D6.7 in reference to providing
25+
source code and instructions for the platform.

‎documentation/INSTALL-linux-ros.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Additional instructions for ROS use cases
2+
Install the following additional packages for ROS:
3+
4+
```
5+
apt-get install ros-melodic-turtlebot3-*
6+
apt-get install ros-melodic-turtlesim-*
7+
apt-get install ros-melodic-rosbridge-server
8+
```
9+
10+
## Patching for jrosbridge
11+
12+
This applies when using the ROS interface for the testing platform.
13+
14+
Because of a problem with jrosbridge (that is used for connecting the
15+
ROS interface to the testing platform), it is necessary to patch a
16+
certain system package for jrosbridge to work on recent Ubuntu versions.
17+
For more information on why this is necessary, please see
18+
[here](https://github.com/RobotWebTools/rosbridge_suite/issues/488)
19+
20+
Please go to the directory **REPO_BASE_PATH/patches** and run the
21+
commands below. (Note this assumes the Python version used for the
22+
rosbridge python components is Python 2.7, it may be a later version
23+
in ROS versions beyond ROS Melodic).
24+
25+
```
26+
27+
export PATCH_DIR=/usr/lib/python2.7/dist-packages/autobahn/websocket
28+
sudo cp ./python_protocol_patch.py $PATCH_DIR
29+
cd $PATCH_DIR
30+
sudo cp protocol.py protocol.py.orig
31+
sudo patch < python_protocol_patch.py
32+
```
33+
34+
To restore everything its previous state, please use the following
35+
commands:
36+
37+
```
38+
PATCH_DIR=/usr/lib/python2.7/dist-packages/autobahn/websocket
39+
cd $PATCH_DIR
40+
sudo cp protocol.py.orig protocol.py
41+
```
42+
43+
## Running the TurtleSim Case Study
44+
45+
- Ensure the Turtlesim example itself runs properly as described
46+
[here](http://wiki.ros.org/turtlesim):
47+
48+
- Pull the latest from the "development-release-aug2022" branch
49+
50+
- In the parent Eclipse:
51+
52+
- Ensure the variable **REPO_BASE_PATH** in the project
53+
uk.ac.york.testing.evolutionary.utilities file, PathDefinitions.java
54+
is set to the absolute path of the root directory in which you checked
55+
out this repository
56+
57+
- The same for **REPO_BASE_PATH** in the project
58+
uk.ac.york.testing.generator, file ModelPathDefinitions.java (again,
59+
this should be set to the absolute path of the root directory in which
60+
you checked out this repository)
61+
62+
- Then for all the listed SESAME projects (except for
63+
uk.ac.york.sesame.testing.generator), right-click on each of them,
64+
select "Run As"... "Maven Install". This makes sure updated JARs are
65+
built for all of them.
66+
67+
- Enter the child Eclipse by right-clicking on selecting the
68+
uk.ac.york.sesame.testing.generator project, and selecting
69+
70+
- Create a new "testTurtle" Java project and copy the models and code
71+
files for the development branch from:
72+
[runtime-EclipseApplication/testTurtle](https://github.com/sesame-project/simulationBasedTesting/tree/development-release-aug2022/runtime-EclipseApplication/testTurtle)
73+
into this project, including "src", "models" and "pom.xml". If you
74+
checked out the development-release-aug2022 branch, this can be found
75+
under your local system on
76+
$REPO_BASE_PATH/runtime-EclipseApplication/testTurtle.
77+
78+
- Copy the ROS launch file
79+
[test.launch](https://github.com/sesame-project/simulationBasedTesting/blob/development-release-aug2022/temp-launch-scripts/launch-scripts/test.launch)
80+
into: $HOME/catkin_ws/src/turtle_custom_launch/launch/test.launch
81+
82+
- Change the MRS launch file path path to your filesystem in
83+
testTurtle.model (in "TestingSpace", "MRS", "Launch File Location") to
84+
the correct path on your system.
85+
86+
- Try generating the code based upon the model testTurtle.model
87+
88+
- Execute the new test runner for ExptRunner_firstExperiment. This
89+
should start the simulator.
90+
91+
- When it starts, select the "Reading from keyboard" xterm and
92+
use the arrow keys to drive it; when fuzzing is active the
93+
velocities will be replaced by random values.
94+
95+
Try cleaning and rebuilding the project in case of any problems.
96+
97+
If you reload the child Eclipse, you may find that you get "Problems
98+
encountered..." on loading the model. In this case, right-click on the
99+
project, select "Generate SESAME Code" and then when the wizard
100+
pops up, choose "Cancel". This will re-register the metamodels.

‎documentation/INSTALL-linux.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,3 +137,10 @@ cd ~/source/KukaCell-2022_12_05_newtriggerzones
137137
```
138138
Edit the file runargs.ini - in particular, if you have a license, set it according to
139139
TTS instructions
140+
141+
# Additional instructions for ROS use case
142+
[Additional instructions for ROS use cases](./INSTALL-linux-ros.md)
143+
144+
# Troubleshooting
145+
[See troubleshooting in case of problems with installation or usage](./TROUBLE.md)
146+

‎documentation/TROUBLE.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Troubleshooting
2+
3+
## "Problems encountered" on loading the model
4+
If you exit and then reload the child Eclipse, you may find that you
5+
get "Problems encountered..." on loading the model. In this case,
6+
right-click on the project, select "Generate SESAME Code" and then
7+
when the wizard pops up, choose "Cancel". This will re-register the
8+
metamodels.
9+
10+
## Windows installation - KUKA machines with Windows installation
11+
12+
If, on attempting to import projects, you get errors such as the
13+
following: "artifact download failed" and "PKIX path building failed":
14+
15+
https://stackoverflow.com/questions/21076179/pkix-path-building-failed-and-unable-to-find-valid-certification-path-to-requ
16+
17+
This is caused by the KUKA firewall replacing the certificates
18+
silently, making the certification verification for Java dependencies
19+
fail.
20+
21+
To workaround, go in each the project directories under Cygwin
22+
```~/academic/sesame/WP6/simulationBasedTesting```, add a directory
23+
*.mvn* under them, and in it, a text file *maven.config*: this file
24+
should contain
25+
26+
```
27+
-Djavax.net.ssl.trustStoreType=WINDOWS-ROOT
28+
```
29+
30+
In this case, whenever you generate a custom projects under the child
31+
Eclipse, you will also need to add an equivalent file
32+
*.mvn/maven.config* with this WINDOWS_ROOT fix
33+
34+
## Kafka message bus problems
35+
If Kafka is giving errors on the terminal at the end of the launch
36+
process, try Ctrl-C to restarting both Kafka and Zookeeper. For some
37+
reason, especially on Windows, it sometimes fails to start properly.
38+
39+
## Debugging problems with tests
40+
If the test runner is not launching tests properly, it is recommended to
41+
go to the low-level tests (under "src" / "(default package") and
42+
create Eclipse Run Configurations to launch them directly. This way,
43+
console messages can be seen.
44+
45+
## gRPC failures to connect
46+
If gRPC fails to connect when launching tests (either constantly or intermittently), try
47+
increasing the timeout *launchDelaySeconds* under
48+
49+
# Additional instructions for ROS use case
50+
[Additional instructions for ROS use cases](./INSTALL-linux-ros.md)

‎documentation/index.md‎

Lines changed: 5 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -6,58 +6,16 @@ Installation instructions for Linux platforms are presented below:
66

77
[Installation instructions](./INSTALL-linux.md)
88

9-
## Installation Video for Linux
9+
### Installation Video for Linux
1010

11-
An installation instructions video for the platform is presented below:
11+
An older installation instructions video for the platform is presented below:
1212
This uses the "development-release-aug2022" branch:
13-
1413
[Installation video](https://drive.google.com/file/d/1O_F2LPpgkkYIkHfmnHXhXkFeUero5v6l/view?usp=sharing)
1514

16-
Please use the video instructions rather than the previous install
17-
instructions, since several steps e.g. setting paths, have been
18-
altered.
19-
20-
21-
22-
## Patching for jrosbridge
23-
24-
This applies when using the ROS interface for the testing platform.
25-
26-
Because of a problem with jrosbridge (that is used for connecting the
27-
ROS interface to the testing platform), it is necessary to patch a
28-
certain system package for jrosbridge to work on recent Ubuntu versions.
29-
For more information on why this is necessary, please see
30-
[here](https://github.com/RobotWebTools/rosbridge_suite/issues/488)
31-
32-
Please go to the directory **REPO_BASE_PATH/patches** and run the
33-
commands below. (Note this assumes the Python version used for the
34-
rosbridge python components is Python 2.7, it may be a later version
35-
in ROS versions beyond ROS Melodic).
36-
37-
```
38-
39-
export PATCH_DIR=/usr/lib/python2.7/dist-packages/autobahn/websocket
40-
sudo cp ./python_protocol_patch.py $PATCH_DIR
41-
cd $PATCH_DIR
42-
sudo cp protocol.py protocol.py.orig
43-
sudo patch < python_protocol_patch.py
44-
```
45-
46-
To restore everything its previous state, please use the following
47-
commands:
48-
49-
```
50-
PATCH_DIR=/usr/lib/python2.7/dist-packages/autobahn/websocket
51-
cd $PATCH_DIR
52-
sudo cp protocol.py.orig protocol.py
53-
```
54-
55-
## Installation Instructions For Windows
15+
We now recommend that you use the [new installation instructions](./INSTALL-linux.md)
5616

57-
The installation instructions for Windows are located at the following
58-
location (upon a seperate branch):
17+
## Installation Instructions for Windows
5918

60-
[Installation Instructions For Windows](https://github.com/sesame-project/simulationBasedTesting/blob/windows/README-windows.md)
6119

6220
## User Guide
63-
[User Guide](./userguide.md)
21+
[User Guide for the platform](./userguide.md)

‎documentation/readme-images/methodology-simtesting.pdf‎

80.4 KB
Binary file not shown.

‎documentation/readme-images/overall-alg-structure.pdf‎

79.6 KB
Binary file not shown.

‎documentation/readme-images/overall-alg-structure.png‎

16.1 KB
Loading

0 commit comments

Comments
 (0)