castacks · andrewjong · Nov 16, 2024 · Nov 15, 2024 · Nov 15, 2024 · Nov 15, 2024
diff --git a/docs/about.md b/docs/about.md
@@ -3,4 +3,12 @@
 This stack is built and maintained by the [AirLab](https://theairlab.org) at Carnegie Mellon University's Robotics Institute. 
 
 # License
-Not sure yet but probably Apache 2.0 or MIT for the open source parts.
+Not sure yet but probably Apache 2.0 or MIT for the open source parts.
+
+# FAQ
+
+!!! question "Phasellus posuere in sem ut cursus"
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
diff --git a/docs/development/create_new_project.md b/docs/development/create_new_project.md
@@ -0,0 +1,28 @@
+# Create a New Project
+
+
+## Option 1: Generate from Template (no further updates from upstream)
+The AirStack repository is setup as a [Template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template) on GitHub.
+This makes it easy to create a new project from AirStack with the "Use this template" button.
+
+![template-button](github_template_button.png)
+
+
+However, generating from a template squashes the entire git history into a single starter commit in your new repository. 
+This prevents pulling in updates from the AirStack repository in the future.
+
+To be able to pull upstream changes from the AirStack repository, use option 2.
+
+## Option 2: Duplicate (for future updates from upstream)
+
+Duplicating a repository preserves the entire history of the repository, making it easier to pull in updates from AirStack in the future.
+Unlike creating a fork, duplicating a repository allows your new repository to be private.
+
+See GitHub's instructions to [duplicate a repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/duplicating-a-repository).
+
+Sample commands are provided below:
+```bash
+git clone --bare https://github.com/castacks/AirStack.git my-airstack
+cd my-airstack
+git push --mirror https://github.com/EXAMPLE-USER/my-airstack.git
+```
diff --git a/docs/development/docker_usage.md b/docs/development/docker_usage.md
@@ -1,8 +1,6 @@
 # General Usage with Docker Compose
 
-AirStack is designed for multi-robot development, and is setup to run multiple robots in simulation.
-
-To mimic interacting with real world robots, we use Docker Compose to manage Docker containers that isolate the simulation, each robot, and the ground control station.
+To mimic interacting with multiple real world robots, we use Docker Compose to manage Docker containers that isolate the simulation, each robot, and the ground control station.
 
 The details of the docker compose setup is in `AirStack/docker-compose.yaml`.
 

diff --git a/docs/development/github_template_button.png b/docs/development/github_template_button.png
diff --git a/docs/getting_started.md b/docs/getting_started.md
@@ -18,7 +18,8 @@ git clone --recursive -j8 git@github.com:castacks/AirStack.git
 
 ### Docker
 
-Install [Docker Desktop](https://docs.docker.com/desktop/install/ubuntu/). This should come installed with docker compose.
+Follow [NVIDIA's instructions](https://docs.nvidia.com/ai-enterprise/deployment/vmware/latest/docker.html) for installing Docker to be compatible with NVIDIA GPUs, including adding the NVIDIA Container Toolkit.
+Make sure `docker-compose-plugin` is also installed with Docker.
 
 ## Configure
 

diff --git a/...obot/autonomy/airstack_system_diagram.png → docs/robot/airstack_system_diagram.png b/...obot/autonomy/airstack_system_diagram.png → docs/robot/airstack_system_diagram.png
diff --git a/docs/robot/autonomy/0_interface/index.md b/docs/robot/autonomy/0_interface/index.md
@@ -1,4 +1,4 @@
-# Interface
+# Robot Interface
 
 The interface defines the communication between the autonomy stack running on the onboard computer and the robot's control unit.
 For example, for drones it converts the control commands from the autonomy stack into MAVLink messages for the flight controller.

diff --git a/docs/robot/autonomy/1_sensors/index.md b/docs/robot/autonomy/1_sensors/index.md
@@ -1 +1,8 @@
-We'll fill this with different things like the ZED-X package, LiDAR, etc
+We'll fill this with different things like the ZED-X package, LiDAR, etc
+
+
+## Launch
+Launch files are under `src/robot/autonomy/sensors/sensors_bringup/launch`.
+
+The main launch command is `ros2 launch sensors_bringup sensors.launch.xml`.
+
diff --git a/docs/robot/autonomy/2_perception/index.md b/docs/robot/autonomy/2_perception/index.md
@@ -6,4 +6,12 @@ Perception modules typically output topics in image space or point cloud space.
 Common perception modules include:
 
 - semantic segmentation
-- VIO (Visual Inertial Odometry)
+- VIO (Visual Inertial Odometry)
+
+
+
+## Launch
+Launch files are under `src/robot/autonomy/perception/perception_bringup/launch`.
+
+The main launch command is `ros2 launch perception_bringup perception.launch.xml`.
+
diff --git a/docs/robot/autonomy/3_local/controls.md b/docs/robot/autonomy/3_local/controls.md
diff --git a/docs/robot/autonomy/3_local/controls/index.md b/docs/robot/autonomy/3_local/controls/index.md
@@ -0,0 +1,7 @@
+# Controls
+
+Controls dictate the actuation of the robot. They are responsible for taking in sensor data and producing control commands. 
+
+The controller should publish control commands directly to topics defined by the [Robot Interface](../../0_interface/index.md).
+
+Currently the AirStack uses a custom controller called "Trajectory Controller".
diff --git a/docs/robot/autonomy/3_local/index.md b/docs/robot/autonomy/3_local/index.md
@@ -0,0 +1,8 @@
+# Local Packages
+The local module includes packages that are specific to the local autonomy of the robot. This includes local mapping, planning, and control.
+
+## Launch
+Launch files are under `src/robot/autonomy/local/local_bringup/launch`.
+
+The main launch command is `ros2 launch local_bringup local.launch.xml`.
+
diff --git a/docs/robot/autonomy/3_local/planning.md → .../robot/autonomy/3_local/planning/index.md b/docs/robot/autonomy/3_local/planning.md → .../robot/autonomy/3_local/planning/index.md
diff --git a/docs/robot/autonomy/3_local/world_model.md → ...bot/autonomy/3_local/world_model/index.md b/docs/robot/autonomy/3_local/world_model.md → ...bot/autonomy/3_local/world_model/index.md
diff --git a/docs/robot/autonomy/4_global/index.md b/docs/robot/autonomy/4_global/index.md
@@ -0,0 +1,10 @@
+# Global Packages
+
+The global packages include global world models and planners.
+
+
+## Launch
+Launch files are under `src/robot/autonomy/global/global_bringup/launch`.
+
+The main launch command is `ros2 launch global_bringup global.launch.xml`.
+
diff --git a/...t/autonomy/4_global/global_trajectory.png → ...y/4_global/planning/global_trajectory.png b/...t/autonomy/4_global/global_trajectory.png → ...y/4_global/planning/global_trajectory.png
diff --git a/docs/robot/autonomy/4_global/planning.md → ...robot/autonomy/4_global/planning/index.md b/docs/robot/autonomy/4_global/planning.md → ...robot/autonomy/4_global/planning/index.md
@@ -1,4 +1,5 @@
-# Global Planning
+[//]: # "global"
+# Planning
 
 ![global_trajectory_diagram](global_trajectory.png)
 

diff --git a/docs/robot/autonomy/4_global/world_model.md b/docs/robot/autonomy/4_global/world_model.md
diff --git a/docs/robot/autonomy/4_global/world_model/index.md b/docs/robot/autonomy/4_global/world_model/index.md
@@ -0,0 +1,6 @@
+[//]: # "global"
+# World Model
+
+Global world models are responsible for maintaining a representation of the world that is used by the global planner to generate a plan. This representation is typically a map of the environment, but can also include other information such as the location of other robots, obstacles, and goals.
+
+The current placeholder world model is a voxelized map representation called [VDB Mapping](https://github.com/fzi-forschungszentrum-informatik/vdb_mapping_ros2).
diff --git a/docs/robot/autonomy/5_behavior/index.md b/docs/robot/autonomy/5_behavior/index.md
@@ -0,0 +1,8 @@
+# Behavior
+The behavior module is responsible for the high-level decision making of the robot. This includes deciding what actions to take based on the current state of the robot and the world around it. The behavior module is responsible for coordinating the actions of the local and global modules to achieve the robot's goals.
+
+## Launch
+Launch files are under `src/robot/autonomy/behavior/behavior_bringup/launch`.
+
+The main launch command is `ros2 launch behavior_bringup behavior.launch.xml`.
+
diff --git a/docs/robot/autonomy/mapping.md b/docs/robot/autonomy/mapping.md
diff --git a/docs/robot/autonomy/perception.md b/docs/robot/autonomy/perception.md
diff --git a/docs/robot/common_topics.md b/docs/robot/common_topics.md
@@ -0,0 +1,11 @@
+
+
+
+
+| Topic                          | Type              | Description                                                                                                                             |
+| -------------------------------| ------------------| ---------------------------------------------------------------------------------------------------------------------------|
+| `/$ROBOT_NAME/odometry`        | [nav_msgs/Odometry](https://docs.ros.org/en/rolling/p/nav_msgs/interfaces/msg/Odometry.html) | Best estimate of robot odometry
+| `/$ROBOT_NAME/global_plan`     | [nav_msgs/Path](https://docs.ros.org/en/rolling/p/nav_msgs/interfaces/msg/Path.html)     | Current target global trajectory for the robot to follow. See [global planning](4_global/planning.md) for more details.
+
+## System Diagram
+![AirStack System Diagram](airstack_system_diagram.png)
diff --git a/docs/simulation/isaac_sim/export_stages_from_unreal.md b/docs/simulation/isaac_sim/export_stages_from_unreal.md
@@ -0,0 +1,38 @@
+# Export Unreal Engine to Isaac Sim
+
+A robot needs a scene to interact in. A scene can be created in any 3D modeling program, though we have found it easiest to export stages from Unreal Engine. This document explains how to export an Unreal Engine environment to an Isaac Sim stage, then how to convert the stage to a physics-enabled scene. 
+
+
+## Exporting Unreal Engine Environments to Isaac Sim Stages
+Generally, Unreal Engine environments can be found on Epic Games' [Fab Marketplace](https://www.fab.com/). For example, the [Open World Demo Collection](https://www.fab.com/listings/3262ab8f-f64a-4124-8efd-82cb19df6249) is a free collection of outdoor environments.
+
+
+The below video explains how to export an Unreal Engine environment to an Isaac Sim stage.
+
+<iframe width="840" height="473" src="https://www.youtube.com/embed/y9qP7wcinHM?si=i5TVd1CFbJUYhWz7" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+
+You can save this file as `[YOUR_ENVIRONMENT_NAME].stage.usd`.
+
+
+### Export Tips
+
+**Complexity:**
+Generally, it works best to export levels that are designed for UE4.27 and below. The advanced rendering features from UE5, i.e. nanite and lumen, aren't compatible with Omniverse. 
+If the level is optimized for the older UE4, then it's more compatible.
+
+Omniverse doesn't perform well with large amounts of vegetation. Anything with complex vegetation takes a long long time to load. Procedural foliage doesn't export well either. Simple geometries like buildings and rocks work better. 
+
+That said you can still achieve photorealism by substituting complex geometries for high quality textures. Isaac seems to do fine with high quality textures.
+
+**Optimization:** After exporting, edit the file with [USD Composer](https://docs.omniverse.nvidia.com/composer/latest/index.html) and run the [Scene Optimizer extension](https://docs.omniverse.nvidia.com/extensions/latest/ext_scene-optimizer.html) for faster performance. USD Composer can be installed via [Omniverse Launcher](https://docs.omniverse.nvidia.com/launcher/latest/index.html).
+
+**Verify the Scale:**  The Omniverse exporter exports in centimeters, but Isaac Sim natively works in meters. For consistency, follow these steps to [change the scene units to be meters](https://forums.developer.nvidia.com/t/how-to-change-units-of-the-grid-from-centimeters-to-meters/301285#:~:text=Find%20the%20%E2%80%9CMeters%20Per%20Unit%E2%80%9D%20property%20and%20set%20it%20to%201%20for%20meters).
+
+To check the scale of the scene, you can add a cube in Isaac Sim and compare it to the exported scene. The cube is 1m x 1m x 1m.
+
+## Turn a Stage into a Physics-Enabled Scene
+
+Adding physics to the stage is as simple as adding a `Physics` property with the "Colliders Preset", as described in the [Isaac docs](https://docs.omniverse.nvidia.com/isaacsim/latest/gui_tutorials/tutorial_intro_simple_objects.html#adding-physics-properties).
+Then save the scene as `[YOUR_ENVIRONMENT_NAME].scene.usd` to clarify that it's a physics-enabled scene.
+
+You're now ready to add robots to the scene on the next page.
diff --git a/docs/simulation/isaac_sim/index.md b/docs/simulation/isaac_sim/index.md
@@ -1 +1,20 @@
-# Isaac Sim
+# Isaac Sim
+
+The primary simulator we support is [NVIDIA Isaac Sim](https://docs.omniverse.nvidia.com/isaacsim/latest/index.html). 
+We chose Isaac Sim as the best balance between photorealism and physics simulation.
+
+
+## USD File Naming Conventions
+AirStack uses the following file naming conventions:
+
+**Purely 3D graphics**
+
+- `*.prop.usd` ⟵ simply a 3D model with materials, typically encompassing just a single object. Used for individual assets or objects (as mentioned earlier), representing reusable props.
+
+- `*.stage.usd` ⟵ an environment composed of many props, but with no physics, no simulation, no robots. simply scene graphics
+
+**Simulation-ready**
+
+- `*.robot.usd` ⟵ a prop representing a robot plus ROS2 topic and TF publishers, physics, etc.
+
+- `*.scene.usd` ⟵ an environment PLUS physics, simulation, or robots
diff --git a/docs/simulation/isaac_sim/scene_setup.md b/docs/simulation/isaac_sim/scene_setup.md
@@ -1,13 +1,14 @@
+# AirStack Scene Setup
 
-## Creating a New Scene
+## Creating a New Scene with Robots
 The easiest way is to reference and copy an existing scene.
 
 ## ROS Publishers Through OmniGraph
 
 
 ### Configure Robot Name, ROS_DOMAIN_ID, and Topic Namespaces
 
-Under the Spirit drone prim is an `Omnigraph` component. This component is used to configure the ROS publishers for the robot. The `Omnigraph` component has the following fields:
+Under the Spirit drone prim is an `ActionGraph` component, which is an [Omnigraph](https://docs.omniverse.nvidia.com/extensions/latest/ext_omnigraph.html). This component is used to configure the ROS publishers for the robot. The `ActionGraph` component has the following fields to configure:
 
 - `robot_name`: The name of the robot. This is used as the top-level namespace for ROS topics.
 - `domain_id`: The ROS domain ID. This is used as the `ROS_DOMAIN_ID` for DDS networking.
@@ -19,6 +20,8 @@ The Omnigraph has subgraphs for each ROS publisher type. For example, TFs, Image
 
 ### Customizing the Omnigraph
 
-Common ROS graphs may be added through the top menu bar: `Isaac Utils > Common Graphs > ROS`.
+Common pre-built graphs for ROS may be added through the top menu bar: `Isaac Utils > Common OmniGraphs`.
+This is helpful for creating various sensor publishers.
 
-We recommend copying them into the top-level `Omnigraph` component. Connect the `robot_name` and `domain_id` fields to your workflow. Then, select all the nodes in your workflow, right-click, and create a subgraph.
+We recommend organizing your work into sub-graphs.
+Copy your omnigraph template them into the top-level `Omnigraph` component, named "ActionGraph". Connect the `robot_name` and `domain_id` fields to your workflow. Then, select all the nodes in your workflow, right-click, and create a subgraph.