# Fall 2017

Welcome to the Fall 2017 Duckietown experience.

# The Fall 2017 Duckietown experience

This is the first time that a class is taught jointly across 3 continents!

There are 4 universities involved in the joint teaching for the term:

• ETH Zürich (ETHZ), with instructors Emilio Frazzoli, Andrea Censi, Jacopo Tani.
• University of Montreal (UdeM), with instructor Liam Paull.
• TTI-Chicago (TTIC), with instructor Matthew Walter.
• National Chiao Tung University (NCTU), with instructor Nick Wang.

This part of the Duckiebook describes all the information that is needed by the students of the four institutions.

At ETHZ, UdeM, TTIC, the class will be more-or-less synchronized. The materials are the same; there is some slight variation in the ordering.

Moreover, there will be some common groups for the projects.

The NCTU class is undergraduate level. Students will learn slightly simplified materials. They will not collaborate directly with the other classes.

# First Steps in Duckietown

## Onboarding Procedure

Welcome aboard! We are so happy you are joining us at Duckietown!

If you do not follow the steps in order, you will suffer from unnecessary confusion.

Please use your full name when it asks you. Ideally, the username should be something like FirstLast or something that resembles your name.

When you sign up, use your university email. This allows to claim an educational discount that will be useful later.

# Logistics for Zürich branch

This section describes information specific to Zürich.

These are the local TAs:

• Shiying Li (shili@student.ethz.ch)
• Ercan Selçuk (ercans@student.ethz.ch)
• Miguel de la Iglesia Valls (dmiguel@student.ethz.ch)
• Harshit Khurana (hkhurana@student.ethz.ch)
• Dzenan Lapandic (ldzenan@student.ethz.ch)
• Marco Erni (merni@ethz.ch)

Also feel free to contact the TAs in Montreal and Chicago.

# Logistics for Montréal branch

This unit contains all necessary info specific for students at Univeristé de Montréal.

# Logistics for Chicago branch

Matt

This section describes information specific to TTIC and UChicago students.

The course website provides a copy of the syllabus, grading information, and details on learning objectives.

Classes take place on Mondays and Wednesdays from 9am-11am in TTIC Room 530. In practice, each class will be divided into an initial lecture period (approximately one hour), followed by a lab session.

The class schedule is maintained as part of the TTIC Class Diary, which includes details on lecture topics, links to slides, etc.

The following is taken from the course syllabus:

The class will assess your grasp of the material through a combination of problem sets, exams, and a final project. The contribution of each to your overall grade is as follows:

• 20%: Problem sets
• 10%: Checkoffs
• 20%: Participation
• 50%: Final project (includes report and presentation). The projects will be group-based, but we will assess the contribution of each student individually.

See the course syllabus for more information on how the participation and final project grades are determined.

The following is taken from the course syllabus:

Late problem sets will be penalized 10% for each day that they are late. Those submitted more than three days beyond their due date will receive no credit.

Each student has a budget of three days that they can use to avoid late penalties. It is up to the student to decide when/how they use these days (i.e., all at once or individually). Students must identify whether and how many days they use when they submit an assignment.

It is not acceptable to use code or solutions from outside class (including those found online), unless the resources are specifically suggested as part of the problem set.

You are encouraged to collaborate through study groups and to discuss problem sets and the project in person and over Slack. However, you must acknowledge who you worked with on each problem set. You must write up and implement your own solutions and are not allowed to duplicate efforts. The correct approach is to discuss solution strategies, credit your collaborator, and write your solutions individually. Solutions that are too similar will be penalized.

Duckietown labs will take place at TTIC in the robotics lab on the 4th floor.

Note: TTIC and U. Chicago students in Matthew Walter’s research group use the lab as their exclusive research and office space. It also houses several robots and hardware to support them. Please respect the space when you use it: try not to distract lab members while they are working and please don’t touch the robots, sensors, or tools.

Duckietown is a collaborative effort involving close interaction among students, TAs, mentors, and faculty across several institutions. The local learning assistants (LAs) at TTIC are:

• Andrea F. Daniele (afdaniele@ttic.edu)
• Falcon Dai (dai@ttic.edu)
• Jon Michaux (jmichaux@ttic.edu)

# Logistics for NCTU branch

Nick and Eric (Nick’s student)

This section describes information specific to NCTU students.

The Duckietown Taiwan Branch Website provides some details about Duckietown Branch in NCTU-Taiwan and results of previous class in NCTU.

Classes take place on Thursday from 1:20pm~4:20om in NCTU Engineering Building 5 Room 635. Each class will be devided into two sessoins. In the first session, Professor Wang will give lessons on foundamental theory and inspire students to come up more creatitive but useful ideas on final projects. In the second sessoin, TAs will give pratical lab on how to use Duckietown platform as their project platform and use ROS as their middleware toward a fantastic work.

The class schedule is maintained as part of the NCTU Class Diary, which includes details on lecture topics, links to slides, etc.

The following is taken from the course syllabus:

This course aims at developing software projects usable in real-world, and focuses on “learning by doing,” “team work,” and “research/startup oriented.”. The contribution of each to your overall grade is as follows:

• Class Participation, In Class Quiz, Problem Sets (10%)
• Midterm Presentation (30%)
• Final Presentation (30%)
• Project Report and Demo Video (30%)

The following is taken from the course syllabus:

Late problem sets will be penalized 10% for each day that they are late. Those submitted more than three days beyond their due date will receive no credit.

Each student has a budget of three days that they can use to avoid late penalties. It is up to the student to decide when/how they use these days (i.e., all at once or individually). Students must identify whether and how many days they use when they submit an assignment.

It is not acceptable to use code or solutions from outside class (including those found online), unless the resources are specifically suggested as part of the problem set.

You are encouraged to collaborate through study groups and to discuss problem sets and the project in person and over Slack. However, you must acknowledge who you worked with on each problem set. You must write up and implement your own solutions and are not allowed to duplicate efforts. The correct approach is to discuss solution strategies, credit your collaborator, and write your solutions individually. Solutions that are too similar will be penalized.

Duckietown labs will take place at NCTU in the same place with the lecture.

Note: The course focus on “learning by doing” which means that the lab session of each class is expectially important.

Duckietown is a collaborative effort involving close interaction among students, TAs, mentors, and faculty across several institutions. The local learning assistants (LAs) at NCTU are:

• Yu-Chieh ‘Tony’ Hsiao (tonycar12002@gmail.com)
• Pin-Wei ‘David’ Chen (ccpwearth@gmail.com)
• Chen-Lung ‘Eric’ Lu (eric565648@gmail.com)
• Yung-Shan ‘Michael’ Su (michael1994822@gmail.com)
• Chen-Hao ‘Peter’ Hung (losttime1001@gmail.com)
• Hong-Ming ‘Peter’ Huang (peterx7803@gmail.com)
• Tzu-Kuan ‘Brian’ Chuang (fire594594594@gmail.com)

# Git usage guide for Fall 2017

## Repositories

These are the repositories we use.

## Git policy for homeworks (TTIC/UDEM)

This does not apply to Zurich.

Homeworks will require you to write and submit coding exercises. They will be submitted using git. Since we have a university plagiarism policy (UdeM’s, TTIC/UChicago) we have to protect students work before the deadline of the homeworks. For this reason we will follow these steps for homework submission:

1. Go here and file a request at the bottom “Request a Discount” then enter your institution email and other info.
2. Go to exercises-fall2017
3. Click “Fork” button in the top right
4. Choose your account if there are multiple options
5. Click on the Settings tab of your repostory, not your account
6. Under “Collaborators and Teams” in the left, click the “X” in the right for the section for “Fall 2017 Vehicle Autonomy Engineers in training”. You will get a popup asking you to confirm. Confirm.

If you have not yet cloned the duckietown repo do it now:

$git clone git@github.com:duckietown/exercises-fall2017.git  Now you need to point the remote of your exercises-fall2017 to your new local private repo. To do, from inside your already previously cloned exercises-fall2017 repo do: $ git remote set-url origin git@github.com:GIT_USERNAME/exercises-fall2017.git


Let’s also add an upstream remote that points back to the original duckietown repo:

$git remote add upstream git@github.com:duckietown/exercises-fall2017.git  If you type $ git remote -v


You should now see:

origin  git@github.com:GIT_USERNAME/exercises-fall2017.git (fetch)
upstream  git@github.com:duckietown/exercises-fall2017.git (fetch)
upstream  git@github.com:duckietown/exercises-fall2017.git (push)


Now the next time you push (without specifying a remote) you will push to your local private repo.

## Git policy for project development

Different than the homeworks, development for the projects will take place in the Software repo since plagiarism is not an issue here. The process is:

1. Create a branch from master

2. Develop code in that branch (note you may want to branch your branches. A good idea would be to have your own “master”, e.g. “your_project-master” and then do pull requests/merges into that branch as things start to work)

3. At the end of the project submit a pull request to master to merge your code. It may or may not get merged depending on many factors.

# Organization

The following roster shows the teaching staff.

Andrea Censi
Liam Paull
Jacopo Tani
First Last
Emilio Frazzoli
First Last
First Last
First Last
First Last
First Last
First Last
First Last
First Last
First Last
First Last
Greta Paull
Kirsten Bowser

Staff: To add yourself to the roster, or to change your picture, add a YAML file and a jpg file to the duckiefleet-fall2017 repository. in the people/staff directory.

## The Activity Tracker

The sheet called “Activity Tracker” describes specific tasks that you must do in a certain sequence. Tasks include things like “assemble your robot” or “sign up on Github”.

The difference between the Areas sheet and the Task sheet is that the Task sheet contains tasks that you have to do once; instead, the Areas sheet contains ongoing activities.

In this sheet, each task is a row, and each person is a column. There is one column for each person in the class, including instructors, TAs, mentors, and students.

You have two options:

• Only use the sheet as a reference;
• Use the sheet actively to track your progress. To do this, send a message to Kirsten with your gmail address, and add yourself.

Each task in the first column is linked to the documentation that describes how to perform the task.

The colored boxes have the following meaning:

• Red: not started. The person has not started the task.
• Blue: in progress. The person is doing the task.
• Yellow: blocked. The person is blocked.
• Green: done. The person is done with the task.
• n/a: the task is not applicable to the person. (Certain tasks are staff-only.)

## The Areas sheet

The sheet called “Areas” describes the points of contact for each part of this experience. These are the people that can offer support. In particular, note that we list two points of contact: one for America, and one for Europe. Moreover, there is a link to a Slack channel, which is the place where to ask for help. (We’ll get you started on Slack in just a minute.)

# Slack Channels

This page describes all of the helpful Slack channels and their purposes so that you can figure out where to get help.

## Channels

You can also easily join the ones that you are interested in by clicking the links in this message.

comment

Note that we can link directly to the channels. (See list in the org sheet.) -AC

# Zürich branch diary

## Wed Sep 20: Welcome to Duckietown!

This was an introduction meeting.

## Monday Sep 25, late at night: Onboarding instructions

At some late hour of the night, we sent out the onboarding instructions.

Please complete the onboarding questionnaire by Tuesday, September 26, 15:00.

## Wednesday Sep 27: Duckiebox distribution, and getting to know each other

Today we distribute the Duckieboxes and we name the robots. In other words, we perform the Duckiebox ceremony.

• getting to know each other;
• naming the robots;
• distribute the Duckieboxes.

If you cannot make it to this class for the Duckiebox distribution, please inform the TA, to schedule a different time.

### Preparation, step 1: choose a name for your robot

Before arriving to class, you must think of a name for your robot.

Here are the constraints:

• The name must work as a hostname. It needs to start with a letter, contains only letters and numbers, and no spaces or punctuation.
• It should be short, easy to type. (You’ll type it a lot.)
• It cannot be your own name.
• It cannot be a generic name like “robot”, “duckiebot”, “car”. It cannot contain brand names.

### Preparation, step 2: prepare a brief elevator pitch

As members of the same community, it is important to get to know a little about each other, so to know who to rely on in times of need.

During the Duckiebox distribution ceremony, you will be asked to walk up to the board, write your name on it, and introduce yourself. Keep it very brief (30 seconds), and tell us:

• what is your professional background and expertise / favorite subject;
• what is the name of your robot;
• why did you choose to name your robot in that way.

You will then receive a Duckiebox from our senior staff, a simple gesture but of sempiternal glory, for which you have now become a member of the Duckietown community. This important moment will be remembered through a photograph. (If in the future you become a famous roboticist, we want to claim it’s all our merit.)

Finally, you will bring the Duckiebox to our junior staff, who will apply labels with your name and the name of the robot. They will also give you labels with your robot name for future application on your Duckiebot.

## Thursday Sep 28: Misc announcements

We created the channel #ethz-chitchat for questions and other random things, so that we can leave this channel #ethz-announcements only for announcements.

We sent the final list to the Department; so hopefully in a couple of days the situation on MyStudies is regularized.

The “lab” time on Friday consists in an empty room for you to use as you wish, for example to assembe the robots together. In particular, it’s on the same floor of the Duckietown room and the IDSC lab.

The instructions for assembling the Duckiebots are here. Note that you don’t have to do the parts that we did for you: buying the parts, soldering the boards, and reproducing the image.

Expected progress: We are happy if we see everybody reaching up to Unit I-12 - RC+camera remotely by Monday October 9. You are encouraged to start very early; it’s likely that you will not receive much help on Sunday October 8…

## Sep 28: some announcements

A couple of announcements:

1. We created #ethz-chitchat for questions and other random things, so that we can leave this channel #ethz-announcements only for announcements.

2. MyStudies should be updated with everybody’s names.

3. The “lab” time tomorrow consists in an empty room for you to use as you wish, for example to assemble the robots together. In particular, it’s on the same floor of the Duckietown room and the IDSC lab.

4. The instructions for assembling the Duckiebots are here. Note that we did for you step I-2 (buying the parts) and I-3 (soldering the boards); and I-6 is optional.

5. We are happy if we see everybody reaching I-13 by the Monday after next. I encourage you to start sooner than later.

6. I see only 30 people in this channel instead of 42. Please tell your friends that now all the action is on Slack.

## Oct 01 (Mon): Announcement

It looks like that the current documentation is misleading in a couple of points. This is partially due to the fact that there is some divergence between Chicago, Montreal and Zurich regarding (1) the parts given out and (2) the setup environment (which networks are available). We did the simple changes (e.g. removing the infamous part 6), but we need some more time to review the other issues. At this point, the best course of action is that you enjoy your weekend without working on Duckietown, while we spend the weekend fixing the documentation.

## Oct 13 (Fri): new series of tasks out

### Taking a video of the joystick control

Please take a video of the robot as it drives with joystick control, as described in Section 1.7 - Upload your video and upload it according to the instructions.

### Camera calibration

Go forth and calibrate the camera! And get help in #help-camera-calib.

### Wheel calibration

This is not ready yet! will be ready in a day or so.

### Taking a log check off

Follow the instructions here to learn how to take a log.

### Data processing exercises

Get help in #ex-data-processing.

## Oct 25 (Wed) Filtering II

a - Lectures (Particle Filter) PowerPoint presentation, PDF.

b - Lectures (Lane Filter) PowerPoint presentation, PDF.

## Nov 1 (Wed) Control Systems

a - Lectures (Control Systems Module I) PowerPoint presentation, PDF.

b - Lectures (Control Systems Module II) PowerPoint presentation, PDF.

Points to be noted - Running what-the-duck on laptop and Duckiebot is mandatory. It helps save time in debugging errors and also is a standard way to ask for help from the staff. Keep repeating it periodically so as to keep the data up-to date - For the people lacking calibrated wheels, this serves as a reminder to calibrate the wheels and keep their duckiebot up-to date - It is advised to fill the lecture feedback form (Feedback form), so as to increase the effectiveness of the lectures - Always check the consistency of the camera calibration checkerboard before camera calibration (one has to check for the correct square size and correct distance between world and checkerboard reference)

## Nov 6 (Mon) Project Pitches

Lecture Project Pitches PDF.

## Nov 8 (Wed) Motion Planing

Lecture Motion Planing PDF.

A few references for planning of Andrea Censi:

## Nov 13 (Mon) Project Team Assignments

• First Lecture: Project Team Assignments PDF.
• Second Lecture: First meeting of the Controllers group –> Filling out the Preliminary Design Document

## Nov 15 (Wed) Putting things together

• First Lecture: Putting things together PDF.
• Second Lecture: Second meeting of the Controllers group –> Filling out the Preliminary Design Document

## Nov 22 (Wed) Fleet Control

• Lecture: Fleet Control in Autonomous Mobility on Demand PDF.

## Nov 27 (Mon) Inermediate design Report

• First Lecture: The intermediate Design report is introduced heretemplate-int-report. It is due on Monday 4th of December.

• Second Lecture was left for project discussion and interaction.

## Nov 29 (Wed) Fleet Control

• First Lecture: Clausdio finished Fleet Control in Autonomous Mobility on Demand PDF.

• Second Lecture Julian Presented the state of the art in data driven vs Model driven robotics. PDF

XXX

XXX

XXX

XXX

XXX

XXX

XXX

XXX

XXX

XXX

XXX

XXX

XXX

# Chicago branch diary

Classes take place on Mondays and Wednesdays from 9am-11am in TTIC Room 530.

# NCTU branch diary

Classes take place on Thursday from 1:20pm-4:20pm in NCTU Engineering Building 5 Room 635.

# Slack Channels

This page describes all of the helpful Slack channels and their purposes so that you can figure out where to get help.

# Guide for mentors [draft]

This section has been removed because it is in status 'draft'. If you are feeling adventurous, you can read it on master.

To disable this behavior, and completely hide the sections, set the parameter show_removed to false in fall2017.version.yaml.

# Project proposals [draft]

This section has been removed because it is in status 'draft'. If you are feeling adventurous, you can read it on master.

To disable this behavior, and completely hide the sections, set the parameter show_removed to false in fall2017.version.yaml.

# System Architecture

## Mission 1

Ensure that the development and integration of the projects into the system goes smoothly and that the resulting system makes sense, and is useful for future duckierations (duckie + generations).

## Mission 2

Where there is a system, there is a want (nay, need) for optimisation. Describing a system’s performance and resource requirements in a quantifiable way is a critical part of being able to benchmark modules and optimise the system.

Mission 2 is to formalise the description of the system characteristics, so that eventually the system performance can be optimised for some given resources.

# Template of a project

Make a copy of this document before editing.

# The Map Description

The map to be used in the Fall 2017 class is shown in Figure 21.1.

The editable keynote file is in this directory of the duckuments repo. The ids on the signs correspond to the Apriltag IDs. For more details see Signage.

# Checkoff: Assembly and Configuration

The first job is to get your Duckiebot put together and up and running.

You should record a video demonstrating that your Duckiebot is up and running. Brownie points for creative videos. Please upload your videos via the following URL:

# Homework: Data Processing (UdeM)

Ability to perform basic operations on images

Build your first ROS package and node

Ability to process imagery live

# Homework: Data Processing (TTIC)

Ability to perform basic operations on images

Build your first ROS package and node

Ability to process imagery live

TTIC deadline: Friday, October 13 11:59pm CT

# Homework: Augmented Reality

Ability to project fake things from an image back into the world

# Checkoff: Robot Calibration

That you have correctly cloned and followed the git procedure outline in Unit A-7 - Git usage guide for Fall 2017

That you have correctly setup your environment variables according to Environment variables (updated Sept 12)

You robot calibrations (wheels and camera (x2)) are merged to git through a PR

Slack channels: #help-wheel-calib, #help-camera-calib

# Exercises: Data Processing (Zurich)

Ability to perform basic operations on images

Build your first ROS package and node

Ability to process imagery live

Slack channel to get help: #ex-data-processing

2 logs of your robot autonomously navigating Duckietown

# Duckietown classes [draft]

This section has been removed because it is in status 'draft'. If you are feeling adventurous, you can read it on master.

To disable this behavior, and completely hide the sections, set the parameter show_removed to false in fall2017.version.yaml.

# First steps [draft]

This section has been removed because it is in status 'draft'. If you are feeling adventurous, you can read it on master.

To disable this behavior, and completely hide the sections, set the parameter show_removed to false in fall2017.version.yaml.

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

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

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

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

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…

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