From 8bdd037791ac0f63ab1468675875d9feda2c727c Mon Sep 17 00:00:00 2001 From: JMoore5353 Date: Tue, 25 Jun 2024 13:08:31 -0600 Subject: [PATCH] rosplane overview page in user guide --- docs/assets/ROSplane-overview.svg | 4 ++ .../rosplane/rosplane-dev-overview.md | 1 + docs/index.md | 4 +- docs/user-guide/roscopter-overview.md | 3 ++ docs/user-guide/rosplane-overview.md | 36 +++++++++++++++++ docs/user-guide/rosplane-setup.md | 40 ++++++++++++++----- mkdocs.yml | 34 +++++++++------- 7 files changed, 97 insertions(+), 25 deletions(-) create mode 100644 docs/assets/ROSplane-overview.svg create mode 100644 docs/developer-guide/rosplane/rosplane-dev-overview.md create mode 100644 docs/user-guide/roscopter-overview.md create mode 100644 docs/user-guide/rosplane-overview.md diff --git a/docs/assets/ROSplane-overview.svg b/docs/assets/ROSplane-overview.svg new file mode 100644 index 0000000..fa5924e --- /dev/null +++ b/docs/assets/ROSplane-overview.svg @@ -0,0 +1,4 @@ + + + +
Path Planner
Path Manager
Path Follower
Controller
Physical Aircraft
Estimator
Navigation Stack
Flight Controller
(ROSflight Firmware)
ROSplane
 \ No newline at end of file diff --git a/docs/developer-guide/rosplane/rosplane-dev-overview.md b/docs/developer-guide/rosplane/rosplane-dev-overview.md new file mode 100644 index 0000000..e776e16 --- /dev/null +++ b/docs/developer-guide/rosplane/rosplane-dev-overview.md @@ -0,0 +1 @@ +# ROSplane Developer Guide Overview \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index f71cad8..2ff4de6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,9 @@ ## What is ROSflight? -ROSflight is a lean and adaptable autopilot system designed from the ground up with researchers in mind. Its purpose is to enable researchers to quickly and easily try out new ideas with minimal effort. Some of ROSflight's key feature are: +ROSflight is a lean and adaptable autopilot system designed from the ground up with researchers in mind. +Its purpose is to enable researchers to quickly and easily try out new ideas with minimal effort. +Some of ROSflight's key feature are: - Lightweight, modular, and well documented code that is easy to understand and modify. - Most of the autopilot exists on a Linux computer rather than a microcontroller, enabling easier development with increased capabilities. diff --git a/docs/user-guide/roscopter-overview.md b/docs/user-guide/roscopter-overview.md new file mode 100644 index 0000000..d73381f --- /dev/null +++ b/docs/user-guide/roscopter-overview.md @@ -0,0 +1,3 @@ +# ROScopter Overview + +ROScopter is still under development. Check the [github repo](https://github.com/rosflight/roscopter) for the latest instructions. \ No newline at end of file diff --git a/docs/user-guide/rosplane-overview.md b/docs/user-guide/rosplane-overview.md new file mode 100644 index 0000000..56f19dd --- /dev/null +++ b/docs/user-guide/rosplane-overview.md @@ -0,0 +1,36 @@ +# ROSplane Overview + +ROSplane is a basic fixed-wing autopilot build around ROS2 for use with the ROSflight autopilot. +It is built according to the methods published in *Small Unmanned Aircraft: Theory and Practice* by Dr. Randy Beard and Dr. Tim McLain. + +As per the [ROSflight vision](../index.md#our-vision), ROSplane is *not* a fully-featured fixed-wing autopilot. +Instead, ROSplane is a simple, lean, ROS2-based fixedwing autopilot + +The core ROSplane package is a simple waypoint-following autopilot. +This includes a navigation stack, a controller, and an estimator. +This can be seen in the figure below. + +| ![Diagram of ROSplane architecture](../assets/ROSplane-overview.svg "ROSplane architecture") | +|:--:| +|*Diagram of the ROSplane architecture*| + +The structure of ROSplane and the nature of ROS2 interfaces allow ROSplane to be very modular, allowing you to write and integrate your own code without having to spend as much time working with interfaces and code integration. +Since it is lean, the time to learn and understand the nature of ROSplane should be small compared to other, more featured (but more complex) autopilots. +This can improve research productivity, decrease debugging time, and improve the development of novel algorithms. + +## Core Functionality + +The ROSplane autopilot allows users to fly waypoint missions with an RC safety pilot. +The simplicity of this framework allows users to add their own autonomy stacks or mission requirements on top of the ROSplane stack. + +For example, the `path_manager` node in the navigation stack in the core ROSplane package directs the `path_follower` node to follow either straight lines or circular arcs. +However, if a project needed to follow B-splines instead, the `path_manager` and the `path_follower` nodes could easily be replaced to achieve that. +Instead of loading a predetermined number of waypoints, higher levels of autonomy (i.e., vision-based guidance, etc.) can also be accomodated by building on top of the ROSplane stack by dynamically feeding the `path_planner` waypoints. + +## Using ROSplane + +For detailed instructions on how to use the core ROSplane package to fly autonomous waypoint missions, see the [ROSplane Setup](./rosplane-setup.md) page. +This page can be used as a guide to building and running ROSplane before you start making your own changes to the autonomy stack. + +For detailed instructions on each of the components of ROSplane, see the [ROSplane Developer Guide](../developer-guide/rosplane/rosplane-dev-overview.md). +This page provides detailed instructions on how to use and change the code for each component of the ROSplane stack. \ No newline at end of file diff --git a/docs/user-guide/rosplane-setup.md b/docs/user-guide/rosplane-setup.md index 8294e37..6c2f481 100644 --- a/docs/user-guide/rosplane-setup.md +++ b/docs/user-guide/rosplane-setup.md @@ -1,10 +1,13 @@ # ROSplane Setup -ROSplane v2.0.0-beta is now available! Check the [github repo](https://github.com/rosflight/rosplane) for the latest instructions. +!!! note + ROSplane v2.0.0-beta is now available! Check the [github repo](https://github.com/rosflight/rosplane) for the latest instructions. ROSplane is a basic fixed-wing autopilot build around ROS2 for use with the ROSflight autopilot. It is built according to the methods published in *Small Unmanned Aircraft: Theory and Practice* by Dr. Randy Beard and Dr. Tim McLain. +See [ROSplane Overview](rosplane-overview.md) for more general information on ROSplane. + ## Requirements ROSplane requires a working ROS2 installation on a companion computer. @@ -39,6 +42,9 @@ cd .. colcon build ``` +!!! warning + The build will fail if you have not built the `rosflight_msgs` previously or if you are not currently building it. + Next, source the `rosflight_ws` install files. If you already added the source command to your `.bashrc` from the [ROS2 Setup](./ros2-setup.md) page, then you can skip this step. @@ -54,7 +60,7 @@ Note that sourcing the `setup.bash` file in the `rosflight_ws` directory will in ## Running ROSplane SIL A controller or a simulated controller can be used to fly the aircraft in simulation. -See the `README.md` file for the `rosflight_ros_pkgs` package for more information on RC controll in simulation. +See the `README.md` file for the `rosflight_ros_pkgs` package for more information on RC control in simulation. ### Launching @@ -63,12 +69,15 @@ A convenience bash script has been included that uses tmux to launch Gazebo, an Note that this requires tmux, so you may need to install it with `sudo apt install tmux`. Run ```bash -./src/rosplane/rosplane/scripts/rosplane_gcs_launch.sh +./src/rosplane/rosplane/scripts/rosplane_gcs_launch.sh -s -r -a anaconda -b example_bag ~/path/to/rosflight_ws +``` +from the `rosflight_ws` directory to run a simulation of ROSplane (`-s`) with a simulated RC transmitter (`-r`) and the Anaconda aerodynamic and control parameters (`-a anaconda`), and also to start recording a ROSbag of all the topics (`-b example_bag`). + +See the script or run +```bash +~/path/to/rosflight_ws/src/rosplane/rosplane/scripts/rosplane_gcs.launch.sh -h ``` -from the `rosflight_ws` directory. -Note that the script needs options specified, so it will fail. -However,it will print out the required configuration options. -See the script for more information. +for more information. #### Alternative Method Alternatively, you can run each of the commands in the bash script individually: @@ -118,7 +127,7 @@ This command will create a directory named `rosflight_memory` where the paramete The ROSflight firmware will automatically check if the `rosflight_memory` directory is present when launched and will use those parameters if available. !!! note - The ROSflight firmware will only look for the `rosflight_memory` directory in the directory where the launch command is run. + The ROSflight firmware will only look for the `rosflight_memory` directory in the directory where the simulation launch command is run. You must launch `rosflight_sim` in the same directory to use the saved parameters; otherwise, reload and re-write the parameters. ### Flying in Sim @@ -131,7 +140,7 @@ Verify that the commands are working and that the aircraft is responding as expe To fly autonomously, use channel 5 to disable RC override. If using a simulated transmitter, use `ros2 service call /toggle_override std_srvs/srv/Trigger` to toggle RC override on/off. -The plane should then take off or fly autonomously in the Gazebo simulator! +The plane should then take off or fly autonomously in the simulator! ## Running ROSplane on Hardware Ensure `rosflight_io` is running on the companion computer, and that the flight controller is connects to the companion computer. @@ -198,4 +207,15 @@ This number is controlled by the `num_waypoints_to_publish_at_start` ROS2 parame Additional waypoints can be published using ```bash ros2 service call /publish_next_waypoint std_srvs/srv/Trigger -``` \ No newline at end of file +``` + +## ROSplane GCS + +To visualize the waypoints and the aircraft, an Rviz publisher and configuration file has been created. + +Run +```bash +ros2 launch rosplane_gcs rosplane_gcs.launch.py +``` +to launch Rviz and the publisher node. +Note that the waypoint publisher from the `path_planner` node and the subscriber in the publisher node have been set up to work like a "latched publisher/subscriber", so you should see the most recently published 20 waypoints, even if you launched RViz after publishing the waypoints. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 798ae44..6f4f83f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,8 +1,8 @@ site_name: ROSflight site_description: 'A lean, open-source autopilot system built by researchers, for researchers' site_url: http://rosflight.org -site_author: 'James Jackson, Daniel Koch, Ian Reid, Brandon Sutherland' -copyright: 'Copyright © 2019, James Jackson and Daniel Koch, BYU MAGICC Lab' +site_author: 'James Jackson, Daniel Koch, Ian Reid, Brandon Sutherland, Jacob Moore' +copyright: 'Copyright © 2024, James Jackson, Daniel Koch, Ian Reid, Brandon Sutherland, Jacob Moore, BYU MAGICC Lab' edit_uri: 'https://github.com/rosflight/rosflight_docs/edit/main/docs/' @@ -49,18 +49,23 @@ nav: - Home: index.md - User Guide: - Overview: user-guide/overview.md - - Getting Started: user-guide/getting-started.md - - Hardware Setup: user-guide/hardware-setup.md - - Flight Controller Setup: user-guide/flight-controller-setup.md - - RC Configuration: user-guide/rc-configuration.md - - ROS2 Setup: user-guide/ros2-setup.md - - Parameter Configuration: user-guide/parameter-configuration.md - - Pre-Flight Checks: user-guide/preflight-checks.md - - Improving Firmware Performance: user-guide/improving-firmware-performance.md - - Autonomous Flight: user-guide/autonomous-flight.md - - ROSplane Setup: user-guide/rosplane-setup.md - - ROScopter Setup: user-guide/roscopter-setup.md - - Running Gazebo Simulation: user-guide/running-gazebo-simulation.md + - Fly with ROSflight: + - Getting Started: user-guide/getting-started.md + - Hardware Setup: user-guide/hardware-setup.md + - Flight Controller Setup: user-guide/flight-controller-setup.md + - RC Configuration: user-guide/rc-configuration.md + - ROS2 Setup: user-guide/ros2-setup.md + - Parameter Configuration: user-guide/parameter-configuration.md + - Pre-Flight Checks: user-guide/preflight-checks.md + - Improving Firmware Performance: user-guide/improving-firmware-performance.md + - Autonomous Flight: user-guide/autonomous-flight.md + - Running Gazebo Simulation: user-guide/running-gazebo-simulation.md + - ROSplane: + - ROSplane Overview: user-guide/rosplane-overview.md + - ROSplane Setup: user-guide/rosplane-setup.md + - ROScopter: + - ROScopter Overview: user-guide/roscopter-overview.md + - ROScopter Setup: user-guide/roscopter-setup.md - Developer Guide: - Contribution Guidelines: developer-guide/contribution-guidelines.md - Style Guide: developer-guide/style-guide.md @@ -70,6 +75,7 @@ nav: - Unit Tests: developer-guide/firmware/unit-tests.md - Debugging: developer-guide/firmware/debugging.md - ROSplane: + - Developer Guide Overview: developer-guide/rosplane/rosplane-dev-overview.md - Controller: - General Controller Overview: developer-guide/rosplane/controller/controller-general-overview.md - Controller Software Architecture: developer-guide/rosplane/controller/controller-software-architecture.md