From d1b4c6ded6bbe382ef42598b0dda1090940ce32b Mon Sep 17 00:00:00 2001
From: Rajat Singhal <rajatsinghal564@gmail.com>
Date: Tue, 21 Jul 2020 11:49:15 +0530
Subject: [PATCH] Add documentation, example script for setWind API

---
 PythonClient/multirotor/set_wind.py | 37 +++++++++++++++++++++++++++++
 docs/apis.md                        | 14 +++++++++++
 docs/settings.md                    |  5 ++++
 3 files changed, 56 insertions(+)
 create mode 100644 PythonClient/multirotor/set_wind.py

diff --git a/PythonClient/multirotor/set_wind.py b/PythonClient/multirotor/set_wind.py
new file mode 100644
index 0000000000..3185462239
--- /dev/null
+++ b/PythonClient/multirotor/set_wind.py
@@ -0,0 +1,37 @@
+import setup_path
+import airsim
+import time
+
+client = airsim.MultirotorClient()
+client.confirmConnection()
+client.enableApiControl(True)
+
+client.armDisarm(True)
+
+# Set wind to (20,0,0) in NED (forward direction)
+print("Setting wind to (20,0,0)")
+wind = airsim.Vector3r(20, 0, 0)
+client.simSetWind(wind)
+
+# Takeoff or hover
+landed = client.getMultirotorState().landed_state
+if landed == airsim.LandedState.Landed:
+    print("taking off...")
+    client.takeoffAsync().join()
+else:
+    print("already flying...")
+    client.hoverAsync().join()
+
+time.sleep(5)
+
+# Set wind to (0,25,0) in NED (towards right)
+print("Setting wind to (0,25,0)")
+wind = airsim.Vector3r(0, 25, 0)
+client.simSetWind(wind)
+
+time.sleep(5)
+
+# Set wind to 0
+print("Resetting wind to (0,0,0)")
+wind = airsim.Vector3r(0, 0, 0)
+client.simSetWind(wind)
diff --git a/docs/apis.md b/docs/apis.md
index a8807f74b4..f8482efcf0 100644
--- a/docs/apis.md
+++ b/docs/apis.md
@@ -193,6 +193,20 @@ This API works alongwith toggling Recording using R button, therefore if it's en
 
 Note that this will only save the data as specfied in the settings. For full freedom in storing data such as certain sensor information, or in a different format or layout, use the other APIs to fetch the data and save as desired.
 
+### Wind API
+
+Wind can be changed during simulation using `simSetWind()`. Wind is specified in World frame, NED direction and m/s values
+
+E.g. To set 20m/s wind in North (forward) direction -
+
+```python
+# Set wind to (20,0,0) in NED (forward direction)
+wind = airsim.Vector3r(20, 0, 0)
+client.simSetWind(wind)
+```
+
+Also see example script in [set_wind.py](https://github.com/Microsoft/AirSim/blob/master/PythonClient/multirotor/set_wind.py)
+
 ### Lidar APIs
 AirSim offers API to retrieve point cloud data from Lidar sensors on vehicles. You can set the number of channels, points per second, horizontal and vertical FOV, etc parameters in [settings.json](settings.md).
 
diff --git a/docs/settings.md b/docs/settings.md
index 2d827cae42..6e6d0b50f7 100644
--- a/docs/settings.md
+++ b/docs/settings.md
@@ -45,6 +45,7 @@ Below are complete list of settings available along with their default values. I
   "PhysicsEngineName": "",
   "SpeedUnitFactor": 1.0,
   "SpeedUnitLabel": "m/s",
+  "Wind": { "X": 0, "Y": 0, "Z": 0 },
   "Recording": {
     "RecordOnMove": false,
     "RecordInterval": 0.05,
@@ -222,6 +223,10 @@ The `InitMethod` determines how object IDs are initialized at startup to generat
 
  If `MeshNamingMethod` is "" or "OwnerName" then we use mesh's owner name to generate random hash as object IDs. If it is "StaticMeshName" then we use static mesh's name to generate random hash as object IDs. Note that it is not possible to tell individual instances of the same static mesh apart this way, but the names are often more intuitive.
 
+## Wind Settings
+
+This setting specifies the wind speed in World frame, in NED direction. Values are in m/s. By default, speed is 0, i.e. no wind.
+
 ## Camera Settings
 The `CameraDefaults` element at root level specifies defaults used for all cameras. These defaults can be overridden for individual camera in `Cameras` element inside `Vehicles` as described later.