From 002081671c597ba789f7e77752f6de489f2f913f Mon Sep 17 00:00:00 2001 From: aurebidart Date: Mon, 11 Aug 2025 13:32:05 -0300 Subject: [PATCH 1/4] Update doc index tree --- docs/index.md | 82 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 57 insertions(+), 25 deletions(-) diff --git a/docs/index.md b/docs/index.md index dc498bf1..329f577c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,27 +3,47 @@ ```{include} ../README.md :relative-docs: docs_build/source :relative-images: docs_build/source/images -``` +```` ```{toctree} :maxdepth: 2 :caption: Introduction ../README.md +transition_from_airsim.md +system_specs.md +faq.md +license.md ``` ```{toctree} :maxdepth: 2 :caption: Getting Started -development/use_source.md development/use_prebuilt.md +development/use_source.md +client_setup.md +use_plugin.md development/dev_setup_linux.md development/dev_setup_win.md development/vscode_user_settings.md development/headless_cloud.md ``` +```{toctree} +:maxdepth: 2 +:caption: Configuration + +config.md +config_scene.md +config_robot.md +multiple_robots.md +command_line_switches.md +gis_scenes.md +modify_drone_physical.md +modify_drone_visual.md +``` + ```{toctree} :maxdepth: 2 :caption: Sensors @@ -40,48 +60,60 @@ development/sensors/display.md ```{toctree} :maxdepth: 2 -:caption: Physics and Simulation +:caption: Controllers -physics/fast_physics.md -physics/matlab_physics.md -development/physics/unreal_physics.md -scene/sim_clock.md -scene/weather_visual_effects.md -development/scene/sim_clock_development.md +controllers/controllers.md +controllers/simple_flight.md +controllers/px4/px4.md +controllers/px4/px4_build.md +controllers/px4/px4_hitl.md +controllers/px4/px4_lockstep.md +controllers/px4/px4_multi_vehicle.md +controllers/px4/px4_sitl.md +controllers/px4/px4_sitl_wsl2.md ``` ```{toctree} :maxdepth: 2 -:caption: Code Structure +:caption: Autonomy -code_structure.md +autonomy/autonomy.md +autonomy/setup.md +autonomy/gym/gym_envs.md ``` ```{toctree} :maxdepth: 2 -:caption: APIs and Programmatic Control - -apis.md +:caption: Data Collection + +datacollection/data_generation.md +datacollection/config.md +datacollection/randomizations.md +datacollection/augmentations.md +datacollection/data_aggregation.md +datacollection/trajectory.md +datacollection/azure.md +datacollection/api.md ``` ```{toctree} :maxdepth: 2 -:caption: Controllers +:caption: Scene & Simulation -controllers/controllers.md -controllers/simple_flight.md -controllers/px4/px4.md -controllers/px4/px4_build.md -controllers/px4/px4_hitl.md -controllers/px4/px4_lockstep.md -controllers/px4/px4_multi_vehicle.md -controllers/px4/px4_sitl.md -controllers/px4/px4_sitl_wsl2.md +scene/sim_clock.md +scene/weather_visual_effects.md +development/scene/sim_clock_internal.md +physics/fast_physics.md +physics/matlab_physics.md ``` ```{toctree} :maxdepth: 2 -:caption: Settings +:caption: APIs & Programmatic Control + +api.md +ros/ros.md +``` ```{toctree} :maxdepth: 1 From fc279f2f1a781fe8ace41df12cbb20c06247dab5 Mon Sep 17 00:00:00 2001 From: aurebidart Date: Mon, 11 Aug 2025 15:31:47 -0300 Subject: [PATCH 2/4] Update sphinx-docs workflow --- .github/workflows/sphinx-docs.yml | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/.github/workflows/sphinx-docs.yml b/.github/workflows/sphinx-docs.yml index 8bc771ca..f17f2a5a 100644 --- a/.github/workflows/sphinx-docs.yml +++ b/.github/workflows/sphinx-docs.yml @@ -27,16 +27,19 @@ jobs: - name: Install dependencies for Python client docs working-directory: ./client/python/projectairsim/docs - run: | - pip install -r requirements.txt + run: pip install -r requirements.txt - name: Build Python client docs working-directory: ./client/python/projectairsim/docs - run: make html + run: | + rm -rf build + make html - name: Build main docs working-directory: ./docs - run: make html + run: | + rm -rf build + make html - name: Copy Python client docs into main docs run: | From e7539fac86bd6da58697c264703637734aee5bc8 Mon Sep 17 00:00:00 2001 From: aurebidart Date: Mon, 11 Aug 2025 15:39:44 -0300 Subject: [PATCH 3/4] Remove Autonomy and datacollection doc from index --- docs/index.md | 23 ----------------------- 1 file changed, 23 deletions(-) diff --git a/docs/index.md b/docs/index.md index 329f577c..70cb555a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -73,29 +73,6 @@ controllers/px4/px4_sitl.md controllers/px4/px4_sitl_wsl2.md ``` -```{toctree} -:maxdepth: 2 -:caption: Autonomy - -autonomy/autonomy.md -autonomy/setup.md -autonomy/gym/gym_envs.md -``` - -```{toctree} -:maxdepth: 2 -:caption: Data Collection - -datacollection/data_generation.md -datacollection/config.md -datacollection/randomizations.md -datacollection/augmentations.md -datacollection/data_aggregation.md -datacollection/trajectory.md -datacollection/azure.md -datacollection/api.md -``` - ```{toctree} :maxdepth: 2 :caption: Scene & Simulation From 8af3e3ef665310b8ecd11a242907e33c14c4bfbd Mon Sep 17 00:00:00 2001 From: aurebidart Date: Tue, 12 Aug 2025 12:35:29 -0300 Subject: [PATCH 4/4] Update links into documentation to be used with web doc --- .github/workflows/sphinx-docs.yml | 3 + build_docs.bat | 48 ----------- build_docs.sh | 21 ----- build_docs_external.bat | 33 -------- build_docs_external.sh | 31 ------- docs/command_line_switches.md | 2 +- docs/config_robot.md | 12 +-- docs/controllers/px4/px4_hitl.md | 8 +- docs/controllers/px4/px4_lockstep.md | 2 +- docs/controllers/px4/px4_multi_vehicle.md | 2 +- docs/controllers/px4/px4_sitl.md | 14 ++-- docs/controllers/simple_flight.md | 2 +- docs/development/scene/sim_clock_internal.md | 2 +- docs/development/use_source.md | 20 ++--- docs/ros/ros.md | 2 +- docs/transition_from_airsim.md | 10 +-- mkdocs.yml | 86 -------------------- mkdocs_external.yml | 79 ------------------ 18 files changed, 41 insertions(+), 336 deletions(-) delete mode 100644 build_docs.bat delete mode 100644 build_docs.sh delete mode 100644 build_docs_external.bat delete mode 100644 build_docs_external.sh delete mode 100644 mkdocs.yml delete mode 100644 mkdocs_external.yml diff --git a/.github/workflows/sphinx-docs.yml b/.github/workflows/sphinx-docs.yml index f17f2a5a..c5d03af3 100644 --- a/.github/workflows/sphinx-docs.yml +++ b/.github/workflows/sphinx-docs.yml @@ -14,6 +14,9 @@ jobs: - name: Checkout repository uses: actions/checkout@v4 + - name: Strip "docs/" prefixes from README + run: sed -i 's|docs/||g' README.md + - name: Set up Python uses: actions/setup-python@v5 with: diff --git a/build_docs.bat b/build_docs.bat deleted file mode 100644 index c789918f..00000000 --- a/build_docs.bat +++ /dev/null @@ -1,48 +0,0 @@ -REM Copyright (C) Microsoft Corporation. -REM Copyright (C) 2025 IAMAI CONSULTING CORP - -REM MIT License. - -@echo off -SETLOCAL - -REM python -m venv env -REM env\Scripts\activate.bat -REM python -m pip install mkdocs - -copy README.md docs\README.md - -REM Strip 'docs/' out of link/image paths in the README.md that was moved into -REM the docs subfolder for mkdocs. -SET find=(docs/ -SET replace=( - -REM Loop through lines but prepend [line #] to each line so the for loop doesn't -REM skip blank lines, then delimit on the ] to set s to the line contents. For -REM blank lines, echo a blank line to the output. -REM -REM To prevent the command processor from handling special characters like the -REM stream redirection operators, the line contents is quoted, processed, then -REM stripped of the outer quotes before appending to the file. -for /f "delims=] tokens=1*" %%a in ('type docs\README.md ^| find /v /n ""') do ( - SET s=%%b - if defined s ( - set s=" %%b " - call SET s=%%s:%find%=%replace%%% - - SETLOCAL ENABLEDELAYEDEXPANSION - echo !s:~2,-2! >> docs\temp_README.md - ENDLOCAL - ) else ( - echo: >> docs\temp_README.md - ) -) -move docs\temp_README.md docs\README.md - -mkdocs build - -copy docs\web.config build_docs - -REM Preview on localhost http://127.0.0.1:8000 - -if "%1" == "serve" mkdocs serve diff --git a/build_docs.sh b/build_docs.sh deleted file mode 100644 index 083664e1..00000000 --- a/build_docs.sh +++ /dev/null @@ -1,21 +0,0 @@ -#!/bin/bash -# Copyright (C) Microsoft Corporation. -# Copyright (C) 2025 IAMAI CONSULTING CORP -# MIT License. - -## Install mkdocs -# python3.7 -m venv env -# source env/bin/activate -# python3.7 -m pip install mkdocs - -cp README.md docs/ - -# find and replace "](docs/" by "](" -sed -i 's/](docs\//](/g' docs/README.md - -mkdocs build - -cp docs/web.config build_docs/ - -## Preview on localhost http://127.0.0.1:8000 -# mkdocs serve diff --git a/build_docs_external.bat b/build_docs_external.bat deleted file mode 100644 index 0899a7c2..00000000 --- a/build_docs_external.bat +++ /dev/null @@ -1,33 +0,0 @@ -REM Copyright (C) Microsoft Corporation. -REM Copyright (C) 2025 IAMAI CONSULTING CORP - -REM MIT License. - -@echo off -SETLOCAL - -REM python -m venv env -REM env\Scripts\activate.bat -REM python -m pip install mkdocs - -if exist build_docs_external_src ( - echo. - echo Deleting pre-existing build_docs_external_src_.. - echo. - del /f /s /q build_docs_external_src\* -) - -echo. -echo Rebuilding build_docs_external_src from docs... -robocopy docs build_docs_external_src /s /xd internal /nfl /ndl /np /njh - -echo. -echo Merging external-only files to build_docs_external_src... -robocopy docs_external build_docs_external_src /s /nfl /ndl /np /njh - -echo. -echo Building HTML files from docs_external... -mkdocs build -f mkdocs_external.yml - -REM Preview on localhost http://127.0.0.1:8000 -if "%1" == "serve" mkdocs serve -f mkdocs_external.yml diff --git a/build_docs_external.sh b/build_docs_external.sh deleted file mode 100644 index 7eeb89dd..00000000 --- a/build_docs_external.sh +++ /dev/null @@ -1,31 +0,0 @@ -#!/bin/bash -# Copyright (C) Microsoft Corporation. -# Copyright (C) 2025 IAMAI CONSULTING CORP -# MIT License. - -## Install mkdocs -# python3.7 -m venv env -# source env/bin/activate -# python3.7 -m pip install mkdocs - -echo Deleting pre-existing build_docs_external_src... -if [ -d build_docs_external_src ]; then - rm -rf build_docs_external_src -fi - -echo Rebuilding build_docs_external_src from docs... -cp -r docs build_docs_external_src -if [ -d build_docs_external_src/internal ]; then - rm -rf build_docs_external_src/internal -fi - -echo Merging docs_external files to build_docs_external_src... -if [ -d docs_external ]; then - cp -r docs_external/* build_docs_external_src/ -fi - -echo Building HTML files from build_docs_external_src... -mkdocs build -f mkdocs_external.yml - -## Preview on localhost http://127.0.0.1:8000 -# mkdocs serve -f mkdocs_external.yml diff --git a/docs/command_line_switches.md b/docs/command_line_switches.md index 4ed3112b..71317d26 100644 --- a/docs/command_line_switches.md +++ b/docs/command_line_switches.md @@ -15,7 +15,7 @@ Project AirSim supports the following command line switches. Since Project AirS | ‑nosound | Disable any sound output | | ‑benchmark | Enabled Unreal's benchmark mode that seems to remove any sleeps in between rendering/tick loops to run without limiting to any real-time execution rate FPS target (this mode needs further testing to confirm any side-effects and how it could be used properly) | | ‑gltfDir=dir/containing/tiles/ | If you'll be using a GIS scene, you can specify the directory to read the tiles from. Alternatively, if you're trying CesiumForUnreal you can provide the root tileset json file. | -| ‑clientauthpubkey=public_key | Specify a client authorization public key to require clients to present a client authorization token before being allowed to use the client API. Overrides the key set by the [PROJECTAIRSIM_CLIENT_AUTH_PUBKEY](#environment_variables) environment variable. | +| ‑clientauthpubkey=public_key | Specify a client authorization public key to require clients to present a client authorization token before being allowed to use the client API. Overrides the key set by the [PROJECTAIRSIM_CLIENT_AUTH_PUBKEY](#environment-variables) environment variable. | The below simulation parameters can also be changed through the comand line: diff --git a/docs/config_robot.md b/docs/config_robot.md index b1328cd8..554d16af 100644 --- a/docs/config_robot.md +++ b/docs/config_robot.md @@ -59,7 +59,7 @@ Project AirSim currently comes with some base configurations for quadrotor drone "physics-type": "unreal-physics" ``` -**[Unreal physics](internal/physics/unreal_physics.md)** uses the **[PhysX](https://developer.nvidia.com/gameworks-physx-overview)** engine that's built-in to Unreal. PhysX can calculate motion for multi-jointed robots with constraints on each joint, as well as rigid body dynamics for aerial drone flight. +**[Unreal physics](tbd)** uses the **[PhysX](https://docs.nvidia.com/gameworks/content/gameworkslibrary/physx/guide/Manual/Introduction.html)** engine that's built-in to Unreal. PhysX can calculate motion for multi-jointed robots with constraints on each joint, as well as rigid body dynamics for aerial drone flight. *Note: The simulation will automatically detect when any actor in the scene is configured to use Unreal Physics, and this will link the physics calculation step to Unreal's rendering step, so the [sim clock setting](config_scene.md#steppable-clock) for `step-ns` may need to be much slower (20 ms = ~50 FPS) to maintain reasonable simulation advancement rate.* @@ -415,7 +415,7 @@ For PX4 in WSL2, the value for `local-host-ip` can be found by running the comma | SITL Configuration | `control-port` | `control-port-remote` | `control-ip-address` | Notes | | ------------------ | -------------- | --------------------- | -------------------- | ----- | | Same computer | Usually `14540` | (Unassigned) | `127.0.0.1` | -| Different computer | (Ignored) | Usually `14580` | IP address of PX4 host | Use [MAVLink Router](https://docs.px4.io/master/en/simulation/#running-simulation-on-a-remote-server) running on the PX4 host. | +| Different computer | (Ignored) | Usually `14580` | IP address of PX4 host | Use [MAVLink Router](https://docs.px4.io/main/en/simulation/#running-simulation-on-a-remote-server) running on the PX4 host. | | PX4 in WSL2 | Usually `14540` | (Unassigned) | `remote` | In WSL2, set environment variable `PX4_SIM_HOST_ADDR` to Project AirSim host IP address. MAVLink Router is not used. When running PX4 on the same computer or in WSL2, PX4 connects to Project AirSim at UDP/IP port `control-port`. When running PX4 remotely, Project AirSim connects to PX4 at the UDP/IP port `control-port-remote`. @@ -468,10 +468,10 @@ The order and number of the actuator `id` tags depends on the airframe: | Project AirSim Airframe | Actuator Order | | -------- | -------------- | -| `quadrotor-x` | [Quadrotor-X order](https://docs.px4.io/master/en/airframes/airframe_reference.html#quadrotor-x) (front right, rear left, front left, rear right) | -| `hexarotor-x` | [Hexarotor-X order](https://docs.px4.io/master/en/airframes/airframe_reference.html#hexarotor-x) (front right, rear left, front left, rear right) | -| `vtol-quad-x-tailsitter` | \*[VTOL Quad Tailsitter order](https://docs.px4.io/master/en/airframes/airframe_reference.html#vtol-quad-tailsitter) (front right, rear left, front left, rear right, unused output port, elevon left, elevon right) -| `vtol-quad-tiltrotor` | \*[VTOL Tiltrotor order](https://docs.px4.io/master/en/airframes/airframe_reference.html#vtol-tiltrotor) (rotor outboard left, rotor inboard left, rotor inboard right, rotor outboard right, tilt outboard left, tilt inboard left, tilt inboard right, tilt outboard right, aileron left, aileron right, elevator, rudder) +| `quadrotor-x` | [Quadrotor-X order](https://docs.px4.io/main/en/airframes/airframe_reference.html#quadrotor-x) (front right, rear left, front left, rear right) | +| `hexarotor-x` | [Hexarotor-X order](https://docs.px4.io/main/en/airframes/airframe_reference.html#hexarotor-x) (front right, rear left, front left, rear right) | +| `vtol-quad-x-tailsitter` | \*[VTOL Quad Tailsitter order](https://docs.px4.io/main/en/airframes/airframe_reference.html#vtol-quad-tailsitter) (front right, rear left, front left, rear right, unused output port, elevon left, elevon right) +| `vtol-quad-tiltrotor` | \*[VTOL Tiltrotor order](https://docs.px4.io/main/en/airframes/airframe_reference.html#vtol-tiltrotor) (rotor outboard left, rotor inboard left, rotor inboard right, rotor outboard right, tilt outboard left, tilt inboard left, tilt inboard right, tilt outboard right, aileron left, aileron right, elevator, rudder) \**Note: The PX4 documentation does not currently show the correct order.* diff --git a/docs/controllers/px4/px4_hitl.md b/docs/controllers/px4/px4_hitl.md index 20097ce1..50504f4f 100644 --- a/docs/controllers/px4/px4_hitl.md +++ b/docs/controllers/px4/px4_hitl.md @@ -21,14 +21,14 @@ You must have one of the supported devices listed above. For manual flight simul 1. Make sure your RC receiver and RC transmitter are bound to each other. 2. Connect the receiver (the vehicle-based radio unit) to the PX4 flight controller's RC port. - Refer to your RC manual and [PX4 docs](https://docs.px4.io/en/getting_started/rc_transmitter_receiver.html) for more information. + Refer to your RC manual and [PX4 docs](https://docs.px4.io/main/en/getting_started/rc_transmitter_receiver.html) for more information. 2. Do not plug the PX4 flight controller device into your computer yet. 3. Download and install [QGroundControl](http://qgroundcontrol.com/). 4. Launch *QGroundControl* and go to the Vehicle Firmware Setup panel (click on the Ground Control logo, select the "Vehicle Setup" tool, then "Firmware" tab.) 5. Connect the PX4 flight controller device to a USB port on your computer. 6. *QGroundControl* should detect the PX4 hardware and offer to setup the firmware on the device. Select the "PX4 Pro Stable Release vx.xx.x" flight stack. -See also the [initial firmware setup video](https://docs.px4.io/master/en/config/). +See also the [initial firmware setup video](https://docs.px4.io/main/en/config/). 7. In *QGroundControl*, configure your PX4 flight controller device for HIL simulation by selecting under "Simulation (Copter)" the "HIL Quadrocopter X" airframe, then click "Apply and Restart" at the top. After the PX4 device reboots and *QGroundControl* reconnects to it, verify that "HIL Quadrocopter X" is still selected. For manual flight simulation, perform these additional steps: @@ -43,7 +43,7 @@ For manual flight simulation, perform these additional steps: Roll and pitch sensitivity | mid-3 mark Altitude and position control sensitivity | mid-2 mark -11. In the [robot configuration file](/config_robot.md), specify PX4 for your vehicle controller like this: +11. In the [robot configuration file](../../config_robot.md), specify PX4 for your vehicle controller like this: ```jsonc { ... @@ -76,7 +76,7 @@ You'll need to replace the "serial-port" entry's value of "serial device name" w After completing the above setup you should now be able to use *QGroundControl* to fly the vehicle in Project AirSim. If an RC transmitter and receiver are connected and configured through the additional setup steps for manual flight simulation, you can manually fly using the RC transmitter. With manual flight you don't need *QGroundControl* after the initial setup. You can usually arm the vehicle by lowering and bringing the two sticks of the RC transmitter together down and inwards. Typically the Stabilized flight mode (instead of Manual) gives a better experience for beginners. For more information see the [PX4 Basic Flying Guide](https://docs.px4.io/master/en/flying/basic_flying.html). -You can also control the drone with a Python script using [the Python APIs](/apis.md). +You can also control the drone with a Python script using [the Python APIs](../../api.md). --- diff --git a/docs/controllers/px4/px4_lockstep.md b/docs/controllers/px4/px4_lockstep.md index 5a1aa3d2..eb47a317 100644 --- a/docs/controllers/px4/px4_lockstep.md +++ b/docs/controllers/px4/px4_lockstep.md @@ -1,6 +1,6 @@ # PX4 Lockstep Mode -Recent versions of PX4 support a new [lockstep feature](https://docs.px4.io/master/en/simulation/#lockstep-simulation) when communicating with a simulator over TCP. `Lockstep` decouples the internal clocks of PX4 and the simulator from real-time and synchronizes them to each other so that both internal clocks advance together. This allows PX4 to behave normally even during unusually long delays in simulator updates. +Recent versions of PX4 support a new [lockstep feature](https://docs.px4.io/main/en/simulation/#lockstep-simulation) when communicating with a simulator over TCP. `Lockstep` decouples the internal clocks of PX4 and the simulator from real-time and synchronizes them to each other so that both internal clocks advance together. This allows PX4 to behave normally even during unusually long delays in simulator updates. It is recommended that when you are running a `lockstep`-enabled version of PX4 in SITL mode that you specify the controller settings within the robot configuration of Project AirSim to set `lock-step` to `true` and set `use-tcp` to `true`. diff --git a/docs/controllers/px4/px4_multi_vehicle.md b/docs/controllers/px4/px4_multi_vehicle.md index 9fda4e07..85d7c354 100644 --- a/docs/controllers/px4/px4_multi_vehicle.md +++ b/docs/controllers/px4/px4_multi_vehicle.md @@ -73,7 +73,7 @@ However, the provided script does not let us view the PX4 console. If you want t You can add more than two vehicles but you will need to make sure you adjust the TCP port for each (ie: vehicle 3's port would be `4562` and so on..) and adjust the spawn point. -4. Now run your client script loading the simulation scene and Project AirSim should connect to PX4 SITL instances via TCP. If you are running the instances with the [PX4 console visible](px4_multi_vehicle.md#Starting-sitl-instances-with-px4-console), you should see a bunch of messages from each PX4 SITL window. Specifically, the following messages tell you that AirSim is connected properly and GPS fusion is stable: +4. Now run your client script loading the simulation scene and Project AirSim should connect to PX4 SITL instances via TCP. If you are running the instances with the [PX4 console visible](px4_multi_vehicle.md), you should see a bunch of messages from each PX4 SITL window. Specifically, the following messages tell you that AirSim is connected properly and GPS fusion is stable: INFO [simulator] Simulator connected on UDP port 14560 INFO [mavlink] partner IP: 127.0.0.1 diff --git a/docs/controllers/px4/px4_sitl.md b/docs/controllers/px4/px4_sitl.md index ec07a2a4..03d4b0c0 100644 --- a/docs/controllers/px4/px4_sitl.md +++ b/docs/controllers/px4/px4_sitl.md @@ -12,7 +12,7 @@ All Project AirSim airframes are supported when using PX4 SITL. See [Starting a For manual flight simulation, you will also need a controller supported by your operating system such as an XBox game controller (see [Remote Controller](#remote-controller), below.) -The [PX4 software](http://dev.px4.io) provides a "software-in-loop" simulation (SITL) version of their stack that runs in natively in Linux. If you are on Windows then you can use the [Cygwin Toolchain](https://docs.px4.io/master/en/setup/dev_env_windows_cygwin.html). +The [PX4 software](https://docs.px4.io/main/en/development/development.html) provides a "software-in-loop" simulation (SITL) version of their stack that runs in natively in Linux. If you are on Windows then you can use the [Cygwin Toolchain](https://docs.px4.io/main/en/dev_setup/dev_env_windows_cygwin.html#windows-development-environment-cygwin-based). **Note:** Whenever you stop the Project AirSim Unreal application you must restart PX4 before you can begin another flight session with Project AirSim and PX4. See [Starting a New Flight Session](#starting-a-new-flight-session), below. @@ -20,7 +20,7 @@ The [PX4 software](http://dev.px4.io) provides a "software-in-loop" simulation ( Before setting up PX4, ensure that the Project AirSim [Client Setup](/client_setup.md) has been completed first. -On Windows, install the [Cygwin Toolchain](https://docs.px4.io/master/en/setup/dev_env_windows_cygwin.html). +On Windows, install the [Cygwin Toolchain](https://docs.px4.io/main/en/dev_setup/dev_env_windows_cygwin.html#windows-development-environment-cygwin-based). 1. Follow the steps through cloning the repository. You may skip the example step to run JMAVSim. 2. In the PX4 console window (started by `run-console.bat`), navigate into the PX4-Autopilot repo directory if not there already: @@ -39,13 +39,13 @@ On Windows, install the [Cygwin Toolchain](https://docs.px4.io/master/en/setup/d Note that this may take a while. PX4 will automatically start at the end of the build. -Proceed to [The First Flight Session](#the-first-a-flight-session), below. +Proceed to [The First Flight Session](#the-first-flight-session), below. ### Setup the PX4 build environment for Linux Before setting up PX4, ensure that the Project AirSim [Client Setup](/client_setup.md) has been completed first. -For reference, the official setup steps for PX4 on Linux [are here.](https://docs.px4.io/master/en/dev_setup/dev_env_linux_ubuntu.html) Follow the instructions for [Gazebo, JMAVSim and NuttX (Pixhawk) Targets](https://docs.px4.io/master/en/dev_setup/dev_env_linux_ubuntu.html#gazebo-jmavsim-and-nuttx-pixhawk-targets). +For reference, the official setup steps for PX4 on Linux [are here.](https://docs.px4.io/main/en/dev_setup/dev_env_linux_ubuntu.html) Follow the instructions for [Gazebo, JMAVSim and NuttX (Pixhawk) Targets](https://docs.px4.io/main/en/dev_setup/dev_env_linux_ubuntu.html#gazebo-jmavsim-and-nuttx-pixhawk-targets). The following steps are the Linux-relevant parts from [our own version of the PX4 build instructions](px4_build.md) which is a bit more concise about what we need exactly: @@ -69,7 +69,7 @@ The following steps are the Linux-relevant parts from [our own version of the PX Note that this may take a while. PX4 will automatically start at the end of the build. -Proceed to [The first flight session](#the-first-a-flight-session), below. +Proceed to [The first flight session](#the-first-flight-session), below. ## The first flight session 1. You should see a message saying the SITL PX4 app is waiting for the simulator (Project AirSim) to connect. You will also see information about which ports are configured for a MAVLink connection to the PX4 app. @@ -298,7 +298,7 @@ To start a flight session, start PX4 by running the same command to build it: ## Remote controller -*QGroundControl* enables manual flight in Project AirSim using a remote control or joystick-like game controller (such as an Xbox game controller) connected to your PC. See [*QGroundControl* Joystick Setup](https://docs.qgroundcontrol.com/master/en/SetupView/Joystick.html) for more information. +*QGroundControl* enables manual flight in Project AirSim using a remote control or joystick-like game controller (such as an Xbox game controller) connected to your PC. See [*QGroundControl* Joystick Setup](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/setup_view/joystick.html#joystick-setup) for more information. ## Advanced PX4 SITL configurations @@ -309,7 +309,7 @@ See [Multi-vehicle simulation with PX4](px4_multi_vehicle.md). ### Running PX4 remotely -PX4 SITL is usually run on the same computer as Project AirSim but it is possible to run PX4 on separate computer. See [Running Simulation on a Remote Server](https://docs.px4.io/v1.testing/en/simulation/#running-simulation-on-a-remote-server) in the PX4 documentation. +PX4 SITL is usually run on the same computer as Project AirSim but it is possible to run PX4 on separate computer. See [Running Simulation on a Remote Server](https://docs.px4.io/main/en/simulation/#running-simulation-on-a-remote-server) in the PX4 documentation. In Project AirSim, put the IP address of the remote computer running PX4 into the `control-ip-address` parameter of the `controller/px4-settings` section in the [robot configuration settings](../../config_robot.md#PX4_communication_port_settings). diff --git a/docs/controllers/simple_flight.md b/docs/controllers/simple_flight.md index 716a43c5..86894c08 100644 --- a/docs/controllers/simple_flight.md +++ b/docs/controllers/simple_flight.md @@ -21,7 +21,7 @@ To use Simple Flight to fly a robot programmatically with a Python mission scrip 6. (Optional) Disarm the vehicle with `projectairsim.Drone.disarm()` 7. (Optional) Disable API control with `projectairsim.Drone.disable_api_control()` -To use Simple Flight to fly a robot manually with a manual controller like an Xbox game controller, see [Using an Xbox controller](#using-an-xbox-game-controller), below. +To use Simple Flight to fly a robot manually with a manual controller like an Xbox game controller, see [Using an Xbox controller](#using-an-xbox-controller), below. ## Using an Xbox controller diff --git a/docs/development/scene/sim_clock_internal.md b/docs/development/scene/sim_clock_internal.md index aeaf0409..68223809 100644 --- a/docs/development/scene/sim_clock_internal.md +++ b/docs/development/scene/sim_clock_internal.md @@ -46,7 +46,7 @@ When you want the simulation to advance only when commanded to do so via a call #### #3 - Use Unreal Physics with the option to pause/resume, do manual step control (but can't scale with real-time) -If any robot actors in a scene are configured to use the **[Unreal's Physics](../physics/unreal_physics.md)** system, the physics update will be done in step with rendering the scene and each iteration of the simulation loop (and each advance of sim-time) will take longer. +If any robot actors in a scene are configured to use the **[Unreal's Physics](tbd)** system, the physics update will be done in step with rendering the scene and each iteration of the simulation loop (and each advance of sim-time) will take longer. The **same `steppable` clock settings can be used** as in non-Unreal Physics scenarios, but if `step-ns` is left set to a very small time step, such as 3 ms, the simulation will advance much slower than real-time due to the rendering occuring at each 3 ms sim-time step. diff --git a/docs/development/use_source.md b/docs/development/use_source.md index abbc614c..82f2e088 100644 --- a/docs/development/use_source.md +++ b/docs/development/use_source.md @@ -1,6 +1,6 @@ # Build From Source as a Developer -For many usage scenarios, **[Using Pre-built Binary Environments](use_prebuilt.md)** or **[Using Project AirSim Plugin in Custom Environments](../use_plugin.md)** is enough to get a simulation up and running. The main development would then be done by setting up the **[Config JSON Settings](../config.md)** and using the **[Project AirSim Client](../client_setup.md)** and **[APIs](../api.md)** to drive the simulation for the particular usage application. +For many usage scenarios, **[Using Pre-built Binary Environments](use_prebuilt)** or **[Using Project AirSim Plugin in Custom Environments](../use_plugin)** is enough to get a simulation up and running. The main development would then be done by setting up the **[Config JSON Settings](../config)** and using the **[Project AirSim Client](../client_setup)** and **[APIs](../api)** to drive the simulation for the particular usage application. If deeper customization or extending new features is needed, building the Project AirSim framework from source can be done through the process described below. @@ -39,11 +39,11 @@ projectairsim ## Initial developer setup -Project AirSim can be developed using Windows 10/Server 2019 or Ubuntu 20.04 Linux. See **[System Specifications](../system_specs.md)** for more details. +Project AirSim can be developed using Windows 10/Server 2019 or Ubuntu 20.04 Linux. See **[System Specifications](../system_specs)** for more details. For details on getting your dev environment set up, choose your platform: -- **[Developer Initial Setup for Windows](dev_setup_win.md)** -- **[Developer Initial Setup for Linux](dev_setup_linux.md)** +- **[Developer Initial Setup for Windows](dev_setup_win)** +- **[Developer Initial Setup for Linux](dev_setup_linux)** --- @@ -51,9 +51,9 @@ For details on getting your dev environment set up, choose your platform: Choose your development tool: -- **[Command Line (Windows/Linux)](#command-line-(windows/linux))** -- **[VS Code (Windows/Linux)](#vs-code-(windows/linux))** -- **[Visual Studio 2019 (Windows only)](#visual-studio-2019-(windows-only))** +- **[Command Line (Windows/Linux)](#command-line-windows-linux)** +- **[VS Code (Windows/Linux)](#vs-code-windows-linux)** +- **[Visual Studio 2019 (Windows only)](#visual-studio-2019-windows-only)** **Note:** Project AirSim sim libs uses CMake which saves build configuration information in a cache, so **if you switch tools** between using command line, VS Code, or Visual Studio 2019 to drive the CMake project in the same folder, you should **clear the cache** by running `build clean` so the next tool can reset the configuration and build again properly. @@ -216,7 +216,7 @@ To develop using a multi-root workspace project file, follow the steps below: Sometimes this is faster to use than the `BlocksEditor` targets for development iteration because it doesn't load all of the Editor overhead on each launch. However, the Editor can be convenient for repeatedly starting/stopping play of the simulation while debugging the same build. -10. **See **[Developing Project AirSim Client Library](#developing-projectairsim-client-library)** for the next steps of interacting with the Blocks simulation through the Python client.** +10. **See **[Developing Project AirSim Client Library](#developing-project-airsim-sim-libs)** for the next steps of interacting with the Blocks simulation through the Python client.** --- @@ -310,7 +310,7 @@ However, it is possible to use Visual Studio to do both in a single project by f Sometimes this is faster to use than the `...Editor` targets for development iteration because it doesn't load all of the Editor overhead on each launch. However, the Editor can be convenient for repeatedly starting/stopping play of the simulation while debugging the same build. -10. **See **[Developing Project AirSim Client Library](#developing-projectairsim-client-library)** for the next steps of interacting with the Blocks simulation through the Python client.** +10. **See **[Developing Project AirSim Client Library](#developing-project-airsim-sim-libs)** for the next steps of interacting with the Blocks simulation through the Python client.** --- @@ -320,7 +320,7 @@ However, it is possible to use Visual Studio to do both in a single project by f 2. Launch the Blocks simulation and start play. -3. Switch to `projectairsim/python` directory using a command line with an activated Python environment that was set up during the **[Project AirSim Client Setup](../client_setup.md)**. +3. Switch to `projectairsim/python` directory using a command line with an activated Python environment that was set up during the **[Project AirSim Client Setup](../client_setup)**. 4. Start executing a client script to load the simulation configured in step 1 and interact with the simulation. diff --git a/docs/ros/ros.md b/docs/ros/ros.md index c3497217..393067a2 100644 --- a/docs/ros/ros.md +++ b/docs/ros/ros.md @@ -192,7 +192,7 @@ The script will load a simulation scene and fly the drone from the launch pad to ## Examples -Samples of using the Project AirSim ROS Bridge are provided in the `ros/examples` directory. See [Project AirSim ROS Bridge Examples](ros_examples.md) for more information. +Samples of using the Project AirSim ROS Bridge are provided in the `ros/examples` directory. --- diff --git a/docs/transition_from_airsim.md b/docs/transition_from_airsim.md index 706e5fcf..cae0f9cb 100644 --- a/docs/transition_from_airsim.md +++ b/docs/transition_from_airsim.md @@ -21,7 +21,7 @@ To convert an existing AirSim Unreal environment to Project AirSim, you can perf "Enabled": true }, -3. Add Project AirSim to the environment following **[How to add the Project AirSim Plugin to a custom Unreal environment](use_plugin.md#how-to-add-the-airsim-v-next-plugin-to-a-custom-unreal-environment)**, including the part about setting the `GameMode` to `AirSimVNextGameMode` since `AirSimGameMode` is no longer valid. +3. Add Project AirSim to the environment following **[How to add the Project AirSim Plugin to a custom Unreal environment](use_plugin)**, including the part about setting the `GameMode` to `AirSimVNextGameMode` since `AirSimGameMode` is no longer valid. 4. On first opening of the `.uproject` file with Unreal Engine 4.25, there may be some warnings about failing to load some AirSim content such as: @@ -57,9 +57,9 @@ General guidelines to update your environment to SunSky: ## Converting an AirSim OSS configuration to Project AirSim -Refer to the [documentation on configuration](config.md) for information about Project AirSim's configuration files and what settings are available. +Refer to the [documentation on configuration](config) for information about Project AirSim's configuration files and what settings are available. -The following is a rough guide on how to handle each element from the AirSim OSS configuration in Project AirSim. Some items are introduced without highlighting their position in the Project AirSim configuration hierarchy. Refer to the [documentation](config.md) to know the exact positions of each configuration item. +The following is a rough guide on how to handle each element from the AirSim OSS configuration in Project AirSim. Some items are introduced without highlighting their position in the Project AirSim configuration hierarchy. Refer to the [documentation](config) to know the exact positions of each configuration item. **"SimMode":** @@ -150,7 +150,7 @@ Not needed. **"RC":** -Not selected through config. See the [remote control guide](controllers/simple_flight#using-an-xbox-controller) for information on how to set up a remote controller with Project Airsim. +Not selected through config. See the [remote control guide](controllers/simple_flight) for information on how to set up a remote controller with Project Airsim. **"X", "Y", "Z", "Yaw", "Roll", "Pitch":** @@ -328,7 +328,7 @@ Project Airsim's client does not automatically set up the environment from a `se world = World(client, "scene_config.jsonc") ``` -Note that the file path is relative to `.\sim_config` where `.` is the location of the script. For information on writing scene configuration files see the [Scene Configuration Settings documentation](config_scene.md). +Note that the file path is relative to `.\sim_config` where `.` is the location of the script. For information on writing scene configuration files see the [Scene Configuration Settings documentation](config_scene). To take control of a drone, initialize it using the name it has in the config. diff --git a/mkdocs.yml b/mkdocs.yml deleted file mode 100644 index cd1cea5e..00000000 --- a/mkdocs.yml +++ /dev/null @@ -1,86 +0,0 @@ -site_name: Project AirSim -site_dir: build_docs -site_description: 'Simulator for autonomous vehicles from Microsoft' -site_url: '' -use_directory_urls: false - -markdown_extensions: - - toc: - permalink: "#" - - projectairsimpp: - include_paths: ".;docs_includes/common;docs_includes/internal" - -theme: - name: 'readthedocs' -extra: - highlightjs: true - version: 1.0.0 - feature: - tabs: true - -nav: - - "Overview": - - "Project AirSim Intro": 'README.md' - - "Changelog": 'changelog.md' - - "System Specs": 'system_specs.md' - - "Getting Started": - - "Using Binaries": 'internal/use_prebuilt.md' - - "Using Project AirSim Plugin": 'use_plugin.md' - - "Building From Source": 'internal/use_source.md' - - "Running Headless": 'internal/headless_cloud.md' - - "Transitioning from AirSim": 'transition_from_airsim.md' - - "Project AirSim Client Setup": - - "Client Setup": 'client_setup.md' - - "Developer Setup": - - "Setup for Windows": 'internal/dev_setup_win.md' - - "Setup for Linux": 'internal/dev_setup_linux.md' - - "VS Code Settings": 'internal/vscode_user_settings.md' - - "Configuration Settings": - - "Config Overview": 'config.md' - - "Scene Settings": 'config_scene.md' - - "Robot Settings": 'config_robot.md' - - "Project AirSim API": - - "API Overview": 'api.md' - - "ROS Integration": - - "ROS Bridge": 'ros/ros.md' - - "ROS Bridge Examples": 'ros/ros_examples.md' - - "build_map Example": 'ros/example_build_map.md' - - "navigate_map Example": 'ros/example_navigate_map.md' - - "Autonomy Blocks": - - "Autonomy Blocks Setup": 'autonomy/setup.md' - - "Autonomy Building-Blocks": 'autonomy/autonomy.md' - - "Autonomy Gym": 'autonomy/gym/gym_envs.md' - - "Controllers": - - "Flight Controllers": 'controllers/controllers.md' - - "Simple Flight Controller": 'controllers/simple_flight.md' - - "PX4 Flight Controller": 'controllers/px4/px4.md' - - "Using PX4 as SITL": 'controllers/px4/px4_sitl.md' - - "Using PX4 as SITL in WSL 2": 'controllers/px4/px4_sitl_wsl2.md' - - "Using PX4 as HITL": 'controllers/px4/px4_hitl.md' - - "Building PX4": 'controllers/px4/px4_build.md' - - "PX4 Lockstep Mode": 'controllers/px4/px4_lockstep.md' - - "PX4 with Multiple Robots": 'controllers/px4/px4_multi_vehicle.md' - - "Sensors": - - "Camera": 'sensors/camera_capture_settings.md' - - "Camera Streaming": 'sensors/camera_streaming.md' - - "Display": 'internal/sensors/display.md' - - "Lidar": 'sensors/lidar.md' - - "Radar": 'sensors/radar.md' - - "Segmentation": 'sensors/segmentation.md' - - "Scene": - - "Simulation Clock": 'internal/scene/sim_clock_internal.md' - - "Weather Visual Effects": 'scene/weather_visual_effects.md' - - "Physics": - - "Fast Physics": 'physics/fast_physics.md' - - "Unreal Physics": 'internal/physics/unreal_physics.md' - - "Multiple Robots": - - "Multiple Robots": 'multiple_robots.md' - - "Customizing Robots": - - "Physical": 'modify_drone_physical.md' - - "Visual": 'modify_drone_visual.md' - - "Runtime Options": - - "Command Line Switches": 'command_line_switches.md' - - "Support": - - "Obtaining Support": 'support.md' - - "FAQ": 'faq.md' - - "License": 'license.md' diff --git a/mkdocs_external.yml b/mkdocs_external.yml deleted file mode 100644 index 4d518700..00000000 --- a/mkdocs_external.yml +++ /dev/null @@ -1,79 +0,0 @@ -site_name: Project AirSim -site_dir: build_docs_external -docs_dir: build_docs_external_src -site_description: 'Simulator for autonomous vehicles from Microsoft' -site_url: '' -use_directory_urls: false - -markdown_extensions: - - toc: - permalink: "#" - - projectairsimpp: - include_paths: ".;docs_includes/common;docs_includes/external" - -theme: - name: 'readthedocs' -extra: - highlightjs: true - version: 1.0.0 - feature: - tabs: true - -nav: - - "Overview": - - "Project AirSim Intro": 'README.md' - - "Changelog": 'changelog.md' - - "System Specs": 'system_specs.md' - - "Getting Started": - - "Project AirSim EAP Quickstart": 'eap_quickstart.md' - - "Using Project AirSim Plugin": 'use_plugin.md' - - "Transitioning from AirSim": 'transition_from_airsim.md' - - "Project AirSim Client Setup": - - "Client Setup": 'client_setup.md' - - "Configuration Settings": - - "Config Overview": 'config.md' - - "Scene Settings": 'config_scene.md' - - "Robot Settings": 'config_robot.md' - - "Project AirSim API": - - "API Overview": 'api.md' - - "ROS Integration": - - "ROS Bridge": 'ros/ros.md' - - "ROS Bridge Examples": 'ros/ros_examples.md' - - "build_map Example": 'ros/example_build_map.md' - - "navigate_map Example": 'ros/example_navigate_map.md' - - "Autonomy Blocks": - - "Autonomy Blocks Setup": 'autonomy/setup.md' - - "Autonomy Building-Blocks": autonomy/autonomy.md - - "Autonomy Gym": 'autonomy/gym/gym_envs.md' - - "Controllers": - - "Flight Controllers": 'controllers/controllers.md' - - "Simple Flight Controller": 'controllers/simple_flight.md' - - "PX4 Flight Controller": 'controllers/px4/px4.md' - - "Using PX4 as SITL": 'controllers/px4/px4_sitl.md' - - "Using PX4 as SITL in WSL 2": 'controllers/px4/px4_sitl_wsl2.md' - - "Using PX4 as HITL": 'controllers/px4/px4_hitl.md' - - "Building PX4": 'controllers/px4/px4_build.md' - - "PX4 Lockstep Mode": 'controllers/px4/px4_lockstep.md' - - "PX4 with Multiple Robots": 'controllers/px4/px4_multi_vehicle.md' - - "Sensors": - - "Camera": 'sensors/camera_capture_settings.md' - - "Camera Streaming": 'sensors/camera_streaming.md' - - "Lidar": 'sensors/lidar.md' - - "Radar": 'sensors/radar.md' - - "Segmentation": 'sensors/segmentation.md' - - "Scene": - - "Simulation Clock": 'scene/sim_clock.md' - - "Weather Visual Effects": 'scene/weather_visual_effects.md' - - "Physics": - - "Fast Physics": 'physics/fast_physics.md' - - "Multiple Robots": - - "Multiple Robots": 'multiple_robots.md' - - "Customizing Robots": - - "Physical": 'modify_drone_physical.md' - - "Visual": 'modify_drone_visual.md' - - "Runtime Options": - - "Command Line Switches": 'command_line_switches.md' - - "Support": - - "Obtaining Support": 'support.md' - - "FAQ": 'faq.md' - - "License": 'license.md'