Fall 2017

🔗

Welcome to the Fall 2017 Duckietown experience.

Because of mathjax bug

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!

This is your onboarding procedure. Please read all the steps and then complete all the steps.

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

Github sign up

🔗

If you don’t already have a Github account, sign up now.

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)

Please contact them on Slack, rather than email.

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)
Because of mathjax bug

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

See the course syllabus for more information on course object and grading policy.

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)
Because of mathjax bug

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)
origin  git@github.com:GIT_USERNAME/exercises-fall2017.git (push)
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.

Because of mathjax bug

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

🔗

Link to 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:

  • Grey: not ready. This means the task is not ready for you to start yet.
  • 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

🔗

Please familiarize yourself with this spreadsheet and bookmark it in your browser.

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

Because of mathjax bug

Getting and giving help

🔗

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.

Duckietown Slack Channels
Channel Purpose
help-accounts Info about necessary accounts, such as Slack, Github, etc.
help-assembly Help putting your robot together
help-camera-calib Help doing the intrinsic and extrinsic calibration of your camera
help-duckuments Help compiling the online documentation
help-git Help with git
help-infrastructure Help with software infrastructure, such as Makefiles, unit tests, continuous integration, etc.
help-laptops Help getting your laptop setup with Ubuntu 16.04
help-parts Help getting the parts for the robot or replacement parts if you broke something
help-robot-setup Help getting the robot setup to do basic things like be driven with a joystick
help-ros Help with the Robot Operating System (ROS)
help-wheel-calib Help doing your odometry calibration
comment

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

Because of mathjax bug

Zürich branch diary

🔗

Wed Sep 20: Welcome to Duckietown!

🔗

This was an introduction meeting.

Monday Sep 25: Introduction to autonomy

🔗

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…

Because of mathjax bug

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 02 (Mon): Networking, logical/physical architectures

🔗

Oct 04 (Wed): Modeling

🔗

Oct 09 (Mon): Autonomy architectures and version control

🔗

Oct 11 (Wed): Computer vision and odometry calibration

🔗

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.

Example of a great video, but with a nonconforming Duckiebot.

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

🔗

See the list of exercises here.

Get help in #ex-data-processing.

Current deadlines for Zurich

Oct 16 (Mon): Line detection

🔗

Oct 18 (Wed): Feature extraction

🔗

Oct 20 (Fri): Lab session

🔗

Oct 23 (Mon) Filtering I

🔗

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

Because of mathjax bug

Montréal branch diary

🔗

Oct 30 (Mon)

🔗

XXX

Nov 01 (Wed)

🔗

XXX

Nov 06 (Mon)

🔗

XXX

Nov 08 (Wed)

🔗

XXX

Nov 13 (Mon)

🔗

XXX

Nov 15 (Wed)

🔗

XXX

Nov 20 (Mon)

🔗

XXX

Nov 22 (Wed)

🔗

XXX

Nov 27 (Mon)

🔗

XXX

Nov 29 (Wed)

🔗

XXX

Dec 04 (Mon)

🔗

XXX

Dec 06 (Wed)

🔗

XXX

Dec 11 (Mon)

🔗

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 TAs

🔗

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 map to be used in the Fall 2017 class

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.

Because of mathjax bug

Fall 2017 Checkoffs and Homeworks

Checkoff: Assembly and Configuration

🔗

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

Upload your video

🔗

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:

Because of mathjax bug

Checkoff: Take a Log

🔗

A verified log in rosbag format uploaded to Dropbox.

Montreal deadline: Oct 4, 11pm

Zurich deadline: Oct 20, 17:00

Homework: Data Processing (UdeM)

🔗

Ability to perform basic operations on images

Build your first ROS package and node

Ability to process imagery live

Montreal deadline: Oct 4, 11:00pm

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

Montreal deadline: Oct 27, 11:00pm
Chicago deadline: Oct 27, 11:59pm
Zurich deadline: Oct ???, 11:59pm

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

Checkoff: Navigation

🔗

2 logs of your robot autonomously navigating Duckietown

Montreal Deadline: Nov 15, 11pm

Chicago Deadline: Nov 15, 11pm

Homework: Lane Filtering

🔗
Montreal deadline: Nov 17, 11:00pm
Chicago deadline: Nov 17, 11:59pm

The Duckietown project

🔗

What is Duckietown?

🔗

Duckietown history and future

🔗

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.

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.

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

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