Skip to content

Commit 1984d2a

Browse files
ssancd03ssancd03
authored
Improved yasmin documentation (#71)
* Yasmin docs v1.0 * Removed old index * Updated docs for yasmin
1 parent 90ee4b1 commit 1984d2a

35 files changed

+7477
-158
lines changed

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1668,6 +1668,8 @@ if __name__ == "__main__":
16681668
<details>
16691669
<summary>Click to expand</summary>
16701670

1671+
> **Note:** When mixing Python and C++ states in the same state machine, they can communicate through the blackboard, but only with primitive data types: `int`, `float`, `bool`, and `string`. Complex objects or ROS messages cannot be directly shared between Python and C++ states.
1672+
16711673
```shell
16721674
ros2 run yasmin_demos factory_demo.py
16731675
```
@@ -3307,6 +3309,8 @@ int main(int argc, char *argv[]) {
33073309
<details>
33083310
<summary>Click to expand</summary>
33093311

3312+
> **Note:** When mixing Python and C++ states in the same state machine, they can communicate through the blackboard, but only with primitive data types: `int`, `float`, `bool`, and `string`. Complex objects or ROS messages cannot be directly shared between Python and C++ states.
3313+
33103314
```shell
33113315
ros2 run yasmin_demos factory_demo
33123316
```
@@ -3449,4 +3453,4 @@ isbn="978-3-031-21062-4"
34493453
year = {2022},
34503454
copyright = {Creative Commons Attribution Non Commercial No Derivatives 4.0 International}
34513455
}
3452-
```
3456+
```

‎docs/citations.html‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>Citations - YASMIN</title>
7+
<link rel="stylesheet" href="style.css">
8+
<script src="sidebar.js"></script>
9+
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/atom-one-dark.min.css">
10+
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
11+
<script>hljs.highlightAll();</script>
12+
<script src="dark_mode.js"></script>
13+
</head>
14+
<body>
15+
<header>
16+
<a href="index.html" class="logo">
17+
<img src="logo.png" alt="YASMIN Logo">
18+
YASMIN
19+
</a>
20+
<div class="nav-links">
21+
<a href="index.html">Docs</a>
22+
<a href="https://github.com/uleroboticsgroup/yasmin" target="_blank">GitHub</a>
23+
<a href="doxygen.html" target="_blank">Doxygen</a>
24+
<button id="theme-toggle" title="Toggle Dark Mode">🌙</button>
25+
</div>
26+
</header>
27+
28+
<div class="container">
29+
<nav class="sidebar">
30+
<h3>Getting Started</h3>
31+
<ul>
32+
<li><a href="index.html">Introduction</a></li>
33+
<li><a href="main_concepts.html">Main Concepts</a></li>
34+
<li><a href="packages.html">Packages Overview</a></li>
35+
<li><a href="docker.html">Docker</a></li>
36+
<li><a href="xml_factory.html">XML</a></li>
37+
</ul>
38+
39+
<h3>Tutorials</h3>
40+
<ul>
41+
<li><a href="tutorials.html">All Tutorials</a></li>
42+
</ul>
43+
44+
<h3 class="collapsible">C++ Tutorials</h3>
45+
<ul>
46+
<li><a href="tutorials/cpp/basic_fsm.html">Writing a Simple FSM</a></li>
47+
<li><a href="tutorials/cpp/remap_demo.html">Blackboard Remapping</a></li>
48+
<li><a href="tutorials/cpp/concurrence_demo.html">Concurrence</a></li>
49+
<li><a href="tutorials/cpp/service_client_demo.html">Service Client</a></li>
50+
<li><a href="tutorials/cpp/action_client_demo.html">Action Client</a></li>
51+
<li><a href="tutorials/cpp/monitor_demo.html">Monitor (Subscriber)</a></li>
52+
<li><a href="tutorials/cpp/publisher_demo.html">Publisher</a></li>
53+
<li><a href="tutorials/cpp/parameters_demo.html">ROS Parameters</a></li>
54+
<li><a href="tutorials/cpp/nav2_demo.html">Nav2 Demo</a></li>
55+
<li><a href="tutorials/cpp/factory_demo.html">Factory (XML)</a></li>
56+
</ul>
57+
58+
<h3 class="collapsible">Python Tutorials</h3>
59+
<ul>
60+
<li><a href="tutorials/python/basic_fsm.html">Writing a Simple FSM</a></li>
61+
<li><a href="tutorials/python/remap_demo.html">Blackboard Remapping</a></li>
62+
<li><a href="tutorials/python/concurrence_demo.html">Concurrence</a></li>
63+
<li><a href="tutorials/python/service_client_demo.html">Service Client</a></li>
64+
<li><a href="tutorials/python/action_client_demo.html">Action Client</a></li>
65+
<li><a href="tutorials/python/monitor_demo.html">Monitor (Subscriber)</a></li>
66+
<li><a href="tutorials/python/publisher_demo.html">Publisher</a></li>
67+
<li><a href="tutorials/python/parameters_demo.html">ROS Parameters</a></li>
68+
<li><a href="tutorials/python/nav2_demo.html">Nav2 Demo</a></li>
69+
<li><a href="tutorials/python/factory_demo.html">Factory (XML)</a></li>
70+
</ul>
71+
72+
<h3>Tools</h3>
73+
<ul>
74+
<li><a href="yasmin_editor.html">YASMIN Editor</a></li>
75+
<li><a href="yasmin_factory.html">YASMIN Factory</a></li>
76+
<li><a href="yasmin_viewer.html">YASMIN Viewer</a></li>
77+
</ul>
78+
79+
<h3>Resources</h3>
80+
<ul>
81+
<li><a href="citations.html">Citations</a></li>
82+
</ul>
83+
</nav>
84+
85+
<main class="main-content content">
86+
<h1>Citations</h1>
87+
<p>If you use YASMIN in your research, please cite the following works:</p>
88+
89+
<h2>Conference Paper</h2>
90+
<p><strong>González-Santamarta, M. Á., Rodríguez-Lera, F. J., Matellán-Olivera, V., & Fernández-Llamas, C. (2023). YASMIN: Yet Another State MachINe. In ROBOT2022: Fifth Iberian Robotics Conference (pp. 528-539). Springer International Publishing.</strong></p>
91+
92+
<div class="citation-box">@InProceedings{10.1007/978-3-031-21062-4_43,
93+
author="Gonz{\'a}lez-Santamarta, Miguel {\'A}.
94+
and Rodr{\'i}guez-Lera, Francisco J.
95+
and Matell{\'a}n-Olivera, Vicente
96+
and Fern{\'a}ndez-Llamas, Camino",
97+
editor="Tardioli, Danilo
98+
and Matell{\'a}n, Vicente
99+
and Heredia, Guillermo
100+
and Silva, Manuel F.
101+
and Marques, Lino",
102+
title="YASMIN: Yet Another State MachINe",
103+
booktitle="ROBOT2022: Fifth Iberian Robotics Conference",
104+
year="2023",
105+
publisher="Springer International Publishing",
106+
address="Cham",
107+
pages="528--539",
108+
abstract="State machines are a common mechanism for defining behaviors in robots where each behavior is based on identifiable stages. There are several libraries available for easing the implementation of state machines in ROS 1, however, the community was focused on SMACH or SMACC. Although these tools are still predominant, there are fewer alternatives for ROS 2. Besides, Behavior Trees are spreading fast, but there is a niche for using State Machines. Here, YASMIN is presented as yet another library specifically designed for ROS 2 for easing the design of robotic behaviors using state machines. It is available in C++ and Python, and provides some default states to speed up the development, in addition to a web viewer for monitoring the execution of the system and helping in the debugging.",
109+
isbn="978-3-031-21062-4"
110+
}</div>
111+
112+
<h2>arXiv Preprint</h2>
113+
<p><strong>González-Santamarta, M. Á., Rodríguez-Lera, F. J., Llamas, C. F., Rico, F. M., & Olivera, V. M. (2022). YASMIN: Yet Another State MachINe library for ROS 2. arXiv preprint arXiv:2205.13284.</strong></p>
114+
115+
<div class="citation-box">@misc{yasmin,
116+
doi = {10.48550/ARXIV.2205.13284},
117+
url = {https://arxiv.org/abs/2205.13284},
118+
author = {González-Santamarta, Miguel Ángel and Rodríguez-Lera, Francisco Javier and Llamas, Camino Fernández and Rico, Francisco Martín and Olivera, Vicente Matellán},
119+
keywords = {Robotics (cs.RO), FOS: Computer and information sciences, FOS: Computer and information sciences},
120+
title = {YASMIN: Yet Another State MachINe library for ROS 2},
121+
publisher = {arXiv},
122+
year = {2022},
123+
copyright = {Creative Commons Attribution Non Commercial No Derivatives 4.0 International}
124+
}</div>
125+
126+
<h2>Links</h2>
127+
<ul>
128+
<li><a href="https://link.springer.com/chapter/10.1007/978-3-031-21062-4_43" target="_blank">Springer - ROBOT2022 Conference Paper</a></li>
129+
<li><a href="https://arxiv.org/abs/2205.13284" target="_blank">arXiv - Technical Report</a></li>
130+
<li><a href="https://github.com/uleroboticsgroup/yasmin" target="_blank">GitHub Repository</a></li>
131+
</ul>
132+
</main>
133+
</div>
134+
135+
<footer>
136+
<p>&copy; 2025 YASMIN Project. Licensed under GPL v3.0. | Documentation generated with <a href="doxygen.html" target="_blank">Doxygen</a></p>
137+
</footer>
138+
</body>
139+
</html>

‎docs/dark_mode.js‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
(function() {
2+
const currentTheme = localStorage.getItem('theme');
3+
if (currentTheme === 'dark-mode') {
4+
document.documentElement.classList.add('dark-mode');
5+
}
6+
})();
7+
8+
document.addEventListener('DOMContentLoaded', () => {
9+
const toggleButton = document.getElementById('theme-toggle');
10+
const html = document.documentElement;
11+
12+
// Set initial button state
13+
if (html.classList.contains('dark-mode')) {
14+
toggleButton.textContent = '☀️';
15+
} else {
16+
toggleButton.textContent = '🌙';
17+
}
18+
19+
toggleButton.addEventListener('click', () => {
20+
html.classList.toggle('dark-mode');
21+
22+
let theme = 'light';
23+
if (html.classList.contains('dark-mode')) {
24+
theme = 'dark-mode';
25+
toggleButton.textContent = '☀️';
26+
} else {
27+
toggleButton.textContent = '🌙';
28+
}
29+
30+
localStorage.setItem('theme', theme);
31+
});
32+
});

‎docs/docker.html‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>Docker - YASMIN</title>
7+
<link rel="stylesheet" href="style.css">
8+
<script src="sidebar.js"></script>
9+
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/atom-one-dark.min.css">
10+
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
11+
<script>hljs.highlightAll();</script>
12+
<script src="dark_mode.js"></script>
13+
</head>
14+
<body>
15+
<header>
16+
<a href="index.html" class="logo">
17+
<img src="logo.png" alt="YASMIN Logo">
18+
YASMIN
19+
</a>
20+
<div class="nav-links">
21+
<a href="index.html">Docs</a>
22+
<a href="https://github.com/uleroboticsgroup/yasmin" target="_blank">GitHub</a>
23+
<a href="doxygen.html" target="_blank">Doxygen</a>
24+
<button id="theme-toggle" title="Toggle Dark Mode">🌙</button>
25+
</div>
26+
</header>
27+
28+
<div class="container">
29+
<nav class="sidebar">
30+
<h3>Getting Started</h3>
31+
<ul>
32+
<li><a href="index.html">Introduction</a></li>
33+
<li><a href="main_concepts.html">Main Concepts</a></li>
34+
<li><a href="packages.html">Packages Overview</a></li>
35+
<li><a href="docker.html">Docker</a></li>
36+
<li><a href="xml_factory.html">XML</a></li>
37+
</ul>
38+
39+
<h3>Tutorials</h3>
40+
<ul>
41+
<li><a href="tutorials.html">All Tutorials</a></li>
42+
</ul>
43+
44+
<h3 class="collapsible">C++ Tutorials</h3>
45+
<ul>
46+
<li><a href="tutorials/cpp/basic_fsm.html">Writing a Simple FSM</a></li>
47+
<li><a href="tutorials/cpp/remap_demo.html">Blackboard Remapping</a></li>
48+
<li><a href="tutorials/cpp/concurrence_demo.html">Concurrence</a></li>
49+
<li><a href="tutorials/cpp/service_client_demo.html">Service Client</a></li>
50+
<li><a href="tutorials/cpp/action_client_demo.html">Action Client</a></li>
51+
<li><a href="tutorials/cpp/monitor_demo.html">Monitor (Subscriber)</a></li>
52+
<li><a href="tutorials/cpp/publisher_demo.html">Publisher</a></li>
53+
<li><a href="tutorials/cpp/parameters_demo.html">ROS Parameters</a></li>
54+
<li><a href="tutorials/cpp/nav2_demo.html">Nav2 Demo</a></li>
55+
<li><a href="tutorials/cpp/factory_demo.html">Factory (XML)</a></li>
56+
</ul>
57+
58+
<h3 class="collapsible">Python Tutorials</h3>
59+
<ul>
60+
<li><a href="tutorials/python/basic_fsm.html">Writing a Simple FSM</a></li>
61+
<li><a href="tutorials/python/remap_demo.html">Blackboard Remapping</a></li>
62+
<li><a href="tutorials/python/concurrence_demo.html">Concurrence</a></li>
63+
<li><a href="tutorials/python/service_client_demo.html">Service Client</a></li>
64+
<li><a href="tutorials/python/action_client_demo.html">Action Client</a></li>
65+
<li><a href="tutorials/python/monitor_demo.html">Monitor (Subscriber)</a></li>
66+
<li><a href="tutorials/python/publisher_demo.html">Publisher</a></li>
67+
<li><a href="tutorials/python/parameters_demo.html">ROS Parameters</a></li>
68+
<li><a href="tutorials/python/nav2_demo.html">Nav2 Demo</a></li>
69+
<li><a href="tutorials/python/factory_demo.html">Factory (XML)</a></li>
70+
</ul>
71+
72+
<h3>Tools</h3>
73+
<ul>
74+
<li><a href="yasmin_editor.html">YASMIN Editor</a></li>
75+
<li><a href="yasmin_factory.html">YASMIN Factory</a></li>
76+
<li><a href="yasmin_viewer.html">YASMIN Viewer</a></li>
77+
</ul>
78+
79+
<h3>Resources</h3>
80+
<ul>
81+
<li><a href="citations.html">Citations</a></li>
82+
</ul>
83+
</nav>
84+
85+
<main class="main-content content">
86+
<h1>Docker</h1>
87+
<p>If your operating system doesn't support ROS 2, Docker is a great alternative. You can use pre-built images from <a href="https://hub.docker.com/r/mgons/yasmin/" target="_blank">DockerHub</a> or create your own custom images.</p>
88+
89+
<h2>Building the Docker Image</h2>
90+
<p>To build the YASMIN Docker image from source, navigate to the YASMIN project directory and run the following command. This process will download the base ROS 2 image, install all YASMIN dependencies, and compile the packages. The build typically takes 5-10 minutes depending on your system:</p>
91+
<pre><code class="language-bash">docker build -t yasmin .</code></pre>
92+
93+
<p>Alternatively, you can use the Makefile shortcut for a more convenient build process:</p>
94+
<pre><code class="language-bash">make docker_build</code></pre>
95+
96+
<p><strong>Note:</strong> The Dockerfile uses multi-stage builds to optimize the final image size. Ensure you have at least 10GB of free disk space for the build process.</p>
97+
98+
<h2>Running the Docker Container</h2>
99+
<p>After building the image, start a Docker container with full GUI support and network access. The command below configures X11 forwarding for graphical applications like the YASMIN Viewer and Editor, enables host networking for ROS 2 communication, and provides necessary permissions:</p>
100+
<pre><code class="language-bash">docker run -it --net=host --ipc=host --privileged \
101+
--env="DISPLAY" \
102+
--env="QT_X11_NO_MITSHM=1" \
103+
--volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \
104+
--volume="${XAUTHORITY}:/root/.Xauthority" \
105+
--entrypoint /bin/bash yasmin</code></pre>
106+
107+
<p>Or use the Makefile shortcut for a simpler command:</p>
108+
<pre><code class="language-bash">make docker_run</code></pre>
109+
110+
<p><strong>What the flags do:</strong></p>
111+
<ul>
112+
<li><code>--net=host</code>: Shares the host's network stack, enabling seamless ROS 2 node communication</li>
113+
<li><code>--ipc=host</code>: Allows shared memory communication for better performance</li>
114+
<li><code>--privileged</code>: Grants extended privileges (required for some hardware access)</li>
115+
<li><code>DISPLAY</code> and X11 volumes: Enable GUI applications to display on your host</li>
116+
</ul>
117+
118+
<h2>Available Docker Images</h2>
119+
<p>Pre-built images are available for multiple ROS 2 distributions on <a href="https://hub.docker.com/r/mgons/yasmin/" target="_blank">DockerHub</a>. These images include all YASMIN packages pre-compiled and ready to use, saving you build time:</p>
120+
<ul>
121+
<li><a href="https://hub.docker.com/r/mgons/yasmin/tags?name=foxy" target="_blank">Foxy</a> - ROS 2 LTS (Long Term Support)</li>
122+
<li><a href="https://hub.docker.com/r/mgons/yasmin/tags?name=galactic" target="_blank">Galactic</a> - Standard release</li>
123+
<li><a href="https://hub.docker.com/r/mgons/yasmin/tags?name=humble" target="_blank">Humble</a> - ROS 2 LTS (Recommended for production)</li>
124+
<li><a href="https://hub.docker.com/r/mgons/yasmin/tags?name=iron" target="_blank">Iron</a> - Standard release</li>
125+
<li><a href="https://hub.docker.com/r/mgons/yasmin/tags?name=jazzy" target="_blank">Jazzy</a> - ROS 2 LTS</li>
126+
<li><a href="https://hub.docker.com/r/mgons/yasmin/tags?name=kilted" target="_blank">Kilted</a> - Standard release</li>
127+
<li><a href="https://hub.docker.com/r/mgons/yasmin/tags?name=rolling" target="_blank">Rolling</a> - Latest development version (unstable)</li>
128+
</ul>
129+
130+
<h2>Using Pre-built Images</h2>
131+
<p>Skip the build process entirely by using pre-built images. Simply pull the image for your desired ROS 2 distribution and run it. This is the fastest way to get started with YASMIN:</p>
132+
<pre><code class="language-bash">docker pull mgons/yasmin:humble
133+
docker run -it --net=host mgons/yasmin:humble</code></pre>
134+
135+
<p><strong>Tip:</strong> Replace <code>humble</code> with any supported ROS 2 distribution tag (foxy, galactic, iron, jazzy, kilted, or rolling) to use a different version.</p>
136+
137+
<h2>Notes</h2>
138+
<ul>
139+
<li>The <code>--net=host</code> flag allows the container to use the host's network stack.</li>
140+
<li>Display forwarding is configured with <code>DISPLAY</code> and X11 volume mounts for GUI applications.</li>
141+
<li>The <code>--privileged</code> flag gives extended privileges to the container (use with caution).</li>
142+
</ul>
143+
</main>
144+
</div>
145+
146+
<footer>
147+
<p>&copy; 2025 YASMIN Project. Licensed under GPL v3.0. | Documentation generated with <a href="doxygen.html" target="_blank">Doxygen</a></p>
148+
</footer>
149+
</body>
150+
</html>

0 commit comments

Comments
 (0)