Implemented Docs Folder

Author: Sean M. Bryan

_config.yml

@@ -1 +1,4 @@
-theme: jekyll-theme-minimal
+theme: jekyll-theme-minimal
+
+plugis:
+    - jekyll-sitemap

Actuation/MotorControllerFeedback.md renamed to docs/Actuation/MotorControllerFeedback.md

@@ -0,0 +1,90 @@
+#  Adaptive Monte Carlo Localization
+
+## What is a particle filter?
+Particle filter are initialized by a very high number of particles spanning the entire state space. As you get additional measurements, you predict and update your measurements which makes your robot have a multi-modal posterior distribution. This is a big difference from a Kalman Filter which approximates your posterior distribution to be a Gaussian. Over multiple iterations, the particles converge to a unique value in state space.
+
+![Particle Filter in Action over Progressive Time Steps](assets/AdaptiveMonteCarloLocalization-65e37.png)
+
+**Figure 1:** Particle Filter in Action over Progressive Time Steps
+
+The steps followed in a Particle Filter are:
+1. **Re-sampling:** Draw with replacement a random sample from the sample set according to the (discrete) distribution defined through the importance weights. This sample can be seen as an instance of the belief.
+
+2. **Sampling:** Use previous belief and the control information to sample 􀀀from the distribution which describes the dynamics of the system. The current belief now represents the density given by the product of distribution and an instance of the previous belief. This density is the proposal distribution used in the next step.
+
+3. **Importance sampling:** Weight the sample by the importance weight, the likelihood of the sample X given the measurement Z.
+
+Each iteration of these three steps generates a sample drawn from the posterior belief. After n iterations, the importance weights of the samples are normalized so that they sum up to 1.
+
+For further details on this topic, [Sebastian Thrun's paper on Particle Filter in Robotics](http://robots.stanford.edu/papers/thrun.pf-in-robotics-uai02.pdf) is a good source for a mathematical understanding of particle filters, their applications and drawbacks.
+
+## What is an adaptive particle filter?
+A key problem with particle filter is maintaining the random distribution of particles throughout the state space, which goes out of hand if the problem is high dimensional. Due to these reasons it is much better to use an adaptive particle filter which converges much faster and is computationally much more efficient than a basic particle filter.
+
+The key idea is to bound the error introduced by the sample-based representation of the particle filter. To derive this bound, it is assumed that the true posterior is given by a discrete, piece-wise constant distribution such as a discrete density tree or a multidimensional histogram. For such a representation we can determine the number of samples so that the distance between the maximum likelihood estimate (MLE) based on the samples and the true posterior does not exceed a pre-specified threshold. As is finally derived, the number of particles needed is proportional to the inverse of this threshold.
+
+[Dieter Fox's paper on Adaptive Particle Filters](http://papers.nips.cc/paper/1998-kld-sampling-adaptive-particle-filters.pdf) delves much deeper into the theory and mathematics behind these concepts. It also covers the implementation and performance aspects of this technique.
+
+## Use of Adaptive Particle Filter for Localization
+To use adaptive particle filter for localization, we start with a map of our environment and we can either set robot to some position, in which case we are manually localizing it or we could very well make the robot start from no initial estimate of its position. Now as the robot moves forward, we generate new samples that predict the robot's position after the motion command. Sensor readings are incorporated by re-weighting these samples and normalizing the weights. Generally it is good to add few random uniformly distributed samples as it helps the robot recover itself in cases where it has lost track of its position. In those cases, without these random samples, the robot will keep on re-sampling from an incorrect distribution and will never recover. The reason why it takes the filter multiple sensor readings to converge is that within a map, we might have dis-ambiguities due to symmetry in the map, which is what gives us a multi-modal posterior belief.
+
+![Localization Process using Particle Filters](assets/AdaptiveMonteCarloLocalization-0d322.png)
+
+[Dieter Fox's paper on Monte Carlo Localization for Mobile Robots](https://www.ri.cmu.edu/pub_files/pub1/fox_dieter_1999_1/fox_dieter_1999_1.pdf) gives further details on this topic and also compares this technique to many others such as Kalman Filter based Localization, Grid Based and Topological Markov Localization.
+
+## Configuring ROS AMCL package
+At the conceptual level, the AMCL package maintains a probability distribution over the set of all possible robot poses, and updates this distribution using data from odometry and laser range-finders. Depth cameras can also be used to generate these 2D laser scans by using the package `depthimage_to_laserscan` which takes in depth stream and publishes laser scan on `sensor_msgs/LaserScan`. More details can be found on the [ROS Wiki](http://wiki.ros.org/depthimage_to_laserscan).
+
+The package also requires a predefined map of the environment against which to compare observed sensor values. At the implementation level, the AMCL package represents the probability distribution using a particle filter. The filter is "adaptive" because it dynamically adjusts the number of particles in the filter: when the robot's pose is highly uncertain, the number of particles is increased; when the robot's pose is well determined, the number of particles is decreased. This enables the robot to make a trade-off between processing speed and localization accuracy.
+
+Even though the AMCL package works fine out of the box, there are various parameters which one can tune based on their knowledge of the platform and sensors being used. Configuring these parameters can increase the performance and accuracy of the AMCL package and decrease the recovery rotations that the robot carries out while carrying out navigation.
+
+There are three categories of ROS Parameters that can be used to configure the AMCL node: overall filter, laser model, and odometery model. The full list of these configuration parameters, along with further details about the package can be found on the [webpage for AMCL](http://wiki.ros.org/amcl). They can be edited in the `amcl.launch` file.
+
+Here is a sample launch file. Generally you can leave many parameters at their default values.
+```
+<launch>
+
+ <arg name="use_map_topic" default="false"/>
+ <arg name="scan_topic" default="scan"/>
+
+ <node pkg="amcl" type="amcl" name="amcl">
+   <param name="use_map_topic" value="$(arg use_map_topic)"/>
+   <!-- Publish scans from best pose at a max of 10 Hz -->
+   <param name="odom_model_type" value="diff"/>
+   <param name="odom_alpha5" value="0.1"/>
+   <param name="gui_publish_rate" value="10.0"/>   <!-- 10.0 -->
+   <param name="laser_max_beams" value="60"/>
+   <param name="laser_max_range" value="12.0"/>
+   <param name="min_particles" value="500"/>
+   <param name="max_particles" value="2000"/>
+   <param name="kld_err" value="0.05"/>
+   <param name="kld_z" value="0.99"/>
+   <param name="odom_alpha1" value="0.2"/>
+   <param name="odom_alpha2" value="0.2"/>
+   <!-- translation std dev, m -->
+   <param name="odom_alpha3" value="0.2"/>
+   <param name="odom_alpha4" value="0.2"/>
+   <param name="laser_z_hit" value="0.5"/>
+   <param name="laser_z_short" value="0.05"/>
+   <param name="laser_z_max" value="0.05"/>
+   <param name="laser_z_rand" value="0.5"/>
+   <param name="laser_sigma_hit" value="0.2"/>
+   <param name="laser_lambda_short" value="0.1"/>
+   <param name="laser_model_type" value="likelihood_field"/>
+   <!-- <param name="laser_model_type" value="beam"/> -->
+   <param name="laser_likelihood_max_dist" value="2.0"/>
+   <param name="update_min_d" value="0.25"/>
+   <param name="update_min_a" value="0.2"/>
+   <param name="odom_frame_id" value="odom"/>
+   <param name="resample_interval" value="1"/>
+   <!-- Increase tolerance because the computer can get quite busy -->
+   <param name="transform_tolerance" value="1.0"/>
+   <param name="recovery_alpha_slow" value="0.0"/>
+   <param name="recovery_alpha_fast" value="0.0"/>
+   <remap from="scan" to="$(arg scan_topic)"/>
+ </node>
+</launch>
+```
+
+Best way to tune these parameters is to record a ROS bag file, with odometry and laser scan data, and play it back while tuning AMCL and visualizing it on RViz. This helps in tracking the performance based on the changes being made on a fixed data-set. 

Actuation/PIDControlArduino.md renamed to docs/Actuation/PIDControlArduino.md

@@ -0,0 +1,40 @@
+# Oculus Prime Navigation
+
+There are multiple techniques to carry out way-point navigation on the Oculus Prime platform using the navigation stack.
+
+1. **"Pure" ROS:** To set a single goal the pure ROS way, bypassing the use of the oculusprime browser UI altogether, first run:
+```
+$ roslaunch oculusprime globalpath_follow.launch
+```
+Or try:
+```
+$ roslaunch oculusprime remote_nav.launch
+```
+  - This `globalpath_follow` launch file sets up the basic nodes necessary to have Oculus Prime go where ROS Navigation wants it to go, and launches the rest of the navigation stack. Once it’s running, you can [set initial position and goals graphically using Rviz](http://wiki.ros.org/oculusprime_ros/navigation_rviz_tutorial)
+
+2. **Via Command Line:** You can also send coordinates via command line (AFTER you set initial position using the web browser or Rviz map). Enter a command similar to:
+```
+$ rostopic pub /move_base_simple/goal geometry_msgs/PoseStamped \
+'{ header: { frame_id: "map" }, pose: { position: { x: 4.797, y: 2.962, z: 0 }, orientation: { x: 0, y: 0, z: 0.999961751128, w: -0.00874621528223 } } }'
+```
+  - Change the coordinates shown to match where your goal is. An easy way to find goal coordinates is to set the goal on the map with a mouse, and while the robot is driving there, enter:
+```
+$ rostopic echo /move_base/current_goal
+```
+  - An example of doing this via a python ROS node, starting with simpler coordinates (x,y,th), can be found [here](https://gist.github.com/xaxxontech/6cbfefd38208b9f8b153).
+
+3. **Waypoints:** If you want to choose from a list of waypoints instead, you can use the functionality built into the oculusprime server and do it via oculusprime commands:
+  - First read the waypoints:
+```
+state rosmapwaypoints
+```
+  - This should return a long comma-separated string with no spaces using the format "name,x,y,th," for all the waypoints, similar to `<telnet> <state> waypointA, 4.387, -0.858, -0.3218, waypointB, 2.081, 2.739, -1.5103`.
+  - Change the coordinates of the particular waypoint you want to change within the string, then send the whole string to the savewaypoints command, eg:
+Advanced -> telnet text command -> enter command:
+```
+savewaypoints waypointA,5.456,-2.345,-0.3218,waypointB,2.081,2.739,-1.5103
+```
+  - Then drive to the new coordinates by sending:
+```
+gotowaypoint waypointA
+```

Actuation/ULN2003AMotorController.md renamed to docs/Actuation/ULN2003AMotorController.md

@@ -0,0 +1,24 @@
+# ROCON Multi-master Framework
+ROCON stands for Robotics in Concert. It is a multi-master framework provided by ROS. It provides easy solutions for multi-robot/device/tablet platforms.
+Multimaster is primarily a means for connecting autonomously capable ROS subsystems. It could of course all be done underneath a single master - but the key point is for subsystems to be autonomously independent. This is important for wirelessly connected robots that can’t always guarantee their connection on the network.
+
+## The Appable Robot
+The appable robot is intended to be a complete framework intended to simplify:
+- Software Installation
+- Launching
+- Retasking
+- Connectivity (pairing or multimaster modes)
+- Writing portable software
+
+It also provides useful means of interacting with the robot over the public interface via two different modes:
+1. **Pairing Mode:** 1-1 human-robot configuration and interaction.
+2. **Concert Mode:** autonomous control of a robot through a concert solution.
+
+## Rapps
+ROS Indigo has introduced the concept of Rapps for setting the multi-master system using ROCON. Rapps are meta packages providing configuration, launching rules and install dependencies. These are essentially launchers with no code.
+- The specifications and parameters for rapps can be found at in the [Rapp Specifications](http://cmumrsdproject.wikispaces.com/link)
+- [A guide](http://cmumrsdproject.wikispaces.com/Creating+Rapps) to creating rapps and working with them is also available.
+
+## The Gateway Model
+The gateway model is the engine of a ROCON Multimaster system. They are used by the Rapp Manager and the concert level components to coordinate the exchange of ROS topics, services and actions between masters. The gateway model is based on the LAN concept where a gateway stands in between your LAN and the rest of the internet, controlling both what communications are allowed through, and what is sent out. Gateways for ROS systems are similar conceptually. They interpose themselves between a ROS system and other ROS systems and are the coordinators of traffic going in and out of a ROS system to remote ROS systems.
+A hub acts as a shared key-value store for multiple ROS systems. Further detailed information on how the topics are shared between the multiple masters can be found [here](http://cmumrsdproject.wikispaces.com/The+Gateway+Model).