The Duckietown Book (Duckiebook)

From kits of parts to an autonomous fleet
in 857 easy steps
without hiding anything

The last version of this "duckiebook" and other related documents are available at the URL
http://book.duckietown.org/

For searching, see the one-page version.

Duckietown classes

Duckietown is an international effort. Many educational institutions have adopted the platform and used to teach robotics and related subjects. If you have used Duckietown in any of your course and cannot find a mention to it here, contact us.

Here, we provide a chronologically ordered compendium of the Duckietown related learning experiences worldwide.

2016

Duckietown was created in 2016.

Massachusetts Institute of Technology

Location: United States of America, Cambridge, Massachusetts

Course title: 2.166 Vehicle Autonomy

Instructors: plenty

Time period:

Highlights: Role-playing experience (Duckietown Engineering Co.), public demo

Summary:

National Chiao Tung University

Location: Hsinchu, Taiwan

Course title: Robotic Vision

Instructors: Prof. Nick Wang

Time period:

Summary:

Highlights:

Tsinghua University

Location:

Course title:

Instructors:

Educational Level:

Time period:

Summary:

Highlights:

Rennselaer Polytechnic Institute

Location:

Course title:

Instructors:

Educational Level:

Time period:

Summary:

Highlights:

to write

to write

to write

Contributing to the documentation

Installing the documentation system

In the following, we are going to assume that the documentation system is installed in ~/duckuments. However, it can be installed anywhere.

We are also going to assume that you have setup a Github account with working public keys.

We are also going to assume that you have installed the duckietown/software in ~/duckietown.

Compiling the documentation (updated Sep 12)

Make sure you have deployed and activated the virtual environment. You can check this by checking which python is active:

$which python /home/user/duckuments/deploy/bin/python  To compile the master versions of the docs, run: $ make master-clean master


To see the result, open the file

./duckuments-dist/master/duckiebook/index.html


If you want to do incremental compilation, you can omit the clean and just use:

$make master  This will be faster. However, sometimes it might get confused. At that point, do make master-clean. Compiling the Fall 2017 version only (introduced Sep 12) To compile the Fall 2017 versions of the docs, run: $ make fall2017-clean fall2017


To see the result, open the file

./duckuments-dist/master/duckiebook/index.html


For incremental compilation, use:

$make fall2017  Single-file compilation There is also the option to compile one single file. To do this, use: $ ./compile-single path to .md file


This is the fastest way to see the results of the editing; however, there are limitations:

• no links to other sections will work.
• not all images might be found.

The workflow to edit documentation (updated Sep 12)

This is the basic workflow:

1. Create a branch called yourname-branch in the duckuments repository.
2. Edit the Markdown in the yourname-branch branch.
3. Run make master to make sure it compiles.
4. Commit the Markdown and push on the yourname-branch branch.
5. Create a pull request.
6. Tag the group duckietown/gardeners.

Create a pull request from the command-line using hub.

Basic Markduck guide

The Duckiebook is written in Markduck, a Markdown dialect.

It supports many features that make it possible to create publication-worthy materials.

Figures

For any element, adding an attribute called figure-id with value fig:figure ID or tab:table ID will create a figure that wraps the element.

For example:

<div figure-id="fig:figure ID">
figure content
</div>


It will create HMTL of the form:

<div id='fig:code-wrap' class='generated-figure-wrap'>
<figure id='fig:figure ID' class='generated-figure'>
<div>
figure content
</div>
</figure>
</div>


To add a caption, add an attribute figure-caption:

<div figure-id="fig:figure ID" figure-caption="This is my caption">
figure content
</div>


Alternatively, you can put anywhere an element figcaption with ID figure id:caption:

<element figure-id="fig:figure ID">
figure content
</element>

<figcaption id='fig:figure ID:caption'>
This the caption figure.
</figcaption>


To refer to the figure, use an empty link:

Please see [](#fig:figure ID).


The code will put a reference to “Figure XX”.

You give IDs to headers using the format:

### header title {#topic ID}


For example, for this subsection, we have used:

### Establishing names of headers {#establishing}


With this, we have given this header the ID “establishing”.

Naming
More than one element with id 'autoid-DO-NOT-USE-THIS-VERY-UNSTABLE-LINK-695fe-192:section'.

Special paragraphs and environments

Special paragraphs tags

The system supports parsing of some special paragraphs.

some of these might be redundant and will be eliminated. For now, I am documenting what is implemented.

Special paragraphs must be separated by a line

A special paragraph is marked by a special prefix. The list of special prefixes is given in the next section.

There must be an empty line before a special paragraph; this is because in Markdown a paragraph starts only after an empty line.

This is checked automatically, and the compilation will abort if the mistake is found.

For example, this is invalid:

See: this book
See: this other book


This is correct:

See: this book

See: this other book


Similarly, this is invalid:

Author: author
Maintainer: maintainer


and this is correct:

Author: author

Maintainer: maintainer


Other div environments

For these, note the rules:

• You must include markdown="1".
• There must be an empty line after the first div and before the closing /div.

Notes and questions

There are three environments: “comment”, “question”, “doubt”, that result in boxes that can be expanded by the user.

These are the one-paragraph forms:

Comment: this is a comment on one paragraph.

comment

this is a comment on one paragraph.

Question: this is a question on one paragraph.

question

this is a question on one paragraph.

Doubt: I have my doubts on one paragraph.

doubt

I have my doubts on one paragraph.

These are the multiple-paragraphs forms:

<div class='comment' markdown='1'>
A comment...

A second paragraph...
</div>

comment

A comment…

A second paragraph…

<div class='question' markdown='1'>
A question...

A second paragraph...
</div>

question

A question…

A second paragraph…

<div class='doubt' markdown='1'>
A question...

Should it not be:

$alternative command A second paragraph... </div>  doubt A question… Should it not be: $ alternative command


A second paragraph…

Using LaTeX constructs in documentation

Working knowledge of LaTeX.

LaTeX equations

We can refer to equations, such as \eqref{eq:one}:

$$2a = a + a \label{eq:one}\tag{1}$$

This uses align and contains \eqref{eq:two} and \eqref{eq:three}.

\begin{align} a &= b \label{eq:two}\tag{2} \\ &= c \label{eq:three}\tag{3} \end{align}

We can refer to equations, such as \eqref{eq:one}:

\begin{equation}
2a = a + a          \label{eq:one}
\end{equation}

This uses align and contains  \eqref{eq:two} and \eqref{eq:three}.

\begin{align}
a &= b       \label{eq:two} \\
&= c       \label{eq:three}
\end{align}


Note that referring to the equations is done using the syntax \eqref{eq:name}, rather than [](#eq:name).

Bibliography support

You need to have installed bibtex2html.

The system supports Bibtex files.

Place *.bib files anywhere in the directory.

Then you can refer to them using the syntax:

[](#bib:bibtex ID)


For example:

Please see [](#bib:siciliano07handbook).


Will result in:

Embedding Latex in Figures through SVG

In order to compile the figures into PDFs you need to have Inkscape installed. Instructions to download and install Inkscape are here.

To embed latex in your figures, you can add it directly to a file and save it as filename.svg file and save anywhere in the /docs directory.

You can run:

\$ make process-svg-figs


And the SVG file will be compiled into a PDF figure with the LaTeX commands properly interpreted.

You can then include the PDF file in a normal way (Section 2.5 - Figures) using filename.pdf as the filename in the <img> tag.

It can take a bit of work to get the positioning of the code to appear properly on the figure.

Embedding videos

It is possible to embed Vimeo videos in the documentation.

Do not upload the videos to your personal Vimeo account; they must all be posted to the Duckietown Engineering account.

This is the syntax:

<dtvideo src="vimeo:vimeo ID"/>


For example, this code:

<div figure-id="fig:example-embed">
<figcaption>Cool Duckietown by night</figcaption>
<dtvideo src="vimeo:152825632"/>
</div>


produces this result:

Depending on the output media, the result will change:

• On the online book, the result is that a player is embedded.
• On the e-book version, the result is that a thumbnail is produced, with a link to the video;
• On the dead-tree version, a thumbnail is produced with a QR code linking to the video (TODO).

move-here tag

If a file contains the tag move-here, the fragment pointed by the src attribute is moved at the place of the tag.

This is used for autogenerated documentation.

Syntax:

# Node node

<move-here src='#package-node-autogenerated'/>


The dependencies below are harder to install. If you don’t manage to do it, then you only lose the ability to compile the PDF. You can do make compile to compile the HTML version, but you cannot do make compile-pdf.

Markduck troubleshooting

Common mistakes with Markdown

Here are some common mistakes encountered.

Not properly starting a list

There must be an empty line before the list starts.

This is correct:

I want to learn:

- robotics
- computer vision


This is incorrect:

I want to learn:
- robotics
- computer vision


and it will be rendered as follows:

I want to learn: - robotics - computer vision - underwater basket weaving

The Duckuments bot

This is an advanced section mainly for Liam.

Documentation style guide

This chapter describes the conventions for writing the technical documentation.

Learning in Duckietown

Jacopo

This chapter is a draft.

We do not refer to teachers and students

We refer to learners. Instructors are learners ahead in the learning curve in comparison to other learners

We don’t examinate

We assess competences

The learning feedback loop

A relevant contribution of modern educational theory is recognizing the importance of feedback in the learning process ().

We love feedback, as it stands at the foundation of control systems theory.

Here, we provide definitions of the key elements in a learning feedback loop, and analogies to their control systems counterparts.

Intended Learning Outcomes

Intended Learning Outcome
An intended learning outcome is a desired, measurable, output of the learning process.

Intended learning outcomes are:

• the starting point in the construction of a learning activity ([1]),

• more effective when formulated with active verbs,

• the equivalent of reference trajectories, or setpoints, in control systems. They represent the ideal output of the controlled system.

Students will understand robotics

Students each build a Duckiebot, implement software and produce demos

Learning Activities

Learning Activities
Methods chosen by the instructor to ease the learners achievement of the intended learning outcomes.

Active learning practices ([1]) have been shown to improve learning.

Instructor explains at the blackboard

Learners work in groups to achieve objectives

Learning activities are analogous to the the output of the controller (instructor), or input to the system (learners). They have to meet the requirements imposed by external constraints, not shown in

Assessment

Assessment
An assessment is a procedure to quantify the level of fulfillment of learning outcomes.

An assessment is analogous to a sensor in a control system loop. It measures the system’s output.

Examples of assessments include: quizzes, colloquia, produced documentation, homework, etc.

Knowledge, Skills and Competences

Here, we provide definitions for knowledge, skills and competences, in addition to describing their relationships (Figure 10.2).

Knowledge

Knowledge
Theoretical facts and information aimed at enabling understanding, and generating or improving skills.

Bayesian inference is handy piece of knowledge when doing robotics.

Practice

Practice
Practical procedures aimed at generating or improving skills, either directly or indirectly by improving knowledge.

Exercises and proofs can be used to practice different skills.

Skills

Skills
A proficiency, facility or dexterity that enables carrying out a function. Skills stem from knowledge, practice and/or aptitude. Skills can be clustered in cognitive, technical and interpersonal, respectively relating to ideas, things and people.

Analyzing tradeoffs between performances and constraints is a critical cognitive skill for robotics.

Python language is a useful technical skill in robotics.

Public speaking is a valuable interpersonal skill useful beyond robotics.

In Duckietown we formalize didactic indivisible units, or atoms, aimed at improving skills through knowledge and practice. Knowledge atoms are listed in XXX. We define as practice atoms:

add general reference to all learning atmos, folder atoms_30_learning_material

Exercise
An exercise is a practice atom aimed at improving technical skills. Exercises are listed in XXX.

Exercises are targeted to different “things” to which technical skills are related. They may be mathematical exercises aimed at practicing a method, or they may be coding exercises aimed at practicing resolutions of hardware implementation challenges.

Proof
A proof is a practice atom aimed at improving cognitive skills.

Deriving the Kalman filter equations helps practice the idea that there is no better approach to state estimation for linear time invariant systems, with “well behaved” measurement and process noises.

Competences

Competences
Set of skills and/or knowledge that leads to superior performance in carrying out a function. Competences must be measurable.

Competences are desirable intended learning outcomes, and typically address the how of the learning process.

Programming is a competence. It requires a skill, e.g., Python, and knowledge, e.g., Bayesian inference, to know what to code. Practice can help improve knowledge or hone skills.

Knowledge graph

This chapter describes something that is not implemented yet.

Markdown format for text-like atoms

For the text-like resources, they are described in Markdown files.

The name of the file does not matter.

All files are encoded in UTF-8.

Each file starts with a H1 header. The contents is the title.

The header has the following attributes:

1. The ID. ({#ID})
2. The status is given by an attribute status, which should be value of the values in Table 11.1.
3. (Optional) The language is given by an attribute lang ({lang=en-US}).
4. (Optional) The type is given by an attribute type ({type=demo}).

Here is an example of a header with all the attributes:

And this is how the Italian translation would look like:

Translations

This part is not implemented yet.

Operation manual - Duckiebot

In this section you will find information to obtain the necessary equipment for Duckietowns and different Duckiebot configurations.

Duckiebot configurations

nothing

Knowledge of Duckiebot configuration naming conventions, their components and functionalities.

After reviewing the configurations, you can proceed to purchasing the components, reading a description of the components, or assembling your chosen configuration.

We define different Duckiebot configurations depending on their time of use and hardware components. This is a good starting point if you are wondering what parts you should obtain to get started.

Branch configuration releases: Fall 2017

All branches release their hardware in two phases, namely a and b.

Soldering boards (DB17)

Shiying

Parts: Duckiebot DB17 parts. The acquisition process is explained in Unit C-2 - Acquiring the parts (DB17-jwd). The configurations are described in Unit C-1 - Duckiebot configurations. In particular:

Tools: Solderer

Experience: some novice-level experience with soldering.

Time: 30 minutes

Soldered DC Motor HAT

It is better to be safe than sorry. Soldering is a potentially hazardous activity. There is a fire hazard as well as the risk of inhaling toxic fumes. Stop a second and make sure you are addressing the safety standards for soldering when following these instructions. If you have never soldered before, seek advice.

Preparing the power cable (DB17)

In configuration DB17 we will need a cable to power the DC motor HAT from the battery. The keen observer might have noticed that such a cable was not included in the DB17 Duckiebot parts chapter. Here, we create this cable by splitting open any USB-A cable, identifying and stripping the power wires, and using them to power the DC motor HAT. If you are unsure about the definitions of the different Duckiebot configurations, read Unit C-1 - Duckiebot configurations.

It is important to note that these instructions are relevant only for assembling a DB17-wjdc configuration Duckiebot (or any subset of it). If you intend to build a DB17-l configuration Duckiebot, you can skip these instructions.

One male USB-A to anything cable.

A pair of scissors.

A multimeter (only if you are not purchasing the suggested components)

Time: 5 minutes

One male USB-A to wires power cable