Because of mathjax bug

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.

Table of contents

🔗
Because of mathjax bug
Because of mathjax bug

The Duckietown project

🔗

What is Duckietown?

🔗

Duckietown history and future

🔗

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.

add contact email

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

Educational Level: Graduate

Time period:

Link:

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

Summary:

Duckietown at MIT in 2016

National Chiao Tung University

🔗

Location: Hsinchu, Taiwan

Course title: Robotic Vision

Instructors: Prof. Nick Wang

Educational Level: Graduate

Time period:

Link:

Summary:

Highlights:

Tsinghua University

🔗

Location:

Course title:

Instructors:

Educational Level:

Time period:

Link:

Summary:

Highlights:

Rennselaer Polytechnic Institute

🔗

Location:

Course title:

Instructors:

Educational Level:

Time period:

Link:

Summary:

Highlights:

First steps

🔗

Duckietown for instructors

🔗

to write

Duckietown for self-guided learners

🔗

to write

Introduction for companies

🔗

to write

Frequently Asked Questions

🔗

Duckumentation documentation

🔗
Because of mathjax bug

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”.

Linking to documentation

🔗

Establishing names of headers

🔗

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”.

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…

Because of mathjax bug

Using LaTeX constructs in documentation

🔗

Working knowledge of LaTeX.

LaTeX equations

🔗

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

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

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:

Please see [3].

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.

Image saved as svg
Image as PDF after processing
Embedding LaTeX in images

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

Because of mathjax bug

Advanced Markduck guide

🔗

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:

The video is at https://vimeo.com/152825632.

Cool Duckietown by night

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'/>

*Compiling the PDF version

🔗

This part describes how to compile the PDF version.

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
- underwater basket weaving

This is incorrect:

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

and it will be rendered as follows:

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

Because of mathjax bug

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.

The learning loop.

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).

The relationship between Knowledge, Skills and Competences.

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.

Because of mathjax bug

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:

# Odometry calibration {#odometry-calibration lang=en-US type='text/theory' status=ready}

This first paragraph will be used as the "summary" for this text.
calibration.en.md

And this is how the Italian translation would look like:

# Calibrazione dell'odometria {#odometry-calibration lang=it type='text/theory' status=draft}

Questo paragrafo sarà usato come un sommario del testo.
calibration.it.md

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.

Because of mathjax bug

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

Assembling the Duckiebot (DB17-jwd)

🔗

Shiying Li

Once you have received the parts and soldered the necessary components, it is time to assemble them in a Duckiebot. Here, we provide the assembly instructions for configurations DB17-wjd.

Duckiebot DB17-wjd parts. The acquisition process is explained in Unit C-2 - Acquiring the parts (DB17-jwd).

Having soldered the DB17-wjd parts. The soldering process is explained in Unit C-3 - Soldering boards (DB17).

Having prepared the power cable. The power cable preparation is explained in Unit C-4 - Preparing the power cable (DB17). Note: Not necessary if you intend to build a DB17-l configuration.

Having installed the image on the MicroSD card. The instructions on how to reproduce the Duckiebot system image are in Unit C-7 - Reproducing the image.

Time: about 40 minutes.

An assembled Duckiebot in configuration DB17-wjd.

The FAQ section at the bottom of this page may already answer some of you comments, questions or doubts.

While assembling the Duckiebot, try to make as symmetric (along the longitudinal axis) as you can. It will help going forward.