Doc update.

docs/apis.md

@@ -1,9 +1,11 @@
 ## Introduction
-This project includes a self-contained cross-platform library to retrieve data from the quadrotor and send the control commands. You can use this library for a simulated drone in Unreal engine or on a real quadrotor such as a MavLink based vehicle platform (and very soon DJI quadrotors such as Matrice).
+This project includes a self-contained cross-platform library to retrieve data from the quadrotor and send the control commands. 
+You can use this library for a simulated drone in Unreal engine or on a real quadrotor such as a MavLink based vehicle platform
+(and very soon DJI quadrotors such as Matrice).
 
 ## Hello Drone
 Here's the taste of how you can use our APIs in C++:
-See also [Python API](python.md).
+See also [Python API](python.md) if you prefer that language.
 
 ```
 #include <iostream>
@@ -18,14 +20,14 @@ int main()
     client.armDisarm(true);
 
     cout << "Press Enter to takeoff" << endl; cin.get();
-    client.takeoff(1000);
+    client.takeoff(60);
 
     cout << "Press Enter to use offboard control" << endl; cin.get();
     client.requestControl();
 
     cout << "Press Enter to move 5 meters in x direction with 1 m/s velocity" << endl; cin.get();    
     auto position = client.getPosition(); // from current location
-    client.moveToPosition(position.x() + 5, position.y(), position.z(), 1);
+    client.moveToPosition(position.x() + 5, position.y(), position.z(), 1, 5*1);
 
     cout << "Press Enter to land" << endl; cin.get();
     client.land();
@@ -44,6 +46,21 @@ In essence, DroneControlBase defines our abstract interface for getting data fro
 We currently have concrete implementation for DroneControlBase for MavLink based vehicles. The implementation for DJI drone 
 platforms, specifically Matrice, is in works.
 
+## Timing
+
+Notice each method of DroneControlBase API takes one of two possible parameters: `float duration` or: `float max_wait_seconds`.
+
+Methods that take `float duration`, like moveByVelocity return control immediately. So you can therefore choose to sleep for this duration, or you can change their mind and call something else which will automatically cancel the moveByVelocity.
+
+Methods that take `float max_wait_seconds`, like takeoff, land, moveOnPath, moveToPosition, moveToZ, and so will block this amount of time waiting for command to be successfully completed. If the command
+completes before the max_wait_seconds they will return True, otherwise
+if the max_wait_seconds times out they will return False. 
+
+If you want to wait for ever pass a big number. But if you want to be able to interrupt even these commands pass 0 and you can do something else or sleep in a loop while checking the drone position, etc. 
+
+Note: We would not recommend interrupting takeoff/land on a real drone, of course, as the results may be unpredictable.
+
+
 ## How to get images from drone?
 Here's a sample code. For more information, please see [DroneControlBase](https://github.com/Microsoft/AirSim/blob/master/AirLib/include/controllers/DroneControllerBase.hpp) class.
 See [Camera Views](camera_views.md) for information on the camera views and how to change them.
@@ -56,7 +73,6 @@ int playWithImages()
     
     msr::airlib::RpcLibClient client;
 
-    client.setImageTypeForCamera(0, DroneControlBase::ImageType::Depth);
     vector<uint8_t> image = client.getImageForCamera(0, DroneControlBase::ImageType::Depth);
     //do something with images
 }
@@ -65,9 +81,15 @@ int playWithImages()
 ## Can I run above code on real quadrotors as well?
 Absolutely! The AirLib is self-contained library that you can put on an offboard computing module such as the Gigabyte barebone Mini PC. 
 This module then can talk to the flight controllers such as Pixhawk using exact same code and MavLink protocol (or DJI protocol). 
-The code you write for testing in the simulator remains unchanged! We will post more detailed guide on how to do this soon.
+The code you write for testing in the simulator remains unchanged! 
+See [AirLib on custom drones](https://github.com/Microsoft/AirSim/blob/master/docs/custom_drone.md).
 
-## What else is in works?
+## What else can I do ?
 
 You can also program AirSim using [Python](python.md).
-We also hope to release ROS adapters for our APIs with Linux builds.
+
+See [move on path](https://github.com/Microsoft/AirSim/wiki/moveOnPath-demo) demo showing video of fast flight through Modular Neighborhood environment.
+
+See [building a hexacopter](https://github.com/Microsoft/AirSim/wiki/hexacopter).
+
+See [building point clouds](https://github.com/Microsoft/AirSim/wiki/Point-Clouds).

docs/custom_drone.md

@@ -1,6 +1,6 @@
-# Airsim on a Real Drone
+# AirLib on a Real Drone
 
-Parts of the AirSim stack can be used on a real drone.  For example, you can run the MavlinkCom library and MavLinkTest app to test the connection
+Parts of the AirLib stack can be used on a real drone.  For example, you can run the MavlinkCom library and MavLinkTest app to test the connection
 between your `big brain` and `little brain`.  For our testing we mounted a Gigabyte Brix BXi7-5500 ultra compact PC on the drone connected to the Pixhawk flight controller over USB.  The Gigabyte PC is running Ubuntu, so we are able to SSH into it over Wifi: 
 
 ![Flamewheel](images/Flamewheel.png)