diff --git a/docs/about.md b/docs/about.md index 414cd30b1..e76a86fdf 100644 --- 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. \ No newline at end of file +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. \ No newline at end of file diff --git a/docs/development/create_new_project.md b/docs/development/create_new_project.md new file mode 100644 index 000000000..f018b7e61 --- /dev/null +++ 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 index 87576b568..528443d93 100644 --- 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 new file mode 100644 index 000000000..a86694f8b Binary files /dev/null and b/docs/development/github_template_button.png differ diff --git a/docs/getting_started.md b/docs/getting_started.md index f2f56abd6..f57e5b24b 100644 --- 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/docs/robot/autonomy/airstack_system_diagram.png b/docs/robot/airstack_system_diagram.png similarity index 100% rename from docs/robot/autonomy/airstack_system_diagram.png rename to docs/robot/airstack_system_diagram.png diff --git a/docs/robot/autonomy/0_interface/index.md b/docs/robot/autonomy/0_interface/index.md index 43afef5c8..342b39a8a 100644 --- 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 index 13cdd61d4..eb1958fba 100644 --- 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 \ No newline at end of file +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 index 557d41a08..ca70232de 100644 --- 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) \ No newline at end of file +- 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 deleted file mode 100644 index 10b80ab9b..000000000 --- a/docs/robot/autonomy/3_local/controls.md +++ /dev/null @@ -1,53 +0,0 @@ -# Local Controls - -The controller should publish control commands directly to topics defined by the [Robot Interface](../0_interface/robot_interface.md). - -## Trajectory Controller - -### Overview - -The trajectory controller takes in a trajectory and publishes a tracking point, which a controller should make the drone fly to, and a look ahead point, which a planner should plan from. The trajectory controller can interpret a trajectory as a standalone complete track, like a figure eight or racetrack pattern for tuning controls, or as separate segments that should be stitched together, for example trajectories output by a local planner. - -The trajectory controller tries to keep the tracking point ahead of the robot in a pure pursuit fashion. The robot's position, the red X in the figure below, is projected onto the trajectory. A sphere, shown in 2d as the cyan circle, is placed around this projected point and the intersection between the sphere and the forward point on the trajectory is used as the tracking point, the blue X. The lookahead point, the orange X, is a fixed time duration along the trajectory. - -![Trajectory Controller](trajectory_controller.png) - -### Modes - -There are several modes that the trajectory controller can be placed in with a service call to the `set_trajectory_mode` service: - -#### TRACK - -This interprets a trajectory published on `trajectory_override` as a complete trajectory that the controller will follow. It is usually used for taking off, landing, and tuning controls on fixed trajectories like figure eights, racetracks, circles, etc... - -#### ADD_SEGMENT - -This interprets a trajectory published on `trajectory_segment_to_add` as a segment of a trajectory which will get stitched onto the current trajectory at the closest point to the start of the new segment. This is usually published by a local planner. Ideally it is published at the location of the lookahead point, which is a fixed time ahead of the tracking point. This fixed time should be greater than the time it takes to plan. For example, if the lookahead point is one second ahead of the tracking point, the local planner should be always take less than one second to plan otherwise the tracking point would already be past the start of the plan. If this happens, the trajectory will fail to be stitched and will be ignored. - -#### PAUSE - -This causes the tracking point to stop where it is. - -#### REWIND - -This makes the tracking point go backwards along the trajectory. This mode is usually used to make the drone blindly backtrack along its trajectory to get it out of a situation it is stuck in. - -#### ROBOT_POSE - -This makes the tracking point and lookahead point always be at the same position as the drone's odometry. This is useful for before takeoff, when the robot may be carried around so that the location where the takeoff starts is at the drone's position. - -### PARAMS - -- `tf_prefix` - The tf names published are prefixed with the string in this parameter. Tfs are published at the tracking point and lookahead point. There are stabilized version, the same but with zero pitch and roll, of these two tfs that are also published. - -- `target_frame` - The tracking point and lookahead point are published in this frame. - -- `look_ahead_time` - How far ahead of the tracking point the lookahead point will be in seconds. - -- `min_virtual_tracking_velocity` - If the velocity on the trajectory is less than this, the tracking point will just move forward in time instead of using the sphere to keep the tracking point ahead of the drone. The units are m/s. - -- `sphere_radius` - This is the radius of the sphere used to determine the position of the tracking point. Making it larger pushes the tracking point farther ahead. - -- `search_ahead_factor` - To search for the point on the trajectory that intersects with the sphere, the algorithm checks a certain distance ahead along the trajectory. This distance is given by `sphere_radius * search_ahead_factor`. If the trajectory zig zags a lot relative to the size of the sphere its possible that the algorithm wouldn't iterate far enough along the trajectory to find the point where it intersects with the sphere. If a large value for this parameter is used it and the trajectory loops back on itself, it is possible that this would cause the tracking point to jump ahead and skip a porition of the trajectory. In almost all cases, this parameter shouldn't need to be changed. - -- `traj_vis_thickness` - The thickness of the trajectory visualization markers. diff --git a/docs/robot/autonomy/3_local/controls/index.md b/docs/robot/autonomy/3_local/controls/index.md new file mode 100644 index 000000000..aab25f865 --- /dev/null +++ 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 index e69de29bb..cae708c0e 100644 --- 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 b/docs/robot/autonomy/3_local/planning/index.md similarity index 100% rename from docs/robot/autonomy/3_local/planning.md rename to docs/robot/autonomy/3_local/planning/index.md diff --git a/docs/robot/autonomy/3_local/world_model.md b/docs/robot/autonomy/3_local/world_model/index.md similarity index 100% rename from docs/robot/autonomy/3_local/world_model.md rename to docs/robot/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 index e69de29bb..eaffb424b 100644 --- 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/docs/robot/autonomy/4_global/global_trajectory.png b/docs/robot/autonomy/4_global/planning/global_trajectory.png similarity index 100% rename from docs/robot/autonomy/4_global/global_trajectory.png rename to docs/robot/autonomy/4_global/planning/global_trajectory.png diff --git a/docs/robot/autonomy/4_global/planning.md b/docs/robot/autonomy/4_global/planning/index.md similarity index 99% rename from docs/robot/autonomy/4_global/planning.md rename to docs/robot/autonomy/4_global/planning/index.md index 07ab015d4..ba0aa1a49 100644 --- a/docs/robot/autonomy/4_global/planning.md +++ b/docs/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 deleted file mode 100644 index eb0bac393..000000000 --- a/docs/robot/autonomy/4_global/world_model.md +++ /dev/null @@ -1 +0,0 @@ -# Global World Model \ No newline at end of file diff --git a/docs/robot/autonomy/4_global/world_model/index.md b/docs/robot/autonomy/4_global/world_model/index.md new file mode 100644 index 000000000..7d1feb6cf --- /dev/null +++ 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). \ No newline at end of file diff --git a/docs/robot/autonomy/5_behavior/index.md b/docs/robot/autonomy/5_behavior/index.md index e69de29bb..17bf102f6 100644 --- 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 deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/robot/autonomy/perception.md b/docs/robot/autonomy/perception.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/robot/common_topics.md b/docs/robot/common_topics.md new file mode 100644 index 000000000..c18d5b8cc --- /dev/null +++ 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) \ No newline at end of file diff --git a/docs/simulation/isaac_sim/export_stages_from_unreal.md b/docs/simulation/isaac_sim/export_stages_from_unreal.md new file mode 100644 index 000000000..610378c0c --- /dev/null +++ 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. + + + +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. \ No newline at end of file diff --git a/docs/simulation/isaac_sim/index.md b/docs/simulation/isaac_sim/index.md index 9ef2e30d2..365097eb9 100644 --- a/docs/simulation/isaac_sim/index.md +++ b/docs/simulation/isaac_sim/index.md @@ -1 +1,20 @@ -# Isaac Sim \ No newline at end of file +# 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 \ No newline at end of file diff --git a/docs/simulation/isaac_sim/scene_setup.md b/docs/simulation/isaac_sim/scene_setup.md index adb00c95d..b35980e7f 100644 --- a/docs/simulation/isaac_sim/scene_setup.md +++ b/docs/simulation/isaac_sim/scene_setup.md @@ -1,5 +1,6 @@ +# 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 @@ -7,7 +8,7 @@ The easiest way is to reference and copy an existing scene. ### 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. \ No newline at end of file +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. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 6462752a8..98986a38e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,12 @@ --- copyright: Copyright © 2024 - 2030 AirLab CMU +docs_dir: . +site_name: AirStack +site_dir: ../site +exclude_docs: | + **/ros_ws/build + **/ros_ws/install + **/kit-app-template/** extra: generator: false social: @@ -31,75 +38,82 @@ markdown_extensions: - toc: permalink: true nav: - - Home: README.md - - Getting Started: getting_started.md + - Home: docs/README.md + - Getting Started: docs/getting_started.md - Development: - - development/index.md - - development/docker_usage.md - - development/vscode/index.md + - docs/development/index.md + - docs/development/docker_usage.md + - docs/development/vscode/index.md - Testing: - - development/testing/index.md - - development/testing/testing_frameworks.md - - development/testing/integration_testing.md - - development/testing/unit_testing.md - - development/testing/system_testing.md - - development/testing/ci_cd.md - - Contributing: development/contributing.md - - ROS Frame Conventions: development/frame_conventions.md + - docs/development/testing/index.md + - docs/development/testing/testing_frameworks.md + - docs/development/testing/integration_testing.md + - docs/development/testing/unit_testing.md + - docs/development/testing/system_testing.md + - docs/development/testing/ci_cd.md + - docs/development/contributing.md + - docs/development/frame_conventions.md - Robot: - - robot/index.md + - docs/robot/index.md + - docs/robot/common_topics.md - Autonomy Modules: - - robot/autonomy/index.md - - Interface: - - robot/autonomy/0_interface/index.md + - Robot Interface: + - docs/robot/autonomy/0_interface/index.md - Sensors: - - robot/autonomy/1_sensors/index.md + - docs/robot/autonomy/1_sensors/index.md - Perception: - - robot/autonomy/2_perception/index.md - - robot/autonomy/2_perception/state_estimation.md + - docs/robot/autonomy/2_perception/index.md + - docs/robot/autonomy/2_perception/state_estimation.md - Local: - - robot/autonomy/3_local/index.md - - World Model: robot/autonomy/3_local/world_model.md - - Planning: robot/autonomy/3_local/planning.md - - Controls: robot/autonomy/3_local/controls.md + - docs/robot/autonomy/3_local/index.md + - World Model: + - docs/robot/autonomy/3_local/world_model/index.md + - Planning: + - docs/robot/autonomy/3_local/planning/index.md + - Controls: + - docs/robot/autonomy/3_local/controls/index.md + - robot/ros_ws/src/autonomy/3_local/c_controls/trajectory_controller/README.md - Global: - - robot/autonomy/4_global/index.md - - World Model: robot/autonomy/4_global/world_model.md - - Planning: robot/autonomy/4_global/planning.md + - docs/robot/autonomy/4_global/index.md + - World Model: + - docs/robot/autonomy/4_global/world_model/index.md + - robot/ros_ws/src/autonomy/global/a_world_models/vdb_mapping_ros2/README.md + - Planning: + - docs/robot/autonomy/4_global/planning/index.md + - robot/ros_ws/src/autonomy/4_global/b_planners/random_walk/README.md - Behavior: - - robot/autonomy/5_behavior/index.md - - Behavior Tree: robot/autonomy/5_behavior/behavior_tree.md - - Behavior Executive: robot/autonomy/5_behavior/behavior_executive.md + - docs/robot/autonomy/5_behavior/index.md + - docs/robot/autonomy/5_behavior/behavior_tree.md + - docs/robot/autonomy/5_behavior/behavior_executive.md - Static Transforms: - - robot/static_transforms/index.md + - docs/robot/static_transforms/index.md - Logging: - - robot/logging/index.md + - docs/robot/logging/index.md - Ground Control Station: - - ground_control_station/index.md + - docs/ground_control_station/index.md - Usage: - - ground_control_station/usage/user_interface.md + - docs/ground_control_station/usage/user_interface.md - Multi-Robot: - - ground_control_station/multi_robot/multi_robot.md + - docs/ground_control_station/multi_robot/multi_robot.md - Simulation: - - simulation/index.md + - docs/simulation/index.md - Isaac Sim: - - simulation/isaac_sim/index.md - - Scene Setup: simulation/isaac_sim/scene_setup.md - - Ascent SITL Extension: simulation/isaac_sim/ascent_sitl_extension.md - - Gazebo: - - simulation/gazebo/scene_setup.md + - docs/simulation/isaac_sim/index.md + - docs/simulation/isaac_sim/export_stages_from_unreal.md + - docs/simulation/isaac_sim/scene_setup.md + - docs/simulation/isaac_sim/ascent_sitl_extension.md - Real World: - - real_world/index.md + - docs/real_world/index.md - Installation on Hardware: - - real_world/installation/index.md - - About: about.md + - docs/real_world/installation/index.md + - About: docs/about.md plugins: - search + - same-dir repo_name: castacks/AirStack repo_url: https://github.com/castacks/AirStack -site_name: AirLab Autonomy Stack theme: - favicon: assets/StackedWhite.png + favicon: docs/assets/StackedWhite.png features: - navigation.indexes - navigation.path @@ -113,17 +127,17 @@ theme: - toc.integrate - toc.follow - content.code.copy - logo: assets/logo_horizontal_white.png + logo: docs/assets/logo_horizontal_white.png name: material palette: - accent: pink - primary: '#CC002B' + primary: custom scheme: default toggle: icon: material/brightness-7 name: Switch to dark mode - accent: pink - primary: '#CC002B' + primary: custom scheme: slate toggle: icon: material/brightness-4 diff --git a/robot/ros_ws/src/autonomy/3_local/c_controls/trajectory_controller/README.md b/robot/ros_ws/src/autonomy/3_local/c_controls/trajectory_controller/README.md new file mode 100644 index 000000000..844909fc3 --- /dev/null +++ b/robot/ros_ws/src/autonomy/3_local/c_controls/trajectory_controller/README.md @@ -0,0 +1,58 @@ +# Trajectory Controller + +## Overview + +The trajectory controller takes in a trajectory and publishes a tracking point, which a controller should make the drone fly to, and a look ahead point, which a planner should plan from. The trajectory controller can interpret a trajectory as a standalone complete track, like a figure eight or racetrack pattern for tuning controls, or as separate segments that should be stitched together, for example trajectories output by a local planner. + +The trajectory controller tries to keep the tracking point ahead of the robot in a pure pursuit fashion. The robot's position, the red X in the figure below, is projected onto the trajectory. A sphere, shown in 2d as the cyan circle, is placed around this projected point and the intersection between the sphere and the forward point on the trajectory is used as the tracking point, the blue X. The lookahead point, the orange X, is a fixed time duration along the trajectory. + +![Trajectory Controller](trajectory_controller.png) + +# Parameters +|
Parameter
| Description +|----------------------------|--------------------------------------------------------------- +| `tf_prefix` | The tf names published are prefixed with the string in this parameter. Tfs are published at the tracking point and lookahead point. There are stabilized versions, the same but with zero pitch and roll, of these two tfs that are also published. | +| `target_frame` | The tracking point and lookahead point are published in this frame. | +| `look_ahead_time` | How far ahead of the tracking point the lookahead point will be in seconds. | +| `min_virtual_tracking_velocity` | If the velocity on the trajectory is less than this, the tracking point will just move forward in time instead of using the sphere to keep the tracking point ahead of the drone. The units are m/s. | +| `sphere_radius` | This is the radius of the sphere used to determine the position of the tracking point. Making it larger pushes the tracking point farther ahead. | +| `search_ahead_factor` | To search for the point on the trajectory that intersects with the sphere, the algorithm checks a certain distance ahead along the trajectory. This distance is given by `sphere_radius * search_ahead_factor`. If the trajectory zigzags a lot relative to the size of the sphere, it's possible that the algorithm wouldn't iterate far enough along the trajectory to find the point where it intersects with the sphere. If a large value for this parameter is used and the trajectory loops back on itself, it is possible that this would cause the tracking point to jump ahead and skip a portion of the trajectory. In almost all cases, this parameter shouldn't need to be changed. | +| `traj_vis_thickness` | The thickness of the trajectory visualization markers. | +# Services + +## Trajectory Modes + +There are several modes that the trajectory controller can be placed in with a service call to the `set_trajectory_mode` service: +See TrajectoryMode.srv. + +| Mode | Description | +| ------------------------------| -------------------------------------------------------------------------------------------------------------------------| +| **TRACK** | This interprets a trajectory subscribed on `~/trajectory_override` as a complete trajectory that the controller will follow. It is usually used for taking off, landing, and tuning controls on fixed trajectories like figure eights, racetracks, circles, etc... +| **ADD_SEGMENT** | This interprets a trajectory subscribed on `~/trajectory_segment_to_add` as a segment of a trajectory which will get stitched onto the current trajectory at the closest point to the start of the new segment. This is usually published by a local planner. Ideally it is published at the location of the lookahead point, which is a fixed time ahead of the tracking point. This fixed time should be greater than the time it takes to plan. For example, if the lookahead point is one second ahead of the tracking point, the local planner should be always take less than one second to plan otherwise the tracking point would already be past the start of the plan. If this happens, the trajectory will fail to be stitched and will be ignored. +| **PAUSE** | This causes the tracking point to stop where it is. +| **REWIND** | This makes the tracking point go backwards along the trajectory. This mode is usually used to make the drone blindly backtrack along its trajectory to get it out of a situation it is stuck in. +| **ROBOT_POSE** | This makes the tracking point and lookahead point always be at the same position as the drone's odometry. This is useful for before takeoff, when the robot may be carried around so that the location where the takeoff starts is at the drone's position. + +# Subscriptions +|
Topic
| Type | Description | +| ----------------------------------| ------------------| ---------------------------------------------------------------------------------------------------------------------------| +| `~/odometry` | [nav_msgs/Odometry](https://docs.ros.org/en/rolling/p/nav_msgs/interfaces/msg/Odometry.html) | Odometry of the robot. +| `~/trajectory_segment_to_add` | [airstack_msgs/TrajectoryXYZVYaw](/common/ros_packages/airstack_msgs/srv/TrajectoryMode.srv) | For **ADD_SEGMENT** mode, this is the trajectory segment to add to the current trajectory. +| `~/trajectory_override` | [airstack_msgs/TrajectoryXYZVYaw](/common/ros_packages/airstack_msgs/srv/TrajectoryMode.srv) | For **TRACK** mode, this overrides the current trajectory and makes the robot follow this directly. + + +# Publications +|
Topic
| Type | Description | +| -------------------------------------| ------------------| ---------------------------------------------------------------------------------------------------------------------------| +| `~/tracking_point` | TODO | TODO +| `~/look_ahead` | TODO | TODO +| `~/traj_drone_point` | TODO | TODO +| `~/virtual_tracking_point` | TODO | TODO +| `~/closest_point` | TODO | TODO +| `~/trajectory_completion_percentage` | TODO | TODO +| `~/trajectory_time` | TODO | TODO +| `~/tracking_error` | TODO | TODO +| `~/velocity_pub` | TODO | TODO +| `~/debug_markers` | TODO | TODO +| `~/trajectory_vis` | TODO | TODO + diff --git a/docs/robot/autonomy/3_local/trajectory_controller.png b/robot/ros_ws/src/autonomy/3_local/c_controls/trajectory_controller/trajectory_controller.png similarity index 100% rename from docs/robot/autonomy/3_local/trajectory_controller.png rename to robot/ros_ws/src/autonomy/3_local/c_controls/trajectory_controller/trajectory_controller.png diff --git a/robot/ros_ws/src/autonomy/4_global/b_planners/random_walk/README.md b/robot/ros_ws/src/autonomy/4_global/b_planners/random_walk/README.md new file mode 100644 index 000000000..c79f6019d --- /dev/null +++ b/robot/ros_ws/src/autonomy/4_global/b_planners/random_walk/README.md @@ -0,0 +1 @@ +# Random Walk Global Planner Baseline \ No newline at end of file diff --git a/docs/stylesheets/extra.css b/stylesheets/extra.css similarity index 70% rename from docs/stylesheets/extra.css rename to stylesheets/extra.css index 312f2436b..c87744e86 100644 --- a/docs/stylesheets/extra.css +++ b/stylesheets/extra.css @@ -3,4 +3,7 @@ --md-primary-fg-color--light: #ECB7B7; --md-primary-fg-color--dark: #90030C; } - \ No newline at end of file + + [data-md-color-scheme="slate"] { + --md-hue: 210; + }