Added documentation

README.md

@@ -1,32 +1,146 @@
 # ardrone-autonomy
 
-Provides key building blocks to create autonomous flight applications
+An autonomous flight library for the ARDrone, built on top of 
-with the AR.Drone. Works as a layer on top of the [node-ar-drone](https://github.com/felixge/node-ar-drone) library. This work is based on 
+the [node-ar-drone](https://github.com/felixge/node-ar-drone) library. 
-the [Visual Navigation for Flying Robots](http://vision.in.tum.de/teaching/ss2013/visnav2013) course.
+Instead of directly controlling the drone speed, you can use Autonomy 
+to plan and execute missions by describing the path, altitude and 
+orientation the drone must follow.
 
-**This work has just started, this branch is the development branch, there are no packaged release yet.**
+This work is based on the [Visual Navigation for Flying Robots](http://vision.in.tum.de/teaching/ss2013/visnav2013) course.
+
+** WARNING: **  This is early work. __Autonomous__ means that this library will move your drone
+automaticaly to reach a given target. There isn't much security in place yet, so if you 
+do something wrong, you may have your drone fly away :-)
+
+** Experiment with this library in a closed/controlled environment before going in the wild **
 
 ## Features
 
-* **Simple State estimation** based on the integration of the drone odometry.
-
-* **Camera back-projection** to estimate the position of an object detected by the camera.
-Currently used to estimate a tag position in the drone coordinate system based on its detection
-by the bottom camera.
-
 * **Extended Kalman Filter** leveraging the onboard tag detection as the observation source
 for an Extended Kalman Filter. This provides much more stable and usable state estimate.
 
-## Upcoming features
+* **Camera projection and back-projection** to estimate the position of an object detected by the camera.
+Currently used to estimate a tag position in the drone coordinate system based on its detection
+by the bottom camera.
 
 * **PID Controler** to autonomously control the drone position.
 
-* **Visual motion estimation** estimates motion from visual image processing.
+* **Mission planner** to prepare a flight/task plan and then execute it.
 
-## Usage
+### Planned features
 
-High level function needs to be implemented to ease things for the end-user,
+* **VSLAM** to improve the drone localization estimates.
-as well as writing some docs. All this is WIP.
+
+* **Object tracking** to detect and track objects in the video stream.
+
+## Mission
+
+This module exposes a high level API to plan and execute missions, by focusing on where
+the drone should go instead of its low-level movements. Here is a simple example, 
+with the drone taking off, travelling alongs a 2 x 2 meters square ane then landing.
+
+```js
+var autonomy = require('ardrone-autonomy');
+var mission  = autonomy.createMission();
+
+mission.takeoff()
+       .zero()       // Sets the current state as the reference
+       .altitude(1)  // Climb to altitude = 1 meter
+       .forward(2)   
+       .right(2)     
+       .backward(2) 
+       .left(2)
+       .hover(1000)  // Hover in place for 1 second
+       .land();
+
+mission.run(function (err, result)
+    if (err) {
+        console.trace("Oops, something bad happened: %s", err.message);
+        mission.client().stop();
+        mission.client().land();
+    } else {
+        console.log("Mission success!");
+        process.exit(0);
+    }
+});
+```
+
+### Mission API
+
+#### mission.log(path)
+
+Log the mission data, csv formatted, in the given file. Makes it really usefull to
+debug/plot the state and controller behavior.
+
+### mission.run(callback)
+
+Execute the mission. The callback has the form `function(err,result)`.
+
+#### mission.takeoff()
+
+Add a takeoff step to the mission.
+
+#### mission.forward/backward/left/right/up/down(distance)
+
+Add a movement step to the mission. The drone will move in the given direction by the distance (in meters) before
+proceeding to next step. The drone will also attempt to maintain all other degrees of freedom.
+
+#### mission.altitude(height)
+
+Add a altitude step to the mission. Will climb to the given height before proceeding to next step.
+
+#### mission.cw/ccw(angle)
+
+Add a rotation step to the mission. Will turn by the given angle (in Deg) before proceeding to the next step.
+
+#### mission.hover(delay)
+
+Add a hover step to the mission. Will hover in place for the given delay (in ms) before proceeding to next step.
+
+#### mission.wait(delay)
+
+Add a wait step to the mission. Will wait for the given delay (in ms) before proceeding to next step.
+
+#### mission.go(position)
+
+Add a movement step to the mission. Will go the given position before proceeding to next step. The position is a Controller goal such as {x: 0, y: 0, z: 1, yaw: 90}.
+
+### mission.task(function)
+
+Add a task step to the mission. Will execute the provided function before proceeding to the next step. A callback argument is passed to the function, it should be called when the 
+task is done.
+
+#### mission.zero()
+
+Add a zeroing step to the mission. This will set the current position/orientation as 
+the base state of the kalman filter (i.e. {x: 0, y:0, yaw:0}). If you are not using
+a tag as your base position, it is a good idea to zero() after takeoff.
+
+## Controller API
+
+This module exposes a high level API to control the position. It is built using an
+Extended Kalman Filter to estimate the position and a PID controller to move the drone
+to a given target.
+
+The easiest way to try the Controller is to play with the repl provided in the examples:
+
+```js
+$ node examples/repl.js
+// Make the drone takeoff
+drone> takeoff()
+// Move the drone to position (1,1)
+drone> ctrl.go({x: 1, y:1});
+// Climb to altitude 2 meters
+drone> ctrl.altitude(2);
+// Spin 90 deg to the right
+drone> ctrl.cw(90);
+// Go back to (0,0)
+drone> ctrl.go({x:0, y:0});
+// Hover in place
+drone> ctrl.hover();
+// Land
+drone> land();
+```
 
 ## License