docs update for Git issues

docs/apis.md

@@ -88,13 +88,20 @@ AirSim offers comprehensive images APIs to retrieve synchronized images from mul
 
 More on [image APIs and Computer Vision mode](image_apis.md).
 
+### Common APIs
+
+* `reset`: This resets the vehicle to its original starting state.
+* `confirmConnection`: Checks state of connection every 1 sec and reports it in Console so user can see the progress for connection.
+* `enableApiControl`: For safety reasons, by default API control for autonomous vehicle is not enabled and human operator has full control (usually via RC or joystick in simulator). The client must make this call to request control via API. It is likely that human operator of vehicle might have disallowed API control which would mean that enableApiControl has no effect. This can be checked by `isApiControlEnabled`.
+* `isApiControlEnabled`: Returns true if API control is established. If false (which is default) then API calls would be ignored. After a successful call to `enableApiControl`, the `isApiControlEnabled` should return true.
+* `ping`: If connection is established then this call will return true otherwise it will be blocked until timeout.
+
 ### APIs for Car
 Car has followings APIs available:
 
 * `setCarControls`: This allows you to set throttle, steering, handbrake and auto or manual gear.
 * `getCarState`: This retrieves the state information including speed, current gear, velocity vector, position and orientation.
 * [Image APIs](image_apis.md).
-* `reset`: This resets the vehicle to its original starting state.
 
 ### APIs for Multirotor
 Multirotor can be controlled by specifying angles, velocity vector, destination position or some combination of these. There are corresponding `move*` APIs for this purpose. When doing position control, we need to use some path following algorithm. By default AirSim uses carrot following algorithm. This is often referred to as "high level control" because you just need to specify very high level goal and the firmware takes care of the rest. Currently lowest level control available in AirSim is moveByAngle API however we will be adding more lower level controls soon as well.
@@ -108,10 +115,14 @@ Methods that take `float max_wait_seconds`, like `takeoff`, `land`, `moveOnPath`
 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. We would not recommend interrupting takeoff/land on a real drone, of course, as the results may be unpredictable.
 
 #### drivetrain
-Many APIs take `drivetrain` parameter which specifies how vehicle is oriented while it moves. For example, a quadrotor may move in West direction while its front is pointing towards North. In fact, quad rotors can move in all 3 axis while its front is pointing to any direction. In this mode of movement, vehicle uses its maximum degree of freedom. In forward-only mode, vehicle move only in the direction its pointing to. So if quadrotor is pointing to North and if we want it to move along West then we must reorient it. This mode is useful if we have only one sensor in the front.
+There are two modes you can fly vehicle: `Drivetrain = ForwardOnly` and `Drivetrain = MaxDegreeOfFreedom`. When you specify ForwardOnly, you are saying that vehicle's front should always point in the direction of travel. So if you want drone to take left turn then it would first rotate so front points to left. This mode is useful when you have only front camera and you are operating vehicle using FPV view. This is more or less like travelling in car where you always have front view. The MaxDegreeOfFreedom means you don't care where the front points to. So when you take left turn, you just start going left like crab. Quadrotors can go in any direction regardless of where front points to. The MaxDegreeOfFreedom enables this mode.
 
 #### yaw_mode
-Many APIs take `yaw_mode` parameter which specifies where vehicle should be pointing to. For example, you may want to move quadrotor while its front is pointing to North-East which means you will set `YawMode::is_rate = false` and `YawMode::yaw_or_rate = 90` (angle unit is degrees for Yaw). In some weired world, you might want your vehicle to continuously rotate at, say 20-degrees/sec, while it moves. YawMode allows you to specify that by setting  `YawMode::is_rate = true` and `YawMode::yaw_or_rate = 20`. However in more sane scenarios, you just don't want yaw to change which you can do by setting yaw rate of 0. The shothand for this is `YawMode::Zero()`. 
+`yaw_mode` has two fields, `yaw_or_rate` and `is_rate`. If is_rate = true then yaw_or_rate is interpreted as angular velocity in degrees/sec which means you want vehicle to rotate continuously around its axis at that angular velocity while moving. If is_rate = false then yaw_or_rate is interpreted as angle in degrees which means you want vehicle to rotate to specific angle (i.e. yaw) and keep that angle while moving. 
+
+You can probably see that YawMode::is_rate = true is pointless in ForwardOnly mode because you are contradicting by saying that keep front pointing ahead but also rotate continuously. However if you have YawMode::is_rate = false in ForwardOnly then you can do some funky stuff. For example, you can have drone do circles and have YawMode::yaw_or_rate = 90 so camera is always pointed to center ("super cool selfie mode"). In MaxDegreeofFreedom, you can get some funky stuff by setting YawMode::is_rate = true and say YawMode::yaw_or_rate = 20. This will cause drone to go in its path while rotating which may allow to do 360 scanning.
+
+In most cases, you just don't want yaw to change which you can do by setting yaw rate of 0. The shothand for this is `YawMode::Zero()`. 
 
 #### lookahead and adaptive_lookahead
 When you ask vehicle to follow a path, AirSim uses "carrot following" algorithm. This algorithm operates by looking ahead on path and adjusting its velocity vector. The parameters for this algorithm is specified by `lookahead` and `adaptive_lookahead`. For most of the time you want algorithm to auto-decide the values by simply setting `lookahead = -1` and `adaptive_lookahead = 0`.

docs/custom_drone.md

@@ -61,3 +61,10 @@ Waiting for drone to report a valid GPS location...
 ## PX4 Specific Tools
 You can run the MavlinkCom library and MavLinkTest app to test the connection
 between your companion computer and flight controller.  
+
+## How Does This Work?
+AirSim uses MavLinkCom component developed by @lovettchris. The MavLinkCom has proxy architecture where by you can open connection to PX4 either using serial or UDP and then other components shares this connection. When PX4 sends MavLink message, all components receives that message. If any component sends message then its received by PX4 only. This allows you to connect any number of components to PX4 [This code](https://github.com/Microsoft/AirSim/blob/master/AirLib/include/vehicles/multirotor/controllers/MavLinkDroneController.hpp#L793) opens connection for LogViewer and QGC. You can add something more if you like.
+
+If you want to use QGC + AirSim togather than you will need QGC to let own the serial port. QGC opens up TCP connection that acts as proxy so any other component can connect to QGC and send MavLinkMessage to QGC and then QGC forwards that message to PX4. So you tell AirSim to connect to QGC and let QGC own serial port.
+
+For companion board, the way we did it earlier was to have Gigabyte Brix on the drone. This x86 full fledged computer that will connect to PX4 through USB. We had Ubuntu on Brix and ran [DroneServer](https://github.com/Microsoft/AirSim/tree/master/DroneServer). The DroneServer created API end point that we can talk to via C++ client code (or Python code) and it translated API calls to MavLink messages. That way you can write your code against same API, test it in simulator and then ran same code on actual vehicle. So the companion computer has DroneServer running along with client code. 

docs/image_apis.md

@@ -124,6 +124,13 @@ See also [other example code](../Examples/StereoImageGenerator.hpp) that generat
 
 For a more complete ready to run sample code please see [sample code in AirSimClient project](../PythonClient/hello_drone.py) for multirotors or [HelloCar sample](../PythonClient/hello_car.py). This code also demonstrates simple activities such as saving images in files or using `numpy` to manipulate images.
 
+## Available Cameras
+### Car
+The camera ID 0 to 4 corresponds to center front, left front, right front, driver head, center rear respectively.
+
+### Multirotor
+The camera ID 0 to 4 corresponds to center front, left front, right front, center downward, center rear respectively.
+
 ## "Computer Vision" Mode
 
 You can use AirSim in so-called "Computer Vision" mode. In this mode, physics engine is disabled and there is no flight controller active. This means when you start AirSim, vehicle would just hang in the air. However you can move around using keyboard (use F1 to see help on keys). You can press Record button to continuously generate images. Or you can call APIs to move around and take images.

docs/px4_setup.md

@@ -92,4 +92,7 @@ drone starts to land.  This is the default behavior of PX4 when offboard mode co
 set this PX4 parameter:
 ```
 param set COM_OBL_ACT 1
-```
+```
+
+#### I get message length mismatches errors
+You might need to set MAV_PROTO_VER parameter in QGC to "Always use version 1". Please see [this issue](https://github.com/Microsoft/AirSim/issues/546) more details.