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/assets/ROSplane_sim.jpg b/docs/assets/ROSplane_sim.jpg new file mode 100644 index 0000000..9a61e01 Binary files /dev/null and b/docs/assets/ROSplane_sim.jpg differ diff --git a/docs/assets/plotjuggler_demo.png b/docs/assets/plotjuggler_demo.png new file mode 100644 index 0000000..4e05de3 Binary files /dev/null and b/docs/assets/plotjuggler_demo.png differ diff --git a/docs/assets/rviz_demo.png b/docs/assets/rviz_demo.png new file mode 100644 index 0000000..de68dc6 Binary files /dev/null and b/docs/assets/rviz_demo.png differ 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..5ff9475 --- /dev/null +++ b/docs/developer-guide/rosplane/rosplane-dev-overview.md @@ -0,0 +1,20 @@ +# ROSplane Developer Guide Overview + +The purpose of the this section is to provide detailed information on each of the components of ROSplane, as shown in the below figure. +It is written with the intent that a user might know how to change each component of ROSplane, not only how to use it. + +Note that the system components not part of ROSplane are not included in this section (ROSflight firmware, physical aircraft setup, etc.). + + +| ![Diagram of ROSplane architecture](../../assets/ROSplane-overview.svg "ROSplane architecture") | +|:--:| +|*Diagram of the ROSplane architecture*| + +Each of these components are described in detail in this section, but the implementation is not fully described. +Please refer to the code for more detailed information on the actual implementation of each of the elements shown above. + +## Contributing to ROSplane + +If you create a new "module" when using ROSplane for your application, please contribute back! +While changes won't be included in the core ROSplane stack (see [ROSflight Vision](../../index.md#our-vision)), we hope to build a repository of modules and projects that have been created by others. +Doing this is also an effective way to share your work and help others build on it. \ 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/flight-controller-setup.md b/docs/user-guide/flight-controller-setup.md index 07ac67d..ff9993c 100644 --- a/docs/user-guide/flight-controller-setup.md +++ b/docs/user-guide/flight-controller-setup.md @@ -69,3 +69,13 @@ sudo apt install dfu-util ``` bash dfu-util -a 0 -s 0x08000000 -D rosflight-F4.bin ``` + +## LEDs + +The meaning of the various LEDs is summarized in the following table. The colors of the LEDs may change depending on your specific board: + +| LED | On | Off | Slow Blink | Fast Blink | +|---------------|---------------|------------------|------------------|------------------| +| Power (Blue) | Board powered | - | - | - | +| Info (Green) | RC control | Offboard control | - | - | +| Warning (Red) | Armed | Disarmed | Error (disarmed) | Failsafe (armed) | \ No newline at end of file diff --git a/docs/user-guide/overview.md b/docs/user-guide/overview.md index 6f288be..d72bcff 100644 --- a/docs/user-guide/overview.md +++ b/docs/user-guide/overview.md @@ -1,5 +1,9 @@ # Overview +!!! tldr + Visit [Getting Started](./getting-started.md) to start setting up ROSflight. + Then visit [ROSplane Overview](./rosplane-overview.md) (for fixedwing aircraft) or [ROScopter Overview](./roscopter-overview.md) (for multirotor aircraft) to set up your autonomy stack. + ## Main Components of ROSflight ROSflight is intended to be used with both a typical flight controller and a companion Linux computer. Although it can be used with just a flight controller, this setup will not offer most of the advantages of ROSflight. @@ -11,7 +15,7 @@ ROSflight is intended to be used with both a typical flight controller and a com - **Companion computer:** A Linux computer, running ROS2, that is mounted on the vehicle and has a physical, serial connection with the flight controller - **Offboard control (setpoints):** The control setpoints passed from the companion computer to the flight controller. The control is "offboard" from the perspective of the flight controller, even though the computer providing those commands is mounted onboard the vehicle. -The following figure illustrates the interactions between the major components of the system: +The following figure illustrates the interactions between the major components of ROSflight: ![System Components](images/components.svg) @@ -31,45 +35,17 @@ Although higher level control is offloaded to the companion computer, enough con ROSplane and ROScopter are not required for using ROSflight and you could choose to use an entirely different autonomy stack if you so desired. -## RC Safety Pilot +### RC Safety Pilot ROSflight is designed for use with offboard control from experimental and research code. -As such, it provides several mechanisms for an RC safety pilot to intervene if something goes wrong with the control setpoints coming from the companion computer: - - - **RC override switch:** The safety pilot can flip a switch on the transmitter to take back RC control. Attitude and throttle override can be mapped independently, meaning you can choose one or the other, put them on separate switches, or put them both on the same switch. Details on these switches are provided on the [RC configuration](rc-configuration.md) page. - - **Stick deviations:** If a stick is deviated from its center position, then that channel is overridden by RC control. This allows the safety pilot to take control without flipping a switch. This may be useful to provide a momentary correction on a single axis. The fraction of stick travel needed to activate the RC override is controlled by the `RC_OVRD_DEV` parameter. The `OVRD_LAG_TIME` parameter controls the amount of time that the override remains active after the sticks return to center. - - **Minimum throttle:** By default, the flight controller takes the minimum of the two throttle commands from RC and offboard control setpoints. This allows the safety pilot to drop the throttle quickly if needed. This behavior can be turned on or off with the `MIN_THROTTLE` parameter. - -## Arming, Errors & Failsafe - -The flight controller can only be armed and disarmed via RC control. -Two mechanisms are provided: sticks (left stick down and right to arm, down and left to disarm) and switch. -Only one of these options can be active at a time. -Details on configuration are given on the [RC configuration](rc-configuration.md) page. - -The firmware runs a number of error checks before allowing the flight controller to arm. -Completing the configuration checklist on the [Getting Started](getting-started.md) page should avoid these errors. -In addition to a few internal health checks, the following conditions are checked: - - - **Mixer:** Valid mixer must have been selected (see the [Hardware Setup](hardware-setup.md) documentation page) - - **IMU calibration:** The IMU must have been calibrated since firmware was flashed (it is recommended that you recalibrate often) - - **RC:** There must be an active RC connection - -In addition to the error checking before arming, the flight controller enters a failsafe mode if the RC connection is lost during flight while armed. -While in failsafe mode the flight controller commands level flight with the throttle value defined by the `FAILSAFE_THR` parameter. - -The following is a simplified version of the finite state machine that defines logic used for the arming, error checks, and failsafe operations: - -![Arming FSM](images/arming-fsm-simplified.svg) - -The state manager also includes functionality for recovering from hard faults if one were to occur, although this is unlikely with unmodified firmware. If a hard fault occurs while the flight controller is armed, the firmware has the ability to immediately rearm after rebooting to enable continued RC control of the vehicle for recovery. +As such, it provides several mechanisms for an RC safety pilot to intervene if something goes wrong with the control setpoints coming from the companion computer. +See the [RC Setup](./rc-configuration.md) page for more information. -## LEDs +## Where do I start? -The meaning of the various LEDs is summarized in the following table. The colors of the LEDs may change depending on your specific board: +To get started with ROSflight, visit the [Getting Started](./getting-started.md) page. +This page will direct you on how to set up your hardware and flight controller to run ROSflight. -| LED | On | Off | Slow Blink | Fast Blink | -|---------------|---------------|------------------|------------------|------------------| -| Power (Blue) | Board powered | - | - | - | -| Info (Green) | RC control | Offboard control | - | - | -| Warning (Red) | Armed | Disarmed | Error (disarmed) | Failsafe (armed) | +After you set up ROSflight, you should set up an autonomy stack to interact with ROSflight. +Visit the [ROSplane Setup](./rosplane-setup.md) page for fixedwing aircraft or the [ROScopter Setup](./roscopter-setup.md) page for multirotor aircraft. +You can also use your own autonomy stack as described in [Autonomous Flight](./autonomous-flight.md). \ No newline at end of file diff --git a/docs/user-guide/rc-configuration.md b/docs/user-guide/rc-configuration.md index 0c3c320..b41e31b 100644 --- a/docs/user-guide/rc-configuration.md +++ b/docs/user-guide/rc-configuration.md @@ -1,5 +1,38 @@ # RC Configuration +## RC Safety Pilot + +ROSflight is designed for use with offboard control from experimental and research code. +As such, it provides several mechanisms for an RC safety pilot to intervene if something goes wrong with the control setpoints coming from the companion computer: + + - **RC override switch:** The safety pilot can flip a switch on the transmitter to take back RC control. Attitude and throttle override can be mapped independently, meaning you can choose one or the other, put them on separate switches, or put them both on the same switch. Details on these switches are provided on the [RC configuration](rc-configuration.md) page. + - **Stick deviations:** If a stick is deviated from its center position, then that channel is overridden by RC control. This allows the safety pilot to take control without flipping a switch. This may be useful to provide a momentary correction on a single axis. The fraction of stick travel needed to activate the RC override is controlled by the `RC_OVRD_DEV` parameter. The `OVRD_LAG_TIME` parameter controls the amount of time that the override remains active after the sticks return to center. + - **Minimum throttle:** By default, the flight controller takes the minimum of the two throttle commands from RC and offboard control setpoints. This allows the safety pilot to drop the throttle quickly if needed. This behavior can be turned on or off with the `MIN_THROTTLE` parameter. + +## Arming, Errors & Failsafe + +The flight controller can only be armed and disarmed via RC control. +Two mechanisms are provided: sticks (left stick down and right to arm, down and left to disarm) and switch. +Only one of these options can be active at a time. +Details on configuration are given on the [RC configuration](rc-configuration.md) page. + +The firmware runs a number of error checks before allowing the flight controller to arm. +Completing the configuration checklist on the [Getting Started](getting-started.md) page should avoid these errors. +In addition to a few internal health checks, the following conditions are checked: + + - **Mixer:** Valid mixer must have been selected (see the [Hardware Setup](hardware-setup.md) documentation page) + - **IMU calibration:** The IMU must have been calibrated since firmware was flashed (it is recommended that you recalibrate often) + - **RC:** There must be an active RC connection + +In addition to the error checking before arming, the flight controller enters a failsafe mode if the RC connection is lost during flight while armed. +While in failsafe mode the flight controller commands level flight with the throttle value defined by the `FAILSAFE_THR` parameter. + +The following is a simplified version of the finite state machine that defines logic used for the arming, error checks, and failsafe operations: + +![Arming FSM](images/arming-fsm-simplified.svg) + +The state manager also includes functionality for recovering from hard faults if one were to occur, although this is unlikely with unmodified firmware. If a hard fault occurs while the flight controller is armed, the firmware has the ability to immediately rearm after rebooting to enable continued RC control of the vehicle for recovery. + ## Binding your Transmitter to your Receiver Follow the instructions in your user manual to bind your transmitter to your RC receiver. You may also be able to find a guide on YouTube with instructions; just search for your particular transmitter and receiver model. 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 e543054..22fee43 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,9 @@ 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. + +![ROSplane SIL Demo](../assets/ROSplane_sim.jpg) ### Launching @@ -63,12 +71,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 +129,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 +142,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 +209,39 @@ 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 / Visualization Tools + +Running and tuning an autopilot requires good tools. +These are the tools we use in our workflow to test and debug the performance of our autopilot. +Let us know if you have better tools! + +### Plotjuggler +[Plotjuggler](https://github.com/facontidavide/PlotJuggler) is a tool to visualize data. +It is versatile and powerful and can plot many different time series at the same time. +It allows you to directly stream ROS2 topics, making it an ideal plotting utility in the field. +We use Plotjuggler extensively to tune our control and estimation loops, and to monitor the status of the airplane. + +![Plotjuggler Demo](../assets/plotjuggler_demo.png) + +While Plotjuggler is not a ROS application, Plotjuggler ROS packages have been created. +See the [Plotjuggler GitHub page](https://github.com/facontidavide/PlotJuggler) for more information or install the ROS2 packages with: +```bash +sudo apt install ros-$ROS_DISTRO-plotjuggler-ros +``` + +We also use a layout file to automatically open up the plots we are interested in. +Use the `Import Layout` button on the Plotjuggler GUI to import the `plotjuggler_layout.xml` file. + +### RViz Waypoint Plotter +Rviz is a ROS2 tool that can visualize 3D information. +We use Rviz to visualize waypoints and the aircraft's performance in achieving those waypoints. + +![Rviz Waypoint Demo](../assets/rviz_demo.png) + +Run the Rviz publisher and Rviz configuration file with +```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. diff --git a/mkdocs.yml b/mkdocs.yml index 39c4421..f0e74ea 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 © 2019-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 + - 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