In the Poppy Project, we are huge fans of Jupyter Notebooks both for development and for documentation. Most of our tests, benchs, experiments, and even debugs are now done using notebooks. Thus, we have decided that pypot's documentation and more generally all the software documentation related to the Poppy Project will smoothly move towards notebooks.
We strongly believe that they have an amazing potential:
- for writing pedalogical contents - by mixing code, explanation, results in an integrated form
- for easily sharing - they can be easily review online and then run locally
- they can also be run remotely on the robot and thus no installation at all is required on the client side, you just need a web browser
We already have written a few tutorial notebooks that you can browse here: https://poppy-project.gitbooks.io/poppy-docs/content/en/programming/notebooks.html
Other notebooks should shorty extend this list!
In the next sections, we decribe how those notebooks can be viewed, installed, run on your robot or locally, shared and how you can contribute by writting your own notebooks!
All the resources content from the Poppy Project is open source. This naturally also extends to the notebooks.
License | Notebooks | Library |
---|---|---|
Name | Creatives Commons BY-SA | GPL v3 |
Logo |
One of the great features of the Notebook is that they can be read directly online without needing to install anything on your laptop. The only thing you need is a web browser!
Thanks to the nbviewer website, you can read any Notebook online. You can also directly view them on Github. The Notebooks from the Poppy Project can be directly found here. A list of the "best" Notebook is also maintained here.
If you want to run notebooks yourself and play with the code you will have to use one of the other techniques described below.
The Poppy Creature we developed are usually provided with an embedded board (e.g. a raspberry pi) with all the software tools needed to run pypot already installed - this means a python interpreter, the pypot and poppy pacakges and Jupyter Notebook server. Thus, you do not need to install anything specific on your personal computer to connect to a remote Notebook.
When plugged, the embedded board of the Poppy Creature should automatically start a Jupyter Notebook server providing access to all the notebooks tutorials.
Assuming that you creature is connected to the same network as your computer (see here for details), they can be accessed just by connecting to an url such as: http://poppy.local.
It's important to note here that the notebook will actually run on the embedded board and not on your local machine! You will thus not be able to easily access a file on your machine using this approach. Similarly, if you need to install an extra python package, you will have to install it directly on the board (e.g. using an ssh connection).
If you want to run Notebooks on your local machine, because you are working with the simulator for instance, you will have to start the jupyter notebook server yourself.
To do this, you will need to find your way in the sometimes confusing python packaging system. In details, you will need (this is not the only way to install all the tools but this is probably the most straightforward):
- a python interpreter (we tested with 2.7, 3.4 or pypy-2.5) see how to install it on your os on python website. You can use pre-packaged Python distribution such as Anaconda or Spyder.
- the pip tool for installing Python packages - this documentation describe how to install pip on your system.
Now that you have a working Python environment, you can install the Jupyter Notebook package using pip (or conda). You only have to run the following line on a command line terminal:
pip install jupyter
Linux users may have to run (depending on their python installation):
sudo pip install jupyter
Then, you need to install pypot and the software for your creature. For instance, to use a PoppyErgoJr:
pip install pypot poppy-ergo-jr
Finally, you can now run the notebook server from a terminal:
jupyter notebook
You can also specify the folder where your notebooks are, for instance on my machine
jupyter notebook ~/dev/pypot/samples/notebooks/
The Poppy forum is the best place to ask for help! You can also use the github issue tracker for specific notebooks issues.
First, please report any bug or issue to our github issue tracker.
Second, you can discuss, suggest, or even better provide us with other Notebooks. We hope to gather as many and as diversified Notebooks as possible. They could be pedagogical content, experiments or just funny behaviours for robotic creatures. The easiest way to share them with us is trough pull requests.
Finally, as we are not native English speaker your encouraged to report any spell checking or any sentence which does not make much sense ^^. Translation to other language are also welcomed!