diff --git a/docs/developer-guide/contribution-guidelines.md b/docs/developer-guide/contribution-guidelines.md index 06543a65..217daa69 100644 --- a/docs/developer-guide/contribution-guidelines.md +++ b/docs/developer-guide/contribution-guidelines.md @@ -8,11 +8,11 @@ Although we strive for complete in-code documentation, in practice this sometime Here is a summary of the key goals and philosophies behind ROSflight. As you look to make contributions to the project, keep these in mind. -- Only include the things that most people will need. The goal of this would be to do most of the work so people can get a MAV in the air quickly and easily, but not overcomplicate the code with features that only a small portion of users would need. +- **Only include the things that most people will need.** The goal of this would be to do most of the work so people can get a MAV in the air quickly and easily, but not overcomplicate the code with features that only a small portion of users would need. -- Be modular and adaptable for many research-centric use cases. This will be accomplished by putting the majority of the autopilot in a well-designed ROS2 framework. That which needs to be on the microcontroller will need to be done so carefully with good coding practices. Additionally, microcontroller code that is the most likely to be expanded upon should include clear interfaces and instructions for doing so. +- **Be modular and adaptable for many research-centric use cases.** This will be accomplished by putting the majority of the autopilot in a well-designed ROS2 framework. That which needs to be on the microcontroller will need to be done so carefully with good coding practices. Additionally, microcontroller code that is the most likely to be expanded upon should include clear interfaces and instructions for doing so. -- Keep everything simple and well documented. The key goal here is to minimize the amount of time and effort it takes someone to go from knowing nothing about ROSflight to being able to implement their own features and making meaningful progress with their research. +- **Keep everything simple and well documented.** The key goal here is to minimize the amount of time and effort it takes someone to go from knowing nothing about ROSflight to being able to implement their own features and making meaningful progress with their research. ## Communication diff --git a/docs/developer-guide/firmware/building-and-flashing.md b/docs/developer-guide/firmware/building-and-flashing.md deleted file mode 100644 index 40ed72b6..00000000 --- a/docs/developer-guide/firmware/building-and-flashing.md +++ /dev/null @@ -1,94 +0,0 @@ -# Building and Flashing the Firmware - - -This guide assumes you are running Ubuntu 22.04 LTS, which is the currently supported development environment. - -## Installing the ARM Embedded Toolchain - -``` bash -sudo apt install gcc-arm-none-eabi -``` - -You can test the installation and check which version is installed by running `arm-none-eabi-gcc --version`. - -## Building the Firmware from Source - -1. To build the firmware, first clone the firmware repository: - ```bash - git clone --recursive https://github.com/rosflight/rosflight_firmware - ``` -1. Create build directory: - ```bash - cd rosflight_firmware && mkdir build && cd build - ``` -1. Build using: (`board_name` should be either `varmint` or `pixracer_pro`) - ```bash - cmake .. -DBOARD_TO_BUILD= && make -j - ``` - -## Flashing firmware - -### Install STM32CubeProgrammer - -We use the STM32CubeProgrammer to flash the flight controller. - -1. Download the programmer [here](https://www.st.com/en/development-tools/stm32cubeprog.html#get-software). - You may have to enter your email to download the software. -1. Install the software by following the instructions in the downloaded package. - -### Flashing the Varmint - -!!! warning "Needed tools" - - You will need an ST-Link STM programmer to flash the firmware. - We use ST-Link V2, and you can find it [on Mouser](https://www.mouser.com/ProductDetail/STMicroelectronics/ST-LINK-V2?qs=H4BOwPtf9MC1sDQ8j3cy4w%3D%3D&mgh=1&utm_id=22314976717&utm_source=google&utm_medium=cpc&utm_marketing_tactic=amercorp&gad_source=1&gad_campaignid=22304734959). - -1. Plug the end of the ribbon cable into the 6-pin slot on the Varmint. - You may have to make your own cable that connects the ST-Link to the 6-pin connector. - - !!! danger - - The Varmint has 2 6-pin connectors. - **Do not** connect the ribbon cable to the port closest to the power wires. - - ![Varmint 6-pin cable](images/varmint_flash_instructions.png) - -1. Power on the Varmint by connecting a battery to the board. - -1. Open STM32CubeProgrammer. - -1. Plug in the USB connector from the ST-Link to the computer. Select "Connect" in the STM32CubeProgrammer. This should detect the ST-Link and connect automatically. - ![Select "Connect"](images/stm_programmer_connect.png) - -1. Navigate to the programming page. - ![Navigate to programming page](images/stm32_programming_page.png) - -1. Select the hex file that was just built and click "Open". - ``` - /path/to/rosflight_firmware/build/boards/varmint_h7/varmint_10X/varmint10X.hex - ``` - ![Select the previously built hex file](images/stm32_select_hex.png) - -1. Select the appropriate options and press "Start Programming" - ![Select options and start programming](images/stm32_select_options.png) - -### Flashing the Pixracer Pro - -Flashing the Pixracer Pro is a very similar process to flashing the Varmint. - -1. The Pixracer Pro does not use the same 6-pin connector to connect to the ST-Link. - Instead, it uses a TC2030 connector with retaining clips. - - !!! tip "Connectors we use" - - In addition to the ST-Link V2 board linked above, we use these cables to flash the Pixracer Pro: - - 1. [20-pin ribbon adapter board](https://www.tag-connect.com/product/arm20-ctx-m) (connect the ST-Link to this adapter) - 2. [Programming cable](https://www.tag-connect.com/product/tc2030-idc-nl) that connects to the adapter board - 3. [TC2030 clip](https://www.tag-connect.com/product/tc2030-retaining-clip-board-3-pack) to attach the programming cable to the board - - ![Connectors for the Pixracer Pro](./images/pixracer_pro_flash_instructions.jpeg) - -1. Power on the Pixracer Pro using a USB-C port. - -2. Follow the instructions from the [Varmint flashing guide](#flashing-the-varmint). diff --git a/docs/developer-guide/firmware/debugging.md b/docs/developer-guide/firmware/debugging.md index 9abb205f..57e79e33 100644 --- a/docs/developer-guide/firmware/debugging.md +++ b/docs/developer-guide/firmware/debugging.md @@ -12,9 +12,9 @@ This guide assumes you are running Ubuntu 22.04 LTS, which is the currently supp ## General Setup -Follow the guide in [Building and Flashing](building-and-flashing.md) to install the compiler toolchain. +Follow the guide in [Building and Flashing](../../user-guide/hardware-and-rosflight/flight-controller-setup.md#building-and-flashing-the-firmware) to install the compiler toolchain. -Also make sure you have configured your computer as described in the [Serial Port Configuration](../../user-guide/concepts/flight-controller-setup.md#serial-port-configuration) section of the user guide. +Also make sure you have configured your computer as described in the [Serial Port Configuration](../../user-guide/hardware-and-rosflight/flight-controller-setup.md#serial-port-configuration) section of the user guide. ### Connect debugger to flight controller diff --git a/docs/developer-guide/firmware/unit-tests.md b/docs/developer-guide/firmware/unit-tests.md index 7c56ccff..ece81edb 100644 --- a/docs/developer-guide/firmware/unit-tests.md +++ b/docs/developer-guide/firmware/unit-tests.md @@ -41,7 +41,7 @@ If you want to manually build and run the unit tests, first build them with the cd mkdir build cd build -cmake .. -DBUILD_TEST=TRUE +cmake .. -DBOARD_TO_BUILD=test make ``` diff --git a/docs/developer-guide/roscopter/roscopter-dev-overview.md b/docs/developer-guide/roscopter/roscopter-dev-overview.md deleted file mode 100644 index 287af77e..00000000 --- a/docs/developer-guide/roscopter/roscopter-dev-overview.md +++ /dev/null @@ -1,5 +0,0 @@ -# ROScopter Developer Guide Overview - -!!! danger - - Documentation for ROScopter is still under development. Please check back soon! diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 00000000..ca42bcab --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,3 @@ +.md-grid { + max-width: 1440px; +} diff --git a/docs/user-guide/concepts/flight-controller-setup.md b/docs/user-guide/concepts/flight-controller-setup.md deleted file mode 100644 index 244a5db9..00000000 --- a/docs/user-guide/concepts/flight-controller-setup.md +++ /dev/null @@ -1,68 +0,0 @@ -# Flight Controller Setup - -!!! Note - This page contains instructions for flashing pre-built firmware binaries. - For instructions on building and flashing from source, see [Building and Flashing](../../developer-guide/firmware/building-and-flashing.md) in the Developer Guide. - -## Compatible Hardware - -Currently, the ROSflight firmware supports: - -1. An in-development board from AeroVironment, the **Varmint**. -This board has an integrated Jetson Orin, but is not yet commercially available. -1. **[MRO's Pixracer Pro](https://store.3dr.com/pixracer-pro/)**, which has the same H7 processor. - -!!! note "Supporting your own board" - - It is possible to write your own board support package (BSP). - If you do create your own support package for the ROSflight firmware, please contribute back! - -## Serial Port Configuration - -!!! tip - You can see which groups you are a member of by running `groups $USER` on the command line. - -The following bullet point is necessary: - -* Be sure your user is in the `dialout` and `plugdev` groups so you have access to the serial ports. You will need to log out and back in for these changes to take effect. -``` bash -sudo usermod -aG dialout,plugdev $USER -``` - -If you experience issues, you may need one or both of the next two bullet points: - -* Temporarily stop the modem-manager (Sometimes, Linux thinks the device is a modem -- this command will be effective until next boot, or until you run the command again with `start` in place of `stop`) -``` bash -sudo systemctl stop ModemManager.service -``` - -* Add the custom udev rule so Linux handles the flight controller properly (copy the following as `/etc/udev/rules.d/45-stm32dfu.rules`) -``` bash -# DFU (Internal bootloader for STM32 MCUs) -SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE="0664", GROUP="plugdev" -``` - -!!! Tip - You can permanently disable the ModemManager if you do not need it, then you won't have to disable it every time you reboot: - ``` - sudo systemctl disable ModemManager.service - ``` - Replace `disable` with `enable` to revert (i.e. if you find some other program you use needs access to it). - Or you can uninstall it entirely from your system: - ``` - sudo apt purge modemmanager - ``` - -## Building and Flashing the Firmware - -Follow the [building and flashing firmware guide](../../developer-guide/firmware/building-and-flashing.md) to build the ROSflight firmware and flash it to your flight controller. - -## 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) | diff --git a/docs/user-guide/concepts/hardware-setup.md b/docs/user-guide/concepts/hardware-setup.md deleted file mode 100644 index e1214993..00000000 --- a/docs/user-guide/concepts/hardware-setup.md +++ /dev/null @@ -1,258 +0,0 @@ -# Hardware Setup - -## Parts List - -To use ROSflight to its full potential, you will need the following system components. -Some components are mounted on your MAV (Miniature Aerial Vehicle), while others are on the ground. -ROSflight supports both multirotor and fixed-wing vehicle types. - - -*Mounted on the MAV* - -1. Aircraft Frame, Motor(s), ESC(s), Battery and Propeller(s) -2. Flight Controller (FC) -3. Vibration Isolation for FC -4. Any external sensors -5. R/C Receiver -6. Companion Computer -7. Wi-Fi Antenna, or access of some kind to ground-station, wireless network (e.g. Ubiquiti Bullet) - -*Ground Station* - -1. Ground-Station, Wireless Network (e.g. Wi-Fi Router, Ubiquiti Rocket) -2. R/C transmitter -3. Laptop or base station computer -4. Joystick (Xbox controller) - -### Frame, Motors, ESCs, Battery, and Propeller - -We do not officially support any specific multirotor or airplane frame, motor, ESC, Battery or Propeller combination. -There are a lot of great resources for building your own MAV, and there are a lot of great kits out there that have all of these parts. - -If you are designing your own multirotor or airplane, you may want to look at [ecalc](https://www.ecalc.ch/), an online tool which can help you design a proper ESC/Battery/Motor/Propeller system for your MAV. - -Some things to keep in mind as you design or build your MAV. - -* Most kits do not include space for a companion computer, cameras, laser scanners or other sensors. Be sure to think about where these components are going to go, and how their placement will affect the CG of the MAV. -* You will likely also need to customize the power circuitry of your MAV to provide power to your companion computer at some specific voltage. Many people like to separate the power electronics (the ESCs and motors), from the computer and companion sensors. This can really come in handy if you are trying to develop code on the MAV, because you can have the computer on and sensors powered, and not worry at all about propellers turning on and causing injury as you move the aircraft about by hand. We will talk about this more when we talk about wiring up your MAV. -* Cheap propellers can cause a huge amount of vibration. Consider buying high-quality propellers, doing a propeller balance, or both. RCGroups, DIY Drones and YouTube have some awesome guides on how to do propeller balancing. -* ESCs will need to be calibrated from 2000 to 1000 us - - -### Flight Controller - -The flight controller is the embedded microcontroller that runs `rosflight_firmware`. -See the [list of compatible hardware](./flight-controller-setup.md) for more information. - -The flight controller includes an IMU and a barometer, as well as some additional sensors depending on the board. - -### External Sensors - -Additional Sensors you may want for your ROSflight setup include: - -* Sonar -* GPS -* Digital Airspeed Sensor (Pitot Tube) - -### Vibration Isolation - -It is really important to isolate your flight controller from vehicle vibrations, such as those caused by propellers and motors. We recommend using small amounts of [Kyosho Zeal](https://www.amainhobbies.com/kyosho-zeal-5mm-vibration-absorption-gyro-receiver-mounting-gel-kyoz8006b/p1391945) to mount a fiberglass plate holding the FC to the MAV. You may also want to try adding mass to the flight control board. We have accomplished this by gluing steel washers to the fiberglass mounting plate. - -![Vibration Isloation](../images/vibration_isolation.png) - -You may need to experiment with the amount of gel you use, how far apart the gel is spaced, and the amount of mass added to the FC mounting plate. The interaction of these factors is difficult to predict, therefore it takes a little bit of experimentation to get it right. - -### Companion Computer - -The only requirement for the companion computer is that it runs Linux (usually an Ubuntu LTS version, but using Docker on other distributions is also an option), ROS2, has at least one USB port, and can be carried by the aircraft. We have had success with the following companion computers, but by no means is this a comprehensive list; it is more by way of suggestion. - -* [NVIDIA Jetson](https://www.nvidia.com/en-us/autonomous-machines/embedded-systems/) -* [MSI CUBI](https://www.msi.com/Business-Productivity-PCs/Products#?tag=Cubi-Series) -* [Intel NUC](https://www.intel.com/content/www/us/en/products/details/nuc.html) -* [Rasberry Pi 3](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) - -### Wi-Fi - -You will need Wi-Fi to communicate with your MAV when it is in the air. Because ROS2 communicates over UDP, it is very easy to use ROS2 to view what is going on in your MAV while it is flying by sending commands and reading sensor data. For most applications, a standard Wi-Fi router and dongle will suffice. For long-range applications, you may want to look into [Ubiquiti](https://www.ubnt.com/) point-to-point Wi-Fi. (We have seen ranges over a mile with these networks.) - -### RC Transmitter and Receiver - -For RC Control, you will need a transmitter with between 6 and 8 channels. Any additional channels will be wasted. We require RC control for safe operation, and only support arming and disarming via RC control. - - -ROSflight only supports PPM (pulse position modulation) and SBUS receivers. Individual channel PWM outputs are not supported. Any configurations with PPM or SBUS and 6-8 channels will be sufficient. - -### Laptop or Base Station Computer - -You will need a laptop which can run ROS2 to communicate with the MAV over the ground station wireless network. To do this natively you'll want a recent Ubuntu LTS version, but this can also be done with Docker containers from pretty much any Linux distribution. Linux within a virtual machine can also work, but is not recommended. - -### Joystick - -A joystick is used for [software-in-the-loop (SIL) simulations](./running-simulations-with-rosflight.md). The joystick is not technically a required component because it is possible to control your MAV from the command line, but it makes things much easier. Our first recommendation is to use the same transmitter you use for hardware as a joystick by plugging it into the computer via USB. We support Taranis QX7 transmitters, Radiomaster TX16s transmitters, RealFlight controllers, and XBOX controllers. Other joysticks can be used, but you may need to create custom axis and button mappings within the ROSflight joystick utility. - -!!! note "Physical vs firmware channels" - If you do write your own mapping, remember that the channel numbers need to be configured properly on both the firmware and the transmitter. - This means that if the RC transmitter outputs "throttle" on channel 3 on the (1 indexed on the transmitter), then the firmware needs to set `RC_F_CHN` to 2 (0 indexed). - - -### Battery Monitor - -A battery monitor is an analog sensor that provides battery voltage and/or battery current information. This data can be used to prevent power loss in air or to measure system load. The sensor outputs an analog voltage proportional to the battery voltage and/or current through the battery. Most flight controllers come equipped with a built-in battery monitor, but if not, small PCB sensors are also available that can be connected to the flight controller. - - -For ROSflight to use a battery monitor, an appropriate multiplier must be set. ROSflight multiplies the analog signal from the monitor by the multiplier to get the final reading. The monitor datasheet should contain the information needed to get the multiplier. For example, the datasheet for the AttoPilot 50V/90A sensor states that it outputs 63.69 mV / V. To get the original battery voltage, the multiplier must be 1/.06369, or 15.7. The multipliers for the voltage and current are set separately, with the `BATT_VOLT_MULT` and `BATT_CURR_MULT` parameters, respectively. - -ROSflight applies a simple low-pass filter to remove noise from the voltage and current measurements. These filters are configurable via the `BATT_VOLT_ALPHA` and `BATT_CURR_ALPHA` [parameters](parameter-configuration.md). The alpha value for a given cutoff frequency \\(a\\), can be calulated with: \\( \alpha = e ^ {-.01a} \\). As battery voltages do not typically change quickly, the default of 0.995 usually suffices. - -More information on battery monitor hardware, including determining appropriate multipliers and creating a simple DIY monitor, can be found on the [OpenPilot Wiki](https://opwiki.readthedocs.io/en/latest/user_manual/revo/voltage_current.html). - -## Wiring Diagram - - -Below is an example wiring diagram for a multirotor using an MSI Cubi as a companion computer. This diagram also includes the motor power switch, which allows for the sensors, flight controller, and companion computer to be powered on while the motors are off. This is a safer way to test sensors, code, etc. as the motors are unable to spin while the switch is off. - -![Wiring Diagram](../images/Wiring_Diagram.png) - -Your needs will likely be slightly different than what is shown. This is meant as an example only and can be adapted to fit your needs. - -## Motor Layouts and Mixer - -The mixer takes in the desired forces and torques from the firmware controller and computes the motor and servo outputs accordingly. -If it is not set correctly, it will likely lead to a crash. -Make sure it is set properly for your airframe! - -!!! tip "Quick Start" - - For a quick start, use one of the "canned mixers". - For a more accurate mixer, use a custom mixer. - -ROSflight offers some pre-computed, "canned" mixers that can be used off the shelf for a variety of common multirotor and fixedwing airframes. -These mixers do not take into account all the parameters of your system (i.e. motor and propeller parameters), so they will be less accurate than they could be. -If you want a more accurate mixer, or have easy access to the motor and prop parameters of your system, then we recommend using a custom mixer. - -!!! warning "Important" - A mixer must be chosen for the firmware to allow arming. - -The desired mixer can be chosen by setting the `PRIMARY_MIXER` parameter to one of the following values: - -| # | Mixer | -|---|---------| -| 0 | ESC calibration | -| 1 | Quad + | -| 2 | Quad X | -| 3 | Hex + | -| 4 | Hex X | -| 5 | Octo + | -| 6 | Octo X | -| 7 | Y6 | -| 8 | X8 | -| 9 | Fixed-wing (traditional AETR) | -| 10 | Inverted V-tail fixedwing (like the RMRC Anaconda frame) | -| 11 | Custom mixer | - -The associated motor layouts are shown below for each mixer. -The **ESC calibration** mixer directly outputs the throttle command equally to each motor, and can be used for calibrating the ESCs. - -![Mixer_1](../images/mixers_1.png) - -The following parameters related to the mixer are optional: - -* `SECONDARY_MIXER` -* `USE_MOTOR_PARAM` -* All the custom mixer params of the form `PRI_MIXER_i_j` or `SEC_MIXER_i_j` - -The following subsections have more detail on these parameters. - -### Secondary Mixer - -ROSflight also has a secondary mixer that can be set using the options in the above table by setting the `SECONDARY_MIXER` param. - -Offboard control commands will use the secondary mixer, while commands from the RC safety pilot will use the primary mixer. -Thus, both RC throttle and attitude override will affect the mixer, as shown in the following image. - -![RC Mixer Configuration](../images/rc_mixer_configuration.png) - -The `mixer_to_use_` structure represents the mixer that will be used when computing the output. -The header, which includes the default PWM rate and the output type for each output channel, is always set to the same as the primary mixer. -See [Defining a Custom Mixer](#defining-a-custom-mixer) for more information. -Note that if the `SECONDARY_MIXER` param is not set, then it will default to the same value as the primary mixer. - -The secondary mixer might be useful when the airframe needs a different mixer for the offboard control (from the companion computer) than for RC control (from the safety pilot). -It allows flexibility for more advanced mixing schemes while still having a functional mixer available to a safety pilot. - -### Using Motor Parameters - -The parameter `USE_MOTOR_PARAM` causes the firmware to compute the actuator outputs differently than if `USE_MOTOR_PARAM` is set false. -As described in _Small Unmanned Aircraft: Theory and Practice_ by Beard and McLain, the mixing matrix is formed using equations from propeller theory, resulting in a set of equations that set the desired forces and torques equal to the square of the angular speeds of the propellers. -If the motor and propeller parameters are known, then the desired voltage (and thus throttle) setting can be computed from the squared angular speeds. - -If the motor and propeller parameters are not known, then some simplifying assumptions are made to compute the desired throttle settings for each motor from the desired forces and torques. -See [the report on the ROSflight mixer derivation](https://github.com/rosflight/rosflight_docs/blob/main/latex-reports/mixer.tex) for more information on the mixer derivation and assumptions. - -!!! tip "Quick Start" - - If using a canned mixer, set `USE_MOTOR_PARAM=0`. - - If using a custom mixer, set `USE_MOTOR_PARAM=1` **only** if the mixer was designed with motor parameters. - -The canned mixing matrices assume that `USE_MOTOR_PARAM` parameter is set to false. -Using a canned mixer matrix and setting `USE_MOTOR_PARAM=1` (i.e. specifying that you want to mix with motor and propeller parameters) will cause the outputs to be scaled incorrectly. -It is not required to use motor and propeller parameters when using a custom mixing matrix, but make sure your custom mixer makes sense. - -Also, if you selected a custom mixer and used the motor parameters to generate the mixer, make sure you set `USE_MOTOR_PARAM=1`. Otherwise, the outputs will likely be scaled incorrectly. - -!!! Important - - We recommend flying your firmware in simulation _before_ loading the firmware onto real hardware to make sure everything is working. - -!!! Warning - - It is not recommended to use a _canned mixer for the primary mixer_ and a _custom mixer for the secondary mixer_ **when the secondary mixer needs `USE_MOTOR_PARAM=1`.** - In other words, both `PRIMARY_MIXER` and `SECONDARY_MIXER` should use motor parameters, or neither should. - - This is important because the canned mixers make assumptions that affect the gains of the controller on the aircraft. - This means that a canned mixer will require slightly different tuning than a custom mixer might. - -### Defining a Custom Mixer - -A custom mixer can be defined by: - -1. Set `PRIMARY_MIXER` (required) and/or `SECONDARY_MIXER` (optional) to the desired value in the mixer table -2. Load the mixing matrix parameters for either/both the primary or the secondary mixer - -Note that computing the parameters of the mixing matrix can be done on the companion computer. - -The firmware loads a custom mixer by loading all mixing matrix values from parameters. -Since there are 6 inputs to the mixer (\(F_x,F_y,F_z,Q_x,Q_y,Q_z\)) and 10 possible outputs, the mixer is a 6x10 matrix and there are 60 parameters associated with each custom mixer. -For a standard quadrotor, however, most of these would be zero, since only the first 4 outputs (columns of the mixer matrix) would be used. - -In addition to the parameters associated with the 6x10 mixing matrix, there are two additional sets of parameters that need to be defined for each output used, the `PRI_MIXER_OUT_i` and the `PRI_MIXER_PWM_i` parameters, which define the output type and the default PWM rate, respectively, for the `i`th output. -See the [Parameter Configuration Page](parameter-configuration.md) for more information on these parameters. -The PWM rate is typically 490 or 50 Hz. - -!!! warning "Mixing Matrix PWM Header" - - Depending on the hardware used, the 10 `PRI_MIXER_PWM_*` parameters need to be grouped into sections. - This is because the PWM outputs are not all on separate interrupts, so it is not possible to set each PWM rate individually. - - The number of interrupts varies based on hardware. - If you don't want to worry about it, just set all the `PRI_MIXER_PWM_i` to the same value, if possible. - -The recommended way to load a custom mixer is to first compute all the required parameters and save them to a file on the companion computer. -The parameters are named `PRI_MIXER_i_j` or `SEC_MIXER_i_j`, where `(i,j)` is the index of the parameter in the 6x10 mixing matrix. -See the [Parameter Configuration Page](parameter-configuration.md) for more information on these parameters. -A convenience script is available in the `roscopter` ROS2 package that will compute the custom mixer and save the parameter values in a format ready to load. - -Once the parameters are saved to a file, load them with the ROS2 service call (make sure `rosflight_io` is running): -```ros2 service call /param_load_from_file rosflight_msgs/srv/ParamFile "{file: absolute/or/relative/path/to/saved/param/file.yaml}"``` - -Also make sure to save those parameters to memory with the ROS2 service call: -```ros2 service call /param_write std_srvs/srv/Trigger``` - -!!! tip - - Test your mixer in simulation first when making changes, to avoid accidents. - -## Connecting to the Flight Controller - -The flight controller communicates with the companion computer over a serial link. ROSflight only supports one serial connection at a time and by default should be the serial link connected to the USB connector on the board. diff --git a/docs/user-guide/customizing-rosflight.md b/docs/user-guide/customizing-rosflight.md index bd65b3a9..e7d34d26 100644 --- a/docs/user-guide/customizing-rosflight.md +++ b/docs/user-guide/customizing-rosflight.md @@ -19,7 +19,7 @@ We also give some examples of how elements of ROSflight could be modified. Modules on the companion computer and modules on the FCU are designed differently, so the methods for customizing the ROSflight autonomy stacks and the ROSflight firmware are different. !!! warning "ROSflight architecture" - This page will not go over the [ROScopter](./roscopter/roscopter-overview.md)/[ROSplane](./concepts/rosplane-overview.md)/[ROSflight firmware](../developer-guide/firmware/code-architecture.md) architecture, but we do reference it. + This page will not go over the [ROScopter](./roscopter/index.md)/[ROSplane](./rosplane/index.md)/[ROSflight firmware](rosflight-firmware/code-architecture.md) architecture, but we do reference it. Please see the respective documentation for a description of each module before reading through this page. ## Customizing ROSflight firmware @@ -27,10 +27,10 @@ The core [ROSflight firmware](./overview.md) resides on an embedded microcontrol Most users of ROSflight will not need to customize the ROSflight firmware, since the vast majority of the autonomy stack is on the companion computer. If you need to customize the ROSflight firmware, first consider if you can accomplish what you need on the companion computer. -If you still need to customize the ROSflight firmware, make your changes and then follow the [building and flashing guide](../developer-guide/firmware/building-and-flashing.md) to flash it on your board. +If you still need to customize the ROSflight firmware, make your changes and then follow the [building and flashing guide](hardware-and-rosflight/flight-controller-setup.md#building-and-flashing-the-firmware) to flash it on your board. -However, since ROSflight currently supports only [limited hardware](./concepts/flight-controller-setup.md), users may need to write a new board-specific support package for the ROSflight firmware. -The ROSflight firmware depends on [an abstraction of a physical board](../developer-guide/firmware/code-architecture.md). +However, since ROSflight currently supports only [limited hardware](./hardware-and-rosflight/flight-controller-setup.md), users may need to write a new board-specific support package for the ROSflight firmware. +The ROSflight firmware depends on [an abstraction of a physical board](rosflight-firmware/code-architecture.md). This means that supporting ROSflight on a new board does not require users to change the core ROSflight firmware code. Instead, users only have to write drivers for sensors and implement the board-specific functions in the interface file. diff --git a/docs/user-guide/hardware-and-rosflight/flight-controller-setup.md b/docs/user-guide/hardware-and-rosflight/flight-controller-setup.md new file mode 100644 index 00000000..103becc7 --- /dev/null +++ b/docs/user-guide/hardware-and-rosflight/flight-controller-setup.md @@ -0,0 +1,158 @@ +# Flight Controller Setup + + +## Compatible Hardware + +Currently, the ROSflight firmware supports: + +1. An in-development board from AeroVironment, the **Varmint**. +This board has an integrated Jetson Orin, but is not yet commercially available. +1. **[MRO's Pixracer Pro](https://store.3dr.com/pixracer-pro/)**, which has the same H7 processor. + +!!! note "Supporting your own board" + + It is possible to write your own board support package (BSP). + If you do create your own support package for the ROSflight firmware, please contribute back! + +## Serial Port Configuration + +!!! tip + You can see which groups you are a member of by running `groups $USER` on the command line. + +The following bullet point is necessary: + +* Be sure your user is in the `dialout` and `plugdev` groups so you have access to the serial ports. You will need to log out and back in for these changes to take effect. +``` bash +sudo usermod -aG dialout,plugdev $USER +``` + +If you experience issues, you may need one or both of the next two bullet points: + +* Temporarily stop the modem-manager (Sometimes, Linux thinks the device is a modem -- this command will be effective until next boot, or until you run the command again with `start` in place of `stop`) +``` bash +sudo systemctl stop ModemManager.service +``` + +* Add the custom udev rule so Linux handles the flight controller properly (copy the following as `/etc/udev/rules.d/45-stm32dfu.rules`) +``` bash +# DFU (Internal bootloader for STM32 MCUs) +SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE="0664", GROUP="plugdev" +``` + +!!! Tip + You can permanently disable the ModemManager if you do not need it, then you won't have to disable it every time you reboot: + ``` + sudo systemctl disable ModemManager.service + ``` + Replace `disable` with `enable` to revert (i.e. if you find some other program you use needs access to it). + Or you can uninstall it entirely from your system: + ``` + sudo apt purge modemmanager + ``` + +## Building and Flashing the Firmware + +This guide assumes you are running Ubuntu 22.04 LTS, which is the currently supported development environment. + +### Installing the ARM Embedded Toolchain + +``` bash +sudo apt install gcc-arm-none-eabi +``` + +You can test the installation and check which version is installed by running `arm-none-eabi-gcc --version`. + +### Building the Firmware from Source + +1. To build the firmware, first clone the firmware repository: + ```bash + git clone --recursive https://github.com/rosflight/rosflight_firmware + ``` +1. Create build directory: + ```bash + cd rosflight_firmware && mkdir build && cd build + ``` +1. Build using: (`board_name` should be either `varmint` or `pixracer_pro`) + ```bash + cmake .. -DBOARD_TO_BUILD= && make -j + ``` + +### Flashing firmware + +#### Install STM32CubeProgrammer + +We use the STM32CubeProgrammer to flash the flight controller. + +1. Download the programmer [here](https://www.st.com/en/development-tools/stm32cubeprog.html#get-software). + You may have to enter your email to download the software. +1. Install the software by following the instructions in the downloaded package. + +#### Flashing the Varmint + +!!! warning "Needed tools" + + You will need an ST-Link STM programmer to flash the firmware. + We use ST-Link V2, and you can find it [on Mouser](https://www.mouser.com/ProductDetail/STMicroelectronics/ST-LINK-V2?qs=H4BOwPtf9MC1sDQ8j3cy4w%3D%3D&mgh=1&utm_id=22314976717&utm_source=google&utm_medium=cpc&utm_marketing_tactic=amercorp&gad_source=1&gad_campaignid=22304734959). + +1. Plug the end of the ribbon cable into the 6-pin slot on the Varmint. + You may have to make your own cable that connects the ST-Link to the 6-pin connector. + + !!! danger + + The Varmint has 2 6-pin connectors. + **Do not** connect the ribbon cable to the port closest to the power wires. + + ![Varmint 6-pin cable](../images/varmint_flash_instructions.png) + +1. Power on the Varmint by connecting a battery to the board. + +1. Open STM32CubeProgrammer. + +1. Plug in the USB connector from the ST-Link to the computer. Select "Connect" in the STM32CubeProgrammer. This should detect the ST-Link and connect automatically. + ![Select "Connect"](../images/stm_programmer_connect.png) + +1. Navigate to the programming page. + ![Navigate to programming page](../images/stm32_programming_page.png) + +1. Select the hex file that was just built and click "Open". + ``` + /path/to/rosflight_firmware/build/boards/varmint_h7/varmint_10X/varmint10X.hex + ``` + ![Select the previously built hex file](../images/stm32_select_hex.png) + +1. Select the appropriate options and press "Start Programming" + ![Select options and start programming](../images/stm32_select_options.png) + +#### Flashing the Pixracer Pro + +Flashing the Pixracer Pro is a very similar process to flashing the Varmint. + +1. The Pixracer Pro does not use the same 6-pin connector to connect to the ST-Link. + Instead, it uses a TC2030 connector with retaining clips. + + !!! tip "Connectors we use" + + In addition to the ST-Link V2 board linked above, we use these cables to flash the Pixracer Pro: + + 1. [20-pin ribbon adapter board](https://www.tag-connect.com/product/arm20-ctx-m) (connect the ST-Link to this adapter) + 2. [Programming cable](https://www.tag-connect.com/product/tc2030-idc-nl) that connects to the adapter board + 3. [TC2030 clip](https://www.tag-connect.com/product/tc2030-retaining-clip-board-3-pack) to attach the programming cable to the board + + ![Connectors for the Pixracer Pro](./../images/pixracer_pro_flash_instructions.jpeg) + +1. Power on the Pixracer Pro using a USB-C port. + +2. Follow the instructions from the [Varmint flashing guide](#flashing-the-varmint). + +## LEDs + +!!! danger "TODO" + Update this table with the updated LED flash patterns. + +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) | diff --git a/docs/user-guide/concepts/getting-started.md b/docs/user-guide/hardware-and-rosflight/getting-started.md similarity index 89% rename from docs/user-guide/concepts/getting-started.md rename to docs/user-guide/hardware-and-rosflight/getting-started.md index 9cf21632..25e304d8 100644 --- a/docs/user-guide/concepts/getting-started.md +++ b/docs/user-guide/hardware-and-rosflight/getting-started.md @@ -6,10 +6,10 @@ Reading through the pages in this user guide in order should provide you with th 2. [Flight controller setup](flight-controller-setup.md): Flash your flight controller with the latest ROSflight firmware. 3. [RC Configuration](rc-configuration.md): Set up your RC transmitter. 4. [ROS2 setup](../installation/installation-hardware.md): Set up ROS2 on your companion computer. - 5. [Parameter configuration](parameter-configuration.md): Configure the flight controller for your setup. The configuration checklists below should help guide you through this process. + 5. [Parameter configuration](../rosflight-firmware/parameter-configuration.md): Configure the flight controller for your setup. The configuration checklists below should help guide you through this process. 6. [Preflight checks](preflight-checks.md): Run through your preflight checks 7. [Improving firmware performance](improving-firmware-performance.md) (multirotors only): Tune the firmware attitude controller gains - 8. [Autonomous flight](autonomous-flight.md) (optional): Set up autonomous flight via offboard control + 8. [Autonomous flight](../rosflight-firmware/autonomous-flight.md) (optional): Set up autonomous flight via offboard control ## Configuration Checklist @@ -25,7 +25,7 @@ The following checklists should help you get a new vehicle set up for the first 6. Set up your RC switches * If you want to arm/disarm using a switch, set the `ARM_CHANNEL` parameter to the appropriate channel (0-indexed) * If you want to use a switch to enable RC override, set the `RC_ATT_OVRD_CHN` and `RC_THR_OVRD_CHN` parameters to the appropriate channel(s) (0-indexed). If you want complete control (attitude and throttle) when you flip the switch, set both these parameters to the same channel. - 7. Calibrate your IMU: start `rosflight_io`, then run `ros2 service call /calibrate_imu std_srvs/srv/Trigger` + 7. Calibrate your IMU: Start [`rosflight_io`](../rosflight-io.md), then run `ros2 service call /calibrate_imu std_srvs/srv/Trigger` 8. Complete the multirotor-specific or fixed-wing-specific checklist below 9. Save the parameters (`ros2 service call /param_write std_srvs/srv/Trigger`) 10. You'll probably want to save a backup of your parameters (call `ros2 service call /param_save_to_file rosflight_msgs/srv/ParamFile "{filename: "params.yml"}"`) @@ -47,7 +47,7 @@ The following checklists should help you get a new vehicle set up for the first 3. Connect power to the motors 4. Drop the throttle to minimum - 5. Set the `PRIMARY_MIXER` parameter back to the appropriate value for your vehicle (see the [Hardware Setup](hardware-setup.md#motor-layouts-and-mixer) page) + 5. Set the `PRIMARY_MIXER` parameter back to the appropriate value for your vehicle (see the [Hardware Setup](../rosflight-firmware/mixer.md) page) 6. Set `ARM_SPIN_MOTORS` back to `1` 2. The `ARM_SPIN_MOTORS` parameter should be set to `1` so the motors spin slowly when armed. The idle throttle setting can be adjusted with the `MOTOR_IDLE_THR` parameter. diff --git a/docs/user-guide/hardware-and-rosflight/hardware-setup.md b/docs/user-guide/hardware-and-rosflight/hardware-setup.md new file mode 100644 index 00000000..7992a5b1 --- /dev/null +++ b/docs/user-guide/hardware-and-rosflight/hardware-setup.md @@ -0,0 +1,120 @@ +# Hardware Setup + +## Parts List + +To use ROSflight to its full potential, you will need the following system components. +Some components are mounted on your MAV (Miniature Aerial Vehicle), while others are on the ground. +ROSflight supports both multirotor and fixed-wing vehicle types. + + +*Mounted on the MAV* + +1. Aircraft Frame, Motor(s), ESC(s), Battery and Propeller(s) +2. Flight Controller (FC) +3. Vibration Isolation for FC +4. Any external sensors +5. R/C Receiver +6. Companion Computer +7. Wi-Fi Antenna, or access of some kind to ground-station, wireless network (e.g. Ubiquiti Bullet) + +*Ground Station* + +1. Ground-Station, Wireless Network (e.g. Wi-Fi Router, Ubiquiti Rocket) +2. R/C transmitter +3. Laptop or base station computer +4. Joystick (Xbox controller) + +### Frame, Motors, ESCs, Battery, and Propeller + +We do not officially support any specific multirotor or airplane frame, motor, ESC, Battery or Propeller combination. +There are a lot of great resources for building your own MAV, and there are a lot of great kits out there that have all of these parts. + +If you are designing your own multirotor or airplane, you may want to look at [ecalc](https://www.ecalc.ch/), an online tool which can help you design a proper ESC/Battery/Motor/Propeller system for your MAV. + +Some things to keep in mind as you design or build your MAV. + +* Most kits do not include space for a companion computer, cameras, laser scanners or other sensors. Be sure to think about where these components are going to go, and how their placement will affect the CG of the MAV. +* You will likely also need to customize the power circuitry of your MAV to provide power to your companion computer at some specific voltage. Many people like to separate the power electronics (the ESCs and motors), from the computer and companion sensors. This can really come in handy if you are trying to develop code on the MAV, because you can have the computer on and sensors powered, and not worry at all about propellers turning on and causing injury as you move the aircraft about by hand. We will talk about this more when we talk about wiring up your MAV. +* Cheap propellers can cause a huge amount of vibration. Consider buying high-quality propellers, doing a propeller balance, or both. RCGroups, DIY Drones and YouTube have some awesome guides on how to do propeller balancing. +* ESCs will need to be calibrated from 2000 to 1000 us + + +### Flight Controller + +The flight controller is the embedded microcontroller that runs `rosflight_firmware`. +See the [list of compatible hardware](./flight-controller-setup.md) for more information. + +The flight controller includes an IMU and a barometer, as well as some additional sensors depending on the board. + +### External Sensors + +Additional Sensors you may want for your ROSflight setup include: + +* Sonar +* GPS +* Digital Airspeed Sensor (Pitot Tube) + +### Vibration Isolation + +It is really important to isolate your flight controller from vehicle vibrations, such as those caused by propellers and motors. We recommend using small amounts of [Kyosho Zeal](https://www.amainhobbies.com/kyosho-zeal-5mm-vibration-absorption-gyro-receiver-mounting-gel-kyoz8006b/p1391945) to mount a fiberglass plate holding the FC to the MAV. You may also want to try adding mass to the flight control board. We have accomplished this by gluing steel washers to the fiberglass mounting plate. + +![Vibration Isloation](../images/vibration_isolation.png) + +You may need to experiment with the amount of gel you use, how far apart the gel is spaced, and the amount of mass added to the FC mounting plate. The interaction of these factors is difficult to predict, therefore it takes a little bit of experimentation to get it right. + +### Companion Computer + +The only requirement for the companion computer is that it runs Linux (usually an Ubuntu LTS version, but using Docker on other distributions is also an option), ROS2, has at least one USB port, and can be carried by the aircraft. We have had success with the following companion computers, but by no means is this a comprehensive list; it is more by way of suggestion. + +* [NVIDIA Jetson](https://www.nvidia.com/en-us/autonomous-machines/embedded-systems/) +* [MSI CUBI](https://www.msi.com/Business-Productivity-PCs/Products#?tag=Cubi-Series) +* [Intel NUC](https://www.intel.com/content/www/us/en/products/details/nuc.html) +* [Rasberry Pi 3](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) + +### Wi-Fi + +You will need Wi-Fi to communicate with your MAV when it is in the air. Because ROS2 communicates over UDP, it is very easy to use ROS2 to view what is going on in your MAV while it is flying by sending commands and reading sensor data. For most applications, a standard Wi-Fi router and dongle will suffice. For long-range applications, you may want to look into [Ubiquiti](https://www.ubnt.com/) point-to-point Wi-Fi. (We have seen ranges over a mile with these networks.) + +### RC Transmitter and Receiver + +For RC Control, you will need a transmitter with between 6 and 8 channels. Any additional channels will be wasted. We require RC control for safe operation, and only support arming and disarming via RC control. + + +ROSflight only supports PPM (pulse position modulation) and SBUS receivers. Individual channel PWM outputs are not supported. Any configurations with PPM or SBUS and 6-8 channels will be sufficient. + +### Laptop or Base Station Computer + +You will need a laptop which can run ROS2 to communicate with the MAV over the ground station wireless network. To do this natively you'll want a recent Ubuntu LTS version, but this can also be done with Docker containers from pretty much any Linux distribution. Linux within a virtual machine can also work, but is not recommended. + +### Joystick + +A joystick is used for [software-in-the-loop (SIL) simulations](../rosflight-sim/index.md). The joystick is not technically a required component because it is possible to control your MAV from the command line, but it makes things much easier. Our first recommendation is to use the same transmitter you use for hardware as a joystick by plugging it into the computer via USB. We support Taranis QX7 transmitters, Radiomaster TX16s transmitters, RealFlight controllers, and XBOX controllers. Other joysticks can be used, but you may need to create custom axis and button mappings within the ROSflight joystick utility. + +!!! note "Physical vs firmware channels" + If you do write your own mapping, remember that the channel numbers need to be configured properly on both the firmware and the transmitter. + This means that if the RC transmitter outputs "throttle" on channel 3 on the (1 indexed on the transmitter), then the firmware needs to set `RC_F_CHN` to 2 (0 indexed). + + +### Battery Monitor + +A battery monitor is an analog sensor that provides battery voltage and/or battery current information. This data can be used to prevent power loss in air or to measure system load. The sensor outputs an analog voltage proportional to the battery voltage and/or current through the battery. Most flight controllers come equipped with a built-in battery monitor, but if not, small PCB sensors are also available that can be connected to the flight controller. + + +For ROSflight to use a battery monitor, an appropriate multiplier must be set. ROSflight multiplies the analog signal from the monitor by the multiplier to get the final reading. The monitor datasheet should contain the information needed to get the multiplier. For example, the datasheet for the AttoPilot 50V/90A sensor states that it outputs 63.69 mV / V. To get the original battery voltage, the multiplier must be 1/.06369, or 15.7. The multipliers for the voltage and current are set separately, with the `BATT_VOLT_MULT` and `BATT_CURR_MULT` parameters, respectively. + +ROSflight applies a simple low-pass filter to remove noise from the voltage and current measurements. These filters are configurable via the `BATT_VOLT_ALPHA` and `BATT_CURR_ALPHA` [parameters](../rosflight-firmware/parameter-configuration.md). The alpha value for a given cutoff frequency \\(a\\), can be calulated with: \\( \alpha = e ^ {-.01a} \\). As battery voltages do not typically change quickly, the default of 0.995 usually suffices. + +More information on battery monitor hardware, including determining appropriate multipliers and creating a simple DIY monitor, can be found on the [OpenPilot Wiki](https://opwiki.readthedocs.io/en/latest/user_manual/revo/voltage_current.html). + +## Wiring Diagram + + +Below is an example wiring diagram for a multirotor using an MSI Cubi as a companion computer. This diagram also includes the motor power switch, which allows for the sensors, flight controller, and companion computer to be powered on while the motors are off. This is a safer way to test sensors, code, etc. as the motors are unable to spin while the switch is off. + +![Wiring Diagram](../images/Wiring_Diagram.png) + +Your needs will likely be slightly different than what is shown. This is meant as an example only and can be adapted to fit your needs. + +## Connecting to the Flight Controller + +The flight controller communicates with the companion computer over a serial link. ROSflight only supports one serial connection at a time and by default should be the serial link connected to the USB connector on the board. diff --git a/docs/user-guide/concepts/improving-firmware-performance.md b/docs/user-guide/hardware-and-rosflight/improving-firmware-performance.md similarity index 100% rename from docs/user-guide/concepts/improving-firmware-performance.md rename to docs/user-guide/hardware-and-rosflight/improving-firmware-performance.md diff --git a/docs/user-guide/concepts/preflight-checks.md b/docs/user-guide/hardware-and-rosflight/preflight-checks.md similarity index 100% rename from docs/user-guide/concepts/preflight-checks.md rename to docs/user-guide/hardware-and-rosflight/preflight-checks.md diff --git a/docs/user-guide/concepts/rc-configuration.md b/docs/user-guide/hardware-and-rosflight/rc-configuration.md similarity index 100% rename from docs/user-guide/concepts/rc-configuration.md rename to docs/user-guide/hardware-and-rosflight/rc-configuration.md diff --git a/docs/developer-guide/firmware/images/HAL.svg b/docs/user-guide/images/HAL.svg similarity index 100% rename from docs/developer-guide/firmware/images/HAL.svg rename to docs/user-guide/images/HAL.svg diff --git a/docs/developer-guide/firmware/images/arming-fsm.svg b/docs/user-guide/images/arming-fsm.svg similarity index 100% rename from docs/developer-guide/firmware/images/arming-fsm.svg rename to docs/user-guide/images/arming-fsm.svg diff --git a/docs/developer-guide/firmware/images/flight_stack.svg b/docs/user-guide/images/flight_stack.svg similarity index 100% rename from docs/developer-guide/firmware/images/flight_stack.svg rename to docs/user-guide/images/flight_stack.svg diff --git a/docs/developer-guide/firmware/images/pixracer_pro_flash_instructions.jpeg b/docs/user-guide/images/pixracer_pro_flash_instructions.jpeg similarity index 100% rename from docs/developer-guide/firmware/images/pixracer_pro_flash_instructions.jpeg rename to docs/user-guide/images/pixracer_pro_flash_instructions.jpeg diff --git a/docs/user-guide/images/primary_secondary_mixer_mixing.svg b/docs/user-guide/images/primary_secondary_mixer_mixing.svg new file mode 100644 index 00000000..80149ce6 --- /dev/null +++ b/docs/user-guide/images/primary_secondary_mixer_mixing.svg @@ -0,0 +1,3 @@ + + +
Header
Primary Mixer
(RC pilot mixer)
Secondary Mixer
(offboard mixer)
RC throttle override active
RC attitude override active

Header

Header

 \ No newline at end of file diff --git a/docs/user-guide/images/rc_mixer_configuration.png b/docs/user-guide/images/rc_mixer_configuration.png deleted file mode 100644 index e3361e56..00000000 Binary files a/docs/user-guide/images/rc_mixer_configuration.png and /dev/null differ diff --git a/docs/developer-guide/firmware/images/stm32_programming_page.png b/docs/user-guide/images/stm32_programming_page.png similarity index 100% rename from docs/developer-guide/firmware/images/stm32_programming_page.png rename to docs/user-guide/images/stm32_programming_page.png diff --git a/docs/developer-guide/firmware/images/stm32_select_hex.png b/docs/user-guide/images/stm32_select_hex.png similarity index 100% rename from docs/developer-guide/firmware/images/stm32_select_hex.png rename to docs/user-guide/images/stm32_select_hex.png diff --git a/docs/developer-guide/firmware/images/stm32_select_options.png b/docs/user-guide/images/stm32_select_options.png similarity index 100% rename from docs/developer-guide/firmware/images/stm32_select_options.png rename to docs/user-guide/images/stm32_select_options.png diff --git a/docs/developer-guide/firmware/images/stm_programmer.png b/docs/user-guide/images/stm_programmer.png similarity index 100% rename from docs/developer-guide/firmware/images/stm_programmer.png rename to docs/user-guide/images/stm_programmer.png diff --git a/docs/developer-guide/firmware/images/stm_programmer_connect.png b/docs/user-guide/images/stm_programmer_connect.png similarity index 100% rename from docs/developer-guide/firmware/images/stm_programmer_connect.png rename to docs/user-guide/images/stm_programmer_connect.png diff --git a/docs/developer-guide/firmware/images/varmint_flash_instructions.png b/docs/user-guide/images/varmint_flash_instructions.png similarity index 100% rename from docs/developer-guide/firmware/images/varmint_flash_instructions.png rename to docs/user-guide/images/varmint_flash_instructions.png diff --git a/docs/user-guide/installation/installation-hardware.md b/docs/user-guide/installation/installation-hardware.md index af49ada0..4303f2bf 100644 --- a/docs/user-guide/installation/installation-hardware.md +++ b/docs/user-guide/installation/installation-hardware.md @@ -155,10 +155,10 @@ Do the following on your companion computer. ROS2 will not be installed on the flight controller unit (FCU). We will only need to build and flash the FCU with the `rosflight_firmware`. -See the [flight controller guide](../concepts/flight-controller-setup.md) for instructions on how to do this. +See the [flight controller guide](../hardware-and-rosflight/flight-controller-setup.md) for instructions on how to do this. ## Next Steps At this point, you have successfully installed ROS2 and set up ROSflight on the companion computer, including all required dependencies. -For guidance on running simulations, see the [tutorials](../tutorials/tutorial-overview.md). +For guidance on running simulations, see the [tutorials](../tutorials/index.md). diff --git a/docs/user-guide/overview.md b/docs/user-guide/overview.md index 9f74f8ed..92c05475 100644 --- a/docs/user-guide/overview.md +++ b/docs/user-guide/overview.md @@ -9,10 +9,10 @@ !!! tip "New to ROSflight?" If you are new to ROSflight, we recommend that you first start by setting up the simulation environment and learning to use the ROSflight ecosystem. - Do this by following the [installation for sim](./installation/installation-sim.md) guides, and then the [ROSflight tutorials](./tutorials/tutorial-overview.md). + Do this by following the [installation for sim](./installation/installation-sim.md) guides, and then the [ROSflight tutorials](./tutorials/index.md). After you do that, you should be ready to start using ROSflight in your own research! - We recommend you first read through the architecture documentation for [ROSplane](./concepts/rosplane-overview.md) and [ROScopter](./roscopter/roscopter-overview.md). + We recommend you first read through the architecture documentation for [ROSplane](./rosplane/index.md) and [ROScopter](./roscopter/index.md). Then visit the [Customizing ROSflight page](./customizing-rosflight.md) for more specifics on how to customize ROSflight for your research. @@ -48,16 +48,16 @@ Although higher level control is offloaded to the companion computer, enough con [ROSplane](https://github.com/rosflight/rosplane) and [ROScopter](https://github.com/rosflight/roscopter) are ROS2 based autonomy stacks that run on the companion computer and do most of the heavy computation of the autopilot. Each portion of their autonomy stacks are organized into highly modular ROS nodes that can be easily swapped out with custom nodes. ROSplane and ROScopter are not required for using ROSflight and you could choose to use an entirely different autonomy stack if you so desired. -See the [ROSplane](./concepts/rosplane-overview.md) and [ROScopter](./roscopter/roscopter-overview.md) documentation for a detailed description of the respective architectures and functionality. +See the [ROSplane](./rosplane/index.md) and [ROScopter](./roscopter/index.md) documentation for a detailed description of the respective architectures and functionality. ### 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. -See the [RC Setup](./concepts/rc-configuration.md) page for more information. +See the [RC Setup](./hardware-and-rosflight/rc-configuration.md) page for more information. ## Where do I start? To get started with ROSflight, we recommend you first set up the simulation environment and walk through the tutorials to get familiar with the ROSflight ecosystem. -If you are ready to start with hardware experiments, first [install the required software](./installation/installation-hardware.md) and then follow the [hardware setup guide](./concepts/getting-started.md) to configure your vehicle for successful flight tests. +If you are ready to start with hardware experiments, first [install the required software](./installation/installation-hardware.md) and then follow the [hardware setup guide](./hardware-and-rosflight/getting-started.md) to configure your vehicle for successful flight tests. diff --git a/docs/user-guide/roscopter/roscopter-overview.md b/docs/user-guide/roscopter/index.md similarity index 91% rename from docs/user-guide/roscopter/roscopter-overview.md rename to docs/user-guide/roscopter/index.md index 4b8073d7..05cf199f 100644 --- a/docs/user-guide/roscopter/roscopter-overview.md +++ b/docs/user-guide/roscopter/index.md @@ -4,7 +4,7 @@ Ready to get fly your code with ROScopter? Start here: - 1. Follow [the ROSflight tutorials](../tutorials/tutorial-overview.md) to set up ROScopter fly waypoint missions in sim. + 1. Follow [the ROSflight tutorials](../tutorials/index.md) to set up ROScopter fly waypoint missions in sim. 2. Read through [the following ROScopter architecture pages](./roscopter-path-planner.md) to understand the responsibilities of each node. 3. Find examples of how to customize ROScopter in the [Customizing ROSflight](../customizing-rosflight.md) page. @@ -40,7 +40,7 @@ See [the ROScopter autonomy stack documentation pages](./roscopter-path-planner. ## Using ROScopter as-is ROScopter's default waypoint-following functionality may be useful to some users. -The [ROSflight tutorials](../tutorials/tutorial-overview.md) walk users through setting up ROSflight and ROScopter in sim, all the way through flying waypoint missions. +The [ROSflight tutorials](../tutorials/index.md) walk users through setting up ROSflight and ROScopter in sim, all the way through flying waypoint missions. Follow those tutorials first to get a feel for the default ROScopter behavior and workflow before you start making your own changes to the autonomy stack. A detailed description of the ROScopter autonomy stack and each module is found in [the ROScopter architecture pages](./roscopter-path-planner.md). @@ -50,7 +50,7 @@ A detailed description of the ROScopter autonomy stack and each module is found ROScopter's default functionality may not be sufficient for many users. Because of this, ROScopter has been designed to be understandable, modular, and customizable. -The [customizing ROflight page](../customizing-rosflight.md) describes how ROScopter is meant to be modified to assist in your research. +The [customizing ROSflight page](../customizing-rosflight.md) describes how ROScopter is meant to be modified to assist in your research. The page also includes examples and scenarios where each node can be modified, removed, or combined to accomplish different tasks. ## ROScopter Architecture Overview diff --git a/docs/user-guide/concepts/autonomous-flight.md b/docs/user-guide/rosflight-firmware/autonomous-flight.md similarity index 72% rename from docs/user-guide/concepts/autonomous-flight.md rename to docs/user-guide/rosflight-firmware/autonomous-flight.md index f62699eb..7731923e 100644 --- a/docs/user-guide/concepts/autonomous-flight.md +++ b/docs/user-guide/rosflight-firmware/autonomous-flight.md @@ -1,6 +1,10 @@ # Autonomous Flight -To perform autonomous flight with ROSflight, we need to send control commands from our companion computer to the firmware. This can be done with ROSplane or ROScopter, which already have completed autonomy stacks developed specifically for ROSflight. We recommend starting with one of these autonomy stacks and building on them to suit your needs. If using a multirotor, follow the [ROScopter setup guide](../roscopter/roscopter-overview.md) to get started. If using a fixed-wing, follow the [ROSplane setup guide](rosplane-setup.md). +To perform autonomous flight with ROSflight, we need to send control commands from our companion computer to the firmware. +This can be done with ROSplane or ROScopter, which already have completed autonomy stacks developed specifically for ROSflight. +We recommend starting with one of these autonomy stacks and building on them to suit your needs. +If using a multirotor, follow the [ROScopter setup guide](../roscopter/index.md) to get started. +If using a fixed-wing, follow the [ROSplane setup guide](../rosplane/rosplane-setup.md). However, ROSplane and ROScopter are optional and an entirely different autonomy stack can be used if desired. To use a different autonomy stack, follow this guide. @@ -64,35 +68,38 @@ The `ignore` field is a bitmask that can be populated by combining the values in ignore = IGNORE_QX | IGNORE_QY | IGNORE_FZ ``` -The best practice is to use enum names rather than the actual numeric values for the `mode` and `ignore` fields. For example, to specify a multirotor attitude angle command in C++ I might have: -```cpp -#include -#include - -rosflight_msgs::msg::Command msg; -msg.header.stamp = node->get_clock()->now(); -msg.mode = rosflight_msgs::msg::Command::MODE_ROLL_PITCH_YAWRATE_THROTTLE; -msg.ignore = rosflight_msgs::msg::Command::IGNORE_NONE; -msg.qx = 0.0; -msg.qy = 0.0; -msg.qz = 0.0; -msg.fz = 0.6; -``` +The best practice is to use enum names rather than the actual numeric values for the `mode` and `ignore` fields. For example, to specify a multirotor attitude angle command I might have: + +=== "C++" + ```cpp + #include + #include + + rosflight_msgs::msg::Command msg; + msg.header.stamp = node->get_clock()->now(); + msg.mode = rosflight_msgs::msg::Command::MODE_ROLL_PITCH_YAWRATE_THROTTLE; + msg.ignore = rosflight_msgs::msg::Command::IGNORE_NONE; + msg.qx = 0.0; + msg.qy = 0.0; + msg.qz = 0.0; + msg.fz = 0.6; + ``` + +=== "Python" + ```python + import rclpy + from rosflight_msgs.msg import Command + + msg = Command() + msg.header.stamp = node.get_clock().now().to_msg() + msg.mode = Command.MODE_ROLL_PITCH_YAWRATE_THROTTLE + msg.ignore = Command.IGNORE_NONE + msg.qx = 0.0 + msg.qy = 0.0 + msg.qz = 0.0 + msg.fz = 0.6 + ``` -In Python I might have: -```python -import rclpy -from rosflight_msgs.msg import Command - -msg = Command() -msg.header.stamp = node.get_clock().now().to_msg() -msg.mode = Command.MODE_ROLL_PITCH_YAWRATE_THROTTLE -msg.ignore = Command.IGNORE_NONE -msg.qx = 0.0 -msg.qy = 0.0 -msg.qz = 0.0 -msg.fz = 0.6 -``` I would then publish this message to the `/command` topic to forward it to the embedded flight controller. !!! note diff --git a/docs/developer-guide/firmware/code-architecture.md b/docs/user-guide/rosflight-firmware/code-architecture.md similarity index 82% rename from docs/developer-guide/firmware/code-architecture.md rename to docs/user-guide/rosflight-firmware/code-architecture.md index 0d601bcb..985a17ac 100644 --- a/docs/developer-guide/firmware/code-architecture.md +++ b/docs/user-guide/rosflight-firmware/code-architecture.md @@ -4,7 +4,7 @@ The firmware is divided into two main components: the _core library_, and a coll This division is intended to allow the same core flight code to run on any processor or platform, either an embedded flight controller or a desktop environment for a software-in-the-loop (SIL) simulation. The interface between these two components is called the _hardware abstraction layer_ (HAL). This architecture is illustrated in the following diagram: -![hardware abstraction layer](images/HAL.svg) +![hardware abstraction layer](../images/HAL.svg) ## Firmware Core Library @@ -42,7 +42,7 @@ Each of these modules is implemented as a C++ class, and encapsulates a cohesive The following diagram illustrates these modules and the data flow between them. Rectangular blocks represent modules in the flight stack, and ellipses represent hardware functionality implemented in the board support layer: -![flight stack](images/flight_stack.svg) +![flight stack](../images/flight_stack.svg) We'll describe each of these modules in the following sections: @@ -52,7 +52,7 @@ While only the comm manager data flow is illustrated on the diagram, all other m The operation of the state manager is defined by the following finite state machine: -![state manager FSM](images/arming-fsm.svg) +![state manager FSM](../images/arming-fsm.svg) The state manager also includes functionality for recovering from hard faults. In the case of a hard fault, the firmware writes a small amount of data to backup memory then reboots. This backup memory location is checked and then cleared after every reboot. The backup memory includes the armed state of the flight controller. On reboot, the firmware will initialize then, if this armed-state flag is set, immediately transition back into the armed state. This functionality allows for continued RC control in the case of a hard fault. Hard faults are not expected with the stable firmware code base, but this feature adds an additional layer of safety if experimental changes are being made to the firmware itself. @@ -62,6 +62,8 @@ It supports the getting and setting of integer and floating-point parameters, an Setting and getting of parameters from the companion computer is done through the serial communication interface. While no other data flow lines are shown on the diagram, all of the other modules interact with the parameter server. +See the [parameter configuration](../rosflight-firmware/parameter-configuration.md) page for more information on each of the ROSflight parameters and how to get and set parameters. + ### Comm Manager This module handles all serial communication between the flight controller and companion computer. This includes streaming data and receiving offboard control setpoints and other commands from the computer. @@ -76,6 +78,17 @@ The implementation is found in [comms/mavlink/mavlink.h](https://github.com/rosf This module is in charge of managing the various sensors (IMU, magnetometer, barometer, differential pressure sensor, sonar altimeter, etc.). Its responsibilities include updating sensor data at appropriate rates, and computing and applying calibration parameters. +For some sensors, the orientation is critical. +For example, the IMU and magnetometer sensor data must be oriented in the correct frame to be interpreted correctly. +The ROSflight firmware expects that the [board implementation](#board-abstraction) handles rotating the sensor data into a board-aligned NED frame. + +In some cases, the magnetometer is mounted to a different board then the main flight controller (e.g. the mRo M10034D GPS/mag board). +In this case, the ROSflight sensor driver does not orient the magnetometer data into the main autopilot-board frame (since it has no idea how the mag board is oriented relative to the autopilot board). + +ROSflight also aligns IMU and magnetometer data with the vehicle NED frame before [streaming the data](#comm-manager) to the companion computer. +This is done using a rotation from the board frame to the vehicle frame. +This rotation from board to vehicle frame can be configured via [parameters](#parameter-server). + ### Estimator This module is responsible for estimating the attitude and attitude rates of the vehicle from the sensor data. @@ -83,6 +96,8 @@ This module is responsible for estimating the attitude and attitude rates of the The RC module is responsible for interpreting the RC signals coming from the transmitter via the receiver. This includes mapping channels to their appropriate functions and reversing directions if necessary. +See the [RC configuration](../hardware-and-rosflight/rc-configuration.md) page for more information on configuring the RC transmitter and parameters. + ### Command Manager The command manager combines inputs from the RC and comm manager modules to produce a control setpoint. Its main purpose is to handle the interaction between offboard commands and the RC safety pilot, as well as to enforce the failsafe command if the state manager reports failsafe mode. @@ -93,3 +108,5 @@ This control output is computed in a generic form (\(Q_x\), \(Q_y\), and \(Q_z\) ### Mixer The mixer takes the outputs computed by the controller and maps them to actual motor commands depending on the configuration of the vehicle. + +See the [Mixer](./mixer.md) documentation page for more information on the details of the mixer and how to configure it. diff --git a/docs/user-guide/rosflight-firmware/mixer.md b/docs/user-guide/rosflight-firmware/mixer.md new file mode 100644 index 00000000..ff812d06 --- /dev/null +++ b/docs/user-guide/rosflight-firmware/mixer.md @@ -0,0 +1,241 @@ +# Mixer + +A controller is responsible for computing commands that drive a system to a given reference. +However, in general the output of a controller is not raw motor commands. +For example, given a quadrotor vehicle, the [ROSflight firmware rate controller](TODO:insertlinkhere) takes in desired angular rates and outputs desired forces and torques that will achieve those rates. +These desired forces and torques are not individual actuator commands. +Thus, these desired forces and torques must be correctly *mapped* to each individual actuator. + +The *mixer* is responsible for mapping, or mixing, the output of a controller to the individual actuator commands of a MAV. +The mixer is highly frame-specific: a quadrotor mixer will be different than a hexarotor mixer since the hexarotor has 2 additional rotors and all six rotors are in physically different locations relative to the vehicle center of mass. + +!!! danger + If the mixer is not set correctly, it will lead to a crash. + Make sure it is set properly for your airframe! + +In ROSflight, the mixer is a matrix and operates on the inputs $u \in \mathbb{R}^m$ as +$$ +\tau = M^\dagger u +$$ +where $\tau \in \mathbb{R}^n$ is the vector of individual motor commands, $M \in \mathbb{R}^{m\times n}$ is the mixing matrix, and $(\cdot)^\dagger$ is the Moore-Penrose pseudoinverse. + +Note that $n$ denotes the number of possible output commands and $m$ denotes the size of the input commands, which for ROSflight is 6. +Note that $m=6$ was arbitrarily chosen, but conveniently corresponds to the number of forces and torques for a 6-DoF body. +The number of possible output commands is dependent on the number of PWM hardware outputs. + +!!! note + + The rest of this guide focuses on **using** the ROSflight mixer. + Please see the [ROSflight 2.0 paper](https://arxiv.org/abs/2510.00995) for more information on the derivation and details of the ROSflight mixer. + + Additionally, this guide tries not to repeat information found in the paper, so we recommend reading through that paper to get an overview of the ROSflight mixer. + +## ROSflight mixer implementation details +Currently supported hardware for the ROSflight firmware has a maximum of 10 output channels. +Thus, the ROSflight mixing matrix is a 6x10 matrix. + +In addition to storing these 60 values, each ROSflight mixer has a header with the following information: + +- PWM rate (in Hz) for each output channel +- [Output type](#defining-a-custom-mixer) (auxiliary, motor, servo, GPIO) + +Users usually won't have to adjust these header values, unless you [define a custom mixer](#defining-a-custom-mixer) as described below. + +## Selecting a primary mixer + +A primary mixer must be selected before the firmware will allow arming of the vehicle. +The primary mixer is used by the RC safety pilot and thus must be a mixer that allows the RC safety pilot to control the vehicle. +Specifically, the `PRIMARY_MIXER` parameter must be set to a valid value. + +As described in the [ROSflight 2.0 paper](https://arxiv.org/abs/2510.00995), ROSflight offers some pre-computed, "canned" mixers that can be used off the shelf for a variety of common multirotor and fixedwing airframes. +These mixers do not take into account all the parameters of your system (i.e. motor and propeller parameters), but instead are based solely on the geometry of the airframe. +If you want a more accurate mixer, or have easy access to the motor and prop parameters of your system, then we recommend using a [custom mixer](#defining-a-custom-mixer). + +The desired mixer must be chosen by [setting the `PRIMARY_MIXER` parameter](../rosflight-firmware/parameter-configuration.md) to one of the following valid values. + + +| # | Mixer | +|---|---------| +| 0 | ESC calibration | +| 1 | Quad + | +| 2 | Quad X | +| 3 | Hex + | +| 4 | Hex X | +| 5 | Octo + | +| 6 | Octo X | +| 7 | Y6 | +| 8 | X8 | +| 9 | Fixed-wing (traditional AETR) | +| 10 | Inverted V-tail fixedwing (like the RMRC Anaconda frame) | +| 11 | Custom mixer | + +The associated motor layouts are shown below for each mixer. +The **ESC calibration** mixer directly outputs the throttle command equally to each motor, and can be used for calibrating the ESCs. + +![Mixer_1](../images/mixers_1.png) + +## Selecting a secondary mixer +As described in the [ROSflight 2.0 paper](https://arxiv.org/abs/2510.00995), the secondary mixer is used by offboard control setpoints (sent by the companion computer). +The secondary mixer can be selected by setting the `SECONDARY_MIXER` parameter to one of the valid values in the previous table. + +The secondary mixer allows flexibility for more advanced mixing schemes while still having a functional mixer available to a safety pilot. +For example, a secondary mixer on a quadrotor could be configured as an identity matrix. +This would allow motor commands to be sent directly from the offboard computer to the motors. +In this case, the primary mixer could be set to mixer 2 so that the RC safety pilot can use the ROSflight angle/rate controllers, whose output is properly mixed to actuator commands by the mixer 2. + +!!! note + If the secondary mixer is not specified (or set to an invalid value), then it will default to the primary mixer. + If you don't need a distinction between the mixer used by the RC safety pilot and the onboard computer, then you do not need to set the secondary mixer parameter. + +## Mixing the primary and secondary mixers +In ROSflight, the RC safety pilot has the ability to independently override the attitude commands, the throttle commands, or both. +See the [RC configuration page](../hardware-and-rosflight/rc-configuration.md) for more information. + +Remember that the RC commands use the primary mixer and offboard control commands use the secondary mixer. +Thus, when only RC attitude override is active (or conversely only RC throttle override) the mixer actually used by ROSflight to mix controller commands is a combination of the primary and secondary mixers. + +When this happens, the primary and secondary mixers are "mixed" as shown in the following image. + +
+ ![RC Mixer Configuration](../images/primary_secondary_mixer_mixing.svg){ width="1200" loading=lazy } +
Diagram of how the actual mixer used by ROSflight, $M$, is "mixed" with the primary and secondary mixers, depending on the status of RC override.
+
+ +The `mixer_to_use_` structure represents the mixer that is actually used when computing the output. +When just RC throttle override is active (i.e. RC pilot controls the throttle while companion computer controls attitude), the $F$ rows of the `mixer_to_use_` are mapped to the $F$ rows of the primary mixer. +When just RC attitude override is active (i.e. RC pilot controls attitude while companion computer controls throttle), the $Q$ rows of the `mixer_to_use_` are mapped to the $Q$ rows of the primary mixer. + +The header, which includes the default PWM rate and the output type for each output channel, is always set to the header of the primary mixer. + + +## Using Motor Parameters +This section gives some background for the `USE_MOTOR_PARAM` firmware parameter and when it should be set. + +As described in _Small Unmanned Aircraft: Theory and Practice_ by Beard and McLain, the mixing matrix is formed using equations from propeller theory, resulting in a set of equations that set the desired forces and torques equal to the square of the angular speeds of the propellers. + +This results in equations of the form +$$ +M^\dagger u = \tau \propto +\begin{bmatrix} +\Omega_1^2 & \Omega_2^2 & \dots & \Omega_{10}^2 +\end{bmatrix}^T +$$ +where $\Omega_i^2$ is the squared angular speed of motor $i$. +Note that constant factors were omitted in the above equation for simplicity, resulting in the proportionality. + +If the motor and propeller parameters are known, then the desired voltage setting can be computed from these squared angular speeds. +The PWM motor output for each motor can be computed from these desired voltage settings. + +If the `USE_MOTOR_PARAM=1`, then the firmware will assume that the mixed output ($\tau$) is a vector of squared angular speeds ($\Omega^2$), and will use the stored motor and propeller parameters to compute motor commands ($\delta$). + +If the motor and propeller parameters are not known, then some simplifying assumptions are made to compute the desired throttle settings for each motor from the desired forces and torques. +In other words, these assumptions result in equations that look like +$$ +M^\dagger u = \tau = +\begin{bmatrix} +\delta_1 & \delta_2 & \dots & \delta_{10} +\end{bmatrix}^T +$$ +where $\delta_i$ is the $i$th PWM motor output. +**This is the form for all precomputed ("canned") mixers.** + +Therefore, if using a canned mixer, set `USE_MOTOR_PARAM=0` so that the firmware interprets the output of the mixer as $\delta$ commands, not $\Omega^2$ commands. + +See [the ROSflight 2.0 publication](https://arxiv.org/abs/2510.00995) for more information on the specific assumptions and more information on the above topics. + + +The canned mixing matrices assume that `USE_MOTOR_PARAM=0`. +Using a canned mixer matrix and setting `USE_MOTOR_PARAM=1` (i.e. specifying that you want to mix with motor and propeller parameters) will cause the outputs to be scaled incorrectly. +It is not required to use motor and propeller parameters when using a custom mixing matrix, but make sure your custom mixer makes sense. + +Also, if you selected a custom mixer and used the motor parameters to generate the mixer, make sure you set `USE_MOTOR_PARAM=1`. Otherwise, the outputs will likely be scaled incorrectly. + +!!! abstract "Summary" + + If using a canned mixer, set `USE_MOTOR_PARAM=0`. + + If using a custom mixer, set `USE_MOTOR_PARAM=1` **only** if the mixer was designed with motor parameters. + +!!! danger + + We recommend flying your firmware in simulation _before_ loading the firmware onto real hardware to make sure everything is working. + +!!! Warning + + It is not recommended to use a _canned mixer for the primary mixer_ and a _custom mixer for the secondary mixer_ **when the secondary mixer needs `USE_MOTOR_PARAM=1`.** + In other words, both `PRIMARY_MIXER` and `SECONDARY_MIXER` should use motor parameters, or neither should. + + This is important because the canned mixers make assumptions that affect the gains of the controller on the aircraft. + This means that a canned mixer will require slightly different tuning than a custom mixer might. + +### Defining a Custom Mixer + +A custom mixer can be defined by: + +1. Set `PRIMARY_MIXER` (required) and/or `SECONDARY_MIXER` (optional) to the custom mixer value in the mixer table +2. Load the mixing matrix parameters for either/both the primary or the secondary mixer + +The firmware loads a custom mixer by loading all mixing matrix values from parameters. +Since there are 6 inputs to the mixer (\(F_x,F_y,F_z,Q_x,Q_y,Q_z\)) and 10 possible outputs, the mixer is a 6x10 matrix and there are 60 parameters associated with each custom mixer. +For a standard quadrotor, however, most of these would be zero, since only the first 4 outputs (columns of the mixer matrix) would be used. + +In addition to the parameters associated with the 6x10 mixing matrix, the [mixer header values](#rosflight-mixer-implementation-details) need to be specified. +Specifically, make sure to define and load the `PRI_MIXER_OUT_i` and the `PRI_MIXER_PWM_i` parameters, which define the output type and the default PWM rate, respectively, for each `i`th output. + +The `PRI_MIXER_OUT_i` values should be set to one of the following values: + +| `PRI_MIXER_OUT_i` value | How channel is interpreted by mixer | +| :--- | :--- | +| 0 | Auxiliary | +| 1 | Servo | +| 2 | Motor | +| 3 | GPIO | + +This designation is important since in ROSflight, motor PWM commands are one-sided (ranging from zero to 1) where servos are two-sided (ranging from -1 to 1). +The mixer uses the output channel type designation from the above table to know how to scale an output value to a standard PWM command (between 1000 and 2000). + +The auxiliary command types are [described below](#auxiliary-inputs). + +See the [Parameter Configuration Page](../rosflight-firmware/parameter-configuration.md) for more information on these parameters. + +!!! note + + The PWM rate is typically 490 or 50 Hz. + +!!! warning "Mixing Matrix PWM Header" + + PWM outputs are run off of hardware timers, which are often tied to particular clocks. + Since there are typically more PWM channels than clocks (and therefore hardware timers), the PWM rate cannot be set individually for each channel. + Instead, there are groups of PWM channels that must all be configured to the same rate. + + This is usually only an issue when dealing with multiple types of actuators (e.g. servos and brushless motors) on a given airframe where the actuators require different PWM rates. + In many cases, servos and motors can be configured to have the same 50Hz rate. + This is how the ROSflight fixedwing canned mixers do it. + + The number of timers varies based on hardware, so double check your board documentation when creating the custom mixer PWM header. + If you don't want to worry about it, just set all the `PRI_MIXER_PWM_i` to the same value, if possible. + +The recommended way to load a custom mixer is to first compute all the required parameters and save them to a file on the companion computer. +The parameters are named `PRI_MIXER_i_j` or `SEC_MIXER_i_j`, where `(i,j)` is the index of the parameter in the 6x10 mixing matrix. +See the [Parameter Configuration Page](../rosflight-firmware/parameter-configuration.md) for more information on these parameters. + +A convenience script is available in the `roscopter` ROS2 package that will compute the custom mixer and save the parameter values in a format ready to load. +The convenience script is found [here](https://github.com/rosflight/roscopter/blob/main/roscopter/scripts/compute_multirotor_mixing_matrix.py) with the configuration file found [here](https://github.com/rosflight/roscopter/blob/main/roscopter/config/multirotor_frame_config.yaml). + +Once the parameters are saved to a file, load them with the ROS2 service call (make sure `rosflight_io` is running): +```ros2 service call /param_load_from_file rosflight_msgs/srv/ParamFile "{file: absolute/or/relative/path/to/saved/param/file.yaml}"``` + +Also make sure to save those parameters to memory with the ROS2 service call: +```ros2 service call /param_write std_srvs/srv/Trigger``` + +## Auxiliary inputs + +ROSflight supports auxiliary inputs, which are defined as inputs that bypass the mixer. +Thus, any output channel in the mixer labeled as `AUX` will not use the mixer. +This can be useful for sending servo commands to landing gears, grasping mechanisms, or other more complicated scenarios. + +!!! tip + + To set a channel in a custom mixer as an `AUX` channel (bypassing the mixer), set the `PRI_MIXER_OUT_i` parameter to 0, where `i` is the number of the channel (zero indexed). + + These values are hard-coded for the canned mixers. diff --git a/docs/user-guide/concepts/parameter-configuration.md b/docs/user-guide/rosflight-firmware/parameter-configuration.md similarity index 97% rename from docs/user-guide/concepts/parameter-configuration.md rename to docs/user-guide/rosflight-firmware/parameter-configuration.md index fbde484b..8b0a9459 100644 --- a/docs/user-guide/concepts/parameter-configuration.md +++ b/docs/user-guide/rosflight-firmware/parameter-configuration.md @@ -8,7 +8,8 @@ The ROSflight firmware has several dozen parameters which it uses to customize p * IMU low-pass filter constant * RC receiver type (PPM or SBUS) -and so on. Access to all parameters is enabled via ROS2 services advertised by `rosflight_io` while the flight controller is connected. +and so on. +Access to all parameters is enabled via ROS2 services advertised by `rosflight_io` while the flight controller is connected (either in sim or in hardware). ## Parameter Interface @@ -45,7 +46,7 @@ Notice that the parameters have been set, but not saved. Parameter changes take #### Changing Parameters via `rosflight_io` ROS2 params -The `rosflight_io` node has some firmware parameters exposed via the ROS2 parameter interface, enabling quick configuration of *some* of the firmware's parameters. +The [`rosflight_io` node](../rosflight-io.md#convenience-parameters) has some firmware parameters exposed via the ROS2 parameter interface, enabling quick configuration of *some* of the firmware's parameters. This means that changing these `rosflight_io` parameters via the standard ROS2 parameter configuration will automatically change them in the firmware. Currently, only the controller gains have been exposed to `rosflight_io`'s parameters. @@ -102,11 +103,11 @@ Because ROSflight ships with default parameters for multirotors, you will probab | MOTOR_IDLE_THR | min throttle command sent to motors when armed (Set above 0.1 to spin when armed) | float | 0.1 | | ARM_CHANNEL | RC switch channel mapped to arming [0 indexed, -1 to disable] | int | 4 | | FIXED_WING | switches on passthrough commands for fixed-wing operation | int | true | -| MIXER | Which mixer to choose - See [Mixer documentation](hardware-setup.md#motor-layouts-and-mixer) | int | 10 | -| ELEVATOR_REV | reverses elevator servo output | int | 0/1 | -| AIL_REV | reverses aileron servo output | int | 0/1 | -| RUDDER_REV | reverses rudder servo output | int | 0/1 | -| CAL_GYRO_ARM | Calibrate gyros when arming - generally only for multirotors | int | false | 0 | 1 | +| PRIMARY_MIXER | Which primary mixer to choose - See [Mixer documentation](../rosflight-firmware/mixer.md) | int | 9 or 10 | +| ELEVATOR_REV | reverses elevator servo output | int | 0 or 1 | +| AIL_REV | reverses aileron servo output | int | 0 or 1 | +| RUDDER_REV | reverses rudder servo output | int | 0 or 1 | +| CAL_GYRO_ARM | Calibrate gyros when arming - generally only for multirotors | int | false | ## Description of all Parameters @@ -127,16 +128,16 @@ This is a list of all ROSflight parameters, including their types, default value | PROP_CQ | Torque coefficient of the propeller | float | 0.0045f | 0 | 100.0 | | VOLT_MAX | Maximum voltage of the battery (V) | float | 25.0f | 0 | 100.0 | | USE_MOTOR_PARAM | Flag to use motor parameters in the mixer | int | false | 0 | 1 | -| PRI_MIXER_OUT_0 | Output type of mixer output 0. | int | 0 | 0 | 1 | -| PRI_MIXER_OUT_1 | Output type of mixer output 1. | int | 0 | 0 | 1 | -| PRI_MIXER_OUT_2 | Output type of mixer output 2. | int | 0 | 0 | 1 | -| PRI_MIXER_OUT_3 | Output type of mixer output 3. | int | 0 | 0 | 1 | -| PRI_MIXER_OUT_4 | Output type of mixer output 4. | int | 0 | 0 | 1 | -| PRI_MIXER_OUT_5 | Output type of mixer output 5. | int | 0 | 0 | 1 | -| PRI_MIXER_OUT_6 | Output type of mixer output 6. | int | 0 | 0 | 1 | -| PRI_MIXER_OUT_7 | Output type of mixer output 7. | int | 0 | 0 | 1 | -| PRI_MIXER_OUT_8 | Output type of mixer output 8. | int | 0 | 0 | 1 | -| PRI_MIXER_OUT_9 | Output type of mixer output 9. | int | 0 | 0 | 1 | +| PRI_MIXER_OUT_0 | Output type of mixer output 0. | int | 0 | 0 | 3 | +| PRI_MIXER_OUT_1 | Output type of mixer output 1. | int | 0 | 0 | 3 | +| PRI_MIXER_OUT_2 | Output type of mixer output 2. | int | 0 | 0 | 3 | +| PRI_MIXER_OUT_3 | Output type of mixer output 3. | int | 0 | 0 | 3 | +| PRI_MIXER_OUT_4 | Output type of mixer output 4. | int | 0 | 0 | 3 | +| PRI_MIXER_OUT_5 | Output type of mixer output 5. | int | 0 | 0 | 3 | +| PRI_MIXER_OUT_6 | Output type of mixer output 6. | int | 0 | 0 | 3 | +| PRI_MIXER_OUT_7 | Output type of mixer output 7. | int | 0 | 0 | 3 | +| PRI_MIXER_OUT_8 | Output type of mixer output 8. | int | 0 | 0 | 3 | +| PRI_MIXER_OUT_9 | Output type of mixer output 9. | int | 0 | 0 | 3 | | PRI_MIXER_PWM_0 | PWM frequenct output for mixer output 0 | float | 0 | 0 | 490 | | PRI_MIXER_PWM_1 | PWM frequenct output for mixer output 1 | float | 0 | 0 | 490 | | PRI_MIXER_PWM_2 | PWM frequenct output for mixer output 2 | float | 0 | 0 | 490 | diff --git a/docs/user-guide/concepts/detailed-launching-guide.md b/docs/user-guide/rosflight-sim/detailed-launching-guide.md similarity index 97% rename from docs/user-guide/concepts/detailed-launching-guide.md rename to docs/user-guide/rosflight-sim/detailed-launching-guide.md index d2fd28a1..1c5e2c43 100644 --- a/docs/user-guide/concepts/detailed-launching-guide.md +++ b/docs/user-guide/rosflight-sim/detailed-launching-guide.md @@ -38,7 +38,7 @@ This following sections detail how to launch and debug these two simulators. !!! tip "New to ROSflight?" If you are new to ROSflight, we recommend that you first start by setting up the simulation environment and learning to use the ROSflight ecosystem. - Do this by following the [installation for sim](../installation/installation-sim.md) guides, and then the [ROSflight tutorials](../tutorials/tutorial-overview.md). + Do this by following the [installation for sim](../installation/installation-sim.md) guides, and then the [ROSflight tutorials](../tutorials/index.md). **This guide assumes you have already followed these tutorials.** @@ -173,7 +173,7 @@ These command line arguments should be passed using the `:=` sy ## Joysticks ROSflight supports several types of transmitters or controllers that you can use to fly around in the sim as the RC safety pilot. If one of the supported transmitters is connected via USB at launch time, then the sim will default to using that controller instead of the default, **which is no RC connection**. -See the [Hardware Setup](./hardware-setup.md#joystick) guide for more information on joysticks. +See the [Hardware Setup](../hardware-and-rosflight/hardware-setup.md#joystick) guide for more information on joysticks. !!! note It is much easier to fly with a real transmitter than with an Xbox-type controller. @@ -196,7 +196,7 @@ Remember that the SIL tries its best to replicate hardware. That means you have to calibrate and set parameters in the same way you do in hardware. If you need a reminder, please follow the [configuration and manual flight tutorial](../tutorials/manually-flying-rosflight-sim.md). -See the [Parameter Configuration](./parameter-configuration.md) pages in this documentation for instructions on how to perform all preflight configuration before the aircraft will arm. +See the [Parameter Configuration](../rosflight-firmware/parameter-configuration.md) pages in this documentation for instructions on how to perform all preflight configuration before the aircraft will arm. You can also run ```bash diff --git a/docs/user-guide/concepts/running-simulations-with-rosflight.md b/docs/user-guide/rosflight-sim/index.md similarity index 97% rename from docs/user-guide/concepts/running-simulations-with-rosflight.md rename to docs/user-guide/rosflight-sim/index.md index a99cbe07..8910b131 100644 --- a/docs/user-guide/concepts/running-simulations-with-rosflight.md +++ b/docs/user-guide/rosflight-sim/index.md @@ -21,7 +21,7 @@ The [detailed launching guide](./detailed-launching-guide.md) contains informati !!! tip "New to ROSflight?" If you are new to ROSflight, we recommend that you first start by setting up the simulation environment and learning to use the ROSflight ecosystem. - Do this by following the [installation for sim](../installation/installation-sim.md) guides, and then the [ROSflight tutorials](../tutorials/tutorial-overview.md). + Do this by following the [installation for sim](../installation/installation-sim.md) guides, and then the [ROSflight tutorials](../tutorials/index.md). After you do that, you should be ready to start using ROSflight in your own research! Visit the [developer guide pages](../../developer-guide/contribution-guidelines.md) for more specifics on how to use ROSflight for your research. diff --git a/docs/user-guide/concepts/simulator-architecture.md b/docs/user-guide/rosflight-sim/simulator-architecture.md similarity index 99% rename from docs/user-guide/concepts/simulator-architecture.md rename to docs/user-guide/rosflight-sim/simulator-architecture.md index 94e9a9c8..f1b68965 100644 --- a/docs/user-guide/concepts/simulator-architecture.md +++ b/docs/user-guide/rosflight-sim/simulator-architecture.md @@ -254,7 +254,7 @@ If you are adding a new sensor (e.g. camera), you could either change the `senso The `rc` module is responsible for publishing RC commands to the `sil_board`. It takes the place of the physical RC receiver in hardware that typically communicates with the flight controller over SBUS or PPM. -As described in the [ROSflight tutorials](../tutorials/manually-flying-rosflight-sim.md#rc-transmitter-control) and [hardware concept pages](./hardware-setup.md#joystick) pages, the `rc` node supports using a physical joystick or a simulated joystick like VimFly. +As described in the [ROSflight tutorials](../tutorials/manually-flying-rosflight-sim.md#rc-transmitter-control) and [hardware concept pages](../hardware-and-rosflight/hardware-setup.md#joystick) pages, the `rc` node supports using a physical joystick or a simulated joystick like VimFly. See the linked documents for more information. If VimFly is not specified and a physical transmitter is not connected when the simulation is launched, it will default to **no direct RC control**. diff --git a/docs/user-guide/concepts/rosplane-overview.md b/docs/user-guide/rosplane/index.md similarity index 84% rename from docs/user-guide/concepts/rosplane-overview.md rename to docs/user-guide/rosplane/index.md index 3d889cdb..65f5e073 100644 --- a/docs/user-guide/concepts/rosplane-overview.md +++ b/docs/user-guide/rosplane/index.md @@ -21,7 +21,15 @@ This can improve research productivity, decrease debugging time, and improve the ## 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. +These waypoints are defined by a 3-D location and (optionally) a desired heading at that location. + +See [the ROSplane autonomy stack documentation pages](../../developer-guide/rosplane/rosplane-dev-overview.md) for a detailed description of each module and its default functionality. + +## Using ROSplane as-is +The simplicity of the ROSplane framework allows users to add their own autonomy stacks or mission requirements on top of the ROSplane stack. + + +## Customizing ROSplane 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. diff --git a/docs/user-guide/concepts/rosplane-setup.md b/docs/user-guide/rosplane/rosplane-setup.md similarity index 99% rename from docs/user-guide/concepts/rosplane-setup.md rename to docs/user-guide/rosplane/rosplane-setup.md index 52f4849b..20d3f825 100644 --- a/docs/user-guide/concepts/rosplane-setup.md +++ b/docs/user-guide/rosplane/rosplane-setup.md @@ -6,7 +6,7 @@ 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. +See [ROSplane Overview](index.md) for more general information on ROSplane. ## Requirements diff --git a/docs/user-guide/tutorials/tutorial-overview.md b/docs/user-guide/tutorials/index.md similarity index 100% rename from docs/user-guide/tutorials/tutorial-overview.md rename to docs/user-guide/tutorials/index.md diff --git a/docs/user-guide/tutorials/manually-flying-rosflight-sim.md b/docs/user-guide/tutorials/manually-flying-rosflight-sim.md index 5b4a8579..2b8a39ef 100644 --- a/docs/user-guide/tutorials/manually-flying-rosflight-sim.md +++ b/docs/user-guide/tutorials/manually-flying-rosflight-sim.md @@ -32,7 +32,7 @@ ros2 node list and verifying that the `rosflight_io` and `sil_board` nodes are included in the list. ### Loading parameters manually -You can load parameters one-by-one or with a YAML file, as described in the [parameter configuration guide](../concepts/parameter-configuration.md). +You can load parameters one-by-one or with a YAML file, as described in the [parameter configuration guide](../rosflight-firmware/parameter-configuration.md). We will load parameters from a file. 1. Navigate to the params directory: @@ -53,7 +53,7 @@ Note that we first navigated to the directory so we could use the built-in `pwd` It just saves time instead of having to type the full path to the file. Here are some of the parameters you just loaded. -For a full list of the firmware's parameters, see [the parameter list](../concepts/parameter-configuration.md). +For a full list of the firmware's parameters, see [the parameter list](../rosflight-firmware/parameter-configuration.md). - **Aircraft configuration**: Sets `FIXED_WING: 0` for multirotor operation - **RC channels**: configures 8 RC channels with appropriate mappings @@ -231,7 +231,7 @@ ROSflight supports several types of transmitters or controllers that you can use - **RealFlight InterLink Controller** If one of the supported transmitters is connected via USB **at launch time**, then the sim will default to using that controller instead of the default, **which is no RC connection**. -See the [Hardware Setup](../concepts/hardware-setup.md#joystick) guide for more information on joysticks. +See the [Hardware Setup](../hardware-and-rosflight/hardware-setup.md#joystick) guide for more information on joysticks. !!! note "Have a joystick not on the list?" Joysticks not on the above list may have incorrect mappings. @@ -315,5 +315,5 @@ Once you have the simulator running, you can: ### Additional Resources -- [ROSflight Parameter Reference](../concepts/parameter-configuration.md): Detailed parameter descriptions -- [Hardware Setup Guide](../concepts/hardware-setup.md): Preparing real hardware for flight +- [ROSflight Parameter Reference](../rosflight-firmware/parameter-configuration.md): Detailed parameter descriptions +- [Hardware Setup Guide](../hardware-and-rosflight/hardware-setup.md): Preparing real hardware for flight diff --git a/docs/user-guide/tutorials/setting-up-roscopter-in-sim.md b/docs/user-guide/tutorials/setting-up-roscopter-in-sim.md index e2ddb3e4..8189572c 100644 --- a/docs/user-guide/tutorials/setting-up-roscopter-in-sim.md +++ b/docs/user-guide/tutorials/setting-up-roscopter-in-sim.md @@ -371,7 +371,6 @@ Once you have ROScopter running autonomously, you can: ### Additional Resources -- [ROSflight Parameter Reference](../concepts/parameter-configuration.md): Detailed firmware parameter descriptions -- [Hardware Setup Guide](../concepts/hardware-setup.md): Preparing real hardware for flight -- [ROScopter Architecture Documentation](../roscopter/roscopter-overview.md): In-depth system design and implementation details - +- [ROSflight Parameter Reference](../rosflight-firmware/parameter-configuration.md): Detailed firmware parameter descriptions +- [Hardware Setup Guide](../hardware-and-rosflight/hardware-setup.md): Preparing real hardware for flight +- [ROScopter Architecture Documentation](../roscopter/index.md): In-depth system design and implementation details diff --git a/docs/user-guide/tutorials/setting-up-rosflight-sim.md b/docs/user-guide/tutorials/setting-up-rosflight-sim.md index a8877f9d..67380f13 100644 --- a/docs/user-guide/tutorials/setting-up-rosflight-sim.md +++ b/docs/user-guide/tutorials/setting-up-rosflight-sim.md @@ -130,7 +130,7 @@ You should see the following output: Note that the `static_transform_publisher` nodes will have different hashes than what is shown above. Each of these nodes performs a different role in the sim. -Detailed information about these nodes and what they do can be found in the [simulation architecture description](../concepts/simulator-architecture.md). +Detailed information about these nodes and what they do can be found in the [simulation architecture description](../rosflight-sim/simulator-architecture.md). You can also see a representation of the data flow by running `rqt_graph` in a new terminal. If you don't see a similar view to what is below, click the refresh icon in the upper left. @@ -152,7 +152,7 @@ The `/dynamics` node handles gravity and other collision forces. This concludes a simulation "tick", and the simulation starts again with the `/sil_board`. -For more information, see the [detailed simulation architecture description](../concepts/simulator-architecture.md). +For more information, see the [detailed simulation architecture description](../rosflight-sim/simulator-architecture.md). ### Topics diff --git a/docs/user-guide/tutorials/setting-up-rosplane-in-sim.md b/docs/user-guide/tutorials/setting-up-rosplane-in-sim.md index eb77e07c..bfdd8537 100644 --- a/docs/user-guide/tutorials/setting-up-rosplane-in-sim.md +++ b/docs/user-guide/tutorials/setting-up-rosplane-in-sim.md @@ -324,7 +324,7 @@ Once you have ROSplane running autonomously, you can: ### Additional Resources -- [ROSflight Parameter Reference](../concepts/parameter-configuration.md): Detailed firmware parameter descriptions -- [Hardware Setup Guide](../concepts/hardware-setup.md): Preparing real hardware for flight +- [ROSflight Parameter Reference](../rosflight-firmware/parameter-configuration.md): Detailed firmware parameter descriptions +- [Hardware Setup Guide](../hardware-and-rosflight/hardware-setup.md): Preparing real hardware for flight - [ROSplane Architecture Documentation](../../developer-guide/rosplane/rosplane-dev-overview.md): In-depth system design and implementation details diff --git a/docs/user-guide/tutorials/tuning-performance-in-sim.md b/docs/user-guide/tutorials/tuning-performance-in-sim.md index 6273cdca..34e9b1cd 100644 --- a/docs/user-guide/tutorials/tuning-performance-in-sim.md +++ b/docs/user-guide/tutorials/tuning-performance-in-sim.md @@ -21,7 +21,7 @@ This tutorial will walk you through: - **Introduce the tools** that we use when flying with ROSflight, and - Help you get a feel for an **autonomy stack architecture** - See the [improving firmware performance](../concepts/improving-firmware-performance.md) guide for more information on tuning the firmware controller and firmware estimator. + See the [improving firmware performance](../hardware-and-rosflight/improving-firmware-performance.md) guide for more information on tuning the firmware controller and firmware estimator. ## Prerequisites @@ -196,7 +196,7 @@ To do this, You should see the gains show up on the right as shown below. These are the firmware gains that we have exposed to `rosflight_io`. -This means that when we change the `rosflight_io` ROS2 parameters (which have the same name as the firmware parameters), the `rosflight_io` node will essentially call the `param_set` service as described in the [parameter configuration guide](../concepts/parameter-configuration.md). +This means that when we change the `rosflight_io` ROS2 parameters (which have the same name as the firmware parameters), the `rosflight_io` node will essentially call the `param_set` service as described in the [parameter configuration guide](../rosflight-firmware/parameter-configuration.md). ![ROSflightIO gains on RQT](../images/rosflight_io_rqt.png) @@ -272,7 +272,7 @@ Here's an example of a somewhat-tuned response: Note that I also added the estimated state to the plot as well. The orange line is the firmware's estimated roll angle, and it tracks the command decently. However, it has a noticeable difference between truth. -This means we should either [tune the firmware response](../concepts/improving-firmware-performance.md), or publish ROScopter's estimated state to the `external_attitude` topic. +This means we should either [tune the firmware response](../hardware-and-rosflight/improving-firmware-performance.md), or publish ROScopter's estimated state to the `external_attitude` topic. !!! tip "External Attitude" @@ -409,5 +409,5 @@ You should now be able to: ### Additional Resources -- [Parameter Reference](../concepts/parameter-configuration.md): Complete parameter documentation -- [Hardware Tuning Guide](../concepts/improving-firmware-performance.md): Considerations for real hardware +- [Parameter Reference](../rosflight-firmware/parameter-configuration.md): Complete parameter documentation +- [Hardware Tuning Guide](../hardware-and-rosflight/improving-firmware-performance.md): Considerations for real hardware diff --git a/mkdocs.yml b/mkdocs.yml index f4b90f6e..c78f596f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,6 +13,7 @@ theme: features: - content.action.edit - navigation.tabs + - navigation.indexes palette: primary: blue grey accent: red @@ -26,7 +27,10 @@ extra: provider: mike extra_javascript: - - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML + - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML + +# extra_css: +# - stylesheets/extra.css markdown_extensions: - admonition @@ -41,7 +45,11 @@ markdown_extensions: - pymdownx.inlinehilite - pymdownx.smartsymbols - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true - pymdownx.tasklist + - md_in_html + - attr_list - toc: permalink: true @@ -58,8 +66,8 @@ nav: - Installation for Sim: user-guide/installation/installation-sim.md - Installation on Hardware: user-guide/installation/installation-hardware.md - Using Docker with ROSflight: user-guide/installation/using-docker-with-rosflight.md - - Tutorials: - - Tutorial overview: user-guide/tutorials/tutorial-overview.md + - Tutorials: + - user-guide/tutorials/index.md - Setting up ROSflight Sim: user-guide/tutorials/setting-up-rosflight-sim.md - Manually flying ROSflight Sim: user-guide/tutorials/manually-flying-rosflight-sim.md - Running ROScopter in Sim: user-guide/tutorials/setting-up-roscopter-in-sim.md @@ -72,36 +80,37 @@ nav: - ROSflight Integration: user-guide/tutorials/user-manual-ROSflight-integration.md - Appendix: user-guide/tutorials/user-manual-appendix.md - ROSflightIO: user-guide/rosflight-io.md - - ROSflight Sim: - - ROSflight Sim Overview: user-guide/concepts/running-simulations-with-rosflight.md - - Detailed Launching Guide: user-guide/concepts/detailed-launching-guide.md - - Simulator Architecture: user-guide/concepts/simulator-architecture.md + - ROSflight Firmware: + - Code Architecture: user-guide/rosflight-firmware/code-architecture.md + - Parameter Configuration: user-guide/rosflight-firmware/parameter-configuration.md + - Mixer: user-guide/rosflight-firmware/mixer.md + - Autonomous Flight: user-guide/rosflight-firmware/autonomous-flight.md - ROSplane: - - ROSplane Overview: user-guide/concepts/rosplane-overview.md - - ROSplane Setup: user-guide/concepts/rosplane-setup.md + - user-guide/rosplane/index.md + - ROSplane Setup: user-guide/rosplane/rosplane-setup.md - ROScopter: - - ROScopter Overview: user-guide/roscopter/roscopter-overview.md + - user-guide/roscopter/index.md - ROScopter Path Planner: user-guide/roscopter/roscopter-path-planner.md - ROScopter Path Manager: user-guide/roscopter/roscopter-path-manager.md - ROScopter Trajectory Follower: user-guide/roscopter/roscopter-trajectory-follower.md - ROScopter Controller: user-guide/roscopter/roscopter-controller.md - ROScopter Estimator: user-guide/roscopter/roscopter-estimator.md - - Hardware and ROSflight: - - Getting Started: user-guide/concepts/getting-started.md - - Hardware Setup: user-guide/concepts/hardware-setup.md - - Flight Controller Setup: user-guide/concepts/flight-controller-setup.md - - RC Configuration: user-guide/concepts/rc-configuration.md - - Parameter Configuration: user-guide/concepts/parameter-configuration.md - - Pre-Flight Checks: user-guide/concepts/preflight-checks.md - - Improving Firmware Performance: user-guide/concepts/improving-firmware-performance.md - - Autonomous Flight: user-guide/concepts/autonomous-flight.md + - ROSflight Sim: + - user-guide/rosflight-sim/index.md + - Detailed Launching Guide: user-guide/rosflight-sim/detailed-launching-guide.md + - Simulator Architecture: user-guide/rosflight-sim/simulator-architecture.md + - ROSflight in Hardware: + - Getting Started: user-guide/hardware-and-rosflight/getting-started.md + - Hardware Setup: user-guide/hardware-and-rosflight/hardware-setup.md + - Flight Controller Setup: user-guide/hardware-and-rosflight/flight-controller-setup.md + - RC Configuration: user-guide/hardware-and-rosflight/rc-configuration.md + - Pre-Flight Checks: user-guide/hardware-and-rosflight/preflight-checks.md + - Improving Firmware Performance: user-guide/hardware-and-rosflight/improving-firmware-performance.md - Customizing ROSflight: user-guide/customizing-rosflight.md - Developer Guide: - Contribution Guidelines: developer-guide/contribution-guidelines.md - Style Guide: developer-guide/style-guide.md - Firmware: - - Code Architecture: developer-guide/firmware/code-architecture.md - - Building and Flashing: developer-guide/firmware/building-and-flashing.md - Unit Tests: developer-guide/firmware/unit-tests.md - Debugging: developer-guide/firmware/debugging.md - ROSplane: @@ -123,11 +132,6 @@ nav: - Path Planner: developer-guide/rosplane/navigation/path-planner.md - Path Manager: developer-guide/rosplane/navigation/path-manager.md - Path Follower: developer-guide/rosplane/navigation/path-follower.md - - ROScopter: - - Developer Guide Overview: developer-guide/roscopter/roscopter-dev-overview.md - Publications: - ROSplane: publications/rosplane.md - ROSflight: publications/rosflight.md -# - ROS Packages: -# - ROSplane: -# - ROScopter: