Permalink
Browse files

restructuring

  • Loading branch information...
tanij committed Dec 16, 2018
1 parent b11f5f3 commit f59381389061e03936033e61fdbbacdb810be066
Showing with 338 additions and 95 deletions.
  1. +5 −2 book/opmanual_duckietown/00_part_duckietown.md
  2. +7 −0 book/opmanual_duckietown/01-duckietown-preliminaries.md
  3. +37 −0 book/opmanual_duckietown/02-duckietown-preliminaries-layers.md
  4. +13 −9 book/opmanual_duckietown/{06_appearance.md → 04-duckietown-appearance-specifications.md}
  5. +39 −0 book/opmanual_duckietown/05-duckietown-preliminaries-definitions.md
  6. +0 −18 book/opmanual_duckietown/05_duckietown_parts.md
  7. +2 −2 book/opmanual_duckietown/07_signs_assembly.md
  8. +5 −6 book/opmanual_duckietown/10_duckietown_assembly.md
  9. +1 −0 book/opmanual_duckietown/11_road_tiles_assembly.md
  10. +0 −28 book/opmanual_duckietown/12_LED_semantics.md
  11. +1 −0 book/opmanual_duckietown/12_traffic_signs_assembly.md
  12. +28 −0 book/opmanual_duckietown/{11_traffic_lights_assembly.md → 13_traffic_lights_assembly.md}
  13. +10 −0 book/opmanual_duckietown/20_duckietown_watchtowers.md
  14. 0 book/opmanual_duckietown/{13_watchtower_overview.md → 24_watchtower_overview.md}
  15. +0 −28 book/opmanual_duckietown/{14_watchtower_hardware.md → 25_watchtower_hardware.md}
  16. 0 book/opmanual_duckietown/{15_watchtower_software.md → 26_watchtower_software.md}
  17. +1 −2 ...kietown/{16_autolocalization_operation_procedure.md → 27_autolocalization_operation_procedure.md}
  18. +3 −0 book/opmanual_duckietown/30_duckietown_troubleshooting.md
  19. +3 −0 book/opmanual_duckietown/images/c-01-resized-1024.jpg
  20. +3 −0 book/opmanual_duckietown/images/c-02-resized-1024.jpg
  21. +3 −0 book/opmanual_duckietown/images/g-1-resized-1024.jpg
  22. +3 −0 book/opmanual_duckietown/images/g-2-resized-1024.jpg
  23. +3 −0 book/opmanual_duckietown/images/g-3-resized-1024.jpg
  24. +3 −0 book/opmanual_duckietown/images/g-4-resized-1024.jpg
  25. +3 −0 book/opmanual_duckietown/images/g-5-resized-1024.jpg
  26. +3 −0 book/opmanual_duckietown/images/g-6-resized-1024.jpg
  27. +3 −0 book/opmanual_duckietown/images/g-7-resized-1024.jpg
  28. +3 −0 book/opmanual_duckietown/images/g2-1-resized-1024.jpg
  29. +3 −0 book/opmanual_duckietown/images/g2-2-resized-1024.jpg
  30. +3 −0 book/opmanual_duckietown/images/g2-3-resized-1024.jpg
  31. +3 −0 book/opmanual_duckietown/images/g2-4-resized-1024.jpg
  32. +3 −0 book/opmanual_duckietown/images/g2-5-resized-1024.jpg
  33. +3 −0 book/opmanual_duckietown/images/g2-6-resized-1024.jpg
  34. +3 −0 book/opmanual_duckietown/images/g2-7-resized-1024.jpg
  35. +3 −0 book/opmanual_duckietown/images/j-1-resized-1024.jpg
  36. +3 −0 book/opmanual_duckietown/images/j-2-resized-1024.jpg
  37. +3 −0 book/opmanual_duckietown/images/j-3-resized-1024.jpg
  38. +3 −0 book/opmanual_duckietown/images/j-4-resized-1024.jpg
  39. +3 −0 book/opmanual_duckietown/images/j-5-resized-1024.jpg
  40. +3 −0 book/opmanual_duckietown/images/j-6-resized-1024.jpg
  41. +3 −0 book/opmanual_duckietown/images/j-7-resized-1024.jpg
  42. +3 −0 book/opmanual_duckietown/images/j-8-resized-1024.jpg
  43. +3 −0 book/opmanual_duckietown/images/l-1-resized-1024.jpg
  44. +3 −0 book/opmanual_duckietown/images/l-2-resized-1024.jpg
  45. +3 −0 book/opmanual_duckietown/images/l-3-resized-1024.jpg
  46. +3 −0 book/opmanual_duckietown/images/l-4-resized-1024.jpg
  47. +3 −0 book/opmanual_duckietown/images/l-5-resized-1024.jpg
  48. +3 −0 book/opmanual_duckietown/images/l-6-resized-1024.jpg
  49. +3 −0 book/opmanual_duckietown/images/tl-01-resized-1024.jpg
  50. +3 −0 book/opmanual_duckietown/images/tl-02-resized-1024.jpg
  51. +3 −0 book/opmanual_duckietown/images/tl-03-resized-1024.jpg
  52. +3 −0 book/opmanual_duckietown/images/tl-04-resized-1024.jpg
  53. +3 −0 book/opmanual_duckietown/images/tl-05-resized-1024.jpg
  54. +3 −0 book/opmanual_duckietown/images/tl-06-resized-1024.jpg
  55. +3 −0 book/opmanual_duckietown/images/tl-07-resized-1024.jpg
  56. +3 −0 book/opmanual_duckietown/images/tl-08-resized-1024.jpg
  57. +3 −0 book/opmanual_duckietown/images/tl-09-resized-1024.jpg
  58. +3 −0 book/opmanual_duckietown/images/tl-10-resized-1024.jpg
  59. +3 −0 book/opmanual_duckietown/images/tl-11-resized-1024.jpg
  60. +3 −0 book/opmanual_duckietown/images/tl-12-resized-1024.jpg
  61. +3 −0 book/opmanual_duckietown/images/tl-13-resized-1024.jpg
  62. +3 −0 book/opmanual_duckietown/images/tl-14-resized-1024.jpg
  63. +3 −0 book/opmanual_duckietown/images/tl-15-resized-1024.jpg
  64. +3 −0 book/opmanual_duckietown/images/tl-16-resized-1024.jpg
  65. +3 −0 book/opmanual_duckietown/images/tl-17-resized-1024.jpg
  66. +3 −0 book/opmanual_duckietown/images/tl-18-resized-1024.jpg
  67. +3 −0 book/opmanual_duckietown/images/tl-19-resized-1024.jpg
  68. +3 −0 book/opmanual_duckietown/images/tl-20-resized-1024.jpg
  69. +3 −0 book/opmanual_duckietown/images/tl-21-resized-1024.jpg
  70. +3 −0 book/opmanual_duckietown/images/tl-22-resized-1024.jpg
  71. +3 −0 book/opmanual_duckietown/images/tl-23-resized-1024.jpg
  72. +3 −0 book/opmanual_duckietown/images/tl-24-resized-1024.jpg
  73. +3 −0 book/opmanual_duckietown/images/tl-25-resized-1024.jpg
  74. +3 −0 book/opmanual_duckietown/traffic_light/parts-resized-1024.jpg
  75. +3 −0 book/opmanual_duckietown/traffic_light/step11-resized-1024.jpg
  76. +3 −0 book/opmanual_duckietown/traffic_light/step12-resized-1024.jpg
  77. +3 −0 book/opmanual_duckietown/traffic_light/step4-resized-1024.jpg
  78. +3 −0 book/opmanual_duckietown/watchtower/step3-resized-1024.jpg
  79. +3 −0 book/opmanual_duckietown/watchtower/step5-resized-1024.jpg
  80. +3 −0 book/opmanual_duckietown/watchtower/step9-resized-1024.jpg
@@ -1,5 +1,8 @@
# Operation manual - Duckietown {#book:duckietowns status=ready}

Maintainer: Liam Paull
Welcome to the Duckietown (city) operation manual. Here you will find the instructions to get started and other useful information.

# Operation manual - Build it {#part:build-it status=ready}
* [](#dt-ops-preliminaries): What you need to know before you start.
* [](#dt-ops-assembly): What you need to know to build a Duckietown.
* [](#dt-ops-watchtowers): Watchtowers, the eyes of Duckietown.
* [](#dt-ops-troubleshooting): What could go wrong, and how to fix it.
@@ -0,0 +1,7 @@
# Preliminaries {#part:dt-ops-preliminaries status=ready}

Before operating Duckiebots in a Duckietown, there are few things to keep in mind.

* [](#dt-ops-layers): What makes a Duckietown a Duckietown?
* [](#dt-ops-city-definitions): What are the minimal Duckietowns to make Duckiebots work?
* [](#dt-ops-appearance-specifications): How should every component of Duckietown look like?
@@ -0,0 +1,37 @@
# Signal layers {#dt-ops-layers status=beta}

<div class='requirements' markdown="1">

Requires: Nothing.

Results: Preliminary knowledge of Duckietown information layers.

Next Steps: [The Duckietown appearance specifications](#dt-ops-appearance-specifications).

</div>

From a functional perspective, Duckietown cities are an integral part of the robotic ecosystem we call Duckietown. They are designed to send information to the Duckiebots, so these can operate.

At a high level, Duckietown is built with two layers, the *floor* and *signals* layers.

## Floor Layer {#dt-ops-floor-layer status=ready}

The floor layer is the substrate on which Duckiebots drive, i.e., the road.

Regardless of the geometry of the roads (straight, curve, intersections), roads are made of two lanes; one for each direction of driving. Lanes are obtained by applying lane markings a black background.

## Signals Layer {#dt-ops-signals-layer status=ready}

The signals layer contains all the [signs](#dt-ops-city-traffic-signs) and other functional objects (e.g., [traffic lights](#traffic-light-assembly) or [watchtowers](#part:dt-ops-watchtowers)) that sit on top of the mats. Objects are functional when they enable some functionality for the Duckiebots. For example, traffic signs are functional because they tell Duckiebots at intersections where they are, and what should they look out for to know when to drive on.

## Non-functional elements {#dt-ops-non-functional-layer status=ready}

The citizens of Duckietown like their cities to be colorful and fun, and encourage all efforts at adding non-functional components to the city. Non functional objects can still sit on the floor, e.g., decorative building, but make sure they don't interfere with the signals or floor layers!

Moreover, although Duckiebot drivers all have their driving licenses and know to focus on the road, the _background_, i.e., whatever is in the room the Duckietown was assembled, matters too. More information in this regards can be found in the [troubleshooting](#part:dt-ops-troubleshooting) section.

<!--
Note: the visual appearance of the area where the Duckietown is created is variable. If you discover that this appearance is causing negative performance, a "wall" of blank tiles constructed vertically can be used to reduce visual clutter.
-->
@@ -1,6 +1,6 @@
# Duckietown Appearance Specification {#duckietown-specs status=beta}
# Appearance Specifications {#dt-ops-appearance-specifications status=beta}

This document describes the Duckietown specification. These are a set of rules for which a functional system has been verified.
This document describes the Duckietown specification. These are a set of rules for which a functional system has been verified. This means that if these rules are followed while building a Duckietown, Duckiebots will (most probably!) work.

Any Duckietown not adhering to the rules described here cannot call itself a "Duckietown", since it is not one.

@@ -13,19 +13,23 @@ the different Duckietowns.

* Version 1.0 - used for MIT 2.166

* Version 2.0 - user for Fall 2017
* Version 2.0 - user for Fall 2017 and throughout 2018.

## Overview
<!--
Duckietown is built with two layers:
Overview
Duckietown is built with two layers:
1. The first is the *floor layer*. The floor is built of interconnected exercise mats with tape on them.
2. The second layer is the *signals layer* and contains all the signs and other objects that sit on top of the mats.
Note: the visual appearance of the area where the Duckietown is created is variable. If you discover that this appearance is causing negative performance, a "wall" of blank tiles constructed vertically can be used to reduce visual clutter.
Note that the visual appearance of the area where the Duckietown is created is variable. If you discover that this appearance is causing negative performance, a "wall" of blank tiles constructed vertically can be used to reduce visual clutter.
-->



## Layer 1 - The Tile Layer
## Layer 1 - The Tile Layer {#dt-ops-floor-app-specs status=beta}

Each tile is a 2 ft x 2 ft square and is able to interlock with the others.

@@ -72,7 +76,7 @@ Currently, the left turn and right turn tiles are symmetric: one is the 90 degre

There are 3 colors of tapes: white, yellow, and red.

#### White tape
#### White tape

\begin{proposition}\label{prop:white_tape}
A Duckiebot never collides with Duckietown if it never crosses or touches a white tape strip.
@@ -184,7 +188,7 @@ A "yield" sign should be visible from the launch tile.

## Traffic Signs {#traffic-signs status=beta}

Requires: To print and assemble the signs refer to [](+opmanual_duckietown#signage).
Requires: To print and assemble the signs refer to [](+docs-opmanual_duckietown#signage).

### Specs

@@ -0,0 +1,39 @@
# Duckietowns and Duckiebot functionalities {#dt-ops-city-definitions status=beta}

Not all functionalities of the Duckiebots require all Duckietown city elements to work. If you are wondering what learning experiences you can explore with what Duckietown, you are in the right place. We define Duckietown configurations of increasing complexity depending on what Duckiebot functionalities they support.

## Only traffic signs (no city) {#dt-ops-no-city-def status=ready}

Without a Duckietown, it will not be possible for Duckiebots to showcase most of their behaviors. Nonetheless, traffic signs have AprilTags, which allow to play with the AprilTag detection and relative pose estimation pipeline, and in turn with the camera calibration and system identification procedures.

## City loops {#dt-ops-loops-def status=ready}

The fundamental Duckiebot behaviors can be explored with a very simple Duckietown. We call these simple cities: _loops_.

City loops are closed road patterns, without intersections, that meet the appearance specifications. They can be made only of floor layer elements, with no signals.

City loops enable to play with the:

* _perception pipeline_: what happens when data is obtained in form of measurements (i.e., images in the `DB17` and `DB18` configurations), and how it is used to extract information, leading the Duckiebots to generate a belief of their position and orientation in the lanes.

* _lane control_: the process that Duckiebots apply to transform beliefs provided by the perception pipeline in decisions on how to steer in order to stay inside the lane.

* _traffic management_: the functionality for which Duckiebots stay at a safety distance from other Duckiebots driving in front of them.

When city loops are augmented with traffic signs, e.g., road names, it is then possible to explore the functionality of:

* _AprilTag detection and relative pose estimation_: how Duckiebots detect AprilTags, and determine their position and orientation relative to them. This information can be used to localize in the map.

If you acquired a Duckietown Starter Pack, you have a city loop with traffic signs.

## Navigable cities {#dt-ops-nav-def status=ready}

Thee more complex Duckiebot behaviors require intersections and other city elements such as traffic lights to work. We define cities that include intersections as _navigable_ cities.

Navigable cities are city loops connected by intersections, meeting the appearance specification. Navigable cities require traffic signs.

Navigable cities enable testing of Duckiebot behaviors. A complete list (for one or more Duckiebots) of behaviors can be found here: [](+docs-opmanual_duckiebot#part:demos).

## Robotarium {#dt-ops-robotarium-def status=ready}

Robotariums (Robotic acquariums) are experimental Duckietows designed for continuous operations. Robotariums require a maintenance area in addition to a Duckietown, providing essential functions like automatic charging. More information on Robotariums can be found here: [](+docs-robotarium#book:robotarium).

This file was deleted.

Oops, something went wrong.
@@ -4,15 +4,15 @@ Assigned: Liam Paull

<div class='requirements' markdown="1">

Requires: The raw materials as described in [](+opmanual_duckietown#duckietown_parts)
Requires: The raw materials as described in [](+docs-opmanual_duckietown#duckietown_parts)

Results: A set of signs to be used for assembling your Duckietown.

</div>

## Build a map

Before beginning with sign assembly you should design a map that adheres to [the specification](+opmanual_duckietown#duckietown-specs).
Before beginning with sign assembly you should design a map that adheres to [the specification](+docs-opmanual_duckietown#duckietown-specs).

An example that was used for the 2017 version of the class is here: [](+fall2017_info#fall2017-map)

@@ -1,8 +1,7 @@
# Duckietown Assembly {#duckietown-assembly status=draft}
# Assembly {#part:dt-ops-assembly status=ready}

Assigned: Shiying Li
Here are some tips on how to assemble a Duckietown efficiently while respecting the [appearance specifications](#dt-ops-appearance-specifications).


Follow the rules in the [](+opmanual_duckietown#duckietown-specs).

Comment: do we need this page at all?
* [](#dt-ops-tiles): How to assemble road tiles.
* [](#dt-ops-city-traffic-signs): How to assemble traffic signs.
* [](#traffic-light-assembly): How to assemble traffic lights.
@@ -0,0 +1 @@
# Road Tiles Assembly {#dt-ops-tiles status=draft}

This file was deleted.

Oops, something went wrong.
@@ -0,0 +1 @@
# Traffic Signs Assembly {#dt-ops-city-traffic-signs status=draft}
@@ -468,3 +468,31 @@ After this step, launch traffic light node.
duckiebot $ make traffic-light

You should see the traffic light shining like crazy now.

# Semantics of LEDS {#LED-semantics status=draft}

Assigned: ???

headlights: white, constant

Assumption:

- **20 fps** to do LED detection

- 1s to decide

- 3 frequencies to detect

tail lights: red, **6 hz square wave**

traffic light "GO" = green, 1 hz** square wave**

traffic light "STOP" = red, 1.5 Hz** square wave**

duckie light on top, state 0 = off

duckie light on top, state 1 = blue, **3 Hz, square wave**

duckie light on top, state 2 = ?, **2.5 Hz square wave**

duckie light on top, state 3 = ?,** ****2 Hz square wave**
@@ -0,0 +1,10 @@
# Watchtowers {#part:dt-ops-watchtowers status=ready}

Watchtowers enable the actual Duckietown city to sense what is going on in its roads.

Note: Watchtowers are an experimental feature of Duckietown, which are currently only used in Robotariums.

* [](#auto-localization-overview): What are watchtowers, and what is their use?
* [](#auto-localization-hardware): How to assemble watchtowers.
* [](#auto-localization-software): How to operate watchtowers.
* [](#auto-localization-operation-procedure): How to operate a network of watchtowers to sense the traffic.
@@ -1,39 +1,11 @@
# Auto-Localization Hardware Preparation {#auto-localization-hardware status=draft}

Assigned: Chen-Lung Eric Lu, Josefine Quack

This document teaches you how to prepare a whole set of watchtower, which includes, hardware preparation, hardware assembly, image preparation and setting up watchtowers in a city.

## Overview

This chapter will guild you what to prepare for building watchtowers and how to assemble them. Also, we'll talk about image preparation. Whenever the watchtowers and the images are prepared, we would give some advices for putting the watchtowers into the city.

## Bill of Material

This is the bill of material for preparing one watchtower.

<div markdown="1">

<col2 id='materials-watchtower' figure-id="tab:materials-watchtower" figure-caption="Bill of materials for a watchtower">
<s>[Wooden Plates] </s> <s>USD ??</s>
<s>[Tubes] </s> <s>USD ??</s>
<s>[Rpi B+](https://tinyurl.com/ybyng4hf) </s> <s>USD 35</s>
<s>[Rpi B+ Heat Sink]() </s> <s>USD 10</s>
<s>[Pi Camera G](https://tinyurl.com/y9dnv2x5) </s> <s>USD 28.99</s>
<s>[1m Camera Cable](https://www.adafruit.com/product/2143) </s> <s>USD 3.95</s>
<s>[16 GB Class 10 MicroSD Card](https://tinyurl.com/ydawrgdx) </s> <s>USD 10</s>
<s>[3m USB to Micro USB Cables](https://goo.gl/BHfaYY) </s> <s>USD 2.99</s>
<s>[5m thin Ethernet cables]() </s> <s>USD 7.99</s>
<s>[USB Charger] </s> <s>USD 30</s>
<s>[Glue](https://tinyurl.com/y87xjpx8) </s> <s>USD 1.7</s>
<s>[M2.5, 12mm Spacers * 2]() </s> <s>USD 1</s>
<s>[M2.5, 6mm Screws * 2]() </s> <s>USD 1</s>
<s>[M2.5, 4mm Screws * 2]() </s> <s>USD 1</s>
<s>Total for a set of watchtower</s> <s>USD ??</s>
</col2>

</div>

## Before Assembly

### From Wooden Plates to Chasis Parts (Laser Cut):
@@ -1,7 +1,6 @@
# Auto-Localization Operation Procedure {#auto-localization-operation-procedure status=draft}

Assigned: Chen-Lung Eric Lu, Josefine Quack
Last Update:
TODO: Move this to the Robotarium book.

In this document, we wrote down the procedure of launching Auto-localization system.

@@ -0,0 +1,3 @@
# Troubleshooting {#part:dt-ops-troubleshooting status=ready}

Let's discuss some common nuisances and, when possible, their solutions.
Oops, something went wrong.

0 comments on commit f593813

Please sign in to comment.