## page was renamed from kobuki/Tutorials/Testing Automatic Docking
## For instruction on writing tutorials
## http://www.ros.org/wiki/WritingTutorials
####################################
##FILL ME IN
####################################
## for a custom note with links:
## note = 
## for the canned note of "This tutorial assumes that you have completed the previous tutorials:" just add the links 
## note.0= 
## descriptive title for the tutorial
## title = Automatic Docking
## multi-line description to be displayed in search 
## description = How to run automatic docking
## the next tutorial description (optional)
## next =
## links to next tutorial (optional)
## next.0.link=[[kobuki/Tutorials/Gazebo Simulation|Gazebo Simulation]]
## next.1.link=
## what level user is this tutorial for 
## level=IntermediateCategory
## keywords = kobuki, docking, automatic docking
####################################

<<IncludeCSTemplate(TutorialCSHeaderTemplate)>>

<<TOC(4)>>

= Overview =

This tutorial will show you how to run automatic docking with kobuki, and will give you a brief description of algorithm. The code is located in [[kobuki_auto_docking]] package. It is implemented as a [[nodelet|Nodelet]], intended to run in the same manager as the kobuki node. To start/stop the algorithm, and get feedback, we use a [[actionlib|Simple Action Server]].


= Running =

== Prerequisites ==

 * Kobuki robot with a netbook
 * Fully installed kobuki stack
 * Docking Station 

== Setup ==

To run automatic docking properly, docking station should be placed in an open space of at least 2 meters wide by 5 meters long. There should be no obstacles between kobuki robot and docking station. And the dock station should be held by a wall or something heavy enough to prevent the robot to push it. A static red light on top of the docking station signals that it is powered on properly.

== Loading ==

If everything is ready, you can easily launch the auto docking algorithm by using the commands below:

 * If you already launched kobuki_node, load the auto-docking nodelet into the running kobuki core. For convenience, just type:

{{{
$ roslaunch kobuki_auto_docking minimal.launch --screen
}}}

 * Or if you have not launched the kobuki core yet, type:

{{{
$ roslaunch kobuki_auto_docking compact.launch --screen
}}}

Be aware that this is just loading the algorithm; it is still not active. The algorithm is implemented as a typical action server. You need to call the server via an action client.

== Activating ==

 * There is a convenient launcher which will run the action client in the [[kobuki_auto_docking]] package. To activate it type:

{{{
$ roslaunch kobuki_auto_docking activate.launch --screen
}}}


Kobuki robot will follow the docking station's infrared ray, and will dock automatically. If the robot manages to dock successfully, both the status LED of robot and docking station will start blinking with green light. When fully charged, you can see a static green light on both, with a happy be-beep sound from the robot:)

= How it works =

== Docking Station ==

Kobuki's docking station has 3 IR([[http://en.wikipedia.org/wiki/Infrared|Infrared]]) emitters. The emitted IR lights cover three regions in front of the docking station: left, central and right, each divided in two sub-fields: near and far. Each beam encodes this information, so the robot knows at any moment in which region and sub-field he is. Also, as regions and fields are independently identified, they can be overlap on its borders.

{{https://docs.google.com/drawings/pub?id=1MoRZWyit8Z1qxkOvrP3AY-KTPxKEfVbwdEWVS4ao7VI&w=600&h=672}}

== IR Receivers ==

Kobuki has 3 IR receivers. When the robot is placed within the field of the docking station, and at least one IR receiver is facing toward it, the robot will catch the signal and stream it to the controller netbook. The information is available on `/mobile_base/sensors/dock_ir` topic, in the form of `kobuki_msgs/DockInfraRed` messages ([[http://ros.org/doc/groovy/api/kobuki_msgs/html/msg/DockInfraRed.html|link]]).

{{https://docs.google.com/drawings/pub?id=1g-JS3qLS__RKpIJDD5Lc5jHVB8ZX2rVmFTuGHFUA5C8&w=800&h=433}}

== Brief Description ==

The basic idea is very simple. If the robot is placed on the central region of the docking station, it's easy to dock. Just by following the central region's signal, the robot can reach the docking station. However, if the robot is placed either on left or right region, things get more interesting.

If the robot is placed on left region, it will turn counter clock-wise until detecting the left region signal on his right sensor. At this point, the robot is facing the central region perpendicularly, so he just need to move forward to reach the central region. Now the robot should see the central region's signal, so reaching the docking station gets trivial. Starting on the right region is similar, but directions are inverted.

= What's next =

You have finished all intermediate tutorials. Continue on the [[kobuki/Tutorials/Kobuki's Control System|next level]].


## AUTOGENERATED DO NOT DELETE 
## TutorialCategory
## FILL IN THE STACK TUTORIAL CATEGORY HERE