Update docs (#2658)

* [docs] Add Python API docs * [docs] Add links for ArduPilot usage * [docs] Update CHANGELOG.md for May, July * [docs] Add more info about Log files * [docs] Fix indentation * [docs] Add note to not clone Airsim in C drive * [docs] Fix RL page link in Readme * [docs] Add PyMarkdown extras extension * [docs] Fix airsim_ros_pkgs.md * Update airsim_ros_pkgs.md * Update build_docs.sh * Update .gitignore Co-authored-by: Ratnesh Madaan <ratneshmadaan@gmail.com>
microsoft · Sep 3, 2020 · fbe6482 · fbe6482
1 parent ba4be15
commit fbe6482
Show file tree

Hide file tree

Showing 10 changed files with 134 additions and 80 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Welcome to AirSim
 
-AirSim is a simulator for drones, cars and more, built on [Unreal Engine](https://www.unrealengine.com/) (we now also have an experimental [Unity](https://unity3d.com/) release). It is open-source, cross platform, and supports hardware-in-loop with popular flight controllers such as PX4 for physically and visually realistic simulations. It is developed as an Unreal plugin that can simply be dropped into any Unreal environment. Similarly, we have an experimental release for a Unity plugin.
+AirSim is a simulator for drones, cars and more, built on [Unreal Engine](https://www.unrealengine.com/) (we now also have an experimental [Unity](https://unity3d.com/) release). It is open-source, cross platform, and supports software-in-the-loop simulation with popular flight controllers such as PX4 & ArduPilot and hardware-in-loop with PX4 for physically and visually realistic simulations. It is developed as an Unreal plugin that can simply be dropped into any Unreal environment. Similarly, we have an experimental release for a Unity plugin.
 
 Our goal is to develop AirSim as a platform for AI research to experiment with deep learning, computer vision and reinforcement learning algorithms for autonomous vehicles. For this purpose, AirSim also exposes APIs to retrieve data and control vehicles in a platform independent way.
 
@@ -98,7 +98,7 @@ Press F10 to see various options available for weather effects. You can also con
 - [Video - Setting up AirSim with Pixhawk Tutorial](https://youtu.be/1oY8Qu5maQQ) by Chris Lovett
 - [Video - Using AirSim with Pixhawk Tutorial](https://youtu.be/HNWdYrtw3f0) by Chris Lovett
 - [Video - Using off-the-self environments with AirSim](https://www.youtube.com/watch?v=y09VbdQWvQY) by Jim Piavis
-- [Reinforcement Learning with AirSim](https://microsoft.github.io/AirSim/docs/reinforcement_learning) by Ashish Kapoor
+- [Reinforcement Learning with AirSim](https://microsoft.github.io/AirSim/reinforcement_learning) by Ashish Kapoor
 - [The Autonomous Driving Cookbook](https://aka.ms/AutonomousDrivingCookbook) by Microsoft Deep Learning and Robotics Garage Chapter
 - [Using TensorFlow for simple collision avoidance](https://github.com/simondlevy/AirSimTensorFlow) by Simon Levy and WLU team
 

diff --git a/build_docs.sh b/build_docs.sh
@@ -1,5 +1,11 @@
 #!/bin/bash
 
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+pushd "$SCRIPT_DIR"  >/dev/null
+
 cp README.md docs/
 sed -i 's/](docs\//](/g' docs/README.md
+
 mkdocs build
+
+popd >/dev/null
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -2,6 +2,31 @@
 
 Below is summarized list of important changes. This does not include minor/less important changes or bug fixes or documentation update. This list updated every few months. For complete detailed changes, please review [commit history](https://github.com/Microsoft/AirSim/commits/master).
 
+### July 2020
+
+* [Allow passing the settings.json file location via `--settings` argument](https://github.com/microsoft/AirSim/pull/2668)
+* [Distance Sensor Upgrades and fixes](https://github.com/microsoft/AirSim/pull/2807)
+* [Update to min CMake version required for VS 2019](https://github.com/microsoft/AirSim/pull/2766)
+* [Fix: Non-linear bias corrupts SurfaceNormals, Segmentation image](https://github.com/microsoft/AirSim/pull/2845)
+* [Fix: `simGetSegmentationObjectID` will always return -1](https://github.com/microsoft/AirSim/pull/2855)
+* [Initial implementation of simLoadLevel, simGet/SetObjectScale, simSpawn|DestroyObject APIs](https://github.com/microsoft/AirSim/pull/2651)
+* [Upgrade `setCameraOrientation` API to `setCameraPose`](https://github.com/microsoft/AirSim/pull/2710)
+* [ROS: All sensors and car support](https://github.com/microsoft/AirSim/pull/2743)
+* [Get rid of potential div-0 errors so we can set dt = 0 for pausing](https://github.com/microsoft/AirSim/pull/2705)
+* [ROS: Add mavros_msgs to build dependencies](https://github.com/microsoft/AirSim/pull/2642)
+* [Move Wiki pages to docs](https://github.com/microsoft/AirSim/pull/2803)
+* [Add Recording APIs](https://github.com/microsoft/AirSim/pull/2834)
+* [Update Dockerfiles and documentation to Ubuntu 18.04](https://github.com/microsoft/AirSim/pull/2865)
+* [Azure development environment and documentation](https://github.com/microsoft/AirSim/pull/2816)
+* [ROS: Add airsim_node to install list](https://github.com/microsoft/AirSim/pull/2706)
+
+### May 2020
+
+* [Fix more issues with PX4 master](https://github.com/microsoft/AirSim/pull/2649)
+* [Reduce warnings level in Unity build](https://github.com/microsoft/AirSim/pull/2672)
+* [Support for Unreal Engine 4.25](https://github.com/microsoft/AirSim/pull/2669)
+* [Unity crash fix, upgrade to 2019.3.12, Linux build improvements](https://github.com/microsoft/AirSim/pull/2328)
+
 ### April 2020
 
 * [Fix issues with PX4 latest master branch](https://github.com/microsoft/AirSim/pull/2634)

diff --git a/docs/airsim_ros_pkgs.md b/docs/airsim_ros_pkgs.md
@@ -3,9 +3,8 @@
 A ROS wrapper over the AirSim C++ client library. 
 
 ##  Setup 
-- Install gcc >= 8.0.0
-`sudo apt-get install gcc-8 g++-8`
-Verify version by `gcc --version`
+- Install gcc >= 8.0.0: `sudo apt-get install gcc-8 g++-8`  
+Verify installation by `gcc-8 --version`
 
 - Ubuntu 16.04
     * Install [ROS kinetic](https://wiki.ros.org/kinetic/Installation/Ubuntu)
@@ -69,18 +68,19 @@ Odometry in NED frame (default name: odom_local_ned, launch name and frame type
 
 - `/tf` [tf2_msgs/TFMessage](https://docs.ros.org/api/tf2_msgs/html/msg/TFMessage.html)
 
-- `/airsim_node/VEHICLE_NAME/altimeter/SENSOR_NAME` [airsim_ros_pkgs::Altimeter] This the current altimeter reading for altitude, pressure, and QNH (https://en.wikipedia.org/wiki/QNH)
+- `/airsim_node/VEHICLE_NAME/altimeter/SENSOR_NAME` [airsim_ros_pkgs/Altimeter](https://github.com/microsoft/AirSim/blob/master/ros/src/airsim_ros_pkgs/msg/Altimeter.msg)  
+This the current altimeter reading for altitude, pressure, and [QNH](https://en.wikipedia.org/wiki/QNH)
 
-- `/airsim_node/VEHICLE_NAME/imu/SENSOR_NAME` [sensor_msgs::Imu] (http://docs.ros.org/api/sensor_msgs/html/msg/Imu.html)
-  IMU sensor data
+- `/airsim_node/VEHICLE_NAME/imu/SENSOR_NAME` [sensor_msgs::Imu](http://docs.ros.org/api/sensor_msgs/html/msg/Imu.html)  
+IMU sensor data
 
-- `/airsim_node/VEHICLE_NAME/magnetometer/SENSOR_NAME` [sensor_msgs::MagneticField] (http://docs.ros.org/api/sensor_msgs/html/msg/MagneticField.html)
+- `/airsim_node/VEHICLE_NAME/magnetometer/SENSOR_NAME` [sensor_msgs::MagneticField](http://docs.ros.org/api/sensor_msgs/html/msg/MagneticField.html)  
   Meausrement of magnetic field vector/compass
 
-- `/airsim_node/VEHICLE_NAME/distance/SENSOR_NAME` [sensor_msgs::Range] (http://docs.ros.org/api/sensor_msgs/html/msg/Range.html)
+- `/airsim_node/VEHICLE_NAME/distance/SENSOR_NAME` [sensor_msgs::Range](http://docs.ros.org/api/sensor_msgs/html/msg/Range.html)  
   Meausrement of distance from an active ranger, such as infrared or IR
 
-- `/airsim_node/VEHICLE_NAME/lidar/SENSOR_NAME` [sensor_msgs::PointCloud2] (http://docs.ros.org/api/sensor_msgs/html/msg/PointCloud2.html)
+- `/airsim_node/VEHICLE_NAME/lidar/SENSOR_NAME` [sensor_msgs::PointCloud2](http://docs.ros.org/api/sensor_msgs/html/msg/PointCloud2.html)  
   LIDAR pointcloud
 
 #### Subscribers: 
@@ -96,8 +96,8 @@ Odometry in NED frame (default name: odom_local_ned, launch name and frame type
 - `/gimbal_angle_quat_cmd` [airsim_ros_pkgs/GimbalAngleQuatCmd](https://github.com/microsoft/AirSim/tree/master/ros/src/airsim_ros_pkgs/msg/GimbalAngleQuatCmd.msg)   
   Gimbal set point in quaternion.    
 
-- `/airsim_node/VEHICLE_NAME/car_cmd` [airsim_ros_pkgs/CarControls]
-  Throttle, brake, steering and gear selections for control. Both automatic and manual transmission control possible, see the car_joy.py script for use.
+- `/airsim_node/VEHICLE_NAME/car_cmd` [airsim_ros_pkgs/CarControls](https://github.com/microsoft/AirSim/blob/master/ros/src/airsim_ros_pkgs/msg/CarControls.msg)  
+Throttle, brake, steering and gear selections for control. Both automatic and manual transmission control possible, see the [`car_joy.py`](https://github.com/microsoft/AirSim/blob/master/ros/src/airsim_ros_pkgs/scripts/car_joy) script for use.
 
 #### Services:
 - `/airsim_node/VEHICLE_NAME/land` [airsim_ros_pkgs/Takeoff](https://docs.ros.org/api/std_srvs/html/srv/Empty.html)
@@ -172,7 +172,7 @@ Odometry in NED frame (default name: odom_local_ned, launch name and frame type
   Target gps position + yaw.   
   In **absolute** altitude. 
 
-- `/airsim_node/VEHICLE_NAME/local_position_goal` [Request: [srv/SetLocalPosition](https://github.com/microsoft/AirSim/blob/master/ros/src/airsim_ros_pkgs/srv/SetLocalPosition.srv)   
+- `/airsim_node/VEHICLE_NAME/local_position_goal` [Request: [srv/SetLocalPosition](https://github.com/microsoft/AirSim/blob/master/ros/src/airsim_ros_pkgs/srv/SetLocalPosition.srv)]   
   Target local position + yaw in global NED frame.   
 
 #### Subscribers:
@@ -200,15 +200,15 @@ Odometry in NED frame (default name: odom_local_ned, launch name and frame type
 ### Misc
 #### Windows Subsytem for Linux on Windows 10
 - WSL setup:
-  * Get [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
-  * Get [Ubuntu 16.04](https://www.microsoft.com/en-us/p/ubuntu-1604-lts/9pjn388hp8c9?activetab=pivot:overviewtab) or [Ubuntu 18.04](https://www.microsoft.com/en-us/p/ubuntu-1804-lts/9n9tngvndl3q?activetab=pivot%3Aoverviewtab)  
-  * Go to Ubuntu 16 / 18 instructions!
+    * Get [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
+    * Get [Ubuntu 16.04](https://www.microsoft.com/en-us/p/ubuntu-1604-lts/9pjn388hp8c9?activetab=pivot:overviewtab) or [Ubuntu 18.04](https://www.microsoft.com/en-us/p/ubuntu-1804-lts/9n9tngvndl3q?activetab=pivot%3Aoverviewtab)  
+    * Go to Ubuntu 16 / 18 instructions!
 
 
 - Setup for X apps (like RViz, rqt_image_view, terminator) in Windows + WSL
-  * Install [Xming X Server](https://sourceforge.net/projects/xming/). 
-  * Find and run `XLaunch` from the Windows start menu.   
-  Select `Multiple Windows` in first popup, `Start no client` in second popup, **only** `Clipboard` in third popup. Do **not** select `Native Opengl`.  
-  * Open Ubuntu 16.04 / 18.04 session by typing `Ubuntu 16.04`  / `Ubuntu 18.04` in Windows start menu.  
-  * Recommended: Install [terminator](http://www.ubuntugeek.com/terminator-multiple-gnome-terminals-in-one-window.html) : `$ sudo apt-get install terminator.` 
+    * Install [Xming X Server](https://sourceforge.net/projects/xming/). 
+    * Find and run `XLaunch` from the Windows start menu.   
+    Select `Multiple Windows` in first popup, `Start no client` in second popup, **only** `Clipboard` in third popup. Do **not** select `Native Opengl`.  
+    * Open Ubuntu 16.04 / 18.04 session by typing `Ubuntu 16.04`  / `Ubuntu 18.04` in Windows start menu.  
+    * Recommended: Install [terminator](http://www.ubuntugeek.com/terminator-multiple-gnome-terminals-in-one-window.html) : `$ sudo apt-get install terminator.` 
     - You can open terminator in a new window by entering `$ DISPLAY=:0 terminator -u`. 
diff --git a/docs/build_linux.md b/docs/build_linux.md
@@ -7,6 +7,7 @@ Only macOS **Catalina (10.15)** is supported.
 We've two options - you can either build inside docker containers or your host machine.
 
 ## Docker
+
 Please see instructions [here](https://github.com/Microsoft/AirSim/blob/master/docs/docker_ubuntu.md)
 
 ## Host machine
@@ -69,17 +70,17 @@ Once AirSim is setup:
 - When Unreal Engine prompts for opening or creating project, select Browse and choose `AirSim/Unreal/Environments/Blocks` (or your [custom](unreal_custenv.md) Unreal project).
 - Alternatively, the project file can be passed as a commandline argument. For Blocks: `./Engine/Binaries/Linux/UE4Editor <AirSim_path>/Unreal/Environments/Blocks/Blocks.uproject`
 - If you get prompts to convert project, look for More Options or Convert-In-Place option. If you get prompted to build, choose Yes. If you get prompted to disable AirSim plugin, choose No.
-- After Unreal Editor loads, press Play button. 
+- After Unreal Editor loads, press Play button.
 
 ### Mac
 
 - Browse to `AirSim/Unreal/Environments/Blocks`.
 - Run `./GenerateProjectFiles.sh <UE_PATH>` from the terminal, where `UE_PATH` is the path to the Unreal installation folder. (By default, this is `/Users/Shared/Epic\ Games/UE_4.24/`) The script creates an XCode workspace by the name Blocks.xcworkspace.
-- Open the XCode workspace, and press the Build and run button in the top left. 
-- After Unreal Editor loads, press Play button. 
+- Open the XCode workspace, and press the Build and run button in the top left.
+- After Unreal Editor loads, press Play button.
 
 See [Using APIs](apis.md) and [settings.json](settings.md) for various options available for AirSim usage.
-Tip: go to 'Edit->Editor Preferences', in the 'Search' box type 'CPU' and ensure that the 'Use Less CPU when in Background' is unchecked. 
+Tip: go to 'Edit->Editor Preferences', in the 'Search' box type 'CPU' and ensure that the 'Use Less CPU when in Background' is unchecked.
 
 ### [Optional] Setup Remote Control (Multirotor Only)
 
@@ -89,38 +90,39 @@ Alternatively, you can use [APIs](apis.md) for programmatic control or use the s
 
 ## FAQs
 
-- I'm getting error "<MyProject> could not be compiled. Try rebuilding from source manually".
-  * This could either happen because of compile error or the fact that your gch files are outdated. Look in to your console window. Do you see something like below?
-   ```
-   fatal error: file  '/usr/include/linux/version.h''/usr/include/linux/version.h'  has  been  modified  since  the  precompiled  header
-   ```
-  * If this is the case then look for *.gch file(s) that follows after that message, delete them and try again. Here's [relevant thread](https://answers.unrealengine.com/questions/412349/linux-ue4-build-precompiled-header-fatal-error.html) on Unreal Engine forums.
-  * If you see other compile errors in console then open up those source files and see if it is due to changes you made. If not, then report it as issue on GitHub.
+- I'm getting error `<MyProject> could not be compiled. Try rebuilding from source manually`.
+    * This could either happen because of compile error or the fact that your gch files are outdated. Look in to your console window. Do you see something like below?
+
+`fatal error: file '/usr/include/linux/version.h''/usr/include/linux/version.h' has been modified since the precompiled header`
+
+* If this is the case then look for *.gch file(s) that follows after that message, delete them and try again. Here's [relevant thread](https://answers.unrealengine.com/questions/412349/linux-ue4-build-precompiled-header-fatal-error.html) on Unreal Engine forums.
+
+* If you see other compile errors in console then open up those source files and see if it is due to changes you made. If not, then report it as issue on GitHub.
 
 - Unreal crashed! How do I know what went wrong?
-  * Go to the `MyUnrealProject/Saved/Crashes` folder and search for the file `MyProject.log` within its subdirectories. At the end of this file you will see the stack trace and messages.
-   You can also take a look at the `Diagnostics.txt` file.
+    * Go to the `MyUnrealProject/Saved/Crashes` folder and search for the file `MyProject.log` within its subdirectories. At the end of this file you will see the stack trace and messages.
+    You can also take a look at the `Diagnostics.txt` file.
 
 - How do I use an IDE on Linux?
-  * You can use Qt Creator or CodeLite. Instructions for Qt Creator are available [here](https://docs.unrealengine.com/latest/INT/Platforms/Linux/BeginnerLinuxDeveloper/SettingUpAnIDE/index.html).
+    * You can use Qt Creator or CodeLite. Instructions for Qt Creator are available [here](https://docs.unrealengine.com/latest/INT/Platforms/Linux/BeginnerLinuxDeveloper/SettingUpAnIDE/index.html).
 
 - Can I cross compile for Linux from a Windows machine?
-  * Yes, you can, but we haven't tested it. You can find the instructions [here](https://docs.unrealengine.com/latest/INT/Platforms/Linux/GettingStarted/index.html).
+    * Yes, you can, but we haven't tested it. You can find the instructions [here](https://docs.unrealengine.com/latest/INT/Platforms/Linux/GettingStarted/index.html).
 
 - What compiler and stdlib does AirSim use?
-  * We use the same compiler that Unreal Engine uses, **Clang 8**, and stdlib, **libc++**. AirSim's `setup.sh` will automatically download them.
+    * We use the same compiler that Unreal Engine uses, **Clang 8**, and stdlib, **libc++**. AirSim's `setup.sh` will automatically download them.
 
 - What version of CMake does the AirSim build use?
-  * 3.10.0 or higher. This is *not* the default in Ubuntu 16.04 so setup.sh installs it for you. You can check your CMake version using `cmake --version`. If you have an older version, follow [these instructions](cmake_linux.md) or see the [CMake website](https://cmake.org/install/).
+    * 3.10.0 or higher. This is *not* the default in Ubuntu 16.04 so setup.sh installs it for you. You can check your CMake version using `cmake --version`. If you have an older version, follow [these instructions](cmake_linux.md) or see the [CMake website](https://cmake.org/install/).
 
 - Can I compile AirSim in BashOnWindows?
-  * Yes, however, you can't run Unreal from BashOnWindows. So this is kind of useful to check a Linux compile, but not for an end-to-end run.
-   See the [BashOnWindows install guide](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide).
-   Make sure to have the latest version (Windows 10 Creators Edition) as previous versions had various issues.
-   Also, don't invoke `bash` from `Visual Studio Command Prompt`, otherwise CMake might find VC++ and try and use that!
+    * Yes, however, you can't run Unreal from BashOnWindows. So this is kind of useful to check a Linux compile, but not for an end-to-end run.
+    See the [BashOnWindows install guide](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide).
+    Make sure to have the latest version (Windows 10 Creators Edition) as previous versions had various issues.
+    Also, don't invoke `bash` from `Visual Studio Command Prompt`, otherwise CMake might find VC++ and try and use that!
 
 - Where can I find more info on running Unreal on Linux?
-   * Start here: [Unreal on Linux](https://docs.unrealengine.com/latest/INT/Platforms/Linux/index.html)
-   * [Building Unreal on Linux](https://wiki.unrealengine.com/Building_On_Linux#Clang)
-   * [Unreal Linux Support](https://wiki.unrealengine.com/Linux_Support)
-   * [Unreal Cross Compilation](https://wiki.unrealengine.com/Compiling_For_Linux)
+    * Start here: [Unreal on Linux](https://docs.unrealengine.com/latest/INT/Platforms/Linux/index.html)
+    * [Building Unreal on Linux](https://wiki.unrealengine.com/Building_On_Linux#Clang)
+    * [Unreal Linux Support](https://wiki.unrealengine.com/Linux_Support)
+    * [Unreal Cross Compilation](https://wiki.unrealengine.com/Compiling_For_Linux)