From daa277985ba5bcfb6d942f34617ecbfa00995e9f Mon Sep 17 00:00:00 2001 From: Laurent Eschenauer Date: Thu, 27 Jun 2013 11:48:47 +0200 Subject: [PATCH] Added documentation --- README.md | 144 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 129 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index a63d71a..bfa108c 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,146 @@ # ardrone-autonomy -Provides key building blocks to create autonomous flight applications -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 [Visual Navigation for Flying Robots](http://vision.in.tum.de/teaching/ss2013/visnav2013) course. +An autonomous flight library for the ARDrone, built on top of +the [node-ar-drone](https://github.com/felixge/node-ar-drone) library. +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, -as well as writing some docs. All this is WIP. +* **VSLAM** to improve the drone localization estimates. + +* **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