=Paper=
{{Paper
|id=Vol-2329/paper-01
|storemode=property
|title=Interactive ROS Tutorials with Jupyter Notebooks
|pdfUrl=https://ceur-ws.org/Vol-2329/paper-01.pdf
|volume=Vol-2329
|authors=Enric Cervera
|dblpUrl=https://dblp.org/rec/conf/erf/Cervera18
}}
==Interactive ROS Tutorials with Jupyter Notebooks==
https://ceur-ws.org/Vol-2329/paper-01.pdf
Interactive ROS Tutorials
with Jupyter Notebooks
Enric Cervera?
Robotic Intelligence Lab
Universitat Jaume-I de Castelló, Spain,
ecervera@uji.es
Abstract. Collaboration is a major strength of ROS, as it was designed
specifically for groups with different expertise (mapping, navigation, vi-
sion, etc) to collaborate and build upon each other’s work. The ROS Wiki
is such an example,1 with the official documentation for ROS packages,
as provided by their developers, and every user has dived into its ROS
tutorials for learning the basic concepts. Those tutorials consist of web
pages with embedded examples of source code that the user can run in
a separate terminal. We aim to transform the static tutorials into inter-
active documents where the user not only reads but also runs the code
inside the same web browser, by using Jupyter Notebook technology.2
Our goal is to make the tutorials more concise and effective, avoiding the
tedious and error-prone copying-and-pasting of code. Also, the integra-
tion of execution results provides the user with step-by-step feedback,
for a more illuminating learning experience.
Keywords: tutorial, interaction, literate computing
1 Introduction
The ROS Tutorials are the primary source of information for learning ROS.
They consist of a collection of web pages about the installation and setup of
the system, the core concepts, and the development of robot applications in the
programming languages C++ or Python.
Each web page presents a specific issue, combining an informative description
interleaved with snippets of code or commands. The code must be first copied
and pasted into an editor, then run in a terminal. The commands can be copy-
pasted directly into the terminal, and executed. Such a workflow requires several
views simultaneously:
– Documentation (teaching materials)
– Edition of the source code
?
ORCID id: 0000-0002-5386-8968. The views and opinions expressed in this article
are those of the author, not affiliated with any of the projects mentioned.
1
http://wiki.ros.org/
2
http://jupyter.org/
TRROS 2018 – European Robotics Forum 2018 Workshop “Teaching Robotics with ROS”
TRROS 2018
(Edited by S. –Schiffer,
European A. Robotics Forum
Ferrein, M. 2018 Workshop
Bharatheesha, “Teaching
and C. Robotics
Hernández with ROS”
Corbato) 11
(Edited by S. Schiffer, A. Ferrein, M. Bharatheesha, and C. Hernández Corbato)
– Execution and monitoring of results
For a proper management of these views, several windows are needed in the
user desktop. A typical layout is shown in Fig. 1, with the browser window at
the left, displaying the documentation, the editor window at the top right, and
the terminal window for execution at the bottom right.
Fig. 1. Desktop layout: left window is the browser with the documentation web page;
top-right is the editor window with the source code; bottom-right is the terminal win-
dow for the execution of the program.
There are some disadvantages in this arrangement, the most obvious one is
the duplication of code: the programming statements are shown in the documen-
tation, then they need to be copied into the development editor. In fact, some
tutorials feature two versions of the same code, a complete one for easy copying
and pasting, and a step-by-step version for the explanations.
In addition, the execution of the code takes place in a third window (the
console), losing the context of the source code. Moreover, the complete program
is run, making it difficult to execute the statements step-by-step, as opposed to
the explanations in the tutorial.
Jupyter notebooks provide an integrated environment for the execution of
code statements, interleaved in the same web pages of documentation. The code
can be executed in cells, or snippets of code with a few statements, and the
results are displayed below the same cell of code. Code cells can be edited and
run freely by the user, interactively. As a result, a single window combines the
three necessary views (teaching materials, edition, execution), as shown in Fig. 2.
TRROS 2018 – European Robotics Forum 2018 Workshop “Teaching Robotics with ROS”
TRROS 2018
(Edited by S. –Schiffer,
European A. Robotics Forum
Ferrein, M. 2018 Workshop
Bharatheesha, “Teaching
and C. Robotics
Hernández with ROS”
Corbato) 22
(Edited by S. Schiffer, A. Ferrein, M. Bharatheesha, and C. Hernández Corbato)
Fig. 2. Interactive ROS Tutorial on a Jupyter notebook: the teaching materials, source
code, and execution results are all presented together in the browser window.
TRROS 2018 – European Robotics Forum 2018 Workshop “Teaching Robotics with ROS”
TRROS 2018
(Edited by S. –Schiffer,
European A. Robotics Forum
Ferrein, M. 2018 Workshop
Bharatheesha, “Teaching
and C. Robotics
Hernández with ROS”
Corbato) 33
(Edited by S. Schiffer, A. Ferrein, M. Bharatheesha, and C. Hernández Corbato)
This paper describes how jupyter notebooks work (Section 2), how ROS and
its tutorials can be integrated in the workflow (Section 3), and a couple of ex-
amples of representative tutorials regarding ROS topics and services (Section 4).
Finally, Section 5 draws some conclusions and outlines the work in progress.
2 Jupyter Notebooks
The Jupyter Notebook is an interactive computing environment that extends the
console-based approach in a new direction: it provides a web-based application
suitable for capturing the whole computation process of developing, document-
ing, and executing code. Its roots lie in the Interactive Python environment [5],
and the ideas behind the proprietary-based Mathematica Notebook environment
[12].
Jupyter Notebooks are experiencing an immense success in recent years, ap-
plied to education and research [7] in a number of disciplines like computer
vision, machine learning, or even the analysis of gravitational wave data [9].
Jupyter implements a ”literate computing” scheme [4], inspired in the ”lit-
erate programming” paradigm [3], a software development style pioneered by
Stanford computer scientist, Donald Knuth, that emphasizes an approach where
exposition with human-friendly text is punctuated with code blocks. Such an ap-
proach seems more adequate for demonstration, teaching and research purposes,
especially for science and technology.
Fig. 3. Jupyter notebook elements.
As a server-client application, there are several processes involved in the user
interaction, as seen in Fig. 3. The kernel is the separate process that actually runs
the code. The notebook server stores code and output, together with markdown
notes (a lightweight markup language that can be converted to HTML), in an
editable document called a notebook. The user interacts with the browser, which
TRROS 2018 – European Robotics Forum 2018 Workshop “Teaching Robotics with ROS”
TRROS 2018
(Edited by S. –Schiffer,
European A. Robotics Forum
Ferrein, M. 2018 Workshop
Bharatheesha, “Teaching
and C. Robotics
Hernández with ROS”
Corbato) 44
(Edited by S. Schiffer, A. Ferrein, M. Bharatheesha, and C. Hernández Corbato)
is connected to the notebook server for rendering notebooks, and sending user
input to the kernel.
There are kernels available for many languages, starting from Julia, Python
and R (the original languages Jupyter was developed for —hence the acronym)
but also to other compiled languages like Java or C++.
3 Integration of Jupyter and ROS
Jupyter notebooks are being used in robotic Internet sites such The Construct
[8], which also integrates 3D simulations with Gazebo. In our approach we will
only focus on the programming task.
ROS development is mainly based on the languages C++ and Python. The
former is perhaps the most widely used client library, and it is designed for high
performance. The latter provides the advantages of an object-oriented scripting
language: it favors implementation speed so that algorithms can be quickly pro-
totyped and tested. Python is a core dependency of ROS, since some tools are
developed in that language.
3.1 Local Install
Jupyter can be easily installed using Python’s package manager,3 or third-party
distributions like Anaconda.4 Once installed, it is launched from the terminal,
where the server keeps running in the background. At the same time, a new
browser window opens and displays the notebook folder, or a specific notebook.
The user can then interact with the notebook, with an environment similar
to that of the console, i.e. all the C++ or Python libraries are accessible as in
any ROS application. Practical examples of tutorials will be shown in Section 4.
Obviously, ROS is a prerequisite that should be available in the system, either
in a local installation or as a Docker image.5
3.2 Notebooks in the Cloud
Since Jupyter Notebooks use a client/server approach, it is possible to run the
server in a different computer than the client. Both machines surely must be
connected, but the connection protocol (http - the WWW protocol) makes it
possible to run the server in any computer connected to Internet.
Free cloud services for IPython and Jupyter already exist, where their basic
functionality can be tested.6
A recent and interesting initiative is Binder,7 which not only enables shar-
ing of live notebooks in a computational environment, but authors can publish
3
https://packaging.python.org/tutorials/installing-packages/
4
https://www.anaconda.com/
5
http://wiki.ros.org/docker/
6
https://try.jupyter.org/
7
https://mybinder.org/
TRROS 2018 – European Robotics Forum 2018 Workshop “Teaching Robotics with ROS”
TRROS 2018
(Edited by S. –Schiffer,
European A. Robotics Forum
Ferrein, M. 2018 Workshop
Bharatheesha, “Teaching
and C. Robotics
Hernández with ROS”
Corbato) 55
(Edited by S. Schiffer, A. Ferrein, M. Bharatheesha, and C. Hernández Corbato)
notebooks in a source code repository along with an environment specification.
By pointing the Binder web service at the repository, a temporary environment
is automatically created with the notebooks and any libraries and data required
to run them. This allows authors to publish their code in an interactive and
immediately verifiable form [2].
An environment specification for ROS can be created based on the ROS
docker images.8 These images provide a simplified and consistent platform to
build and deploy applications, with an easy way to develop, reuse and ship
software [11].
We have upgraded the ROS docker images with the necessary packages for
running Jupyter along ROS, so that the example tutorials presented in the next
section are stored in a GitHub repository that can be run either in a local
environment, or in the cloud using the Binder service.9
4 Tutorial Examples
For demonstration purposes, we have adapted the tutorials for some of the most
fundamental concepts in ROS: topics and services [6]. Topics are named buses
over which nodes exchange messages. They have anonymous publish / subscribe
semantics: nodes that are interested in data subscribe to the relevant topic;
nodes that generate data publish to the relevant topic. There can be multiple
publishers and subscribers to a topic.
The publish / subscribe model is a very flexible communication paradigm,
but its many-to-many one-way transport is not appropriate for request / reply
interactions. For that purpose, ROS features another paradigm called Service,
which is defined by a pair of messages: one for the request and one for the
reply. A providing ROS node offers a service under a string name, and a client
calls the service by sending the request message and awaiting the reply. Client
libraries usually present this interaction to the programmer as if it were a remote
procedure call.
We have developed the Jupyter Notebook versions of the ROS tutorials for
writing a simple publisher and subscriber of topics, and a simple service and
client. The primary programming language is Python, but a working example in
C++ will also be presented.
4.1 Writing a Simple Publisher and Subscriber
This tutorial consists of one section for the publisher node, and another section
for the subscriber node.10 Each section is divided into two sub-sections, a first
part with the code, and a second one with the ”code explained”. This last part
consists of the code split into chunks of a few lines, followed by paragraphs of
description about each code fragment.
8
https://hub.docker.com/ /ros/
9
https://github.com/RobInLabUJI/ROS-Tutorials
10
http://wiki.ros.org/ROS/Tutorials/WritingServiceClient(python)
TRROS 2018 – European Robotics Forum 2018 Workshop “Teaching Robotics with ROS”
TRROS 2018
(Edited by S. –Schiffer,
European A. Robotics Forum
Ferrein, M. 2018 Workshop
Bharatheesha, “Teaching
and C. Robotics
Hernández with ROS”
Corbato) 66
(Edited by S. Schiffer, A. Ferrein, M. Bharatheesha, and C. Hernández Corbato)
We first divide the materials into two notebooks, for the publisher and the
subscriber. The first section is not necessary, since the code in the ”explanatory”
section can be readily executed in the notebook. So this second section is trans-
ferred to the notebook by simply moving the source code into ”code cells” and
the description into the ”markdown cells” (Fig. 4).
Fig. 4. Adapting the ROS Topics tutorial webpage (left) to a Jupyter Notebook (right).
The source code is transferred to code cells, and the explanatory text is copied into
markdown cells. The layout remains very similar, and the links are kept.
Some additional simplifications apply: the initial declaration for Python scripts
is not necessary, since the Jupyter environment is already running a Python ker-
nel. For the same reason, it is not necessary to add the lines of code for checking
that a ”main” application is running. One should keep in mind that for the code
to be re-useable in another execution environment, the full source code should
be used.
The subscriber code is adapted in a similar way. The resulting document has
fewer lines than the original, since there is no duplicated code, and some unnec-
essary statements have been removed. In addition, it can be readily executed
from the same browser, without need to launch the script in a console terminal
(Fig. 5).
4.2 Writing a Simple Service and Client
The structure of this tutorial is similar to the previous one.11 Again, the tutorial
is split into two notebooks, for the service and client respectively. Each note-
book consists of the contents of the section ”code explained”, either as code or
markdown cells.
The code can be readily executed on each notebook in parallel, and the results
of the remote call are shown in both notebooks too (Fig. 6).
11
http://wiki.ros.org/ROS/Tutorials/WritingServiceClient(python)
TRROS 2018 – European Robotics Forum 2018 Workshop “Teaching Robotics with ROS”
TRROS 2018
(Edited by S. –Schiffer,
European A. Robotics Forum
Ferrein, M. 2018 Workshop
Bharatheesha, “Teaching
and C. Robotics
Hernández with ROS”
Corbato) 77
(Edited by S. Schiffer, A. Ferrein, M. Bharatheesha, and C. Hernández Corbato)
Fig. 5. Published and subscriber code running in Jupyter notebooks. The output of
each node is displayed in the corresponding notebook.
Fig. 6. Service and client code running in Jupyter notebooks. The output of each node
is displayed in the corresponding notebook.
TRROS 2018 – European Robotics Forum 2018 Workshop “Teaching Robotics with ROS”
TRROS 2018
(Edited by S. –Schiffer,
European A. Robotics Forum
Ferrein, M. 2018 Workshop
Bharatheesha, “Teaching
and C. Robotics
Hernández with ROS”
Corbato) 88
(Edited by S. Schiffer, A. Ferrein, M. Bharatheesha, and C. Hernández Corbato)
4.3 Adapting Tutorials in C++
Though Jupyter has evolved from IPython, much effort has been devoted to
the separation between the kernel running the code, and the notebook frontend.
Nowadays, more than 40 different kernels are available, each for a huge variety
of programming languages.12
One of such kernels is based on Cling, an interactive C++ Interpreter [10]
developed within ROOT, a framework for data processing created at CERN [1].
We have also adapted the C++ versions of the topics and services tutorials
to jupyter notebooks. Similar to Python, slight changes are needed: the main
function is removed, since the code is run interactively step-by-step; blocks of
code cannot be split across cells, e.g. loops or if-else constructs. Care must be
taken with the declarations, since any second run raises an error. The solution
is to restart the kernel, which eliminates all declared variables for a fresh start.
The results of a C++ notebook for the tutorial on ROS services is shown in
Fig. 7. These results are coming from a local install, since at this moment the
Binder version of the tutorial only features the Python kernel.
Fig. 7. Service and client C++ code running in Jupyter notebooks.
5 Conclusions and Future Work
Jupyter notebooks bring new live to ROS tutorials; instead of copying-and-
pasting code and running it in a terminal console, the code is interleaved in
12
https://github.com/jupyter/jupyter/wiki/Jupyter-kernels
TRROS 2018 – European Robotics Forum 2018 Workshop “Teaching Robotics with ROS”
TRROS 2018
(Edited by S. –Schiffer,
European A. Robotics Forum
Ferrein, M. 2018 Workshop
Bharatheesha, “Teaching
and C. Robotics
Hernández with ROS”
Corbato) 99
(Edited by S. Schiffer, A. Ferrein, M. Bharatheesha, and C. Hernández Corbato)
the same tutorial, where it can be run, and its output is displayed in context.
Tutorials become more concise, and the user workflow is greatly simplified, thus
enhancing the learning process.
Jupyter is an open-source, cross-platform project that has become enor-
mously popular in the recent years. A variety of programming languages is sup-
ported, including C++ and Python, the most widely-used languages in ROS. In
future extensions, we plan to test languages like Lisp, Go, Haskell, Java, Node.js,
Julia, and Ruby: all of them are available both in Jupyter kernels and ROS client
libraries.13 14
The notebook platform is easily installed in a local computer alongside with
ROS, or it can be deployed in a cloud server. The Binder web service allows
any author to publish a tutorial in a public web repository that becomes live
instantly, allowing other users to try ROS without even installing it in their
computers.
Though the adaptation of existing tutorials to interactive notebooks can be
time-consuming, as it is done manually by now, we encourage the ROS commu-
nity to use these tools for the development of new materials, since teaching of
robotics and ROS can greatly benefit from them.
In the future, we plan to evaluate groups of students for quantitative measure-
ments of the user proficiency in comparison with the classical tutorial approach.
Acknowledgments
Support of IEEE RAS through the CEMRA program (Creation of Educational
Material for Robotics and Automation) is gratefully acknowledged. This paper
describes research done at the Robotic Intelligence Laboratory. Support for this
laboratory is provided in part by Ministerio de Economia y Competitividad
(DPI2015-69041-R), by Generalitat Valenciana (PROMETEOII/2014/028) and
by Universitat Jaume I (P1-1B2014-52).
References
1. Antcheva, I., Ballintijn, M., Bellenot, B., Biskup, M., Brun, R., Buncic, N., Canal,
P., Casadei, D., Couet, O., Fine, V., et al.: Root—a c++ framework for petabyte
data storage, statistical analysis and visualization. Computer Physics Communi-
cations 182(6), 1384–1385 (2011)
2. Kluyver, T., Ragan-Kelley, B., Pérez, F., Granger, B.E., Bussonnier, M., Frederic,
J., Kelley, K., Hamrick, J.B., Grout, J., Corlay, S., et al.: Jupyter notebooks-
a publishing format for reproducible computational workflows. In: F. Loizides,
B. Schmidt (eds.) Positioning and Power in Academic Publishing: Players, Agents
and Agendas, pp. 87–90 (2016)
3. Knuth, D.E.: Literate programming. CSLI Lecture Notes, Stanford, CA: Center
for the Study of Language and Information (CSLI), 1992 (1992)
13
https://github.com/jupyter/jupyter/wiki/Jupyter-kernels
14
http://wiki.ros.org/Client%20Libraries
TRROS 2018 – European Robotics Forum 2018 Workshop “Teaching Robotics with ROS”
TRROS 2018
(Edited by S. –Schiffer,
European A. Robotics Forum
Ferrein, M. 2018 Workshop
Bharatheesha, “Teaching
and C. Robotics
Hernández with ROS”
Corbato) 10
10
(Edited by S. Schiffer, A. Ferrein, M. Bharatheesha, and C. Hernández Corbato)
4. Millman, K.J., Pérez, F., Stodden, V., Leisch, F., Peng, R.: Developing open-source
scientific practice. Implementing Reproducible Research 149 (2014)
5. Pérez, F., Granger, B.E.: Ipython: a system for interactive scientific computing.
Computing in Science & Engineering 9(3) (2007)
6. Quigley, M., Conley, K., Gerkey, B., Faust, J., Foote, T., Leibs, J., Wheeler, R.,
Ng, A.Y.: Ros: an open-source robot operating system. In: ICRA workshop on
open source software, vol. 3, p. 5. Kobe, Japan (2009)
7. Shen, H.: Interactive notebooks: Sharing the code. Nature News 515(7525), 151
(2014)
8. Tellez, R.: A thousand robots for each student: Using cloud robot simulations to
teach robotics. In: M. Merdan, W. Lepuschitz, G. Koppensteiner, R. Balogh (eds.)
Robotics in Education, pp. 143–155. Springer International Publishing, Cham
(2017)
9. Vallisneri, M., Kanner, J., Williams, R., Weinstein, A., Stephens, B.: The ligo open
science center. In: Journal of Physics: Conference Series, vol. 610, p. 012021. IOP
Publishing (2015)
10. Vasilev, V., Canal, P., Naumann, A., Russo, P.: Cling–the new interactive inter-
preter for root 6. In: Journal of Physics: Conference Series, vol. 396, p. 052071.
IOP Publishing (2012)
11. White, R., Christensen, H.: Ros and docker. In: Robot Operating System (ROS),
pp. 285–307. Springer (2017)
12. Wolfram, S.: Mathematica: a system for doing mathematics by computer. Addison-
Wesley (1991)
TRROS 2018 – European Robotics Forum 2018 Workshop “Teaching Robotics with ROS”
TRROS 2018
(Edited by S. –Schiffer,
European A. Robotics Forum
Ferrein, M. 2018 Workshop
Bharatheesha, “Teaching
and C. Robotics
Hernández with ROS”
Corbato) 11
11
(Edited by S. Schiffer, A. Ferrein, M. Bharatheesha, and C. Hernández Corbato)