From c3154e864ae82c05b132c394bf3b10ebe63cd4fa 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..8022c1ea67
--- /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 (25,0,0) in NED (forward direction)
+print("Setting wind to (25,0,0)")
+wind = airsim.Vector3r(25, 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,30,0) in NED (towards right)
+print("Setting wind to (0,30,0)")
+wind = airsim.Vector3r(0, 30, 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 e3ed611d6f..8e90c4687e 100644
--- a/docs/apis.md
+++ b/docs/apis.md
@@ -179,6 +179,20 @@ Please note that `Roadwetness`, `RoadSnow` and `RoadLeaf` effects requires addin
 
 Please see [example code](https://github.com/Microsoft/AirSim/blob/master/PythonClient/computer_vision/weather.py) for more details.
 
+### 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 8059e489c6..10acb13082 100644
--- a/docs/settings.md
+++ b/docs/settings.md
@@ -37,6 +37,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,
@@ -214,6 +215,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 its "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.