Skip to content

Commit 4816785

Browse files
JMoore5353JMoore5353
committed
feat: initial restructuring of the simulator documentation
1 parent 9545f07 commit 4816785

5 files changed

Lines changed: 163 additions & 16 deletions

File tree

‎docs/user-guide/hardware-setup.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@ You will need a laptop which can run ROS2 to communicate with the MAV over the g
8686

8787
### Joystick
8888

89-
A joystick is used for [software-in-the-loop (SIL) simulations](running-gazebo-simulation.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.
89+
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.
9090

9191
### Battery Monitor
9292

docs/user-guide/running-gazebo-simulation.md renamed to docs/user-guide/simulator/detailed-launching-guide.md

Lines changed: 26 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,35 @@
1-
# Running Simulations in Gazebo
1+
# Detailed Launching Guide
2+
Detailed launching instructions for the `rosflight_sim` module.
3+
For a quick copy-paste instructions, see the [quick start guide](running-simulations-with-rosflight.md#quick-start)
24

3-
ROSflight comes with a useful tool allowing it to perform software-in-the-loop (SIL) simulations of the ROSflight firmware in Gazebo.
5+
!!! note
6+
To simulate a fixed-wing mav, just change all instances of `multirotor` in the steps below to `fixedwing`.
47

5-
## Architecture of the SIL Simulation
8+
## A note on sims and viz
9+
A _simulator_ includes many different modules, such as dynamic propagation, sensor creation, forces and moments computation, etc.
10+
One of these modules is the _visualization_ module, that provides the graphical element to the simulator.
11+
Different visualizers provide different functionality and require different information.
12+
For example, [Gazebo Classic](https://classic.gazebosim.org/) handles the dynamic propagation (integration) for users, while a simple visualizer like RViz does not.
613

7-
To best mimic the hardware experience of ROSflight, the SIL plugin for Gazebo actually implements the firmware source code as a library. We just implemented a different "board layer" which uses gazebo instead of hardware calls for things like `imu_read()` and `pwm_write()`. Instead of a serial link over USB to the flight controller, we use a UDP connection bouncing off of localhost to communicate between `rosflight_io` and the firmware. This means the interface to the SIL plugin is identical to that of hardware. `rosflight_io` is the main gateway to the firmware in simulation, just as it is in hardware.
14+
Since each _visualizer_ in large part determines what other functionality the _simulator_ modules need to provide, they are tightly coupled.
15+
Thus, in this guide, we will refer interchangeably between _simulator_ and _visualizer_.
816

9-
The following table summarizes the correlation between connections in hardware and simulation:
17+
## Sims that ship with `rosflight_sim`
18+
The ROSflight simulation module was designed to be as modular as possible, in order to support different simulation and visualization needs.
19+
Currently, we support 2 visualizers out-of-the-box:
1020

11-
| Connection Type | Hardware | Simulation |
12-
|-----------------------------------------|--------------|------------------------------------------|
13-
| Serial communications to `rosflight_io` | USB / UART | UDP |
14-
| RC | PPM Receiver | ROS2 `RC` topic (`rosflight_msgs/RCRaw`) |
15-
| Motors | PWM | Gazebo Plugin |
16-
| Sensors | SPI/I2C | Gazebo Plugin |
21+
- [Gazebo Classic](https://classic.gazebosim.org/)
22+
- A "standalone" visualizer using [ROS2 RViz](https://docs.ros.org/en/humble/Tutorials/Intermediate/RViz/RViz-Main.html#rviz) tool
1723

18-
## Quick-Start Guide to SIL Simulation
24+
Adding your own visualizer is part of what `rosflight_sim` was designed for.
25+
See the [instructions on adding your own visualizer](simulator-architecture.md#adding-your-own-visualizer) page for more information on plugging in your simulator into `rosflight_sim`.
1926

20-
!!! note
21-
To simulate a fixed-wing mav, just change all instances of `multirotor` in the steps below to `fixedwing`.
27+
This following sections detail how to launch and debug these two simulators.
28+
29+
!!! TODO
30+
Continue here with the detailed launching guide. Add figures and the architecture image to show what nodes run with Gazebo
31+
32+
## Gazebo Classic
2233

2334
* Setup ROSflight with the [ROS2 Setup](ros2-setup.md) guide, making sure to install the `-desktop` package of ROS2, not the `-ros-base`.
2435

@@ -67,3 +78,4 @@ Remember, the SIL tries its best to replicate hardware. That means you have to c
6778
ros2 launch rosflight_sim multirotor_init_firmware.launch.py
6879
```
6980
to load all required parameters and perform initial calibrations for a quick simulation setup.
81+

‎docs/user-guide/simulator/running-simulations-with-rosflight.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Running Simulations with ROSflight
2+
3+
ROSflight a modular simulation package allowing it to perform software-in-the-loop (SIL) simulations of the ROSflight firmware.
4+
5+
!!! TODO
6+
add a good image of the sim here.
7+
8+
## Motivation
9+
The goals of the ROSflight simulation module (called `rosflight_sim`) are to
10+
11+
- Enable **easy and extensive SIL** testing of an aircraft,
12+
- Provide to the sim the **exact same software** that flies the physical aircraft,
13+
- Support a **variety of simulators** out of the box -- from photorealistic to bare-bones, and
14+
- Enable users to plug in their own simulators if needed.
15+
16+
See the [quick start](#quick-start) guide below or see the [detailed launching guide](detailed-launching-guide.md).
17+
18+
See the [simulator architecture](simulator-architecture.md) description page for more information on adding your own simulator to `rosflight_sim`.
19+
20+
## Quick-Start
21+
### Installation
22+
```bash
23+
// Clone from GitHub
24+
cd /path/to/rosflight_ws/src
25+
git clone --recursive https://github.com/rosflight/rosflight_ros_pkgs.git
26+
27+
// Install dependencies
28+
cd rosflight_ros_pkgs
29+
sudo rosdep init
30+
rosdep update
31+
rosdep install --from-path . -y --ignore-src
32+
33+
// Build the workspace
34+
cd /path/to/rosflight_ws
35+
colcon build
36+
37+
// Source the workspace
38+
source install/setup.bash
39+
40+
// Add the source to the .bashrc (optional)
41+
echo "source /path/to/rosflight_ws/install/setup.bash" >> ~/.bashrc
42+
```
43+
44+
### Launching
45+
```bash
46+
// Ensure the `rosflight_ws` workspace is sourced (see installation instructions above)
47+
48+
// Launch a fixedwing simulation with VimFly (or connected joystick -- see detailed instructions)
49+
ros2 launch rosflight_sim fixedwing_standalone.launch.py use_vimfly:=true
50+
51+
// Launch a multirotor simulation with VimFly (or connected joystick -- see detailed instructions)
52+
ros2 launch rosflight_sim multirotor_standalone.launch.py use_vimfly:=true
53+
```
54+
55+
This quick-start guide will launch the `standalone_sim` visualization engine (using RViz).
56+
For other out-of-the box supported visualizers, see the detailed launching instructions below.
57+
58+
If you run into errors or problems when launching, please see the detailed launching instructions.
59+
60+
!!! TODO
61+
Continue on the detailed launching guide. Certainly put the architecture on a separate page. There you can run through how everything is working.
62+
Add a page in the developer guide explaining how to add your own sim interfaces / dynamics / etc. to the sim.
63+
64+
65+
66+
67+
68+
69+
70+
71+
## Architecture of the SIL Simulation
72+
73+
!!! TODO
74+
Make a figure of the new architecture. Maybe make it be a GIF? We could replace the table below
75+
76+
To best mimic the hardware experience of ROSflight, the SIL plugin for Gazebo actually implements the firmware source code as a library.
77+
We just implemented a different "board layer" which uses gazebo instead of hardware calls for things like `imu_read()` and `pwm_write()`.
78+
Instead of a serial link over USB to the flight controller, we use a UDP connection bouncing off of localhost to communicate between `rosflight_io` and the firmware.
79+
This means the interface to the SIL plugin is identical to that of hardware.
80+
The `rosflight_io` node is the main gateway to the firmware in simulation, just as it is in hardware.
81+
82+
The following table summarizes the correlation between connections in hardware and simulation:
83+
84+
| Connection Type | Hardware | Simulation |
85+
|-----------------------------------------|--------------|------------------------------------------|
86+
| Serial communications to `rosflight_io` | USB / UART | UDP |
87+
| RC | PPM Receiver | ROS2 `RC` topic (`rosflight_msgs/RCRaw`) |
88+
| Motors | PWM | Gazebo Plugin |
89+
| Sensors | SPI/I2C | Gazebo Plugin |
90+
91+
## Troubleshooting
92+
### Installation and Building
93+
#### It doesn't build.
94+
- Ensure git submodules are checked out at:
95+
- rosflight_ros_pkgs/rosflight_firmware
96+
- rosflight_ros_pkgs/rosflight_firmware/lib/eigen
97+
98+
99+
100+
101+
102+
103+
104+
105+
106+
107+
108+
109+
110+
111+
112+
113+
114+
115+
116+
117+
118+
119+
120+
121+
122+
123+
124+
125+
126+
127+
128+
129+

‎docs/user-guide/simulator/simulator-architecture.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Simulator Architecture
2+
3+
## Adding your own simulator

‎mkdocs.yml‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,10 @@ nav:
5959
- Pre-Flight Checks: user-guide/preflight-checks.md
6060
- Improving Firmware Performance: user-guide/improving-firmware-performance.md
6161
- Autonomous Flight: user-guide/autonomous-flight.md
62-
- Running Gazebo Simulation: user-guide/running-gazebo-simulation.md
62+
- ROSflight Sim:
63+
- ROSflight Sim Overview: user-guide/simulator/running-simulations-with-rosflight.md
64+
- Detailed Launching Guide: user-guide/simulator/detailed-launching-guide.md
65+
- Simulator Architecture: user-guide/simulator/simulator-architecture.md
6366
- ROSplane:
6467
- ROSplane Overview: user-guide/rosplane-overview.md
6568
- ROSplane Setup: user-guide/rosplane-setup.md

0 commit comments

Comments
 (0)