Skip to content

Commit 7dec0c1

Browse files
git-afsantosgit-afsantos
committed
improved package documentation
bumped version of fictibot packages
1 parent 156c62b commit 7dec0c1

File tree

7 files changed

+211
-10
lines changed

7 files changed

+211
-10
lines changed

‎CHANGELOG.md

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Changelog
2+
All notable changes to this project will be documented in this file.
3+
4+
The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
5+
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
6+
7+
## [0.2.0] - 2021-01-25
8+
### Added
9+
- Several project files under [projects](./projects).
10+
- Several scripts to run HAROS under [scripts](./scripts).
11+
- `minimal_example` package.
12+
- `fictibot_msgs` package.
13+
- Subscriber to a custom message type in `fictibot_controller`.
14+
- `state` topic publisher to `fictibot_multiplex`.
15+
- Conditional subscribers to `fictibot_controller`.
16+
17+
### Changed
18+
- Improved [README](./README.md) documentation.
19+
20+
## [0.1.0] - 2018-03-27
21+
### Added
22+
- `fictibot_driver` package.
23+
- `fictibot_controller` package.
24+
- `fictibot_multiplex` package.
25+
- `index.yaml` basic project file.

‎CONTRIBUTING.md

+65
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Contributing
2+
3+
When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.
4+
5+
Please note we have a code of conduct, please follow it in all your interactions with the project.
6+
7+
## Pull Request Process
8+
9+
1. Ensure any install or build dependencies are removed before the end of the layer when doing a build.
10+
2. Update the README.md with details of changes to the interface, this includes new environment variables, exposed ports, useful file locations and container parameters.
11+
3. Increase the version numbers in any examples files and the README.rst to the new version that this Pull Request would represent.
12+
The versioning scheme we use is [SemVer](http://semver.org/).
13+
4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you.
14+
15+
## Code of Conduct
16+
17+
### Our Pledge
18+
19+
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
20+
21+
### Our Standards
22+
23+
Examples of behavior that contributes to creating a positive environment include:
24+
25+
* Using welcoming and inclusive language
26+
* Being respectful of differing viewpoints and experiences
27+
* Gracefully accepting constructive criticism
28+
* Focusing on what is best for the community
29+
* Showing empathy towards other community members
30+
31+
Examples of unacceptable behavior by participants include:
32+
33+
* The use of sexualized language or imagery and unwelcome sexual attention or advances
34+
* Trolling, insulting/derogatory comments, and personal or political attacks
35+
* Public or private harassment
36+
* Publishing others' private information, such as a physical or electronic address, without explicit permission
37+
* Other conduct which could reasonably be considered inappropriate in a professional setting
38+
39+
### Our Responsibilities
40+
41+
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
42+
43+
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
44+
45+
### Scope
46+
47+
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
48+
Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
49+
Representation of a project may be further defined and clarified by project maintainers.
50+
51+
### Enforcement
52+
53+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at *[email protected]*.
54+
All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances.
55+
The project team is obligated to maintain confidentiality with regard to the reporter of an incident.
56+
Further details of specific enforcement policies may be posted separately.
57+
58+
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
59+
60+
### Attribution
61+
62+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
63+
64+
[homepage]: http://contributor-covenant.org
65+
[version]: http://contributor-covenant.org/version/1/4/

‎LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2017 André Santos
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.

‎README.md

+97-7
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,99 @@
1-
HAROS Tutorials
2-
===============
1+
# HAROS Tutorials
32

4-
This is a repository with example code to try out [HAROS](http://github.com/git-afsantos/haros).
3+
This is a repository with example code to try out the various features of the [HAROS framework](http://github.com/git-afsantos/haros).
54

6-
* clone the repo: `https://github.com/git-afsantos/haros_tutorials.git`
7-
* add the repository root directory to the `ROS_PACKAGE_PATH` (replace `<repo-root-directory>`): `ROS_PACKAGE_PATH=$ROS_PACKAGE_PATH:<repo-root-directory>/haros_tutorials`
8-
* cd into the repository directory: `cd haros_tutorials/`
9-
* run the full analysis and visualize the results: `haros full -p my_index.yaml`
5+
## What Is In The Box
6+
7+
This repository contains ROS packages that serve no particular purpose, other than to try out HAROS.
8+
The `minimal_example` package is a minimal ROS package composed of two nodes with a ROS publisher, a ROS subscriber, a ROS service server, a ROS service client and a ROS parameter.
9+
The remaining four packages, `fictibot_drivers`, `fictibot_controller`, `fictibot_multiplex` and `fictibot_msgs` make up a fictitious mobile robot system, called Fictibot.
10+
The packages provide software drivers for the mobile base, a random walker controller, a multiplexer to filter commands by priority and message definitions, respectively.
11+
Despite being a fictitious robot, the system can be executed normally, using `rosrun`, or `roslaunch` with the various launch files contained in the packages.
12+
13+
In addition to the ROS packages, this repository also contains [example project files for HAROS](./projects) and [scripts](./scripts) to help execute HAROS.
14+
15+
## Installing
16+
17+
You can automate much of the installation of HAROS and this repository with [make-haros-easy](https://github.com/git-afsantos/make-haros-easy).
18+
19+
For a manual installation, the first step is to ensure that you have a working [catkin workspace](http://wiki.ros.org/catkin/Tutorials/create_a_workspace).
20+
Depending on your setup, you might want to work with multiple workspaces, and create a new workspace for this tutorial.
21+
Let us call it `haros_ws`.
22+
23+
Clone this repository into the source space of this workspace, by default `src`.
24+
25+
```bash
26+
cd haros_ws/src
27+
git clone https://github.com/git-afsantos/haros_tutorials.git
28+
```
29+
30+
Simply build the packages with `catkin_make`, and you are ready to use the packages in a ROS environment.
31+
32+
```bash
33+
cd ..
34+
catkin_make
35+
source devel/setup.bash
36+
```
37+
38+
To use these packages with HAROS and Clang, an additional step is required.
39+
You have to create a `compile_commands.json` file in the `build` directory of the workspace.
40+
You can do it either with `catkin` or with `cmake`.
41+
42+
```bash
43+
cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1 -DCMAKE_CXX_COMPILER=/usr/bin/clang++-3.8 src
44+
```
45+
46+
Or
47+
48+
```bash
49+
catkin_make -DCMAKE_EXPORT_COMPILE_COMMANDS=1 -DCMAKE_CXX_COMPILER=/usr/bin/clang++-3.8
50+
```
51+
52+
Replace `src` in the first command with the source space of your workspace, if it is named differently.
53+
Replace `/usr/bin/clang++-3.8` with the correct path to your `clang++` version.
54+
55+
## Standalone Usage
56+
57+
To try out the ROS packages on their own, use any of the provided launch files.
58+
They set up different use scenarios, sometimes showcasing some ROS features and quirks that might not be well known.
59+
60+
A normal use case, using the three Fictibot nodes:
61+
62+
```bash
63+
roslaunch fictibot_controller multiplexer.launch
64+
```
65+
66+
Two Fictibot systems at the same time:
67+
68+
```bash
69+
roslaunch fictibot_controller dual_bots.launch
70+
```
71+
72+
Some quirks with `rosparam` that might not be obvious from the documentation (read the launch file's comments as well):
73+
74+
```bash
75+
roslaunch fictibot_controller test_rosparam.launch
76+
```
77+
78+
## Usage With HAROS
79+
80+
You can try out HAROS manually with any of the provided [project files](./projects).
81+
Alternatively, feel free to use some pre-made [scripts](./scripts) that test out different features.
82+
83+
- [`scripts/minimal.sh`](./scripts/minimal.sh) runs model extraction on `minimal_example` and any available plugins.
84+
- [`scripts/fictibot.sh`](./scripts/fictibot.sh) runs model extraction on various configurations of Fictibot and any available plugins.
85+
- [`scripts/queries.sh`](./scripts/queries.sh) defines architectural queries for some configurations of Fictibot and executes [`haros_plugin_pyflwor`](https://github.com/git-afsantos/haros-plugin-pyflwor).
86+
- [`scripts/hpl.sh`](./scripts/hpl.sh) defines [HPL properties](https://github.com/git-afsantos/hpl-specs) for the various Fictibot nodes and runs test generation with [`haros_plugin_pbt_gen`](https://github.com/git-afsantos/haros-plugin-pbt-gen).
87+
- [`scripts/perf.sh`](./scripts/perf.sh) defines the ground truth of the `multiplex` computation graph and evaluates the model extractor's accuracy with [`haros_plugin_model_ged`](https://github.com/git-afsantos/haros-plugin-model-ged).
88+
89+
## Bugs, Questions and Support
90+
91+
Please use the [issue tracker](https://github.com/git-afsantos/haros_tutorials/issues).
92+
93+
## Contributing
94+
95+
See [CONTRIBUTING](./CONTRIBUTING.md).
96+
97+
## Acknowledgment
98+
99+
This work is financed by the ERDF – European Regional Development Fund through the Operational Programme for Competitiveness and Internationalisation - COMPETE 2020 Programme and by National Funds through the Portuguese funding agency, FCT - Fundação para a Ciência e a Tecnologia within project PTDC/CCI-INF/29583/2017 (POCI-01-0145-FEDER-029583).

‎fictibot_controller/package.xml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<?xml version="1.0"?>
22
<package>
33
<name>fictibot_controller</name>
4-
<version>0.1.0</version>
4+
<version>0.2.0</version>
55
<description>The fictibot_controller package</description>
66

77
<maintainer email="[email protected]">Andre Santos</maintainer>

‎fictibot_msgs/package.xml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<?xml version="1.0"?>
22
<package>
33
<name>fictibot_msgs</name>
4-
<version>0.1.0</version>
4+
<version>0.2.0</version>
55
<description>The fictibot_msgs package</description>
66

77
<maintainer email="[email protected]">Andre Santos</maintainer>

‎fictibot_multiplex/package.xml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<?xml version="1.0"?>
22
<package>
33
<name>fictibot_multiplex</name>
4-
<version>0.1.0</version>
4+
<version>0.2.0</version>
55
<description>The fictibot_multiplex package</description>
66

77
<maintainer email="[email protected]">Andre Santos</maintainer>

0 commit comments

Comments
 (0)