Add more docs

utiasDSL · Oct 17, 2024 · d2ebb67 · d2ebb67
1 parent 8d87df9
commit d2ebb67
Show file tree

Hide file tree

Showing 25 changed files with 150 additions and 23 deletions.
diff --git a/docs/challenge/deployment.rst b/docs/challenge/deployment.rst
@@ -1,2 +1,36 @@
 Deployment
-==========
+==========
+
+The idea for the deployment is to have an environment that exactly matches the interfaces and observation space of the simulation. Since the action space for the controller is identical, controllers can be directly deployed on the real drone without any modifications.
+
+.. warning::
+    Please be aware that running a controller on the real drone may still exhibit significant differences compared to the simulation due to the sim2real gap.
+
+Motion Tracking
+~~~~~~~~~~~~~~~
+We use a Vicon motion tracking system to track the motion of the drone. The Vicon system consists of several cameras that are placed around the track, and a base station that calculates object poses by triangulation. Gates, obstacles and the drone are all equipped with reflective markers, which can be tracked by the cameras. We use the Vicon bridge from ETH's ASL to send the poses into ROS.
+
+Deploying Your Controller
+~~~~~~~~~~~~~~~~~~~~~~~~~
+To deploy your controller on the real drone, use the deployment script in the ``lsy_drone_racing/scripts`` folder. Before running the script, make sure to set the correct drone parameters in the Crazyswarm package. Place the drone on its start position, power it on, and launch the Crazyswarm ROS node with 
+
+.. code-block:: bash
+
+    roslaunch crazyswarm hover_swarm.launch
+
+.. note::
+    Make sure the drone has enough battery to complete the track. If a red LED is constantly turned on, the drone is low on battery. A blinking red LED indicates that the battery is sufficiently charged.
+
+.. note::
+    You should restart the drone after every flight to reset the internal state estimators and its command mode.
+
+.. warning::
+    Only turn on the drone once you placed it on the start position. The internal sensors of the drone are reset on power-on, and turning it on while you are still moving it around may cause internal estimators to drift.
+
+This should open up an RViz window with the drone frame and the world frame. You can now launch your controller by running
+
+.. code-block:: bash
+
+    python scripts/deploy_controller.py --controller <controller_name>
+
+The deployment script will first check if the real track poses and the drone starting pose is within acceptable bounds of the configured track. If not, the script will print an error message and terminate. If the poses are correct, the drone will take off, fly through the track, print out the final lap time, and land automatically.
diff --git a/docs/challenge/overview.rst b/docs/challenge/overview.rst
@@ -1,2 +1,19 @@
 Overview
-========
+========
+
+Welcome to the LSY Drone Racing Project! This is a platform developed by the LSY Lab at the Technical University of Munich for testing and developing autonomous drone racing algorithms in simulation and deploy the same controller without any modification on real drones. You are not restricted to any specific algorithm, as long as your interfaces are compatible with our predefined controller interface.
+
+The Drone
+~~~~~~~~~
+We use the Crazyflie nano quadcopter for our challenge. It is a small, low-cost drone that is easy to program and control. You can find more information about the drone at https://www.bitcraze.io/. Crazyflies have the advantage of being fully open-source and having a large community, which makes it easy to find libraries and tools for programming and controlling the drone. Furthermore, their low price reduces the barrier to entry for participants, and the loss of a drone during the competition is less painful.
+
+The Track
+~~~~~~~~~
+Contrary to other drone racing challenges, we not only include gates in our tracks, but also obstacles designed to be avoided by the drones. The current iteration uses four gates and four obstacles. Gates have to be traversed in the correct order and in the correct direction. Passing a gate in the opposite direction will not count as a successful pass.
+
+Project Goals
+~~~~~~~~~~~~~
+The goal of the project is to develop a controller that can navigate the drone through the track with the least possible time on a real Crazyflie drone. As previously mentioned, controllers have to be compatible with the predefined interface. Once you have designed a controller and verified its performance and safety in simulation, you can deploy it on the real hardware.
+
+.. warning::
+    While the interfaces are the same and we take great care to ensure that the simulation faithfully reproduces the real-world behavior of the drones, running a controller on the real drone is significantly different from running it in simulation. Be aware that unexpected behavior might occur, depending on the actual drone and the used controller, and further extensive tuning and testing may be necessary.
diff --git a/docs/conf.py b/docs/conf.py
@@ -27,7 +27,7 @@
 
 # Mock imports on ReadTheDocs that are not available with pip
 if on_rtd:
-    autodoc_mock_imports = ["pycffirmware"]
+    autodoc_mock_imports = ["pycffirmware", "rospy", "rosgraph", "pycrazyswarm", "stable_baselines3", "tf2_msgs"]
 
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/control/controller.rst b/docs/control/controller.rst
@@ -1,5 +1,5 @@
-Controller
-==========
+control.controller
+==================
 
 .. automodule:: lsy_drone_racing.control.controller
     :members:

diff --git a/docs/control/index.rst b/docs/control/index.rst
@@ -1,3 +1,8 @@
+lsy_drone_racing.control
+========================
+
+.. automodule:: lsy_drone_racing.control
+
 .. toctree::
     :hidden:
 

diff --git a/docs/control/ppo_controller.rst b/docs/control/ppo_controller.rst
@@ -1,5 +1,5 @@
-PPO Controller
-==============
+control.ppo_controller
+======================
 
 .. automodule:: lsy_drone_racing.control.ppo_controller
     :members:

diff --git a/docs/control/trajectory_controller.rst b/docs/control/trajectory_controller.rst
@@ -1,5 +1,5 @@
-Trajectory Controller
-======================
+control.trajectory_controller
+=============================
 
 .. automodule:: lsy_drone_racing.control.trajectory_controller
     :members:

diff --git a/docs/envs/drone_racing_deploy_env.rst b/docs/envs/drone_racing_deploy_env.rst
@@ -0,0 +1,5 @@
+envs.drone_racing_deploy_env
+============================
+
+.. automodule:: lsy_drone_racing.envs.drone_racing_deploy_env
+    :members:
diff --git a/docs/envs/drone_racing_env.rst b/docs/envs/drone_racing_env.rst
@@ -0,0 +1,5 @@
+envs.drone_racing_env
+=====================
+
+.. automodule:: lsy_drone_racing.envs.drone_racing_env
+    :members:
diff --git a/docs/envs/index.rst b/docs/envs/index.rst
@@ -0,0 +1,10 @@
+lsy_drone_racing.envs
+=====================
+
+.. automodule:: lsy_drone_racing.envs
+
+.. toctree::
+    :hidden:
+
+    drone_racing_env
+    drone_racing_deploy_env
diff --git a/docs/index.rst b/docs/index.rst
@@ -34,6 +34,8 @@ Docs are work in progress. Please check back later.
 
    utils/index
 
+   vicon
+
 
 Indices and tables
 ==================

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,2 +1 @@
 sphinx-book-theme==1.1.2
-stable-baselines3==2.3.0  # Required for PPO example controller
diff --git a/docs/sim/drone.rst b/docs/sim/drone.rst
@@ -1,5 +1,5 @@
-Drone
-=====
+sim.drone
+=========
 
 .. automodule:: lsy_drone_racing.sim.drone
     :members:

diff --git a/docs/sim/index.rst b/docs/sim/index.rst
@@ -1,3 +1,8 @@
+lsy_drone_racing.sim
+=====================
+
+.. automodule:: lsy_drone_racing.sim
+
 .. toctree::
     :hidden:
 

diff --git a/docs/sim/noise.rst b/docs/sim/noise.rst
@@ -1,5 +1,5 @@
-Noise
-=====
+sim.noise
+=========
 
 .. automodule:: lsy_drone_racing.sim.noise
     :members:

diff --git a/docs/sim/physics.rst b/docs/sim/physics.rst
@@ -1,5 +1,5 @@
-Physics
-=======
+sim.physics
+===========
 
 .. automodule:: lsy_drone_racing.sim.physics
     :members:
diff --git a/docs/sim/sim.rst b/docs/sim/sim.rst
@@ -1,5 +1,5 @@
-Sim
-===
+sim.sim
+=======
 
 .. automodule:: lsy_drone_racing.sim.sim
     :members:
diff --git a/docs/sim/symbolic.rst b/docs/sim/symbolic.rst
@@ -1,5 +1,5 @@
-Symbolic Model
-==============
+sim.symbolic
+============
 
 .. automodule:: lsy_drone_racing.sim.symbolic
     :members:
diff --git a/docs/utils/import_utils.rst b/docs/utils/import_utils.rst
@@ -0,0 +1,5 @@
+utils.import_utils
+==================
+
+.. automodule:: lsy_drone_racing.utils.import_utils
+    :members:
diff --git a/docs/utils/index.rst b/docs/utils/index.rst
@@ -0,0 +1,11 @@
+lsy_drone_racing.utils
+======================
+
+.. automodule:: lsy_drone_racing.utils
+
+.. toctree::
+    :hidden:
+
+    utils
+    ros_utils
+    import_utils
diff --git a/docs/utils/ros_utils.rst b/docs/utils/ros_utils.rst
@@ -0,0 +1,5 @@
+utils.ros_utils
+===============
+
+.. automodule:: lsy_drone_racing.utils.ros_utils
+    :members:
diff --git a/docs/utils/utils.rst b/docs/utils/utils.rst
@@ -0,0 +1,5 @@
+utils.utils
+===========
+
+.. automodule:: lsy_drone_racing.utils.utils
+    :members:
diff --git a/docs/vicon.rst b/docs/vicon.rst
@@ -0,0 +1,5 @@
+lsy_drone_racing.vicon
+======================
+
+.. automodule:: lsy_drone_racing.vicon
+    :members:
diff --git a/lsy_drone_racing/envs/__init__.py b/lsy_drone_racing/envs/__init__.py
@@ -1,4 +1,17 @@
-"""Register environments."""
+"""This module contains the environments for the drone racing challenge.
+
+Environments are split into simulation and real-world environments. The simulation environments use
+the simulation module to provide a realistic simulation of the drone racing challenge for training,
+testing and iterating on controller designs. The real-world environments mirror the interface of the
+simulation environments, but use the Vicon motion capture system to track the drone and race track
+elements in the lab, and sent the controller actions to the real drone.
+
+Note:
+    While the interfaces are the same and we try to keep the environments as similar as possible,
+    the dynamics of the drone and all observations are subject to a sim2real gap. The transition
+    between simulation and real-world may therefore require additional tuning of the controller
+    design.
+"""
 
 from gymnasium import register
 

diff --git a/lsy_drone_racing/envs/drone_racing_deploy_env.py b/lsy_drone_racing/envs/drone_racing_deploy_env.py
@@ -5,9 +5,10 @@
 :mod:~lsy_drone_racing.envs.drone_racing module.
 
 Key components:
-1. DroneRacingDeployEnv: A Gymnasium environment for controlling a real Crazyflie drone in a
+
+- :class:~.DroneRacingDeployEnv: A Gymnasium environment for controlling a real Crazyflie drone in a
    physical race track, using Vicon motion capture for positioning.
-2. DroneRacingThrustDeployEnv: A variant of DroneRacingDeployEnv that uses collective thrust
+- :class:~.DroneRacingThrustDeployEnv: A variant of DroneRacingDeployEnv that uses collective thrust
    and attitude commands for control.
 
 These environments maintain consistent interfaces with their simulation counterparts
-Original file line number
+Diff line change
@@ Expand Up / @@ -34,6 +34,8 @@ Docs are work in progress. Please check back later. @@
        utils/index
+       vicon
     Indices and tables
     ==================
@@ Expand Down @@
Original file line number	Diff line number	Diff line change
		@@ -1,2 +1 @@
		sphinx-book-theme==1.1.2
		stable-baselines3==2.3.0 # Required for PPO example controller