Skip to content

Commit 25a3ab6

Browse files
JMoore5353JMoore5353
committed
feat: initial draft of first two tutorial pages. Used Claude, then edited
1 parent 1f81f2f commit 25a3ab6

6 files changed

Lines changed: 580 additions & 23 deletions

File tree

‎docs/user-guide/tutorials/manually-flying-rosflight-sim.md‎

Lines changed: 339 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,355 @@
22

33
The purpose of this tutorial is to enable users to **configure the ROSflight firmware** through the parameter interface and **fly in sim** using a keyboard or a supported transmitter.
44

5-
#### Prerequisite Tutorials and guides:
5+
## Prerequisites:
66
* [Setting up ROSflight sim](./setting-up-rosflight-sim.md)
77

88
## Overview
99

10+
This tutorial walks through the complete process of manually flying an aircraft in ROSflight simulation. You will learn to:
11+
12+
- Load firmware parameters appropriate for your aircraft
13+
- Calibrate the IMU
14+
- Saving parameters to memory
15+
- Fly using a supported RC transmitter or keyboard controls via VimFly
16+
- Troubleshoot common issues during manual flight
17+
18+
By the end of this tutorial, you will have a fully configured simulation environment ready for manual flight operations.
19+
1020
## Loading firmware parameters
1121

22+
After launching the simulator, you must load the firmware parameters.
23+
Parameters control the behavior of the firmware and how users will interact with the firmware.
24+
The ROSflight is highly configurable, but we have provided YAML files that contain a good default configuration for both multirotors and fixedwing vehicles.
25+
26+
Parameter configuration is handled by the `rosflight_io` node, which exposes some of the firmware's parameters to the ROS2 parameter system.
27+
In addition, `rosflight_io` has many services that allow users to configure the firmware.
28+
Ensure `rosflight_io` (and the rest of the simulation is running) using
29+
```bash
30+
ros2 node list
31+
```
32+
and verifying that the `rosflight_io`, `rosflight_sil_manager`, and `rosflight_sil` nodes are included in the list.
33+
34+
### Loading parameters manually
35+
You can load parameters one-by-one or with a YAML file, as described in the [parameter configuration guide](../concepts/parameter-configuration.md).
36+
We will load parameters from a file.
37+
38+
1. Navigate to the params directory:
39+
```bash
40+
cd /path/to/rosflight_ws/rosflight_ros_pkgs/rosflight_sim/params
41+
```
42+
43+
1. Load the multirotor or fixedwing parameter YAML files:
44+
```bash
45+
# For multirotor
46+
ros2 service call /param_load_from_file rosflight_msgs/srv/ParamFile "{filename: $(pwd)/multirotor_firmware.yaml"
47+
48+
# For fixedwing
49+
ros2 service call /param_load_from_file rosflight_msgs/srv/ParamFile "{filename: $(pwd)/fixedwing_firmware.yaml"
50+
```
51+
52+
Note that we first navigated to the directory so we could use the built-in `pwd` Linux command.
53+
It just saves time instead of having to type the full path to the file.
54+
55+
Here are some of the parameters you just loaded.
56+
For a full list of the firmware's parameters, see [the parameter list](../concepts/parameter-configuration.md).
57+
58+
- **Aircraft configuration**: Sets `FIXED_WING: 0` for multirotor operation
59+
- **RC channels**: configures 8 RC channels with appropriate mappings
60+
- **Mixer configuration**: Uses custom mixer (`PRIMARY_MIXER: 11`) with motor parameters
61+
- **Control gains**: Loads PID gains for roll, pitch, and yaw rate and angle controllers
62+
- **Safety settings**: Sets minimum throttle and failsafe configurations
63+
- **RC override**: Configures attitude and throttle override channels
64+
65+
See the `*.yaml` files in the `rosflight_ros_pkgs/rosflight_sim/params` directory for more information on exactly what parameters were loaded, and what the values were.
66+
1267
## Calibrating the IMU
1368

69+
The IMU (inertial measurement unit) calibration is essential for proper attitude estimation and flight control.
70+
The firmware will not arm until the IMU has been calibrated.
71+
72+
To manually calibrate the IMU, use the calibration service provided by `rosflight_io`:
73+
74+
```bash
75+
# Calibrate IMU
76+
ros2 service call /calibrate_imu std_srvs/srv/Trigger
77+
78+
# Optional: Calibrate barometer
79+
ros2 service call /calibrate_baro std_srvs/srv/Trigger
80+
```
81+
82+
These commands may take a few seconds to complete.
83+
Pay attention to the output.
84+
You should see something like:
85+
```bash
86+
[rosflight_io-9] [INFO] [1751393533.505232221] [rosflight_io]: Parameter ACC_X_BIAS has new value -0.0507161
87+
[rosflight_io-9] [WARN] [1751393533.505511027] [rosflight_io]: There are unsaved changes to onboard parameters
88+
[rosflight_io-9] [INFO] [1751393533.505577958] [rosflight_io]: Parameter ACC_Y_BIAS has new value 0.215514
89+
[rosflight_io-9] [INFO] [1751393533.505683879] [rosflight_io]: Parameter ACC_Z_BIAS has new value 0.0193333
90+
[rosflight_io-9] [INFO] [1751393533.505775730] [rosflight_io]: [Autopilot]: IMU offsets captured
91+
[rosflight_io-9] [INFO] [1751393533.505820657] [rosflight_io]: Autopilot RECOVERED ERROR: Uncalibrated IMU
92+
[rosflight_io-9] [INFO] [1751393533.506043698] [rosflight_io]: Parameter GYRO_X_BIAS has new value -0.18134
93+
[rosflight_io-9] [INFO] [1751393533.506251903] [rosflight_io]: Parameter GYRO_Y_BIAS has new value -0.142449
94+
[rosflight_io-9] [INFO] [1751393533.506363563] [rosflight_io]: Parameter GYRO_Z_BIAS has new value 0.218309
95+
```
96+
97+
!!! warning "Calibration when armed"
98+
Calibration will fail if the aircraft is armed.
99+
ROSflight will also not allow the aircraft to be armed if the calibration is not performed, so this is uncommon.
100+
101+
!!! note "Calibrating for each flight"
102+
In hardware, IMU calibration should be performed before each flight session.
103+
This ensures your IMU is well calibrated.
104+
In sim, if you don't save the parameters to a file (as described below), then you will need to recalibrate.
105+
106+
Additionally, the aircraft will not arm until firmware parameters are properly loaded.
107+
These steps are mandatory for every simulation session (if you don't write the params as described below).
108+
109+
## Saving parameters to memory
110+
The ROSflight sim tries to mimic hardware as much as possible.
111+
By default, parameters in the firmware are not saved to flash memory, so they do not persist across reboots of the sim.
112+
113+
To save firmware parameters (including calibration values) to memory, use the `rosflight_io` service call:
114+
```bash
115+
ros2 service call /param_write std_srvs/srv/Trigger
116+
```
117+
118+
In hardware, this service call will write all the firmware's parameters to the SD card, where they will load on boot.
119+
In sim, however, it will generate a directory called `rosflight_memory` in the directory where the command to launch the sim occurred.
120+
121+
To load those same parameters by default the next time that `rosflight_sim` is launched, just launch `rosflight_sim` from the directory that contains the `rosflight_memory` directory.
122+
123+
!!! example
124+
Suppose I am in a directory with the following file structure:
125+
```bash
126+
rosflight_ws
127+
├── build
128+
├── install
129+
├── log
130+
└── src
131+
```
132+
133+
And I launch the simulation from this directory using `ros2 launch rosflight_sim multirotor_standalone.launch.py`.
134+
I then write the params with `ros2 service call /param_write std_srvs/srv/Trigger`.
135+
136+
My new file structure will be:
137+
```bash
138+
rosflight_ws
139+
├── build
140+
├── install
141+
├── log
142+
├── rosflight_memory
143+
└── src
144+
```
145+
146+
To load those parameters by default when I launch `rosflight_sim` in the future, I just need to launch it from the directory that contains the `rosflight_sim` directory (in this case, `rosflight_ws`).
147+
148+
## Convenience script
149+
150+
We have provided a convenience script that does the above actions for you (loading parameters, calibrating the IMU, and writing params to memory).
151+
To use it, open a new terminal and run:
152+
153+
```bash
154+
# For multirotor
155+
ros2 launch rosflight_sim multirotor_init_firmware.launch.py
156+
157+
# For fixed-wing
158+
ros2 launch rosflight_sim fixedwing_init_firmware.launch.py
159+
```
160+
161+
This launch file performs three critical tasks:
162+
163+
1. **Loads parameters** that are aircraft-specific from YAML files
164+
2. Automatically **calibrates** the IMU
165+
3. **Saves** the loaded parameters to firmware memory
166+
167+
You can use this instead of doing the three actions manually.
168+
14169
## Flying
15170

171+
### Keyboard Control with VimFly
172+
173+
VimFly provides keyboard-based control for manual flight operations. Launch your simulation with VimFly enabled:
174+
175+
```bash
176+
# Launch with VimFly keyboard control
177+
ros2 launch rosflight_sim multirotor_standalone.launch.py use_vimfly:=true
178+
```
179+
180+
#### VimFly Control Mapping
181+
182+
| Key | Function | Description |
183+
|-----|----------|-------------|
184+
| `a` | Increase Thrust | Raises throttle in 10% increments |
185+
| `s` | Decrease Thrust | Lowers throttle in 10% increments |
186+
| `h` | Roll Left | Commands left roll input |
187+
| `l` | Roll Right | Commands right roll input |
188+
| `j` | Pitch Backward | Commands backward pitch input |
189+
| `k` | Pitch Forward | Commands forward pitch input |
190+
| `d` | Yaw Left (CCW) | Commands counter-clockwise yaw |
191+
| `f` | Yaw Right (CW) | Commands clockwise yaw |
192+
| `t` | Arm/Disarm Toggle | Arms or disarms the aircraft |
193+
| `r` | RC Override Toggle | Toggles RC override mode |
194+
195+
!!! tip "VimFly Window Focus"
196+
The VimFly window must be in focus to receive keyboard input. Click on the VimFly terminal window to ensure it's active before attempting to control the aircraft.
197+
198+
### RC Transmitter Control
199+
200+
ROSflight simulation supports various RC transmitters for more realistic flight control:
201+
202+
#### Supported Transmitters
203+
- **FrSky Taranis Q-X7** (USB connection)
204+
- **RadioMaster TX16S** (USB connection)
205+
- **RadioMaster Boxer** (USB connection)
206+
- **Xbox Controller**
207+
- **RealFlight InterLink Controller**
208+
209+
#### RC Channel Mapping
210+
211+
TODO: continue here. Verify that these RC inputs are correct, and then make sure you understand that the firmware interprets these values according to the parameters, separate from the RC node.
212+
213+
| Channel | Function | Typical Stick/Switch |
214+
|---------|----------|---------------------|
215+
| 0 (AIL) | Roll Control | Right stick horizontal |
216+
| 1 (ELV) | Pitch Control | Right stick vertical |
217+
| 2 (THR) | Throttle | Left stick vertical |
218+
| 3 (RUD) | Yaw Control | Left stick horizontal |
219+
| 4 | Arm Switch | Auxiliary switch |
220+
| 5 | RC Override | Auxiliary switch |
221+
| 6-7 | Additional Switches | User-configurable |
222+
223+
#### RC Setup Process
224+
225+
1. **Connect Transmitter**: Connect your RC transmitter via USB **before you launch the sim**
226+
2. **Verify Detection**: Check that the transmitter is detected by monitoring RC output:
227+
```bash
228+
ros2 topic echo /rc_raw
229+
```
230+
3. **Calibrate Transmitter**: Ensure center sticks output 1500μs and full deflection reaches 1000-2000μs
231+
4. **Test Controls**: Verify all channels respond correctly before flight
232+
233+
#### RC Safety Features
234+
235+
- **RC Override**: Safety pilot can take control using stick deviation or switches
236+
- **Failsafe Mode**: Aircraft enters level flight if RC connection is lost
237+
- **Arming Control**: Aircraft can only be armed via RC transmitter
238+
- **Independent Override**: Attitude and throttle can be overridden separately
239+
240+
### Flight Operations
241+
242+
#### Pre-flight Checklist
243+
1. ✅ Firmware parameters loaded
244+
2. ✅ IMU calibrated successfully
245+
3. ✅ Control input method selected (VimFly or RC)
246+
4. ✅ Aircraft armed and ready for flight
247+
248+
#### Basic Flight Sequence
249+
1. **Arm the Aircraft**: Use `t` key (VimFly) or arm switch (RC)
250+
2. **Apply Throttle**: Gradually increase throttle for takeoff
251+
3. **Control Attitude**: Use roll, pitch, and yaw inputs for maneuvering
252+
4. **Monitor Flight**: Observe aircraft behavior and sensor readings
253+
5. **Land Safely**: Reduce throttle and control descent
254+
6. **Disarm**: Disarm the aircraft after landing
255+
256+
!!! warning "Safety Considerations"
257+
- Always maintain visual contact with the simulated aircraft
258+
- Be prepared to use RC override if using autonomous modes
259+
- Monitor battery levels and flight time limits
260+
- Practice emergency procedures in simulation
261+
16262
## Troubleshooting
17263

264+
### Common Issues and Solutions
265+
266+
#### Aircraft Won't Arm
267+
268+
**Symptoms**: Aircraft refuses to arm despite proper setup
269+
270+
**Possible Causes and Solutions**:
271+
- **IMU not calibrated**: Run `ros2 service call /calibrate_imu std_srvs/srv/Trigger`
272+
- **Parameters not loaded**: Execute the appropriate firmware initialization launch file
273+
- **RC not connected**: Verify RC transmitter connection or use VimFly
274+
- **Safety checks failing**: Check for error messages in the rosflight_io node output
275+
276+
#### VimFly Not Responding
277+
278+
**Symptoms**: Keyboard inputs not controlling the aircraft
279+
280+
**Solutions**:
281+
- **Window focus**: Click on the VimFly terminal window to ensure it has focus
282+
- **Pygame dependency**: Verify pygame is installed: `pip install pygame`
283+
- **Launch parameter**: Ensure `use_vimfly:=true` is set in launch command
284+
- **RC override**: Check if RC override is enabled and disable if necessary
285+
286+
#### RC Transmitter Not Detected
287+
288+
**Symptoms**: No RC input detected in simulation
289+
290+
**Solutions**:
291+
- **USB connection**: Verify transmitter is connected via USB
292+
- **Device permissions**: Check USB device permissions and udev rules
293+
- **Joystick mode**: Ensure transmitter is in USB joystick mode
294+
- **Monitor output**: Use `ros2 topic echo /rc_raw` to verify RC signals
295+
296+
#### Poor Flight Performance
297+
298+
**Symptoms**: Aircraft is unstable or difficult to control
299+
300+
**Solutions**:
301+
- **Parameter verification**: Ensure correct firmware parameters are loaded
302+
- **IMU recalibration**: Recalibrate IMU if attitude estimation appears incorrect
303+
- **Control gains**: Check if PID gains are appropriate for aircraft type
304+
- **Simulation rate**: Verify simulation is running at proper real-time rate
305+
306+
#### Simulation Lag or Stuttering
307+
308+
**Symptoms**: Jerky or delayed response to control inputs
309+
310+
**Solutions**:
311+
- **System resources**: Close unnecessary applications to free CPU/memory
312+
- **Simulation complexity**: Reduce visual complexity in Gazebo simulation
313+
- **Network latency**: Check for network issues if using remote display
314+
- **Hardware acceleration**: Ensure graphics drivers are properly installed
315+
316+
### Getting Help
317+
318+
If issues persist after trying these solutions:
319+
320+
1. **Check Logs**: Review ROS2 node output for error messages
321+
2. **Community Support**: Post questions on ROSflight forums or GitHub issues
322+
3. **Documentation**: Refer to additional ROSflight documentation for detailed troubleshooting
323+
4. **Hardware Verification**: Test with different RC transmitters or input methods
324+
18325
## Review
326+
327+
You have successfully completed the manual flight tutorial for ROSflight simulation. You should now be able to:
328+
329+
✅ **Initialize Firmware**: Load appropriate parameters for multirotor or fixed-wing aircraft
330+
✅ **Calibrate Sensors**: Perform IMU calibration for proper attitude estimation
331+
✅ **Control Aircraft**: Fly using either VimFly keyboard controls or RC transmitter
332+
✅ **Troubleshoot Issues**: Diagnose and resolve common simulation problems
333+
334+
### Key Concepts Learned
335+
336+
- **Parameter Management**: Understanding how firmware parameters control aircraft behavior
337+
- **Sensor Calibration**: Importance of IMU calibration for flight stability
338+
- **Control Methods**: Differences between keyboard and RC transmitter control
339+
- **Safety Procedures**: RC override and failsafe mechanisms for safe operation
340+
341+
### Next Steps
342+
343+
Now that you can manually fly in simulation, consider exploring:
344+
345+
- **Autonomous Flight**: Learn to implement waypoint navigation and autonomous missions
346+
- **Custom Controllers**: Develop and test custom flight control algorithms
347+
- **Hardware Integration**: Transition from simulation to real hardware testing
348+
- **Advanced Scenarios**: Practice emergency procedures and complex flight maneuvers
349+
350+
### Additional Resources
351+
352+
- [ROSflight Parameter Reference](../concepts/parameter-configuration.md): Detailed parameter descriptions
353+
- [Hardware Setup Guide](../concepts/hardware-setup.md): Preparing real hardware for flight
354+
- [Safety Guidelines](../concepts/safety.md): Important safety considerations for real flight operations
355+
356+
Continue with the ROSflight documentation to expand your autopilot development skills and explore advanced features of the ROSflight ecosystem.

‎docs/user-guide/tutorials/setting-up-roscopter-in-sim.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,19 @@
11
# Setting up ROScopter in Sim
2+
3+
#### Prerequisite Tutorials and Guides:
4+
5+
6+
## ROScopter overview
7+
8+
## Launching `standalone_sim`
9+
10+
11+
## Launching ROScopter Autonomy Stack
12+
13+
14+
## Loading missions
15+
16+
17+
## Enabling Autonomous Flight
18+
19+

0 commit comments

Comments
 (0)