admin/inav
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sync inav to Gitea
Make sure docs are updated / settings_md (push) Canceled after 0s
Details
Build firmware / test (push) Canceled after 0s
Details
Build firmware / build-SITL-Windows (push) Canceled after 0s
Details
Build firmware / build-SITL-Mac (push) Canceled after 0s
Details
Build firmware / build-SITL-Linux (push) Canceled after 0s
Details
Build firmware / build-SITL-Linux-arm64 (push) Canceled after 0s
Details
Build firmware / upload-artifacts (push) Canceled after 0s
Details
Build firmware / build-single-target (push) Canceled after 0s
Details
Build firmware / build (9) (push) Canceled after 0s
Details
Build firmware / build (8) (push) Canceled after 0s
Details
Build firmware / build (7) (push) Canceled after 0s
Details
Build firmware / build (6) (push) Canceled after 0s
Details
Build firmware / build (5) (push) Canceled after 0s
Details
Build firmware / build (4) (push) Canceled after 0s
Details
Build firmware / build (3) (push) Canceled after 0s
Details
Build firmware / build (2) (push) Canceled after 0s
Details
Build firmware / build (14) (push) Canceled after 0s
Details
Build firmware / build (13) (push) Canceled after 0s
Details
Build firmware / build (12) (push) Canceled after 0s
Details
Build firmware / build (11) (push) Canceled after 0s
Details
Build firmware / build (10) (push) Canceled after 0s
Details
Build firmware / build (1) (push) Canceled after 0s
Details
Build firmware / build (0) (push) Canceled after 0s
Details
Build firmware / detect (push) Canceled after 0s
Details
Build pre-release / build (push) Canceled after 0s
Details
Build pre-release / Release (push) Canceled after 0s
Details

Browse Source
This commit is contained in:
admin
2026-08-03 16:37:40 +08:00
commit dac37fd077
14095 changed files with 5603119 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/1wire.md
+74
View File
@@ -0,0 +1,74 @@
# 1-wire passthrough esc programming
### ESCs must have the BlHeli Bootloader.
If your ESCs didn't come with BlHeli Bootloader, you'll need to flash them with an ArduinoISP programmer first. [Here's a guide](http://bit.ly/blheli-f20).
This is the option you need to select for the bootloader:
![Flashing BlHeli Bootloader](assets/images/blheli-bootloader.png)
Currently supported on all boards with at least 128kB of flash memory (all F3, F4 and F7).
## Usage
- Plug in the USB cable and connect to your board with the INAV configurator.
- Open the BlHeli Suite.
- Ensure you have selected the correct Atmel or SILABS "Cleanflight" option under the "Select ATMEL / SILABS Interface" menu option.
- Ensure you have port for your external USB/UART adapter selected, if you're using one, otherwise pick the same COM port that you normally use for INAV.
- Click "Connect" and wait for the connection to complete. If you get a COM error, hit connect again. It will probably work.
- Use the boxes at the bottom to select the ESCs you have connected. Note that the boxes correspond directly to the ports on your flight controller. For example if you have motors on ports 1-4, pick boxes 1-4 or in the case of a tri-copter that uses motors on ports 3, 4 and 5, select those ports in BlHeli.
- Click "Read Setup"
- Use BlHeli suite as normal.
- When you're finished with one ESC, click "Disconnect"
## Implementing and Configuring targets
The following parameters can be used to enable and configure this in the related target.h file:
USE_SERIAL_1WIRE Enables the 1wire code, defined in target.h
- For new targets
- in `target.h`
```
// Turn on serial 1wire passthrough
#define USE_SERIAL_1WIRE
// How many escs does this board support?
#define ESC_COUNT 6
// STM32F3DISCOVERY TX - PC3 connects to UART RX
#define S1W_TX_GPIO GPIOC
#define S1W_TX_PIN GPIO_Pin_3
// STM32F3DISCOVERY RX - PC1 connects to UART TX
#define S1W_RX_GPIO GPIOC
#define S1W_RX_PIN GPIO_Pin_1
```
- in `serial_1wire.c`
```
// Define your esc hardware
#if defined(STM32F3DISCOVERY)
const escHardware_t escHardware[ESC_COUNT] = {
{ GPIOD, 12 },
{ GPIOD, 13 },
{ GPIOD, 14 },
{ GPIOD, 15 },
{ GPIOA, 1 },
{ GPIOA, 2 }
};
```
## Development Notes
On the STM32F3DISCOVERY, an external pullup on the ESC line may be necessary. I needed a 3v, 4.7k pullup.
docs/ADSB.md
+111
View File
@@ -0,0 +1,111 @@
# ADS-B
[Automatic Dependent Surveillance Broadcast](https://en.wikipedia.org/wiki/Automatic_Dependent_Surveillance%E2%80%93Broadcast)
is an air traffic surveillance technology that enables aircraft to be accurately tracked by air traffic controllers and other pilots without the need for conventional radar.
## Current state
OSD can be configured to shows the closest aircraft.
## OSD ADSB Info element
* "-" no ADSB device detected
* "H" IMU heading is not valid
* "G" no GPS fix or less than 4 stats
* "[Number]" count of ADSB aircrafts
## OSD ADSB Warning element
OSD can be configured to simple view (one line) or to extended view (two lines) by \
`set osd_adsb_warning_style=EXTENDED`
### Simple view
`{distance to vehicle} {direction to vehicle} {altitude diff}`
### Extended view
`{distance to vehicle} {direction to vehicle} {altitude diff}` \
`{Emiter Type} {Vehicle direction} {Vehicle Speed}`
![ADSB OSD](assets/images/adsb-info.png)
## Hardware
All ADSB receivers which can send Mavlink [ADSB_VEHICLE](https://mavlink.io/en/messages/common.html#ADSB_VEHICLE) message are supported
* [PINGRX](https://uavionix.com/product/pingrx-pro/) (not tested)
* [TT-SC1](https://www.aerobits.pl/product/aero/) (tested)
* [ADSBee1090](https://pantsforbirds.com/adsbee-1090/) (tested)
* [SoftRF](https://github.com/lyusupov/SoftRF/wiki/Nano-Edition) (tested)
## TT-SC1 settings
* download software for ADSB TT-SC1 from https://www.aerobits.pl/product/aero/ , file Micro_ADSB_App-vX.XX.X_win_setup.zip and install it
* connect your ADSB to FC, connect both RX and TX pins
* in INAV configurator ports TAB set telemetry MAVLINK, and baudrate 115200
* go to CLI in inav configurator and set serialpassthrough for port you connected ADSB ```serialpassthrough [PORT_YOU_SELECTED - 1] 115200 rxtx``` and close configurator
* open ADSB program you installed, got to settings and set "telemetry" = MAVLINK,
PCB board for TT-SC1-B module https://oshwlab.com/error414/adsb-power-board
![TT-SC1 settings](Screenshots/ADSB_TTSC01_settings.png)
## ADSBee 1090 settings
* connect to ADSBee1090 via USB and set COMMS_UART to mavlink2 \
``
AT+PROTOCOL=COMMS_UART,MAVLINK2
``\
``
AT+BAUDRATE=COMMS_UART,115200
``\
It's recommended to turn of wifi \
``
AT+ESP32_ENABLE=0
``\
``
AT+SETTINGS=SAVE
``
* in INAV configurator ports TAB set telemetry MAVLINK, and baudrate 115200
* https://pantsforbirds.com/adsbee-1090/quick-start/
## SoftRF settings
SoftRF supports only MAVLink version 1.
```
set mavlink_version = 1
save
```
The baud rate for SoftRF is 57600. INAV provides minimal support for SoftRF and supports only
the mandatory MAVLink messages: `MAVLINK_MSG_ID_HEARTBEAT`, `MAVLINK_MSG_ID_SYSTEM_TIME`, and `MAVLINK_MSG_ID_GPS_RAW_INT`.
The following messages are not supported: `MAVLINK_MSG_ID_SYS_STATUS`, `MAVLINK_MSG_ID_VFR_HUD`, and `MAVLINK_MSG_ID_ATTITUDE`.
## Alert and Warning
The ADS-B warning/alert system supports two operating modes, controlled by the parameter osd_adsb_calculation_use_cpa (ON or OFF).
---
### ADS-B Warning and Alert Messages (CPA Mode OFF)
The ADS-B warning/alert system supports two operating modes, controlled by the parameter **osd_adsb_calculation_use_cpa** (ON or OFF).
When **osd_adsb_calculation_use_cpa = OFF**, the system evaluates only the **current distance between the aircraft and the UAV**. The aircraft with the **shortest distance** is always selected for monitoring.
- If the aircraft enters the **warning zone** (`adsb_distance_warning`), the corresponding **OSD element is displayed**.
- If the aircraft enters the **alert zone** (`adsb_distance_alert`), the **OSD element starts blinking**, indicating a higher-priority alert.
This mode therefore provides a simple proximity-based warning determined purely by real-time distance.
---
### ADS-B Warning and Alert Messages (CPA Mode ON)
When **osd_adsb_calculation_use_cpa = ON**, the system evaluates aircraft using the **Closest Point of Approach (CPA)** and predicted trajectories, not only the current distance.
1. **Aircraft already inside the alert zone**
If one or more aircraft are currently inside the **alert zone** (`adsb_distance_alert`), the **closest aircraft** to the UAV is selected and the **OSD element blinks**.
2. **Aircraft in the warning zone, none predicted to enter the alert zone**
If aircraft are present in the **warning zone** (`adsb_distance_warning`), but none of them are predicted to enter the **alert zone** (their CPA distance is greater than `adsb_distance_alert`), the **closest aircraft to the UAV** is selected and the **OSD element remains steady** (no blinking).
3. **Aircraft in the warning zone, one predicted to enter the alert zone**
If at least one aircraft in the **warning zone** is predicted to enter the **alert zone**, that aircraft is selected and the **OSD element blinks**.
4. **Aircraft in the warning zone, multiple predicted to enter the alert zone**
If multiple aircraft are predicted to enter the **alert zone**, the system selects the aircraft that will **reach the alert zone first**, and the **OSD element blinks**.
![ADSB CPA_ON](assets/images/adsb-CPA-on.png)
docs/API/MSP_extensions.md
+161
View File
@@ -0,0 +1,161 @@
# MSP Extensions
INAV includes a number of extensions to the MultiWii Serial Protocol (MSP). This document describes
those extensions in order that 3rd party tools may identify INAV firmware and react appropriately.
Issue the MSP_API_VERSION command to find out if the firmware supports them.
## Mode Ranges
### MSP\_MODE\_RANGES
The MSP\_MODE\_RANGES returns the current auxiliary mode settings from the flight controller. It should be invoked
before any modification is made to the configuration.
The message returns a group of 4 unsigned bytes for each 'slot' available in the flight controller. The number of
slots should be calculated from the size of the returned message.
| Command | Msg Id | Direction | Notes |
|---------|--------|-----------|-------|
| MSP\_MODE\_RANGES | 34 | to FC | Following this command, the FC returns a block of 4 bytes for each auxiliary mode 'slot'|
Unassigned slots have rangeStartStep == rangeEndStep. Each element contains the following fields.
| Data | Type | Notes |
|------|------|-------|
| permanentId | uint8 | See [Modes in the wiki](https://github.com/iNavFlight/inav/wiki/Modes) for a definition of the permanent ids |
| auxChannelIndex | uint8 | The Aux switch number (indexed from 0) |
| rangeStartStep | uint8 | The start value for this element in 'blocks' of 25 where 0 == 900 and 48 == 2100 |
| rangeEndStep | uint8 | The end value for this element in 'blocks' of 25 where 0 == 900 and 48 == 2100 |
Thus, for a INAV firmware with 40 slots 160 bytes would be returned in response to MSP\_MODE\_RANGES,
### MSP\_SET\_MODE\_RANGE
The MSP\_SET\_MODE\_RANGE is used to inform the flight controller of
auxiliary mode settings. The client *must* return all auxiliary
elements, including those that have been disabled or are undefined, by
sending this message for all auxiliary slots.
| Command | Msg Id | Direction |
|---------|--------|-----------|
| MSP\_SET\_MODE\_RANGE | 35 | to FC |
| Data | Type | Notes |
|------|------|-------|
| sequence id | uint8 | A monotonically increasing ID, from 0 to the number of slots -1 |
| permanentId | uint8 | See [Modes in the wiki](https://github.com/iNavFlight/inav/wiki/Modes) for a definition of the permanent ids |
| auxChannelIndex | uint8 | The Aux channel number (indexed from 0) |
| rangeStartStep | uint8 | The start value for this element in 'blocks' of 25 where 0 == 900 and 48 == 2100 |
| rangeEndStep | uint8 | The end value for this element in 'blocks' of 25 where 0 == 900 and 48 == 2100 |
### Implementation Notes
* The client should make no assumptions about the number of slots available. Rather, the number should be computed
from the size of the MSP\_MODE\_RANGES message divided by the size of the returned data element (4 bytes);
* The client should ensure that all changed items are returned to the flight controller, including those where a
switch or range has been disabled;
* A 'null' return, with all values other than the sequence id set to 0, must be made for all unused slots, up to
the maximum number of slots calculated from the initial message.
## Adjustment Ranges
### MSP\_ADJUSTMENT\_RANGES
The MSP\_ADJUSTMENT\_RANGES returns the current adjustment range settings from
the flight controller. It should be invoked before any modification is
made to the configuration.
The message returns a group of 6 unsigned bytes for each 'slot'
available in the flight controller. The number of slots should be
calculated from the size of the returned message.
| Command | Msg Id | Direction | Notes |
|---------|--------|-----------|-------|
| MSP\_ADJUSTMENT\_RANGES | 52 | to FC | Following this command, the FC returns a block of 6 bytes for each adjustment range 'slot'|
Unassigned slots have rangeStartStep == rangeEndStep. Each element contains the following fields.
| Data | Type | Notes |
|------|------|-------|
| adjustmentStateIndex | uint8 | See below |
| auxChannelIndex | uint8 | The Aux channel number (indexed from 0) used to activate the adjustment |
| rangeStartStep | uint8 | The start value for this element in 'blocks' of 25 where 0 == 900 and 48 == 2100 |
| rangeEndStep | uint8 | The end value for this element in 'blocks' of 25 where 0 == 900 and 48 == 2100 |
| adjustmentFunction | uint8 | See below |
| auxSwitchChannelIndex | uint8 | The Aux channel number used to perform the function (indexed from 0) |
Thus, for a INAV firmware with 12 slots 72 bytes would be returned in response to MSP\_ADJUSTMENT\_RANGES,
### MSP\_SET\_ADJUSTMENT\_RANGE
The MSP\_SET\_ADJUSTMENT\_RANGE is used to inform the flight controller of
adjustment range settings. The client *must* return all adjustment range
elements, including those that have been disabled or are undefined, by
sending this message for all adjustment range slots.
| Command | Msg Id | Direction |
|---------|--------|-----------|
| MSP\_SET\_ADJUSTMENT\_RANGE | 53 | to FC |
| Data | Type | Notes |
|------|------|-------|
| sequence id | uint8 | A monotonically increasing ID, from 0 to the number of slots -1 |
| adjustmentStateIndex | uint8 | See below |
| auxChannelIndex | uint8 | The Aux channel number (indexed from 0) |
| rangeStartStep | uint8 | The start value for this element in 'blocks' of 25 where 0 == 900 and 48 == 2100 |
| rangeEndStep | uint8 | The end value for this element in 'blocks' of 25 where 0 == 900 and 48 == 2100 |
| adjustmentFunction | uint8 | See below |
| auxSwitchChannelIndex | uint8 | The Aux channel number used to perform the function (indexed from 0) |
### MSP\_SET\_1WIRE
The MSP\_SET\_1WIRE is used to enable serial1wire passthrough
note: it would be ideal to disable this when armed
| Command | Msg Id | Direction |
|---------|--------|-----------|
| MSP\_SET\_1WIRE | 243 | to FC |
| Data | Type | Notes |
|------|------|-------|
| esc id | uint8 | A monotonically increasing ID, from 0 to the number of escs -1 |
#### AdjustmentIndex
The FC maintains internal state for each adjustmentStateIndex, currently 4 simultaneous adjustment states are maintained. Multiple adjustment ranges
can be configured to use the same state but care should be taken not to send multiple adjustment ranges that when active would confict.
e.g. Configuring two identical adjustment ranges using the same slot would conflict, but configuring two adjustment ranges that used
only one half of the possible channel range each but used the same adjustmentStateIndex would not conflict.
The FC does NOT check for conflicts.
#### AdjustmentFunction
There are many adjustments that can be made, the numbers of them and their use is found in the documentation of the cli `adjrange` command in the 'Inflight Adjustents' section.
### Implementation Notes
* The client should make no assumptions about the number of slots available. Rather, the number should be computed
from the size of the MSP\_ADJUSTMENT\_RANGES message divided by the size of the returned data element (6 bytes);
* The client should ensure that all changed items are returned to the flight controller, including those where a
switch or range has been disabled;
* A 'null' return, with all values except for the sequence id set to 0, must be made for all unused slots,
up to the maximum number of slots calculated from the initial message.
## Deprecated MSP
The following MSP commands are replaced by the MSP\_MODE\_RANGES and
MSP\_SET\_MODE\_RANGE extensions, and are not recognised by
INAV.
* MSP\_BOX
* MSP\_SET\_BOX
See also
--------
[The wiki](https://github.com/iNavFlight/inav/wiki/Modes) describes the user visible implementation for the INAV
modes extension.
docs/Autotune - fixedwing.md
Executable
+59
View File
@@ -0,0 +1,59 @@
# Airplane Autotune instructions
Airplane PIFF autotune is inspired by ArduPilot Plane firmware.
Getting a good set of roll/pitch/yaw PIFF parameters for your aircraft is essential for stable flight. To help with this it is highly recommended that you use the AUTOTUNE system described below.
## What AUTOTUNE does
The AUTOTUNE mode is a flight mode that acts on top of normal ANGLE/HORIZON/ACRO mode and uses changes in flight attitude input by the pilot to learn the tuning values for roll, pitch and yaw tuning.
In general pilot needs to activate AUTOTUNE mode while in the air and then fly the plane for a few minutes. While flying the pilot needs to input as many sharp attitude changes as possible so that the autotune code can learn how the aircraft responds and figure out PIFF gains.
## Before flying with AUTOTUNE
Before taking off you need to set up a few parameters for your airplane:
parameter | explanation
--------- | -----------
roll_rate | Maximum roll rate limit for your ariplane. Must not exceed physical limit of your plane
pitch_rate | Maximum pitch rate limit for your ariplane. Must not exceed physical limit of your plane
yaw_rate | Maximum yaw rate limit for your ariplane. Must not exceed physical limit of your plane
fw_p_level | Self-leveling strength. Bigger value means sharper response
fw_i_level | Self-leveling filtering. Usual value for airplanes is 1-5 Hz
max_angle_inclination_rll | Maximum roll angle in [0.1 deg] units
max_angle_inclination_pit | Maximum pitch angle in [0.1 deg] units
tpa_breakpoint | Cruise throttle (expected throttle that you would be flying most of the time)
tpa_rate | Amount of TPS curve to apply (usually should be in range 50-80 for most airplanes)
For most hobby-sized airplanes roll/pitch rate limits should be in range 70-120 deg/s (7-12 for `roll_rate` and `pitch_rate` values). Small and agile flying wings can reach 180-200 deg/s.
Other things to check:
* It's highly recommended that you fly in MANUAL and trim your servo midpoints for stable flight
* Make sure you have center of gravity according to manual to your aircraft
* Check that your failsafe activates correctly (test on the ground with propeller off for safety)
## Flying in AUTOTUNE
Once you are all setup you can take off normally and switch to AUTOTUNE mode once you have gained altitude.
When you engage AUTOTUNE mode a few things will happen:
* The autotune system will immediately setup some default values for your roll, pitch and yaw P and I gains
* The autotune system will monitor requested roll and pitch rates (as determined by your transmitter stick movements). When the demanded roll or pitch rate exceeds certain threshold the autotune system will use the response of the aircraft to learn roll or pitch tuning values
* Every 5 seconds the autotune system will store the snapshot of parameters you have. When you switch out of AUTOTUNE mode the last remembered parameters are restored
* You may find the plane is quite sluggish when you first enter AUTOTUNE. You will find that as the tune progresses this will get better. Make sure your flight area has plenty of room for slow large-radius turns.
* Don't land in AUTOTUNE mode - during landing airplane doesn't reach it full performance which may be read by autotune system as insufficient gains.
The key to a successful autotune is to input rapid movements with the transmitter sticks. You should only do one of either roll or pitch at a time, and you should move the stick rapidly to the maximum deflection.
## Don't stop too early
The more you fly the better it will get. Let autotune analyze how your airplane behaves and figure decent tune for you. Once you feel that airplane is flying good in AUTOTUNE - keep flying well past that point to finalize the tune.
## Completing the tune
Once you have tuned reasonable PIFF parameters with AUTOTUNE you should complete the tune by switching out of AUTOTUNE to ANGLE or MANUAL and landing the airplane.
Note that AUTOTUNE mode doesn't automatically save parameters to EEPROM. You need to disarm and issue a [stick command](Controls.md) to save configuration parameters.
docs/Backup and Restore.md
+107
View File
@@ -0,0 +1,107 @@
# Backup and Restore
INAV Configurator can automatically back up your configuration before flashing firmware and offer to restore it afterwards. When upgrading across major versions (e.g. 7.x → 8.x → 9.x), settings are automatically migrated to the new firmware format.
For manual CLI-based backup and restore, see the [CLI documentation](Cli.md#backup-via-cli).
## Automatic Backup & Restore During Firmware Flash
### What happens automatically
1. **Before flashing** (with or without Full Chip Erase enabled): Your current CLI configuration (`diff all`) is automatically captured and saved to the backup directory.
2. **After flashing**: Depending on the situation, the Configurator offers to restore your settings if Full Chip Erase was enabled:
| Scenario | Behavior |
|----------|----------|
| **Patch update** (e.g. 8.0.0 → 8.0.1) | Auto-restore offered immediately |
| **Minor update** (e.g. 8.0.0 → 8.1.0) | Auto-restore offered immediately |
| **Major upgrade** (e.g. 7.x → 8.x) with migration profile available | Migration preview shown — confirm to restore with converted settings |
| **Major upgrade** without migration profile | Warning shown — restore still possible but some settings may fail |
| **Major downgrade** (e.g. 9.x → 7.x) | Auto-restore blocked — manual restore only (settings may be incompatible) |
| **Local firmware file** (loaded from disk) | No auto-restore offered — backup is still saved |
| **Flash without Full Chip Erase** | Backup taken, no restore offered |
### Migration Preview
When updating across major versions (e.g. 7.x → 9.x), the Configurator shows a **migration preview overlay** before restoring. This lists:
- **Removed settings** — settings that no longer exist in the new firmware (will be skipped)
- **Renamed settings** — settings whose name changed (automatically converted)
- **Renamed commands** — CLI commands that were renamed (automatically converted)
- **Value replacements** — setting values that changed meaning (automatically converted)
- **Setting remappings** — numeric IDs that were renumbered (automatically converted)
- **Warnings** — settings whose semantics changed and require manual review
You can review all changes before confirming or cancelling the restore.
Multi-step migrations are handled automatically. For example, a 7.x → 9.x upgrade applies migration profiles in sequence (7→8, then 8→9).
## Manual Backup & Restore
The Firmware Flasher tab provides three buttons:
- **Backup Config** — saves your current CLI configuration to a file (opens save dialog)
- **Restore Config** — loads a backup file and restores it to your flight controller
- If the backup is from a different major version, the migration preview is shown first
- If no migration profile exists for the version gap, a warning is shown but you can still proceed
- **Open Backups Folder** — opens the backup directory in your file manager
For CLI-based backup and restore procedures, see [Backup via CLI](Cli.md#backup-via-cli) and [Restore via CLI](Cli.md#restore-via-cli).
## Backup File Location
Backups are stored in your OS-specific application data directory:
| OS | Path |
|----|------|
| **Windows** | `%APPDATA%/inav-configurator/backups/` |
| **macOS** | `~/Library/Application Support/inav-configurator/backups/` |
| **Linux** | `~/.config/inav-configurator/backups/` |
Use the **Open Backups Folder** button in the Firmware Flasher tab to open this directory.
## Backup File Naming
| Type | Format |
|------|--------|
| Auto-backups | `UPDATE_inav_backup_{version}_{board}_{YYYY-MM-DD_HHMMSS}.txt` |
| Manual backups | `inav_backup_{version}_{board}_{YYYY-MM-DD_HHMMSS}.txt` |
Auto-backups are pruned automatically — only the 10 most recent are kept. Files you rename are never pruned.
## Backup File Format
Backup files are plain-text CLI dumps with a metadata header:
```
# INAV Backup
# Version: 8.0.0
# Board: SPEEDYBEEF405V4
# Date: 2026-04-11T10:30:00.000Z
# Craft: MyQuad
#
# INAV/SPEEDYBEEF405V4 8.0.0 Apr 1 2026 / 12:00:00 (abc1234)
# GCC-13.2.1
# ...
set gyro_main_lpf_hz = 110
set acc_hardware = AUTO
...
```
You can open and edit these files with any text editor.
## Restore Error Handling
If errors occur during restore (e.g. unknown settings, invalid values):
- An error dialog shows the affected lines
- You can choose:
- **Save anyway** — saves the successfully applied settings and reboots
- **Abort** — discards all changes and exits CLI mode
## Tips
- **Always flash with Full Chip Erase** when upgrading to a new version. This ensures clean defaults and triggers automatic backup and restore.
- **Review migration previews carefully** — especially the warnings section, which highlights settings whose meaning may have changed.
- **Keep manual backups** before major upgrades. While auto-backup handles this, having an extra copy in a known location gives peace of mind.
- **Use `diff` over `dump`** for backups. The `diff` format only stores settings that differ from defaults, which makes restoring safer across versions. The auto-backup feature already uses `diff all`.
docs/Battery.md
+509
View File
@@ -0,0 +1,509 @@
# Battery Monitoring
INAV has a battery monitoring feature. The voltage of the main battery can be measured by the system and used to trigger a low-battery warning [buzzer](Buzzer.md), on-board status LED flashing and LED strip patterns.
Low battery warnings can:
* Help ensure you have time to safely land the aircraft
* Help maintain the life and safety of your LiPo/LiFe batteries, which should not be discharged below manufacturer recommendations
Minimum and maximum cell voltages can be set, and these voltages are used to auto-detect the number of cells in the battery when it is first connected.
Per-cell monitoring is not supported, as we only use one ADC to read the battery voltage.
## Supported targets
All targets support battery voltage monitoring unless stated.
## Connections
When dealing with batteries **ALWAYS CHECK POLARITY!**
Measure expected voltages **first** and then connect to the flight controller. Powering the flight controller with
incorrect voltage or reversed polarity will likely fry your flight controller. Ensure your flight controller
has a voltage divider capable of measuring your particular battery voltage.
On the first battery connection is always advisable to use a current limiter device to limit damages if something is wrong in the setup.
### Sparky
See the [Sparky board chapter](Board%20-%20Sparky.md).
## Voltage measurement
Enable the `VBAT` feature to enable the measurement of the battery voltage and the use of the voltage based OSD battery gauge, voltage based and energy based battery alarms.
### Calibration
`vbat_scale` - Adjust this setting to match actual measured battery voltage to reported value. Increasing this value increases the measured voltage.
### Voltage measurement source
Two voltage sources are available: raw voltage and sag compensated voltage. The raw voltage is the voltage directly measured at the battery while the sag compensated voltage is calculated by an algorithm aiming to provide a stable voltage source for gauges, telemetry and alarms. When the current drawn from a battery varies the provided voltage also varies due to the internal resistance of the battery, it is called sag. The sag can often trigger the battery alarms before the battery is empty and if you are relying on the battery voltage to know the charge state of your battery you have to land or cut the throttle to know the real, without load, battery voltage. The sag compensation algorithm simulates a battery with zero internal resistance and provides a stable reading independent from the drawn current.
You can select the voltage source used for battery alarms and telemetry with the `bat_voltage_source` setting. It can be set to either `RAW` for using raw battery voltage or `SAG_COMP` for using the calculated sag compensated voltage.
You can see an illustration of the sag compensation algorithm in action in the following graph:
![Voltage graph](assets/images/sag_compensated_battery_voltage_plot.png)
### Voltage based OSD gauge and alarms
Up to 3 battery profiles are supported. You can select the battery profile from the GUI, OSD menu, [stick commands](Controls.md) and CLI command `battery_profile n`. Each profile stores the following voltage settings:
`bat_cells` - Specify the number of cells of your battery. Allows the automatic selection of the battery profile when set to a value greater than 0. Set to 0 (default) for auto-detecting the number of cells (see next setting)
`vbat_cell_detect_voltage` - Maximum voltage per cell, used for auto-detecting the number of cells of the battery. Should be higher than maximum cell voltage to take into account possible drift in measured voltage and keep cell count detection accurate (0.01V unit, i.e. 430 = 4.30V)
`vbat_max_cell_voltage` - Maximum voltage per cell when the battery is fully charged. Used for the OSD voltage based battery gauge (0.01V unit, i.e. 420 = 4.20V)
`vbat_warning_cell_voltage` - Cell warning voltage. A cell voltage bellow this value triggers the first (short beeps) voltage based battery alarm if used and also the blinking of the OSD voltage indicator if the battery capacity is not used instead (see bellow) (0.01V unit, i.e. 370 = 3.70V)
`vbat_min_cell_voltage` - Cell minimum voltage. A cell voltage bellow this value triggers the second (long beeps) voltage based battery alarm if used and the OSD gauge will display 0% if the battery capacity is not used instead (see bellow) (0.01V unit, i.e. 350 = 3.50V)
e.g.
```
battery_profile 1
set vbat_scale = 1100
set vbat_max_cell_voltage = 430
set vbat_warning_cell_voltage = 340
set vbat_min_cell_voltage = 330
```
# Current Monitoring
Current monitoring (amperage) is supported by connecting a current meter to the appropriate current meter ADC input (see the documentation for your particular board).
When enabled, the following values calculated and used by the telemetry and OLED display subsystems:
* Amps
* mAh used
* Capacity remaining
## Configuration
Enable current monitoring using the CLI command:
```
feature CURRENT_METER
```
Configure the current meter type using the `current_meter_type` settings here:
| Value | Sensor Type |
| ----- | ---------------------- |
| 0 | None |
| 1 | ADC/hardware sensor |
| 2 | Virtual sensor |
Configure capacity using the `battery_capacity` setting, in mAh units.
If you're using an OSD that expects the multiwii current meter output value, then set `multiwii_current_meter_output` to `1` (this multiplies amperage sent to MSP by 10).
### ADC Sensor
The current meter may need to be configured so the value read at the ADC input matches actual current draw. Just like you need a voltmeter to correctly calibrate your voltage reading you also need an ammeter to calibrate the current sensor.
Use the following settings to adjust calibration:
`current_meter_scale`
`current_meter_offset`
### Virtual Sensor
The virtual sensor uses the throttle position to calculate an estimated current value. This is useful when a real sensor is not available. The following settings adjust the virtual sensor calibration:
| Setting | Description |
| ----------------------------- | -------------------------------------------------------- |
| `current_meter_scale` | The throttle scaling factor [centiamps, i.e. 1/100th A] |
| `current_meter_offset` | The current at zero throttle (while disarmed) [centiamps, i.e. 1/100th A] |
There are two simple methods to tune these parameters: one uses a battery charger and another depends on actual current measurements.
#### Tuning Using Actual Current Measurements
If you know your craft's current draw while disarmed (Imin) and at maximum throttle while armed (Imax), calculate the scaling factors as follows:
```
current_meter_scale = (Imax - Imin) * 100000 / (Tmax + (Tmax * Tmax / 50))
current_meter_offset = Imin * 100
```
Note: Tmax is maximum throttle offset (i.e. for `max_throttle` = 1850, Tmax = 1850 - 1000 = 850)
For example, assuming a maximum current of 34.2A, a minimum current of 2.8A, and a Tmax `max_throttle` = 1850:
```
current_meter_scale = (Imax - Imin) * 100000 / (Tmax + (Tmax * Tmax / 50))
= (34.2 - 2.8) * 100000 / (850 + (850 * 850 / 50))
= 205
current_meter_offset = Imin * 100 = 280
```
#### Tuning Using Battery Charger Measurement
If you cannot measure current draw directly, you can approximate it indirectly using your battery charger.
However, note it may be difficult to adjust `current_meter_offset` using this method unless you can
measure the actual current draw with the craft disarmed.
Note:
+ This method depends on the accuracy of your battery charger; results may vary.
+ If you add or replace equipment that changes the in-flight current draw (e.g. video transmitter,
camera, gimbal, motors, prop pitch/sizes, ESCs, etc.), you should recalibrate.
The general method is:
1. Fully charge your flight battery
2. Fly your craft, using >50% of your battery pack capacity (estimated)
3. Note INAV's reported mAh draw
4. Re-charge your flight battery, noting the mAh charging data needed to restore the pack to fully charged
5. Adjust `current_meter_scale` to according to the formula given below
6. Repeat and test
Given (a) the reported mAh draw and the (b) mAh charging data, calculate a new `current_meter_scale` value as follows:
```
current_meter_scale = (reported_draw_mAh / charging_data_mAh) * old_current_meter_scale
```
For example, assuming:
+ A INAV reported current draw of 1260 mAh
+ Charging data to restore full charge of 1158 mAh
+ A existing `current_meter_scale` value of 400 (the default)
Then the updated `current_meter_scale` is:
```
current_meter_scale = (reported_draw_mAh / charging_data_mAh) * old_current_meter_scale
= (1260 / 1158) * 400
= 435
```
## Power and Current Limiting
INAV includes an advanced power and current limiting system to protect your battery and ESCs from excessive discharge rates. This feature automatically reduces throttle output when current or power draw exceeds configured limits.
### Why Use Power Limiting?
Power and current limiting helps:
- **Protect batteries** from exceeding their C-rating and getting damaged
- **Prevent voltage sag** and brown-outs during high-throttle maneuvers
- **Extend battery lifespan** by avoiding excessive discharge rates
- **Improve safety** by preventing ESC or battery overheating
- **Comply with regulations** that may limit power output
### How It Works
The power limiter uses a PI (Proportional-Integral) controller to smoothly reduce throttle when current or power exceeds limits. It supports two operating modes:
1. **Continuous Limit**: The sustained current/power that can be drawn indefinitely
2. **Burst Limit**: A higher current/power allowed for a short duration before falling back to the continuous limit
This burst mode allows brief high-power maneuvers (like punch-outs or quick climbs) while protecting the battery during sustained high-throttle flight.
### Configuration
Power limiting requires a current sensor (`CURRENT_METER` feature). Power-based limiting additionally requires voltage measurement (`VBAT` feature).
#### Basic Settings (per battery profile)
| Setting | Description | Unit | Range |
|---------|-------------|------|-------|
| `limit_cont_current` | Continuous current limit | dA (deci-amps) | 0-2000 (0-200A) |
| `limit_burst_current` | Burst current limit | dA | 0-2000 (0-200A) |
| `limit_burst_current_time` | Duration burst is allowed | ds (deci-seconds) | 0-600 (0-60s) |
| `limit_burst_current_falldown_time` | Ramp-down duration from burst to continuous | ds | 0-600 (0-60s) |
| `limit_cont_power` | Continuous power limit | dW (deci-watts) | 0-20000 (0-2000W) |
| `limit_burst_power` | Burst power limit | dW | 0-20000 (0-2000W) |
| `limit_burst_power_time` | Duration burst power is allowed | ds | 0-600 (0-60s) |
| `limit_burst_power_falldown_time` | Ramp-down duration for power | ds | 0-600 (0-60s) |
**Note**: Set any limit to `0` to disable that specific limiter.
#### Advanced Tuning Settings
| Setting | Description | Default | Range |
|---------|-------------|---------|-------|
| `limit_pi_p` | Proportional gain for PI controller | 100 | 10-500 |
| `limit_pi_i` | Integral gain for PI controller | 15 | 10-200 |
| `limit_attn_filter_cutoff` | Low-pass filter cutoff frequency | 50 Hz | 10-200 |
### Example Configurations
#### Example 1: Simple Current Limiting (50A continuous)
Protect a 1500mAh 4S 50C battery (75A max burst, 50A continuous safe):
```
battery_profile 1
set limit_cont_current = 500 # 50A continuous
set limit_burst_current = 750 # 75A burst
set limit_burst_current_time = 100 # 10 seconds
set limit_burst_current_falldown_time = 20 # 2 second ramp-down
```
#### Example 2: Power Limiting for Racing (500W limit)
Limit total system power for racing class restrictions:
```
battery_profile 1
set limit_cont_power = 4500 # 450W continuous
set limit_burst_power = 5000 # 500W burst
set limit_burst_power_time = 50 # 5 seconds
set limit_burst_power_falldown_time = 10 # 1 second ramp-down
```
#### Example 3: Combined Current and Power Limiting
Protect both battery (current) and ESCs (power):
```
battery_profile 1
# Current limits (battery protection)
set limit_cont_current = 600 # 60A continuous
set limit_burst_current = 800 # 80A burst
set limit_burst_current_time = 100 # 10 seconds
# Power limits (ESC protection)
set limit_cont_power = 8000 # 800W continuous
set limit_burst_power = 10000 # 1000W burst
set limit_burst_power_time = 100 # 10 seconds
```
### Understanding Burst Mode
When you exceed the continuous limit, the system uses "burst reserve" (like a capacitor):
- **Burst reserve** starts full and depletes when current/power exceeds the continuous limit
- When reserve is empty, the limit drops to the continuous value
- The `falldown_time` setting creates a smooth ramp-down instead of an abrupt drop
- Reserve recharges when current/power drops below the continuous limit
**Example timeline** (60A continuous, 80A burst, 10s burst time, 2s falldown):
```
Time Limit Reason
---- ----- ------
0s 80A Full burst reserve
5s 80A Still have reserve (using 5s of 10s)
10s 80A Reserve depleted
10-12s 80→60A Ramping down over 2 seconds
12s+ 60A Continuous limit active
```
### OSD Elements
Three OSD elements display power limiting status:
- **`OSD_PLIMIT_REMAINING_BURST_TIME`**: Shows remaining burst time in seconds
- **`OSD_PLIMIT_ACTIVE_CURRENT_LIMIT`**: Shows current limit being enforced (blinks when limiting)
- **`OSD_PLIMIT_ACTIVE_POWER_LIMIT`**: Shows power limit being enforced (blinks when limiting)
Enable these in the OSD tab to monitor limiting during flight.
### Calibration Tips
1. **Find your battery's limits**: Check manufacturer specifications for continuous and burst C-ratings
- Continuous limit = `battery_capacity_mAh × continuous_C_rating / 100` (in dA)
- Burst limit = `battery_capacity_mAh × burst_C_rating / 100` (in dA)
2. **Test incrementally**: Start with conservative limits and increase gradually
3. **Monitor in flight**: Use OSD elements to see when limiting activates
4. **Calibrate current sensor**: Accurate current readings are critical - see "Current Monitoring" section above
5. **Tune PI controller**: If limiting feels abrupt or causes oscillation, adjust `limit_pi_p` and `limit_pi_i`:
- Increase P for faster response (may cause oscillation)
- Increase I for better steady-state accuracy
- Decrease if throttle oscillates during limiting
### Notes
- Power limiting is part of the battery profile system - each profile can have different limits
- Both current and power limiting can be active simultaneously - the most restrictive applies
- Limiting is applied smoothly via PI controller to avoid abrupt throttle cuts
- The system uses instantaneous current/power readings for responsive limiting
- Set limits to `0` to disable a specific limiter while keeping others active
## Battery capacity monitoring
For the capacity monitoring to work you need a current sensor (`CURRENT_METER` feature). For monitoring energy in milliWatt hour you also need voltage measurement (`VBAT` feature). For best results the current and voltage readings have to be calibrated.
It is possible to display the remaining battery capacity in the OSD and also use the battery capacity thresholds (`battery_capacity_warning` and `battery_capacity_critical`) for battery alarms.
For the remaining battery capacity to be displayed users need to set the `battery_capacity` setting (>0) and the battery to be full when plugged in. If the `battery_capacity` setting is set to 0 the remaining battery capacity item in the OSD will display `NA` and the battery gauge will use an estimation based on the battery voltage otherwise it will display the remaining battery capacity down to the `battery_capacity_critical` setting (battery considered empty) and the battery gauge will be based on the remaining capacity. For the capacity thresholds to be used for alarms the `battery_capacity_warning` and `battery_capacity_critical` settings also needs to be set (>0) and the plugged in battery to be full when plugged in. The battery capacity settings unit can be set using the `battery_capacity_unit`. MilliAmpere hour and milliWatt hour units are supported. The value are absolute meaning that `battery_capacity_warning` is the battery capacity left when the battery is entering the `warning` state and `battery_capacity_critical` is the battery capacity left when the battery is considered empty and entering the `critical` state.
For the battery to be considered full the mean cell voltage of the battery needs to be above `vbat_max_cell_voltage - 140mV` (by default 4.1V). So a 3S battery will be considered full above 12.3V and a 4S battery above 16.24V. If the battery plugged in is not considered full the remaining battery capacity OSD item will show `NF` (Not Full).
For the remaining battery capacity and battery gauge to be the most precise (linear relative to throttle from full to empty) when using battery capacity monitoring users should use the milliWatt hour unit for the battery capacity settings.
### Example configuration
```
set battery_capacity_unit = MAH // battery capacity values are specified in milliAmpere hour
set battery_capacity = 2200 // battery capacity is 2200mAh
set battery_capacity_warning = 660 // the battery warning alarm will sound and the capacity related OSD items will blink when left capacity is less than 660 mAh (30% of battery capacity)
set battery_capacity_critical = 440 // the battery critical alarm will sound and the OSD battery gauge and remaining capacity item will be empty when left capacity is less than 440 mAh (20% of battery capacity)
```
Note that in this example even though your warning capacity (`battery_capacity_warning`) is set to 30% (660mAh), since 440mAh (`battery_capacity_critical`) is considered empty (0% left), the OSD capacity related items will only start to blink when the remaining battery percentage shown on the OSD is below 12%: (`battery_capacity_warning`-`battery_capacity_critical`)*100/(`battery_capacity`-`battery_capacity_critical`)=(660-440)*100/(2200-440)=12.5
## Battery profiles
Up to 3 battery profiles are supported. You can select the battery profile from the GUI, OSD menu, [stick commands](Controls.md) and CLI command `battery_profile n`. Battery profiles store the following settings (see above for an explanation of each setting):
- `bat_cells`
- `vbat_cell_detect_voltage`
- `vbat_max_cell_voltage`
- `vbat_warning_cell_voltage`
- `vbat_min_cell_voltage`
- `battery_capacity`
- `battery_capacity_warning`
- `battery_capacity_critical`
- `throttle_idle`
- `throttle_scale`
- `turtle_mode_power_factor`
- `nav_fw_cruise_thr`
- `nav_fw_min_thr`
- `nav_fw_max_thr`
- `nav_fw_pitch2thr`
- `nav_fw_launch_thr`
- `nav_fw_launch_idle_thr`
- `failsafe_throttle`
- `nav_mc_hover_thr`
To enable the automatic battery profile switching based on battery voltage enable the `BAT_PROF_AUTOSWITCH` feature. For a profile to be automatically selected the number of cells of the battery needs to be specified (>0).
### Battery profiles configuration examples
#### Simple example
In this example we want to use two different type of batteries for the same aircraft and switch manually between them. The first battery is a Li-Po (4.20V/cell) and the second battery is a Li-Ion (4.10V/cell).
```
battery_profile 1
set bat_cells = 0
set vbat_max_cell_voltage = 420
set vbat_warning_cell_voltage = 370
set vbat_min_cell_voltage = 340
battery_profile 2
set bat_cells = 0
set vbat_max_cell_voltage = 410
set vbat_warning_cell_voltage = 280
set vbat_min_cell_voltage = 250
```
#### Simple example with automatic profile switching
In this example we want to use two different batteries for the same aircraft and automatically switch between them when the battery is plugged in. The first battery is a Li-Po 2200mAh 3S and the second battery is a LiPo 1500mAh 4S. Since the INAV defaults for the cell detection voltage and max voltage are adequate for standard LiPo batteries they will not be modified. The warning and minimum voltage are not modified either in this example but you can set them to the value you like. Since we are using battery capacities only the warning voltage (kept at default in this example) will be used and only for triggering the battery voltage indicator blinking in the OSD.
```
feature BAT_PROF_AUTOSWITCH
battery_profile 1
set bat_cells = 3
set battery_capacity = 2200
set battery_capacity_warning = 440
set battery_capacity_critical = 220
battery_profile 2
set bat_cells = 4
set battery_capacity = 1500
set battery_capacity_warning = 300
set battery_capacity_critical = 150
```
#### Advanced automatic switching example
Profile 1 is for a 3S 2200mAh Li-Po pack (max 4.20V/cell), profile 2 for a 3S 4000mAh Li-Ion pack (max 4.10V/cell) and profile 3 for a 4S 1500mAh Li-Po pack (max 4.20V/cell).
With this configuration if the battery plugged in is less than 12.36V (3 x 4.12) the profile 2 will be automatically selected else if the battery voltage is less than 12.66V (3 x 4.22) the profile 1 will be automatically selected else if the battery voltage is less 17.20V (4 x 4.3) the profile 3 will be automatically selected. If a matching profile can't be found the last selected profile is used.
```
feature BAT_PROF_AUTOSWITCH
battery_profile 1
set bat_cells = 3
set vbat_cell_detect_voltage = 422
set vbat_max_cell_voltage = 420
set vbat_warning_cell_voltage = 350
set vbat_min_cell_voltage = 330
set battery_capacity = 2200
set battery_capacity_warning = 440
set battery_capacity_critical = 220
battery_profile 2
set bat_cells = 3
set vbat_cell_detect_voltage = 412
set vbat_max_cell_voltage = 410
set vbat_warning_cell_voltage = 300
set vbat_min_cell_voltage = 280
set battery_capacity = 4000
set battery_capacity_warning = 800
set battery_capacity_critical = 400
battery_profile 3
set bat_cells = 4
set vbat_cell_detect_voltage = 430
set vbat_max_cell_voltage = 420
set vbat_warning_cell_voltage = 350
set vbat_min_cell_voltage = 330
set battery_capacity = 1500
set battery_capacity_warning = 300
set battery_capacity_critical = 150
```
#### Change control profile based on battery profile
You can change the control profile, automatically, based on the battery profile. This allows for fine tuning of each power choice.
```
feature BAT_PROF_AUTOSWITCH
battery_profile 1
set bat_cells = 3
set controlrate_profile = 1
battery_profile 2
set bat_cells = 4
set controlrate_profile = 2
```
## Remaining flight time and flight distance estimation
The estimated remaining flight time and flight distance estimations can be displayed on the OSD (for fixed wing only for the moment). They are calculated from the GPS distance from home, remaining battery capacity and average power draw. They are taking into account the requested altitude change and heading to home change after altitude change following the switch to RTH. They are also taking into account the estimated wind if `osd_estimations_wind_compensation` is set to `ON`. When the timer and distance indicator reach 0 they will blink and you need to go home in a straight line manually or by engaging RTH. You should be left with at least `rth_energy_margin`% of battery left when arriving home if the cruise speed and power are set correctly (see bellow).
To use this feature the following conditions need to be met:
- The `VBAT`, `CURRENT_METER` and `GPS` features need to be enabled
- The battery capacity needs to be specified in mWh (`battery_capacity` setting > 0 and `battery_capacity_unit` set to `MWH`)
- The average ground speed of the aircraft without wind at cruise throttle needs to be set (`nav_fw_cruise_speed` setting in cm/s)
- The average power draw at zero throttle needs to be specified (`idle_power` setting in 0.01W unit)
- The average power draw at cruise throttle needs to be specified (`cruise_power` setting in 0.01W unit)
- The battery needs to be full when plugged in (voltage >= (`vbat_max_cell_voltage` - 100mV) * cells)
It is advised to set `nav_fw_cruise_speed` a bit lower than the real speed and `cruise_power` 10% higher than the power at cruise throttle to ensure variations in throttle during cruise won't cause the aircraft to draw more energy than estimated.
If `---` is displayed during flight instead of the remaining flight time/distance it means at least one of the above conditions aren't met. If the OSD element is blinking and the digits are replaced by the horizontal wind symbol it means that the estimated horizontal wind is too strong to be able to return home at `nav_fw_cruise_speed`.
## Automatic throttle compensation based on battery voltage
This features aims to compensate the throttle to get constant thrust with the same throttle request despite the battery voltage going down during flight. It can be used by enabling the `THR_VBAT_COMP` feature. This feature needs the sag compensated voltage which needs a current sensor (real or virtual) to be calculated.
It is working like this: `used_throttle = requested_throttle * (1 + (battery_full_voltage / sag_compensated_voltage - 1) * thr_comp_weight)`.
The default `thr_comp_weight` of 1 should be close to ideal but if you want to tune this feature you need to find the difference in throttle value to achieve the same thrust (same power) when your battery is full and when your battery is almost empty then set `thr_comp_weight` to `(empty_battery_throttle / full_battery_throttle - 1) / (battery_full_voltage / battery_empty_sag_compensated_voltage - 1)`
Example:
If the drawn power is 100W when the battery is full (12.6V) with 53% throttle and the drawn power is 100W with 58% throttle when the battery is almost empty with the sag compensated voltage being 11.0V `thr_comp_weight` needs to be set to this value to compensate the throttle automatically:
`(58 / 53 - 1) / (12.6 / 11.0 - 1) = 0.649`
Known limitation: it doesn't work in 3D mode (3D feature)
docs/Blackbox.md
+240
View File
@@ -0,0 +1,240 @@
# Blackbox flight data recorder
![Rendered flight log frame](Screenshots/blackbox-screenshot-1.jpg)
## Introduction
This feature transmits your flight data information on every control loop iteration over a serial port to an external logging device to be recorded, SD card, or to a dataflash chip which is present on some flight controllers.
After your flight, you can view the resulting logs using the interactive log viewer:
https://github.com/iNavFlight/blackbox-log-viewer
You can also use the `blackbox_decode` tool to turn the logs into CSV files for analysis, or render your flight log as a
video using the `blackbox_render` tool. Those tools can be found in this repository:
https://github.com/iNavFlight/blackbox-tools
## Logged data
The blackbox records flight data on every iteration of the flight control loop. It records the current time in microseconds, P, I and D corrections for each axis, your RC command stick positions (after applying expo curves), gyroscope data, accelerometer data (after your configured low-pass filtering), barometer and rangefinder readings, 3-axis magnetometer readings, raw VBAT and current measurements, RSSI, and the command being sent to each motor speed controller. This is all stored without any approximation or loss of precision, so even quite subtle problems should be
detectable from the fight data log.
GPS data is logged whenever new GPS data is available. Although the CSV decoder will decode this data, the video renderer does not yet show any of the GPS information (this will be added later).
## Supported configurations
The maximum data rate that can be recorded to the flight log is fairly restricted, so anything that increases the load can cause the flight log to drop frames and contain errors.
The Blackbox is typically used on tricopters and quadcopters. Although it will work on hexacopters and octocopters, because these craft have more motors to record, they must transmit more data to the flight log. This can increase the number of dropped frames. Although the browser-based log viewer supports hexacopters and octocopters, the command-line `blackbox_render` tool currently only supports tri- and quadcopters.
INAV's `looptime` setting decides how frequently an update is saved to the flight log. The default looptime on INAV is 2000us. If you're using a looptime smaller than about 2400, you may experience some dropped frames due to the high required data rate. In that case you will need to reduce the sampling rate in the Blackbox settings, or increase your logger's baudrate to 250000. See the later section on configuring the Blackbox feature for details.
## Setting up logging
First, you must enable the Blackbox feature. In the [INAV Configurator][] enter the Configuration tab, tick the "BLACKBOX" feature at the bottom of the page, and click "Save and reboot"
Now you must decide which device to store your flight logs on. You can either transmit the log data over a serial port to an external logging device like the [OpenLog serial data logger][] to be recorded to a microSDHC card, or if you have a compatible flight controller you can store the logs on the onboard dataflash storage instead.
### OpenLog serial data logger
The OpenLog is a small logging device which attaches to your flight controller using a serial port and logs your flights to a MicroSD card.
The OpenLog ships from SparkFun with standard "OpenLog 3" firmware installed. Although this original OpenLog firmware will work with the Blackbox, in order to reduce the number of dropped frames it should be reflashed with the higher performance [OpenLog Blackbox firmware][]. The special Blackbox variant of the OpenLog firmware also ensures that the OpenLog is using INAV compatible settings, and defaults to 115200 baud.
You can find the Blackbox version of the OpenLog firmware [here](https://github.com/iNavFlight/openlog-blackbox-firmware), along with instructions for installing it onto your OpenLog.
[OpenLog serial data logger]: https://www.sparkfun.com/products/9530
[OpenLog Blackbox firmware]: https://github.com/iNavFlight/openlog-blackbox-firmware
#### microSDHC
Your choice of microSDHC card is very important to the performance of the system. The OpenLog relies on being able to make many small writes to the card with minimal delay, which not every card is good at. A faster SD-card speed rating is not a guarantee of better performance.
##### microSDHC cards known to have poor performance
- Generic 4GB Class 4 microSDHC card - the rate of missing frames is about 1%, and is concentrated around the most interesting parts of the log!
- Sandisk Ultra 32GB (unlike the smaller 16GB version, this version has poor write latency)
##### microSDHC cards known to have good performance
- Transcend 16GB Class 10 UHS-I microSDHC (typical error rate < 0.1%)
- Sandisk Extreme 16GB Class 10 UHS-I microSDHC (typical error rate < 0.1%)
- Sandisk Ultra 16GB (it performs only half as well as the Extreme in theory, but still very good)
You should format any card you use with the [SD Association's special formatting tool][] , as it will give the OpenLog the best chance of writing at high speed. You must format it with either FAT, or with FAT32 (recommended).
[SD Association's special formatting tool]: https://www.sdcard.org/downloads/formatter_4/
### Choosing a serial port for the OpenLog
First, tell the Blackbox to log using a serial port (rather than to an onboard dataflash chip). Go to the Configurator's CLI tab, enter `set blackbox_device=SERIAL` to switch logging to serial, and save.
You need to let INAV know which of [your serial ports][] you connect your OpenLog to (i.e. the Blackbox port), which you can do on the Configurator's Ports tab.
You should use a hardware serial port. SoftSerial ports can be used for the Blackbox. However, because they are limited to 19200 baud, your logging rate will need to be severely reduced to compensate. Therefore the use of SoftSerial is not recommended.
When using a hardware serial port, Blackbox should be set to at least 115200 baud on that port. When using fast looptimes (<2500), a baud rate of 250000 should be used instead in order to reduce dropped frames.
The serial port used for Blackbox cannot be shared with any other function (e.g. GPS, telemetry) except the MSP protocol. If MSP is used on the same port as Blackbox, then MSP will be active when the board is disarmed, and Blackbox will be active when the board is armed. This will mean that you can't use the Configurator or any other function that requires MSP, such as an OSD or a Bluetooth wireless configuration app, while the board is armed.
Connect the "TX" pin of the serial port you've chosen to the OpenLog's "RXI" pin. Don't connect the serial port's RX pin to the OpenLog, as this will cause the OpenLog to interfere with any shared functions on the serial port while disarmed.
The key criteria to choose a serial port are:
* Should be a hardware serial port rather than SoftSerial.
* Cannot be shared with any other function (GPS, telemetry) except MSP.
* If MSP is used on the same UART, MSP will stop working when the board is armed.
#### OpenLog configuration
Power up the OpenLog with a microSD card inside, wait 10 seconds or so, then power it down and plug the microSD card into your computer. You should find a "CONFIG.TXT" file on the card, open it up in a text editor. You should see the baud rate that the OpenLog has been configured for (usually 115200 or 9600 from the factory). Set the baud rate to match the rate you entered for the Blackbox in the Configurator's Port tab (typically 115200 or 250000).
Save the file and put the card back into your OpenLog, it will use those settings from now on.
If your OpenLog didn't write a CONFIG.TXT file, create a CONFIG.TXT file with these contents and store it in the root of the MicroSD card:
```
115200
baud
```
If you are using the original OpenLog firmware, use this configuration instead:
```
115200,26,0,0,1,0,1
baud,escape,esc#,mode,verb,echo,ignoreRX
```
#### OpenLog protection
The OpenLog can be wrapped in black electrical tape or heat-shrink in order to insulate it from conductive frames (like carbon fibre), but this makes its status LEDs impossible to see. I recommend wrapping it with some clear heatshrink tubing instead.
![OpenLog installed](Wiring/blackbox-installation-1.jpg "OpenLog installed with double-sided tape, SDCard slot pointing outward")
### Onboard dataflash storage
Some flight controllers have an onboard SPI NOR dataflash chip which can be used to store flight logs instead of using an OpenLog.
These chips are also supported:
* Micron/ST M25P16 - 16 Mbit / 2 MByte
* Micron N25Q064 - 64 Mbit / 8 MByte
* Winbond W25Q64 - 64 Mbit / 8 MByte
* Micron N25Q0128 - 128 Mbit / 16 MByte
* Winbond W25Q128 - 128 Mbit / 16 MByte
* Puya PY25Q128HA - 128 Mbit / 16 MByte
* Winbond W25N01 - 1 Gbit / 128 MByte
* Winbond W25N02 - 2 Gbit / 256 MByte
#### Enable recording to dataflash
On the Configurator's CLI tab, you must enter `set blackbox_device=SPIFLASH` to switch to logging to an onboard dataflash chip, then save.
[your serial ports]: https://github.com/iNavFlight/inav/blob/master/docs/Serial.md
[INAV Configurator]: https://chrome.google.com/webstore/detail/inav-configurator/fmaidjmgkdkpafmbnmigkpdnpdhopgel
## Configuring the Blackbox
The Blackbox currently provides two settings (`blackbox_rate_num` and `blackbox_rate_denom`) that allow you to control the rate at which data is logged. These two together form a fraction (`blackbox_rate_num / blackbox_rate_denom`) which decides what portion of the flight controller's control loop iterations should be logged. The default is 1/1 which logs every iteration.
If you're using a slower MicroSD card, you may need to reduce your logging rate to reduce the number of corrupted logged frames that `blackbox_decode` complains about. A rate of 1/2 is likely to work for most craft.
You can change the logging rate settings by entering the CLI tab in the [INAV Configurator][] and using the `set` command, like so:
```
set blackbox_rate_num = 1
set blackbox_rate_denom = 2
```
The data rate for my quadcopter using a looptime of 2400 and a rate of 1/1 is about 10.25kB/s. This allows about 18 days of flight logs to fit on my OpenLog's 16GB MicroSD card, which ought to be enough for anybody :).
If you are logging using SoftSerial, you will almost certainly need to reduce your logging rate to 1/32. Even at that logging rate, looptimes faster than about 1000 cannot be successfully logged.
If you're logging to an onboard dataflash chip instead of an OpenLog, be aware that the 2MB of storage space it offers is pretty small. At the default 1/1 logging rate, and a 2400 looptime, this is only enough for about 3 minutes of flight. This could be long enough for you to investigate some flying problem with your craft, but you may want to reduce the logging rate in order to extend your recording time.
To maximize your recording time, you could drop the rate all the way down to 1/32 which would result in a logging rate of about 10-20Hz and about 650 bytes/second of data. At that logging rate, a 2MB dataflash chip can store around 50 minutes of flight data, though the level of detail is severely reduced and you could not diagnose flight problems like vibration or PID setting issues.
The CLI command `blackbox` allows setting which Blackbox fields are recorded to conserve space and bandwidth. Possible fields are:
* `NAV_ACC` - Navigation accelerometer readouts
* `NAV_PID` - Navigation PID debug
* `NAV_POS` - Current and target position and altitude
* `MAG` - Magnetometer raw values
* `ACC` - Accelerometer raw values
* `ATTI` - Attitude as computed by INAV position estimator
* `RC_DATA` - RC channels 1-4 as returned by the radio receiver
* `RC_COMMAND` - RC_DATA converted to [-500:500] scale (for A,E,R) with expo and deadband
* `MOTORS` - motor output
* `GYRO_RAW` - Raw Gyro data
* `PEAKS_R` - Roll axis noise peak
* `PEAKS_P` - Pitch axis noise peak
* `PEAKS_Y` - Yaw axis noise peak
* `SERVOS` - Servo outputs (for planes, tris, etc.)
Usage:
* `blackbox` currently enabled Blackbox fields
* `blackbox list` all available fields
* `blackbox -MOTORS` disable MOTORS logging
* `blackbox MOTORS` enable MOTORS logging
### Debug Mode Logging
In addition to the standard blackbox fields above, INAV supports logging debug values for troubleshooting and analysis via the `debug_mode` setting. When a debug mode is active, it populates 8 debug values (`debug[0]` through `debug[7]`) with mode-specific data that gets logged to the blackbox.
Available debug modes include:
- `FLOW_RAW` - Optical flow sensor raw data (useful for sensor alignment)
- `LANDING` - Landing mode debugging
- `POS_EST` - Position estimation debugging
- `GPS` - GPS debugging
- `ALTITUDE` - Altitude estimation debugging
- And 20+ other modes for specific subsystems
To use debug mode logging:
```
set debug_mode = FLOW_RAW # Enable a specific debug mode
set debug_mode = NONE # Disable debug mode (default)
```
You can view current debug values in the CLI with the `debug` command, or display them in real-time on your OSD using the `OSD_DEBUG` element.
For technical details on debug logging and blackbox internals, see the [Blackbox Internals](development/Blackbox%20Internals.md) documentation.
## Usage
The Blackbox starts recording data as soon as you arm your craft, and stops when you disarm.
If your craft has a buzzer attached, you can use INAV's arming beep to synchronize your Blackbox log with your flight video. INAV's arming beep is a "long, short" pattern. The beginning of the first long beep will be shown as a blue line in the flight data log, which you can sync against your recorded audio track.
You should wait a few seconds after disarming your craft to allow the Blackbox to finish saving its data.
### Usage - OpenLog
Each time the OpenLog is power-cycled, it begins a fresh new log file. If you arm and disarm several times without cycling the power (recording several flights), those logs will be combined together into one file. The command line tools will ask you to pick which one of these flights you want to display/decode.
Don't insert or remove the SD card while the OpenLog is powered up.
### Usage - Dataflash chip
After your flights, you can use the [INAV Configurator][] to download the contents of the dataflash to your computer. Go to the "dataflash" tab and click the "save flash to file..." button. Saving the log can take 2 or 3 minutes.
![Dataflash tab in Configurator](Screenshots/blackbox-dataflash.png)
After downloading the log, be sure to erase the chip to make it ready for reuse by clicking the "erase flash" button.
If you try to start recording a new flight when the dataflash is already full, Blackbox logging will be disabled and nothing will be recorded.
### Usage - Logging switch
If you're recording to an onboard flash chip, you probably want to disable Blackbox recording when not required in order to save storage space. To do this, you can add a Blackbox flight mode to one of your AUX channels on the Configurator's modes tab. Once you've added a mode, Blackbox will only log flight data when the mode is active.
A log header will always be recorded at arming time, even if logging is paused. You can freely pause and resume logging while in flight.
## Viewing recorded logs
After your flights, you'll have a series of flight log files with a .TXT extension.
You can view these .TXT flight log files interactively using your web browser with the INAV Blackbox Explorer:
https://github.com/iNavFlight/blackbox-log-viewer
This allows you to scroll around a graphed version of your log and examine your log in detail. You can also export a video of your log to share it with others!
You can decode your logs with the `blackbox_decode` tool to create CSV (comma-separated values) files for analysis, or render them into a series of PNG frames with `blackbox_render` tool, which you could then convert into a video using another software package.
You'll find those tools along with instructions for using them in this repository:
https://github.com/iNavFlight/blackbox-tools
docs/Boards.md
+36
View File
@@ -0,0 +1,36 @@
# Flight controller hardware
### Recommended boards
These boards are well tested with INAV and are known to be of good quality and reliability.
| Board name | CPU Family | Target name(s) | GPS | Compass | Barometer | Telemetry | RX | Blackbox |
|---------------------------|:----------:|:-------------------------:|:----:|:-------:|:--------------:|:---------:|:------------------------------:|:--------------------:|
| [Diatone Mamba H743](https://inavflight.com/shop/s/bg/1929033) | H7 | MAMBAH743 | All | All | All | All | All | SERIAL, SD |
| [Matek F765-WSE](https://inavflight.com/shop/s/bg/1890404) | F7 | MATEKF765SE | All | All | All | All | All | SERIAL, SD |
| [Matek F722-SE](https://inavflight.com/shop/p/MATEKF722SE) | F7 | MATEKF722SE | All | All | All | All | All | SERIAL, SD |
| [Holybro Kakute H7](https://inavflight.com/shop/s/bg/1914066) | H7 | KAKUTEH7 | All | All | All | All | All | SERIAL, SD |
It's possible to find more supported and tested boards [here](https://github.com/iNavFlight/inav/wiki/Welcome-to-INAV,-useful-links-and-products)
There is also a [full list of all supported boards](https://github.com/iNavFlight/inav/wiki/Boards,-Targets-and-PWM-allocations).
### Boards documentation
See the [docs/boards](https://github.com/iNavFlight/inav/tree/master/docs/boards) folder for additional information regards to many targets in INAV, to example help in finding pinout and features. _Feel free to help improve the docs._
### Boards based on F4/F7 CPUs
These boards are powerful and in general support everything INAV is capable of. Limitations are quite rare and are usually caused by hardware design issues.
### Boards based on F3 CPUs
Boards based on STM32F3 MCUs are no longer supported by latest INAV version. Last release is 2.6.1.
### Boards based on F1 CPUs
Boards based on STM32F1 CPUs are no longer supported by latest INAV version. Last release is 1.7.3
### Not recommended for new setups
F1 and F3 boards are no longer recommended. Users should choose a board from the supported F4 or F7 devices available in the latest release.
docs/Broken USB recovery.md
+79
View File
@@ -0,0 +1,79 @@
# Broken USB recovery
It is possible to flash INAV without USB over UART 1 or 3.
## Prerequisites:
- USB/UART adapter (FT232, CP2102, etc.)
- STM32 Cube Programmer (https://www.st.com/en/development-tools/stm32cubeprog.html)
To gain access to the FC via Configurator, MSP must be activated on a UART as standard. Some FCs already have this enabled by default, if not a custom firmware must be created.
The following targets have MSP activated on a UART by default:
| Target | Standard MSP Port |
|-----------| ----------- |
| AOCODARCF4V3 | UART5 |
| ATOMRCF405NAVI_DELUXE | UART1 |
| FF_F35_LIGHTNING | UART1 |
| FLYCOLORF7V2 | UART4 |
| GEPRCF405_BT_HD | UART5* |
| GEPRCF722_BT_HD | UART4* |
| IFLIGHT_BLITZ_F7_AIO | UART1 |
| JHEMCUF405WING | UART6 |
| JHEMCUH743HD | UART4 |
| KAKUTEH7 | UART1 and UART2* |
| KAKUTEH7WING | UART6 |
| MAMBAF405_2022A | UART4 |
| MAMBAF405US | UART4 |
| MAMBAF722 | UART4 |
| MAMBAF722 APP | UART4*|
| MAMBAF722WING | UART4 |
| MAMBAF722_X8 | UART4 |
| MAMBAH743 | UART4* |
| MATEKF405SE | UART1 |
| NEUTRONRCH743BT | UART3* |
| SDMODELH7V1 | UART1 and UART2 |
| SKYSTARSH743HD | UART4 |
| SPEEDYBEEF4 | UART5* |
| SPEEDYBEEF405MINI | UART4* |
| SPEEDYBEEF405V3 | UART4* |
| SPEEDYBEEF405V4 | UART4* |
| SPEEDYBEEF405WING | UART6 |
| SPEEDYBEEF7 | UART6 |
| SPRACINGF4EVO | UART1 |
| TMOTORF7V2 | UART5 |
(*) No Pads/Pins, Port is used interally (Bluetooth)
## Custom firmware:
If the FC does not have MSP activated on a UART by default or does not have a connector for it, a custom firmware must be built.
The following procedure describes the process under Windows 10/11:
Please read [Building in Windows 2010 or 11 with Linux Subsystem](https://github.com/iNavFlight/inav/blob/master/docs/development/Building%20in%20Windows%2010%20or%2011%20with%20Linux%20Subsystem.md)
and follow the instructions up to "Building with Make".
In the step 'prepare build environment' add the option `-DMSP_UART=SERIAL_PORT_USARTX` to `cmake`
Replace the X in SERIAL_PORT_USARTX with the number of UART/serial port on which MSP is to be activated.
Example:
For UART 2: `cmake -DMSP_UART=SERIAL_PORT_USART2 ..`
For UART 3: `cmake -DMSP_UART=SERIAL_PORT_USART3 ..`
etc.
Build the firmware as described in the document above (`make [YOUR_TARGET]`).
## Flashing via Uart:
1. Disconnect ALL peripherals and the USB Cable from the FC. To power the FC use a battery or use the 5V provided from the USB/Serial Converter.
2. Connect UART 1 or 3 (other UARTS will not work) and GND to the USB/Serial converter (RX -> TX, TX -> RX)
3. Keep the boot/dfu button pressed
4. Switch on the FC / supply with power
5. Start STM32 CubeProgrammer and go to "Erasing & Programming", second option in the menu.
6. Select UART (blue dropdown field) and select the COM port of the USB/Serial adapter and press "Connect". The corresponding processor should now be displayed below.
7. Click on "Full flash erase". This is also necessary if you are flashing the same firmware version that was previously on the FC, otherwise MSP may not be activated on the UART.
8. Under "Download" load the previously created firmware (`INAV_X.X.X_[Your Target].hex`) or the standard firmware if UART is already activated there. The option "Verify programming" is optional but recommended. Make sure that "Skip flash erase while programming" is NOT activated.
9. Click "Start Programming"
After the process is completed, switch the FC off and on again and then the Configurator can connect to the FC via USB/serial adapter and the previously configured UART.
docs/Buzzer.md
+130
View File
@@ -0,0 +1,130 @@
# Buzzer
INAV supports a buzzer which is used for the following purposes:
* Low and critical battery alarms (when battery monitoring enabled)
* Arm/disarm tones (and warning beeps while armed)
* Notification of calibration complete status
* TX-AUX operated beeping - useful for locating your aircraft after a crash
* Failsafe status
* Flight mode change
* Rate profile change (via TX-AUX switch)
If the arm/disarm is via the control stick, holding the stick in the disarm position will sound a repeating tone. This can be used as a lost-model locator.
Three beeps immediately after powering the board means that the gyroscope calibration has completed successfully. INAV calibrates the gyro automatically upon every power-up. It is important that the copter stay still on the ground until the three beeps sound, so that gyro calibration isn't thrown off. If you move the copter significantly during calibration, INAV will detect this, and will automatically re-start the calibration once the copter is still again. This will delay the "three beeps" tone. If you move the copter just a little bit, the gyro calibration may be incorrect, and the copter may not fly correctly. In this case, the gyro calibration can be performed manually via [stick command](Controls.md), or you may simply power cycle the board.
There is a special arming tone used if a GPS fix has been attained, and there's a "ready" tone sounded after a GPS fix has been attained (only happens once). The tone sounded via the TX-AUX-switch will count out the number of satellites (if GPS fix).
The CLI command `play_sound` is useful for demonstrating the buzzer tones. Repeatedly entering the command will play the various tones in turn. Entering the command with a numeric-index parameter (see below) will play the associated tone.
Buzzer is enabled by default on platforms that have buzzer connections.
## Tone sequences
Buzzer tone sequences (square wave generation) are made so that : 1st, 3rd, 5th, .. are the delays how long the beeper is on and 2nd, 4th, 6th, .. are the delays how long beeper is off. Delays are in milliseconds/10 (i.e., 5 => 50ms).
Sequences:
0 GYRO_CALIBRATED 20, 10, 20, 10, 20, 10 Gyro is calibrated
1 RX_LOST_LANDING 10, 10, 10, 10, 10, 40, 40, 10, 40, 10, 40, 40, 10, 10, 10, 10, 10, 70 SOS morse code
2 RX_LOST 50, 50 TX off or signal lost (repeats until TX is okay)
3 DISARMING 15, 5, 15, 5 Disarming the board
4 ARMING 30, 5, 5, 5 Arming the board
5 ARMING_GPS_FIX 5, 5, 15, 5, 5, 5, 15, 30 Arming and GPS has fix
6 BAT_CRIT_LOW 50, 2 Battery is critically low (repeats)
7 BAT_LOW 25, 50 Battery is getting low (repeats)
8 NULL multi beeps GPS status (sat count)
9 RX_SET 10, 10 RX is set (when aux channel is set for beep or beep sequence how many satellites has found if GPS enabled)
10 ACC_CALIBRATION 5, 5, 5, 5 ACC inflight calibration completed
11 ACC_CALIBRATION_FAIL 20, 15, 35, 5 ACC inflight calibration failed
12 READY_BEEP 4, 5, 4, 5, 8, 5, 15, 5, 8, 5, 4, 5, 4, 5 GPS locked and copter ready
13 NULL multi beeps Variable # of beeps (confirmation, GPS sat count, etc)
14 DISARM_REPEAT 0, 100, 10 Stick held in disarm position (after pause)
15 ARMED 0, 245, 10, 5 Board is armed (after pause ; repeats until board is disarmed or throttle is increased)
You can use [this tool](https://www.mrd-rc.com/tutorials-tools-and-testing/useful-tools/helpful-inav-buzzer-code-checker/) to hear current buzzer sequences or enter custom sequences.
## Controlling buzzer usage
The usage of the buzzer can be controlled by the CLI `beeper` command.
### List current usage
```
beeper
```
### List all buzzer setting options
```
beeper list
```
giving:
```
Available: RUNTIME_CALIBRATION HW_FAILURE RX_LOST RX_LOST_LANDING DISARMING ARMING ARMING_GPS_FIX BAT_CRIT_LOW
BAT_LOW GPS_STATUS RX_SET ACTION_SUCCESS ACTION_FAIL READY_BEEP MULTI_BEEPS DISARM_REPEAT ARMED SYSTEM_INIT
ON_USB LAUNCH_MODE CAM_CONNECTION_OPEN CAM_CONNECTION_CLOSED ALL PREFERED
```
The `beeper` command syntax follows that of the `feature` command; a minus (`-`) in front of a name disables that function.
So to disable the beeper / buzzer when powered by USB (may enhance domestic harmony):
```
beeper -ON_USB
```
Now the `beeper` command will show:
```
# beeper
Disabled: ON_USB
```
*Note: SYSTEM_INIT sequence is not affected by ON_USB setting and will still be played on USB connection. Disable both ON_USB and SYSTEM_INIT to disable buzzer completely when FC is powered from USB.*
*Note: ON_USB setting requires present and configured battery voltage metter.*
To disable all features use:
```
beeper -ALL
```
To store current set to preferences use (preferences also require ```save```):
```
beeper PREFERED
```
To restore set from preferences use:
```
beeper -PREFERED
```
To activate an external beeper via aux channel switch, assign aux channel and set both:
```
beeper RX_SET
beeper MULTI_BEEPS
```
If MULTI_BEEPS is not set, the beeper will not sound after GPS lock.
As with other CLI commands, the `save` command is needed to save the new settings.
## Types of buzzer supported
Most FCs require ACTIVE buzzers. Active buzzers are enabled/disabled by simply enabling or disabling a GPIO output pin on the board.
This means the buzzer must be able to generate its own tone simply by having power applied to it.
Passive buzzers that need an analog or PWM signal do not work and will make clicking noises or no sound at all.
Passive buzzers are supported on FCs which are designed to work with passive buzzers only (so far there is no available, except rare cases like Matek F765-WSE where passive buzzer is preinstalled).
Examples of a known-working buzzers.
* [Hcm1205x Miniature Buzzer 5v](http://www.rapidonline.com/Audio-Visual/Hcm1205x-Miniature-Buzzer-5v-35-0055)
* [MultiComp MCKPX-G1205A-3700 TRANSDUCER, THRU-HOLE, 4V, 30MA](http://uk.farnell.com/multicomp/mckpx-g1205a-3700/transducer-thru-hole-4v-30ma/dp/2135914?CMP=i-bf9f-00001000)
* [3-24V Piezo Electronic Tone Buzzer Alarm 95DB](https://inavflight.com/shop/s/bg/919348)
docs/Channel forwarding.md
+15
View File
@@ -0,0 +1,15 @@
# Channel forwarding
Starting from INAV 2.0, _channel forwarding_ feature is removed. Channel forwarding functionality can be configured using _Mixer Configurator Tab_ instead.
Channel forwarding using mixer works for all flight controllers that supports servos in either multirotor or airplane configuration. Bear in mind, that some boards might not have any servo outputs in multirotor configuration. In this case, channel forwarding will just not work. Refer to the board documentation to find out if servos are available in multirotor configuration.
## How to setup channel forwarding
![Mixer GUI](assets/images/mixer_forwarding.png)
1. Open Mixer tab
1. Add new _servo rule_ for given servo index
1. Choose source as one of _RC Roll_, _RC Pitch_, _RC Yaw_, _RC Throttle_ or _RC Channel 5_ to _RC Channel 16_
1. When required, servo direction can be modified by applying negative weight
1. It is possible to limit servo speed. Refer to [Mixer documentation](Mixer.md)
docs/Cli.md
+251
View File
@@ -0,0 +1,251 @@
# Command Line Interface (CLI)
INAV has a command line interface (CLI) that can be used to change settings and configure the FC.
## Accessing the CLI.
The CLI can be accessed via the GUI tool or via a terminal emulator connected to the CLI serial port.
1. Connect your terminal emulator to the CLI serial port (which, by default, is the same as the MSP serial port)
2. Use the baudrate specified by msp_baudrate (115200 by default).
3. Send a `#` character.
To save your settings type in 'save', saving will reboot the flight controller.
To exit the CLI without saving power off the flight controller or type in 'exit'.
To see a list of other commands type in 'help' and press return.
To dump your configuration (including the current profile), use the 'dump' or 'diff' command.
See the other documentation sections for details of the cli commands and settings that are available.
## Backup via CLI
> **Note:** The INAV Configurator now performs automatic backups before flashing and can restore settings afterwards, including migration across major versions. See [Backup and Restore](Backup%20and%20Restore.md) for details. The CLI method below remains available for manual backup.
Disconnect main power, connect to cli via USB/FTDI.
dump using cli
```
control_profile 0
dump
```
dump control_profiles using cli if you use them
```
control_profile 1
dump control_profile
control_profile 2
dump control_profile
```
copy screen output to a file and save it.
Alternatively, use the `diff` command to dump only those settings that differ from their default values (those that have been changed).
## Restore via CLI.
Use the cli `defaults` command first.
When restoring from backup it's a good idea to do a dump of the latest defaults so you know what has changed - if you do this each time a firmware release is created you will be able to see the cli changes between firmware versions. If you blindly restore your backup you would not benefit from these new defaults or may even end up with completely wrong settings in case some parameters changed semantics and/or value ranges.
It may be good idea to restore settings using the `diff` output rather than complete `dump`. This way you can have more control on what is restored and the risk of mistakenly restoring bad values if the semantics changes is minimised.
To perform the restore simply paste the saved commands in the Configurator CLI tab and then type `save`.
After restoring it's always a good idea to `dump` or `diff` the settings once again and compare the output with previous one to verify if everything is set as it should be.
## Flight Controller opereration while connected to the CLI
While connected to the CLI, all Logical Switches are temporarily disabled (5.1.0 onwards).
## CLI Command Reference
| `Command` | Description |
|-----------| ----------- |
| `adjrange` | Configure adjustment ranges |
| `assert` | |
| `aux` | Configure modes |
| `batch` | Start or end a batch of commands |
| `battery_profile` | Change battery profile |
| `beeper` | Show/set beeper (buzzer) [usage](Buzzer.md) |
| `bind_msp_rx` | Initiate binding for MSP receivers (mLRS) |
| `bind_rx` | Initiate binding for SRXL2 or CRSF receivers |
| `blackbox` | Configure blackbox fields |
| `bootlog` | Show init logs from [serial_printf_debugging](./development/serial_printf_debugging.md) |
| `color` | Configure colors |
| `defaults` | Reset to defaults and reboot |
| `dfu` | DFU mode on reboot |
| `diff` | List configuration changes from default |
| `dump` | Dump configuration |
| `exit` | |
| `feature` | List or enable <val> or disable <-val> |
| `flash_erase` | Erase flash chip |
| `flash_info` | Show flash chip info |
| `flash_read` | |
| `flash_write` | |
| `get` | Get variable value |
| `gpspassthrough` | Passthrough gps to serial |
| `gvar` | Configure global variables |
| `help` | Displays CLI help and command parameters / options |
| `led` | Configure leds |
| `logic` | Configure logic conditions |
| `map` | Configure rc channel order |
| `memory` | View memory usage |
| `mmix` | Custom motor mixer |
| `mode_color` | Configure mode and special colors |
| `motor` | Get/set motor |
| `msc` | Enter USB Mass storage mode. See [USB MSC documentation](USB_Mass_Storage_(MSC)_mode.md) for usage information. |
| `osd_layout` | Get or set the layout of OSD items |
| `pid` | Configurable PID controllers |
| `play_sound` | `<index>`, or none for next item |
| `control_profile` | Change profile |
| `resource` | View currently used resources |
| `rxrange` | Configure rx channel ranges |
| `safehome` | Define safe home locations. See the [safehome documentation](Safehomes.md) for usage information. |
| `save` | Save and reboot |
| `sd_info` | Sdcard info |
| `serial` | Configure serial ports. [Usage](Serial.md) |
| `serialpassthrough` | Passthrough serial data to port, with `<id> <baud> <mode> <options>`, where `id` is the zero based port index, `baud` is a standard baud rate, mode is `rx`, `tx`, or both (`rxtx`), and options is a short string like `8N1` or `8E2` |
| `servo` | Configure servos |
| `set` | Change setting with name=value or blank or * for list |
| `smix` | Custom servo mixer |
| `status` | Show status. Error codes can be looked up [here](https://github.com/iNavFlight/inav/wiki/%22Something%22-is-disabled----Reasons) |
| `tasks` | Show task stats |
| `temp_sensor` | List or configure temperature sensor(s). See [temperature sensors documentation](Temperature-sensors.md) for more information. |
| `timer_output_mode` | Override automatic timer / pwm function allocation. [Additional Information](#timer_outout_mode)|
| `version` | Show version |
| `wp` | List or configure waypoints. See the [navigation documentation](Navigation.md#cli-command-wp-to-manage-waypoints). |
Notes:
* Available commands depend upon hardware specific and debug build options. Not all commands are available in every FC.
* The above list shows the output available in the CLI `help` command. This may also show additional information.
### serial
The syntax of the `serial` command is `serial <id> <function_value> <msp-baudrate> <gps-baudrate> <telemetry-baudate> <peripheral-baudrate>`.
A shorter form is also supported to enable and disable a single function using `serial <id> +n` and `serial <id> -n`, where n is the a serial function identifier. The following values are available:
| Function | Bit Identifier | Numeric value |
|-----------------------|---------------|----------------|
| MSP | 0 | 1 |
| GPS | 1 | 2 |
| TELEMETRY_FRSKY | 2 | 4 |
| TELEMETRY_HOTT | 3 | 8 |
| TELEMETRY_LTM | 4 | 16 |
| TELEMETRY_SMARTPORT | 5 | 32 |
| RX_SERIAL | 6 | 64 |
| BLACKBOX | 7 | 128 |
| TELEMETRY_MAVLINK | 8 | 256 |
| TELEMETRY_IBUS | 9 | 512 |
| RCDEVICE | 10 | 1024 |
| VTX_SMARTAUDIO | 11 | 2048 |
| VTX_TRAMP | 12 | 4096 |
| UAV_INTERCONNECT | 13 | 8192 |
| OPTICAL_FLOW | 14 | 16384 |
| LOG | 15 | 32768 |
| RANGEFINDER | 16 | 65536 |
| VTX_FFPV | 17 | 131072 |
| ESCSERIAL | 18 | 262144 |
| TELEMETRY_SIM | 19 | 524288 |
| FRSKY_OSD | 20 | 1048576 |
| DJI_HD_OSD | 21 | 2097152 |
| SERVO_SERIAL | 22 | 4194304 |
| TELEMETRY_SMARTPORT_MASTER | 23 | 8388608 |
| UNUSED | 24 | 16777216 |
| MSP_DISPLAYPORT | 25 | 33554432 |
| GIMBAL_SERIAL | 26 | 67108864 |
| HEADTRACKER_SERIAL | 27 | 134217728 |
Thus, to enable MSP and LTM on a port, one would use the function **value** of 17 (1 << 0)+(1<<4), aka 1+16, aka 17.
```
serial 0 17 57600 57600 57600 57600
```
but to remove LTM using the +/- shorthand, use the **bit Id** (4, TELEMETRY_LTM):
```
serial 0 -4
```
`serial` can also be used without any argument to print the current configuration of all the serial ports.
### `timer_output_mode`
Since INAV 7, the firmware can dynamically allocate servo and motor outputs. This removes the need for bespoke targets for special cases (e.g. `MATEKF405` and `MATEKF405_SERVOS6`).
#### Syntax
```
timer_output_mode [timer [function]]
```
where:
* Without parameters, lists the current timers and modes
* With just a `timer` lists the mode for that timer
* With both `timer` and `function`, sets the function for that timers
Note:
* `timer` identifies the timer **index** (from 0); thus is one less than the corresponding `TIMn` definition in a target's `target.c`.
* The function is one of `AUTO` (the default), `MOTORS` or `SERVOS`.
Motors are allocated first, hence having a servo before a motor may require use of `timer_output_mode`.
#### Example
The original `MATEKF405` target defined a multi-rotor (MR) servo on output S1. The later `MATEKF405_SERVOS6` target defined (for MR) S1 as a motor and S6 as a servo. This was more logical, but annoying for anyone who had a legacy `MATEKF405` tricopter with the servo on S1.
#### Solution
There is now a single `MATEKF405` target. The `target.c` sets the relevant outputs as:
```
DEF_TIM(TIM3, CH1, PC6, TIM_USE_OUTPUT_AUTO, 0, 0), // S1
DEF_TIM(TIM8, CH2, PC7, TIM_USE_OUTPUT_AUTO, 0, 1), // S2 UP(2,1)
DEF_TIM(TIM8, CH3, PC8, TIM_USE_OUTPUT_AUTO, 0, 1), // S3 UP(2,1)
DEF_TIM(TIM8, CH4, PC9, TIM_USE_OUTPUT_AUTO, 0, 0), // S4 UP(2,1)
DEF_TIM(TIM2, CH1, PA15, TIM_USE_MC_MOTOR | TIM_USE_LED, 0, 0), // S5 UP(1,7)
DEF_TIM(TIM1, CH1, PA8, TIM_USE_OUTPUT_AUTO, 0, 0), // S6 UP(2,5)
DEF_TIM(TIM4, CH3, PB8, TIM_USE_OUTPUT_AUTO, 0, 0), // S7 D(1,7)!S5 UP(2,6)
```
Using the "motors first" allocation, the servo would end up on S6, which in the legacy "tricopter servo on S1" case is not desired.
Forcing the S1 output (`TIM3`) to servo is achieved by:
```
timer_output_mode 2 SERVOS
```
with resulting `resource` output:
```
C06: SERVO4 OUT
C07: MOTOR1 OUT
C08: MOTOR2 OUT
C09: MOTOR3 OUT
```
Note that the `timer` **index** in the `timer_output_mode` line is one less than the mnemonic in `target.c`, `timer` of 2 for `TIM3`.
Note that the usual caveat that one should not share a timer with both a motor and a servo still apply.
## Flash chip management
For targets that have a flash data chip, typically used for blackbox logs, the following additional comamnds are provided.
| Command | Effect |
| ------- | ------ |
| `flash_erase` | Erases the flash chip |
| `flash_info` | Displays flash chip information (used, free etc.) |
| `flash_read <length> <address>` | Reads `length` bytes from `address` |
| `flash_write <address> <data>` | Writes `data` to `address` |
## CLI Variable Reference
See [Settings.md](Settings.md).
docs/Configuration.md
+35
View File
@@ -0,0 +1,35 @@
# Configuration
INAV is configured primarily using the INAV Configurator GUI.
Both the command line interface and GUI are accessible by connecting to a serial port on the target,
be it a USB virtual serial port, physical hardware UART port or a SoftSerial port.
See the Serial section for more information and see the Board specific sections for details of the serial ports available on the board you are using.
The GUI cannot currently configure all aspects of the system, the CLI must be used to enable or configure
some features and settings.
__The INAV Configurator now (versions after 9.0.x) automatically backs up your settings before flashing firmware and can restore them afterwards (when Full Chip Erase is enabled), including automatic migration across major versions. For details, see [Backup and Restore](Backup%20and%20Restore.md). You can also manually backup and restore settings using the [CLI](Cli.md#backup-via-cli).__
## GUI
![INAV Gui](Screenshots/cleanflight-gui.png)
The GUI tool is the preferred way of configuration. The GUI tool also includes a terminal which
can be used to interact with the CLI.
[INAV Configurator on Chrome store](https://chrome.google.com/webstore/detail/inav-configurator/fmaidjmgkdkpafmbnmigkpdnpdhopgel)
If you cannot use the latest version of the GUI to access the FC due to firmware compatibility issues you can still access the FC via the CLI to backup your settings, or you can install an old version of the configurator.
Old versions of the configurator can be downloaded from the configurator releases page: https://github.com/iNavFlight/inav-configurator/releases
See the README file that comes with the configurator for installation instructions.
## CLI
INAV can also be configured by a command line interface.
See the CLI section of the documentation for more details.
docs/Control Profiles.md
+170
View File
@@ -0,0 +1,170 @@
# Control Profiles
A profile is a set of configuration settings.
Currently, INAV gives you three control profiles. The default control profile is `1`.
## Changing control profiles
### Stick Commands
Control profiles can be selected using a GUI or the following stick combinations:
| Profile # | Throttle | Yaw | Pitch | Roll |
| -------- | -------- | ----- | ------ | ------ |
| 1 | Down | Left | Middle | Left |
| 2 | Down | Left | Up | Middle |
| 3 | Down | Left | Middle | Right |
### CLI
The CLI `control_profile` command can also be used to change control profiles:
```
control_profile <index>
```
### Programming (4.0.0 onwards)
You can change control profiles using the programming frame work. This allows a lot of flexability in how you change profiles.
For example, using a simple switch on channel 15.
[![For example, using a simple switch](https://i.imgur.com/SS9CaaOl.png)](https://i.imgur.com/SS9CaaO.png)
Or using the speed to change control profiles. In this example:
- when lower than 25 cm/s (basically not flying), control profiles are not effected.
- Below 2682 cm/s (60 mph | 97 Km/h) use control profile 1
- Above 5364 cm/s (120 mph | 193 Km/h) use control profile 3
- Between 2683 and 5364 cm/s, use control profile 2
[![Using speed to change profiles](https://i.imgur.com/WjkuhhWl.png)](https://i.imgur.com/WjkuhhW.png)
> [!NOTE]
> From INAV 8.0, the programming framework operator is **Set Control Profile** and the **Flight** Operand is **Active Control Profile**. Pre-INAV 8.0, they were **Set Profile** and **Active Profile** respectively.
#### Configurator use with control profile changing logic.
If you have logic conditions that change the profiles. You may find that if you manually change the control profile; using the drop down boxes in the top right of Configurator. That they switch back to a different control profile. This is because the logic conditions are still running in the background. If this is the case, the simplest solutuion is to temporarily disable the switches that trigger the `Set Control Profile` operations. Remember to re-enable these switches after you have made your changes.
[![Disabled SET PROFILE switches](https://i.imgur.com/AeH9ll7l.png)](https://i.imgur.com/AeH9ll7.png)
## Profile Contents
The values contained within a control profile can be seen by using the CLI `dump control_profile` command.
e.g
```
# dump control_profile
# control_profile
control_profile 1
set mc_p_pitch = 40
set mc_i_pitch = 30
set mc_d_pitch = 23
set mc_cd_pitch = 60
set mc_p_roll = 40
set mc_i_roll = 30
set mc_d_roll = 23
set mc_cd_roll = 60
set mc_p_yaw = 85
set mc_i_yaw = 45
set mc_d_yaw = 0
set mc_cd_yaw = 60
set mc_p_level = 20
set mc_i_level = 15
set mc_d_level = 75
set fw_p_pitch = 5
set fw_i_pitch = 7
set fw_d_pitch = 0
set fw_ff_pitch = 50
set fw_p_roll = 5
set fw_i_roll = 7
set fw_d_roll = 0
set fw_ff_roll = 50
set fw_p_yaw = 6
set fw_i_yaw = 10
set fw_d_yaw = 0
set fw_ff_yaw = 60
set fw_p_level = 20
set fw_i_level = 5
set fw_d_level = 75
set max_angle_inclination_rll = 300
set max_angle_inclination_pit = 300
set dterm_lpf_hz = 110
set dterm_lpf_type = PT2
set yaw_lpf_hz = 0
set fw_iterm_throw_limit = 165
set fw_loiter_direction = RIGHT
set fw_reference_airspeed = 1500.000
set fw_turn_assist_yaw_gain = 1.000
set fw_turn_assist_pitch_gain = 1.000
set fw_iterm_limit_stick_position = 0.500
set fw_yaw_iterm_freeze_bank_angle = 0
set pidsum_limit = 500
set pidsum_limit_yaw = 350
set iterm_windup = 50
set rate_accel_limit_roll_pitch = 0
set rate_accel_limit_yaw = 10000
set heading_hold_rate_limit = 90
set nav_mc_pos_z_p = 50
set nav_mc_vel_z_p = 100
set nav_mc_vel_z_i = 50
set nav_mc_vel_z_d = 10
set nav_mc_pos_xy_p = 65
set nav_mc_vel_xy_p = 40
set nav_mc_vel_xy_i = 15
set nav_mc_vel_xy_d = 100
set nav_mc_vel_xy_ff = 40
set nav_mc_heading_p = 60
set nav_mc_vel_xy_dterm_lpf_hz = 2.000
set nav_mc_vel_xy_dterm_attenuation = 90
set nav_mc_vel_xy_dterm_attenuation_start = 10
set nav_mc_vel_xy_dterm_attenuation_end = 60
set nav_fw_pos_z_p = 40
set nav_fw_pos_z_i = 5
set nav_fw_pos_z_d = 10
set nav_fw_pos_xy_p = 75
set nav_fw_pos_xy_i = 5
set nav_fw_pos_xy_d = 8
set nav_fw_heading_p = 60
set nav_fw_pos_hdg_p = 30
set nav_fw_pos_hdg_i = 2
set nav_fw_pos_hdg_d = 0
set nav_fw_pos_hdg_pidsum_limit = 350
set mc_iterm_relax = RP
set mc_iterm_relax_cutoff = 15
set d_boost_min = 0.500
set d_boost_max = 1.250
set d_boost_max_at_acceleration = 7500.000
set d_boost_gyro_delta_lpf_hz = 80
set antigravity_gain = 1.000
set antigravity_accelerator = 1.000
set antigravity_cutoff_lpf_hz = 15
set pid_type = AUTO
set mc_cd_lpf_hz = 30
set fw_level_pitch_trim = 0.000
set smith_predictor_strength = 0.500
set smith_predictor_delay = 0.000
set smith_predictor_lpf_hz = 50
set fw_level_pitch_gain = 5.000
set thr_mid = 50
set thr_expo = 0
set tpa_rate = 0
set tpa_breakpoint = 1500
set fw_tpa_time_constant = 0
set rc_expo = 70
set rc_yaw_expo = 20
set roll_rate = 20
set pitch_rate = 20
set yaw_rate = 20
set manual_rc_expo = 70
set manual_rc_yaw_expo = 20
set manual_roll_rate = 100
set manual_pitch_rate = 100
set manual_yaw_rate = 100
set fpv_mix_degrees = 0
set rate_dynamics_center_sensitivity = 100
set rate_dynamics_end_sensitivity = 100
set rate_dynamics_center_correction = 10
set rate_dynamics_end_correction = 10
set rate_dynamics_center_weight = 0
set rate_dynamics_end_weight = 0
```
docs/Controls.md
+116
View File
@@ -0,0 +1,116 @@
# Controls
## Arming
When armed, the aircraft is ready to fly and the motors will spin when throttle is applied. With multirotors, the motors will spin at a slow speed when armed (this feature may be disabled by setting MOTOR_STOP, but for safety reasons, that is not recommended).
Arming and disarming is done using a switch, set up on the modes page. (NOTE: Stick arming was removed in INAV 2.2)
**YAW STICK ARMING OVERRIDE:**
Arming is disabled when Nav modes are configured and no GPS lock is available or if a WP mission is loaded but the first WP is farther than the `nav_wp_safe_distance` setting. This Arming block can be bypassed if need be by setting `nav_extra_arming_safety` to `ALLOW_BYPASS` and moving the Yaw stick to the high position when the Arm switch is used. This bypasses GPS Arm blocking pre INAV 4.0.0 and both GPS and "First WP too far" Arm blocking from INAV 4.0.0.
## Stick Positions
The three stick positions are:
|Position | Approx. Channel Input|
|----------------|----------------------|
|LOW | 1000 |
|CENTER | 1500 |
|HIGH | 2000 |
The stick positions are combined to activate different functions:
| Function | Throttle | Yaw | Pitch | Roll |
| ----------------------------- | -------- | ------- | ------ | ------ |
| Control Profile 1 | LOW | LOW | CENTER | LOW |
| Control Profile 2 | LOW | LOW | HIGH | CENTER |
| Control Profile 3 | LOW | LOW | CENTER | HIGH |
| Battery profile 1 | HIGH | LOW | CENTER | LOW |
| Battery profile 2 | HIGH | LOW | HIGH | CENTER |
| Battery profile 3 | HIGH | LOW | CENTER | HIGH |
| Calibrate Gyro | LOW | LOW | LOW | CENTER |
| Calibrate Acc | HIGH | LOW | LOW | CENTER |
| Calibrate Compass/Zero Yaw | HIGH | HIGH | LOW | CENTER |
| Trim Acc Left | HIGH | CENTER | CENTER | LOW |
| Trim Acc Right | HIGH | CENTER | CENTER | HIGH |
| Trim Acc Forwards | HIGH | CENTER | HIGH | CENTER |
| Trim Acc Backwards | HIGH | CENTER | LOW | CENTER |
| Save current waypoint mission | LOW | CENTER | HIGH | LOW |
| Load current waypoint mission | LOW | CENTER | HIGH | HIGH |
| Unload waypoint mission | LOW | CENTER | LOW | HIGH |
| Increase WP mission index | LOW | CENTER | CENTER | HIGH |
| Decrease WP mission index | LOW | CENTER | CENTER | LOW |
| Bypass Nav Arm disable | LOW | HIGH | CENTER | CENTER |
| Save setting | LOW | LOW | LOW | HIGH |
| Enter OSD Menu (CMS) | CENTER | LOW | HIGH | CENTER |
| Enter Camera OSD(RuncamDevice)| CENTER | HIGH | CENTER | CENTER |
| Exit Camera OSD (RuncamDevice)| CENTER | LOW | CENTER | CENTER |
| Confirm - Camera OSD | CENTER | HIGH | CENTER | CENTER |
| Navigation - Camera OSD | CENTER | CENTER | * | * |
For graphical stick position in all transmitter modes, check out [this page](https://www.mrd-rc.com/tutorials-tools-and-testing/inav-flight/inav-stick-commands-for-all-transmitter-modes/).
![Stick Positions](assets/images/StickPositions.png)
## Compass Calibration and Yaw Zero Reset
The stick function `Calibrate Compass/Zero Yaw` provides 2 functions depending on whether or not a compass is available.
If a compass is available the stick function initiates the compass calibration routine.
If no compass is available the stick function will reset the current yaw/heading estimate to zero (North) and also set the heading as trusted. This is useful on multirotors, allowing the craft yaw/heading to be correctly aligned to actual North simply by physically pointing the craft North then using the stick function to zero the yaw estimate. Since this also sets the heading as trusted Nav modes reliant on heading will be available immediately after arming without the need to fly fast enough to obtain a valid heading from GPS ground course.
## Yaw control
While arming/disarming with sticks, your yaw stick will be moving to extreme values. In order to prevent your craft from trying to yaw during arming/disarming while on the ground, your yaw input will not cause the craft to yaw when the throttle is LOW (i.e. below the `min_check` setting).
For tricopters, you may want to retain the ability to yaw while on the ground, so that you can verify that your tail servo is working correctly before takeoff. You can do this by setting `tri_unarmed_servo` to `1` on the CLI (this is the default). If you are having issues with your tail rotor contacting the ground during arm/disarm, you can set this to `0` instead. Check this table to decide which setting will suit you:
<table>
<tr>
<th colspan="5">Is yaw control of the tricopter allowed?</th>
</tr>
<tr>
<th></th><th colspan="2">Disarmed</th><th colspan="2">Armed</th>
</tr>
<tr>
<th></th><th>Throttle low</th><th>Throttle normal</th><th>Throttle low</th><th>Throttle normal</th>
</tr>
<tr>
<td rowspan="2">tri_unarmed_servo = 0</td><td>No</td><td>No</td><td>No</td><td>Yes</td>
</tr>
<tr>
<td>No</td><td>No</td><td>No</td><td>Yes</td>
</tr>
<tr>
<td rowspan="2">tri_unarmed_servo = 1</td><td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td>
</tr>
<tr>
<td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td>
</tr>
</table>
## Throttle settings and their interaction
*Terminology. After INAV 2.3, the setting `min_throttle` was replaced with `throttle_idle` which is more appropriate to modern hardware. In this document `min_throttle` may be taken as either the older `min_throttle` value, or the throttle value calculated from the modern `throttle_idle` setting. The way that `throttle_idle` generates a throttle value is described in `Cli.md`.*
`min_command` -
With motor stop enabled this is the command sent to the esc's when the throttle is below min_check or disarmed. With motor stop disabled, this is the command sent only when the copter is disarmed. This must be set well below motors spinning for safety.
`min_check` -
With switch arming mode is in use, lowering your throttle below min_check will result in motors spinning at `throttle_idle` (min_throttle). When using the default stick arming, lowering your throttle below min_check will result in motors spinning at min_throttle and yaw being disabled so that you may arm/disarm. With motor stop enabled, lowering your throttle below min_check will also result in motors off and the esc's being sent min_command. Min_check must be set to a level that is 100% reliably met by the throttle throw. A setting too low may result in a dangerous condition where the copter can’t be disarmed. It is ok to set this below `throttle_idle` (min_throttle) because the FC will automaticly scale the output to the ESCs
`throttle_idle` (previously `min_throttle)` -
Typically set to just above reliable spin up of all motors. Sometimes this is set slightly higher for prop stall prevention during advanced maneuvers or sometimes considerably higher to produce a desired result. When armed with motor stop off, your motors will spin at this command so keep that in mind from a safety stand point.
`max_check` -
Throttle positions above this level will send max_command to the ESCs.
`max_throttle` -
This is the max command to the ESCs from the flight controller.
In depth videos explaining these terms are available from Joshua Bardwell here:
https://www.youtube.com/watch?v=WFU3VewGbbA
https://www.youtube.com/watch?v=YNRl0OTKRGA
docs/DJI compatible OSD.md
+50
View File
@@ -0,0 +1,50 @@
# DJI compatible MSP DisplayPort OSD (DJI O3 "Canvas Mode")
INAV 6.0 includes a special mode for MSP DisplayPort that supports DJI's incomplete implementations of MSP DisplayPort. This can be found on products like the DJI O3 Air Unit. INAV 6.1 expands this to include HD canvas sizes from BetaFlight 4.4.
Different flight controller firmware have different OSD symbols and elements and require different fonts. BetaFlight's font is a single page and supports a maximum of 256 glyphs, INAV's font is currently 2 pages and supports up to 512 different glyphs. DJI's font is single page and based, but not the same as, BetaFlight's font.
While there is some overlap between the glyphs in DJI and INAV, it is not possible to perform a 1 to 1 mapping for all the them. In cases where there is no suitable glyph in the DJI font, a question mark `?` will be displayed.
This mode can be enabled by selecting DJI43COMPAT or DJIHDCOMPAT as video format in the OSD tab of the configurator or by typing the following command on the CLI:
`set osd_video_system = DJI43COMPAT`
or
`set osd_video_system = DJIHDCOMPAT`
## Limitations
* Canvas size needs to be manually changed to HD on the Display menu in DJI's goggles (you may need a firmware update) and set as DJIHDCOMPAT in the OSD tab of the configurator.
* Unsupported Glyphs show up as `?`
## FAQ
### I see a lot of `?` on my OSD.
That is expected. When your INAV OSD widgets use glyphs that don't have a suitable mapping in DJI's font.
### Does it work with the G2 and Original Air Unit/Vista?
Yes.
### Is this a replacement for WTFOS?
Not exactly. WTFOS is a full implementation of MSP-Displayport for rooted Air Unit/Vista/Googles V2 and actually works much better than DJI compatibility mode. It can use all of INAV's OSD elements as intended. If you have the option of WTFOS or DJI compatability mode. WTFOS is the best option.
### Can INAV fix DJI's product?
No. OSD renderinng happens on the googles/air unit side of things. Please ask DJI to fix their incomplete MSP DisplayPort implemenation. You can probably request it in [DJI's forum](https://forum.dji.com/forum.php?mod=forumdisplay&fid=129&filter=typeid&typeid=767). To see what you're missing out on with O3. Check out what WTFOS did with the original system. Not only could the pilots upload the fonts of their choosing (who doesn't want a cool SneakyFPV font on their OSD). But there were no problems supporting and firmware. Plus, there was even an option to save the OSD to a file and overlay that over your DVR video. If you're reading this far. Please recommend to DJI that they fix their product, to at least what was possible with WTFOS.
### DJI's font now has more symbols, can you update INAV?
Maybe. If a future version of DJI's font includes more Glyphs that can be mapped into INAV. It is fairly simple to add the mapping. However, the best solution would be full support of MSP DisplayPort by DJI. Then there will never be an issue with missing icons. As the latest INAV font would be able to be uploaded on to the goggles.
### Can you replace glyph `X` with text `x description`?
While it might technically be possible to replace some glyphs with text in multiple cells, it will introduce a lot of complexity in the OSD rendering and configuration for something we hope is a temporary workaround.
### Does DJI support Canvas Mode?
Actually, no. What DJI calls Canvas Mode is actually MSP DisplayPort and is a character based OSD. Currently, the only true implementaion of Canvas Mode is with FrSKY PixelOSD. This was found on some F722 flight controllers from Matek.
docs/Display.md
Executable
+79
View File
@@ -0,0 +1,79 @@
# Display
INAV supports displays to provide information to you about your aircraft and INAV state.
When the aircraft is armed, an "Armed" message is displayed. When it is disarmed, a summary page is displayed. Page cycling has been removed and no other information is currently available
![Stick Positions](assets/images/inav_display_armed.jpg)
![Stick Positions](assets/images/inav_display_status.jpg)
There is currently no way to change the information on the display
## Supported Hardware
I2c IIC Serial Oled LCD LED Module 12864 (<a href="http://a.co/5hxXEvZ">http://a.co/5hxXEvZ</a> used in status image above)
SSD1306
UG-2864HSWEG01
## Configuration
From the CLI enable the `DASHBOARD` feature
```
feature DASHBOARD
```
### SSD1306 OLED displays
The SSD1306 display is a 128x64 OLED display that is visible in full sunlight, small and consumes very little current.
This makes it ideal for aircraft use.
There are various models of SSD1306 boards out there, they are not all equal and some require addtional modifications
before they work. Choose wisely!
Links to displays:
* [banggood.com](https://inavflight.com/shop/s/bg/958196) 0.96 Inch 4Pin White IIC I2C OLED Display Module 12864 LED For Arduino
* [banggood.com](https://inavflight.com/shop/s/bg/969147) 0.96 Inch 4Pin IIC I2C Blue OLED Display Module For Arduino
* [wide.hk](http://www.wide.hk/products.php?product=I2C-0.96%22-OLED-display-module-%28-compatible-Arduino-%29) I2C 0.96" OLED display module
* [witespyquad.gostorego.com](http://witespyquad.gostorego.com/accessories/readytofly-1-oled-128x64-pid-tuning-display-i2c.html) ReadyToFlyQuads 1" OLED Display
* [multiwiicopter.com](http://www.multiwiicopter.com/products/1-oled) PARIS 1" OLED 128x64 PID tuning screen AIR
The banggood.com display is the cheapest at the time of writing and will correctly send I2C ACK signals.
### SSD1315 OLED displays
SSD1315 is newer generation drop in replacement for SSD1306. Tested and working unit is bought from https://www.aliexpress.com/item/1005006901360788.html
#### Crius CO-16
This display is best avoided but will work if you modify it.
Step 1
As supplied the I2C ack signal is not sent because the manufacturer did not bridge D1 and D2 together. To fix this solder
the two pins together as they enter the screen. Failure to do this will result is a screen that doesn't display anything.
Step 2
Pin 14 must be disconnected from the main board using a scalpel. Then connect a 10nF or 100nF capacitor between pins 30 and the
lifted pin 14.
Step 3
Connect a 100K resistor between Pin 9 and the lifted Pin 14.
Failure to perform steps 2 and 3 will result in a display that only works on power up some of the time any may display random dots
or other display corruption.
More can be read about this procedure here: http://www.multiwii.com/forum/viewtopic.php?f=6&t=2705&start=10
![Crius CO-16 Diagram](Wiring/Crius CO-16 OLED diagram.png)
![Crius CO-16 Modification](Wiring/Crius CO-16 OLED modifications.jpg)
## Connections
Connect +5v, Ground, I2C SDA and I2C SCL from the flight controller to the display.
docs/ESC and servo outputs.md
+35
View File
@@ -0,0 +1,35 @@
# ESC and servo outputs
## ESC protocols
INAV support the following ESC protocols:
* "standard" PWM with 50-400Hz update rate
* OneShot125
* OneShot42
* Multishot
* Brushed motors
* DSHOT150, DSHOT300, DSHOT600
ESC protocol can be selected in Configurator. No special configuration is required.
Check the ESC documentation for the list of protocols that are supported.
## Servo outputs
By default, INAV uses 50Hz servo update rate. If you want to increase it, make sure that servos support
higher update rates. Only high end digital servos are capable of handling 200Hz and above!
## Servo output mapping
Not all outputs on a flight controller can be used for servo outputs. It is a hardware thing. Always check flight controller documentation.
While motors are usually ordered sequentially, here is no standard output layout for servos! Some boards might not be supporting servos in _Multirotor_ configuration at all!
## Modifying output mapping
INAV 7 introduced extra functionality that let you force only some outputs to be either *MOTORS* or *SERVOS*, with some restrictions dictated by the hardware.
The main restrictions is that outputs are associated with timers, which can be shared between multiple outputs and two outputs on the same timer need to have the same function.
The easiest way to modify outputs, is to use the Mixer tab in the Configurator, as it will clearly show you which timer is used by all outputs, but you can also use `timer_output_mode` on the cli.
docs/Failsafe.md
+151
View File
@@ -0,0 +1,151 @@
# Failsafe
Failsafe is a state the flight controller is meant to enter when the radio receiver loses the RC link. Any of these of these conditions will trigger it:
* Any flight channel (pitch, roll, throttle or yaw) sends no pulses
* Any channel is outside the valid range between `rx_min_usec` and `rx_max_usec`
* The FAILSAFE aux mode is activated
If the failsafe happens while the flight controller is disarmed, it only prevent arming. If it happens while armed, the failsafe policy configured in `failsafe_procedure` is engaged. The available procedures are:
* __DROP:__ Just kill the motors and disarm (crash the craft).
* __LAND:__ (replaces **SET-THR** from INAV 4.0) Performs an Emergency Landing. Enables auto-level mode (for multirotor) or enters a preconfigured roll/pitch/yaw spiral down (for airplanes). If altitude sensors are working an actively controlled descent is performed using the Emergency Landing descent speed (`nav_emerg_landing_speed`). If altitude sensors are unavailable descent is performed with the throttle set to a predefined value (`failsafe_throttle`). The descent can be limited to a predefined time (`failsafe_off_delay`) after which the craft disarms. This is meant to get the craft to a safe-ish landing (or more realistically, a controlled crash). Other than using altitude sensors for an actively controlled descent it doesn't require any extra sensors other than basic gyros and accelerometers.
* __SET-THR:__ (Pre INAV 4.0) Same as **LAND** except it doesn't use an Emergency Landing but is limited instead to just setting the throttle to a predefined value (`failsafe_throttle`) to perform a descent. It doesn't require any extra sensors other than basic gyros and accelerometers.
* __RTH:__ (Return To Home) One of the key features of INAV, it automatically navigates the craft back to the home position and (optionally) lands it. Similarly to all other automated navigation methods, it requires GPS for any type of craft, plus compass and barometer for multicopters.
* __NONE:__ Do nothing. This is meant to let the craft perform a fully automated flight (eg. waypoint flight) outside of radio range. Highly unsafe when used with manual flight.
Note that:
* Should the failsafe disarm the flight controller (**DROP**, **LAND/SET-THR** after `failsafe_off_delay` or **RTH** with `nav_disarm_on_landing` ON), the flight controller will be disarmed and re-arming will be locked until the signal from the receiver is restored for 30 seconds AND the arming switch is in the OFF position (when an arm switch is in use).
* Prior to starting failsafe it is checked if the throttle position has been below `min_throttle` for the last `failsafe_throttle_low_delay` seconds. If it was, the craft is assumed to be on the ground and is simply disarmed. This feature can be disabled completely by setting `failsafe_throttle_low_delay` to zero, which may be necessary to do if the craft may fly long with zero throttle (eg. gliders).
## Notes about safety
* If the craft is landed but armed, the failsafe may make the motors and props spin again and even make the craft take off (in case of **RTH** failsafe). Take expecially care of this when using `MOTOR_STOP` feature. **Props will spin up without warning**. Have a look at the `failsafe_throttle_low_delay` setting explained above to learn when this could happen.
* If any required navigation sensor becomes unavailable during a Return to Home (eg. loss of GPS fix), an emergency landing, as used by the **LAND** procedure, will be performed after a short timeout. An emergency landing would also be performed right when the failsafe is triggered if any required sensor is reported as unavailable.
* The **SET-THR** procedure doesn't control descent in any way other than setting a fixed throttle. This is also the case for the **LAND** procedure when altitude sensors are unavailable. Thus, appropriate testing must be performed to find the right throttle value. Consider that a constant throttle setting will yield different thrusts depending on battery voltage, so when you evaluate the throttle value do it with a loaded battery. Failure to do so may cause a flyaway.
* When the failsafe mode is aborted (RC signal restored/failsafe switch set to OFF), the current stick positions will be enforced immediately. Be ready to react quickly.
## RX configuration
In order to engage failsafe mode correctly, you must configure your receiver to do one of the following on signal loss:
* Send no signal/pulses over the channels
* Send an invalid signal over the channels (for example, send values lower than `rx_min_usec`)
* Set an aux channel to engage FAILSAFE mode.
and
* Ensure your receiver does not set any aux channel so that the craft would disarm.
## Failsafe Settings
Failsafe delays are configured in 0.1 second units. Distances are in centimeters (1/100 of a meter).
### Parameters relevant to all failsafe procedures
#### `failsafe_procedure`
Selects the failsafe procedure. Valid procedures are **DROP**, **LAND/SET-THR**, **RTH** and **NONE**. See above for a description of each one.
#### `failsafe_delay`
Guard time for failsafe activation when rx channel data is lost or invalid. This is the amount of time the flight controller waits to see if it begins receiving a valid signal again before activating failsafe. Does not apply when activating the FAILSAFE aux mode.
#### `failsafe_recovery_delay`
Guard time for failsafe de-activation after signal is recovered. This is the amount of time the flight controller waits to see if the signal is consistent before turning off failsafe procedure. Usefull to avoid swithing in and out of failsafe RTH. Does not apply when disactivating the FAILSAFE aux mode.
#### `failsafe_stick_threshold`
This parameter defines recovery from failsafe by stick motion. When set to zero failsafe procedure will be cleared as soon as RC link is recovered. When this is set to a non-zero value - failsafe won't clear immediately when if RC link is recovered, you will have to move any of Roll/Pitch/Yaw sticks more than this value to exit failsafe.
The use-case is the Return To Home failsafe: when on the edge of radio coverage you may end up entering and exiting failsafe if radio link is sporadic - happens a lot with long-range pilots. Setting `failsafe_stick_threshold` to a certain value (i.e. 100) RTH will be initiated on first signal loss and will continue as long as pilots want it to continue. When RC link is solid (based on RSSI etc) pilot will move sticks and regain control.
#### `failsafe_throttle_low_delay`
Time throttle level must have been below 'min_throttle' to _only disarm_ instead of _full failsafe procedure_. Set to zero to disable.
#### `failsafe_min_distance`
If failsafe happens when craft is closer than this distance in centimeters from home, failsafe will not execute regular failsafe_procedure, but will execute procedure specified in failsafe_min_distance_procedure instead. 0 = Normal failsafe_procedure always taken.
#### `failsafe_min_distance_procedure`
What failsafe procedure to initiate in Stage 2 when craft is closer to home than failsafe_min_distance.
#### `rx_min_usec`
The lowest channel value considered valid.
#### `rx_max_usec`
The highest channel value considered valid.
### Parameters relevant to **RTH** failsafe procedure
#### `nav_min_rth_distance`
If the failsafe happens while the craft is within this distance from the home position, the home position is considered immediately reached.
#### `nav_rth_climb_first`
If ON the craft rises to `nav_rth_altitude` before heading to home position. if OFF the craft climbs on the way to home position.
#### `nav_rth_climb_ignore_emerg`
When this option is OFF (default) and when you initiate RTH without GPS fix - aircraft will initiate emergency descent and go down. If you set this option to ON - aircraft will reach the RTH target altitude before initiating emergency descent. This is done for cases where GPS coverage is poor (i.e. in the mountains) - allowing UAV to climb up might improve GPS coverage and allow safe return instead of landing in a place where UAV might be impossible to recover.
#### `nav_rth_tail_first`
Only relevant for multirotors. If this is OFF the craft will head to home position head first, if ON it'll be tail first
#### `nav_rth_altitude`
The altitude used as reference for the RTH procedure.
#### `nav_rth_alt_mode`
How and when to reach `nav_rth_altitude`. Please read [the page on the wiki](https://github.com/iNavFlight/inav/wiki/Navigation-modes#rth-altitude-control-modes) for a description of the available modes.
#### `nav_rth_abort_threshold`
If the craft increases its distance from the point the failsafe was triggered first by this amount, RTH procedure is aborted and an emergency landing is initiated. It's meant to avoid flyaways due to navigation issues, like strong winds.
#### `nav_rth_allow_landing`
Enables landing when home position is reached. If OFF the craft will hover indefinitely over the home position.
#### `nav_disarm_on_landing`
Instructs the flight controller to disarm the craft when landing is detected
### Parameters relevant to **LAND/SET-THR** failsafe procedure
#### `failsafe_off_delay`
Delay after failsafe activates before motors finally turn off. This is the amount of time 'failsafe_throttle' is active. If you fly at higher altitudes you may need more time to descend safely. Set to zero to keep `failsafe_throttle` active indefinitely.
#### `nav_emerg_landing_speed`
(**LAND** only) Actively controlled descent speed when altitude sensors are available. If altitude sensors aren't available landing descent falls back to using the fixed thottle setting `failsafe_throttle` so ensure this is also set correctly.
#### `failsafe_throttle`
Throttle level used for landing. Specify a value that causes the aircraft to descend at about 1M/sec. Default is set to 1000 which should correspond to throttle off.
#### `failsafe_fw_roll_angle`
This parameter defines the amount of roll angle (in 1/10 deg units) to execute on failsafe. Negative = LEFT
#### `failsafe_fw_pitch_angle`
This parameter defines the amount of pitch angle (in 1/10 deg units) to execute on failsafe for an airplane. Negative = CLIMB
#### `failsafe_fw_yaw_rate`
This parameter defines the amount of yaw rate (in deg per second units) to execute on failsafe for an airplane. Negative = LEFT
docs/Fixed Wing Landing.md
+119
View File
@@ -0,0 +1,119 @@
# Fixed Wing Landing
## Introducion
INAV supports advanced automatic landings for fixed wing aircraft from version 7.1.
The procedure is based on landings for man-carrying aircraft, so that safe landings at a specific location are possible.
Supported are landings at Safehome after "Return to Home" or at a defined LAND waypoint for missions.
Every landing locations can be defined with a target point and 2 different approach headings (colinear to the landing strips) with exclusive direction or opposite directions allowed.
This enables up to 4 different approach directions, based on the landing site and surrounding area.
## General procedure:
1. After reaching Safehome/LAND Waypoint the altitude is corrected to "Approach Altitude".
2. The aircraft circles for at least 30 seconds to determine the wind direction and strength.
3. The landing direction and the approach waypoints are calculated on the basis of the measured wind parameters. If no headwind landing is possible or the wind strength is greater than "Max. tailwind" (see Global Parameters), return to point 2.
4. The landing is initiated. The aircraft flies the downwind course, "Approach Altitude" is held.
5. Base Leg: the altitude is reduced from 2/3 of "Approach Altitude".
6. Final Approach: The engine power is reduced using "Pitch2throttle modifier" to reduce speed and the altitude is gradually reduced towards "Land Altitude" while approaching the Safehome coordinates.
7. Glide: When "Glide Altitude" is reached, the motor is switched off and the pitch angle of "Glide Pitch" is held.
7. Flare: Only if a LIDAR/Rangefinder sensor is present: the motor remains switched off and the pitch angle of "Flare Pitch" is held
8. Landing: As soon as INAV has detected the landing, it is automatically disarmed, see setting `nav_disarm_on_landing`.
To activate the automatic landing, the parameter `nav_rth_allow_landing` must be set to `ALWAYS` or `FAILSAFE`.
> [!WARNING]
> If landing is activated and no parameters are set for the landing site (Safehome and/or landing waypoint), the old landing procedure (circling until close to the ground, then hovering out) is performed.
> This is probably not what you want.
The following graphics illustrate the process:
![Approach Drawing Up](/docs/assets/images/Approach-Drawing-Up.png "Approach Drawing Up")
![Approach Drawing Side](/docs/assets/images/Approach-Drawing-Side.png "Approach Drawing Side")
## Landing site parameters
### The following parameters are set for each landing site (Safefome/LAND waypoint):
All settings can also be conveniently made in the Configurator via Mission Control.
CLI command `fwapproach`:
`fwapproach <index> <Approach altitude> <Land altitude> <Approach direction> <approach heading 1> <approach heading 2> <sea level>`
`fwapproach` has 17 slots in which landing parameters can be stored. In slot 0-7 the landing parameters for Safehome are stored, in 8 - 16 the parameters for waypoint missions. Only one landing point per mission can be saved.
* index: 0 - 17, 0 - 7 Safehome, 8 - 16 Mission
* Approach direction: 0 - Left, 1 - Right. Always seen from the primary landing direction (positive value), i.e. whether the aircraft flies left or right turns on approach.
* Approach Altitude: Initial altitude of the approach, the altitude at which the wind direction is determined and the downwind approach, in cm
* Land Altitude: Altitude of the landing site, in cm
* Approach heading 1 and 2: Two landing directions can be set, values: 0 - +/-360. 0 = landing direction is deactivated.
A positive value means that you can approach in both directions, a negative value means that this direction is exclusive.
Example: 90 degrees: It is possible to land in 90 degrees as well as in 270 degrees. -90 means that you can only land in a 90 degree direction.
This means that practically 4 landing directions can be saved.
* Sea Level: 0 - Deactivated, 1 - Activated. If activated, approach and land altitude refer to normal zero (sea level), otherwise relative altitude to the altitude during first GPS fix.
> [!CAUTION]
> The Configuator automatically determines the ground altitude based on databases on the Internet, which may be inaccurate. Please always compare with the measured GPS altitude at the landing site to avoid crashes.
### Global parameters
All settings are available via “Advanced Tuning” in the Configurator.
* `nav_fw_land_approach_length`: Length of the final approach, measured from the land site (Safehome/Waypoint) to the last turning point.
In cm. Max: 100000, Min: 100, Default: 35000
* `nav_fw_land_final_approach_pitch2throttle_mod`: Modifier for pitch to throttle ratio at final approach. This parameter can be used to reduce speed during the final approach.
Example: If the parameter is set to 200% and Pitch To Throttle Ratio is set to 15, Pitch To Throttle Ratio is set to 30 on the final approach. This causes a reduction in engine power on approach when the nose is pointing downwards.
In Percent. Min: 100, Max: 400, Default: 100
* `nav_fw_land_glide_alt`: Initial altitude of the glide phase. The altitude refers to "Landing Altitude", see above under "Landing site parameters"
In cm. Min: 100, Max: 5000, Default: 200
* `nav_fw_land_flare_alt`: Initial altitude of the flare phase. The altitude refers to "Landing Altitude", see above under "Landing site parameters"
In cm. Min: 0, Max: 5000, Default: 200
* `nav_fw_land_glide_pitch`: Pitch value for glide phase.
In degrees. Min: 0, Max: 45, Default: 0
* `nav_fw_land_flare_pitch`: Pitch value for flare phase.
In degrees. Min: 0, Max: 45, Default: 8
* `nav_fw_land_max_tailwind`: Max. tailwind if no landing direction with downwind is available. Wind strengths below this value are ignored (error tolerance in the wind measurement). Landing then takes place in the main direction. If, for example, 90 degrees is configured, landing takes place in this direction, NOT in 270 degrees (see above).
In cm/s. Min: 0; Max: 3000, Default: 140
### General paramters and tuning tips
* `nav_fw_wp_tracking_accuracy`: Its highly recommended that this parameter is used and tuned well. Only with WP-Tracking enabled, the Aircraft will try to precisely align with the runway during approach.
If WP-Tracking is not used, the Plane will head straight to the landiung location without flying in line with the intended landing strip. Wind can intensively alter the final landing heading.
* `nav_fw_pitch2thr`: The navigation throttle modifier has to be tuned well to allow stable navigation during climbs and descents to prevent a stall. Make sure your plane maintains Ground or Airspeed, when climbing in any navigation mode.
The Craft should not get slower and not speed ub significantly during a navigation climb, if P2T is tuned properly.
* `nav_wp_radius`: This parameter might be too high if you have set up your craft with INAV 6 or INAV 7. With a too high value, the turning points for the Crosswind-Leg and Final Approach are hit too early and make it difficult for the plane to align to the runway or cut short the approach.
Make sure this parameter is not set greater than 1000 (cm). The better your craft and navigation system is tuned, the lower this value can be. We recommend to start with 1000 for flying wings and 800 for a Plane with Tail.
* Test your Navigation-Tuning: A better Navigation-Tune will reward you with smoother and more reliable landings. To test your nav systems limit, we recommend to create a waypoint missions with many 90° turn angles with shorter and shorter tracks.
With this Method, you can find out how well your plane can follow a navigation path and how long it takes to align to a waypoint track. A well tuned plane should be able to pull of a WP Mission that looks like this, where the distance between WP6 and WP7 si recommended to be the minimum approach length:
![Test Waypoint Track](https://github.com/iNavFlight/inav/assets/33039058/a929cd0c-80b1-42d6-815d-89a90e9daa1b)
## Waypoint missions
Only one landing waypoint per mission can be active and saved and the landing waypoint must be the last waypoint of the mission.
If the altitude of the waypoint and the "Approach Altitude" are different, the altitude of the waypoint is approached first and then the altitude is corrected to "Approach Altitude".
## Logic Conditions
The current landing state can be retrieved via ID 41 in "Flight" (FW Land State). This allows additional actions to be executed according to the landing phases, e.g. deployment of the landing flaps.
| Returned value | State |
| --- | --- |
| 0 | Idle/Inactive |
| 1 | Loiter |
| 2 | Downwind |
| 3 | Base Leg |
| 4 | Final Approach |
| 5 | Glide |
| 6 | Flare |
docs/GPS_fix_estimation.md
+132
View File
@@ -0,0 +1,132 @@
# GPS Fix estimation (dead reckoning, RTH without GPS) for fixed wing
Video demonstration
[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/wzvgRpXCS4U/0.jpg)](https://www.youtube.com/watch?v=wzvgRpXCS4U)
There is possibility to allow plane to estimate it's position when GPS fix is lost.
The main purpose is RTH without GPS.
It works for fixed wing only.
Plane should have the following sensors:
- acceleromenter, gyroscope
- barometer
- GPS
- magnetometer (optional, highly recommended)
- pitot (optional)
By befault, all navigation modes are disabled when GPS fix is lost. If RC signal is lost also, plane will not be able to enable RTH. Plane will switch to LANDING instead. When flying above unreachable spaces, plane will be lost.
GPS fix estimation allows to recover plane using magnetometer and baromener only.
GPS Fix is also estimated on GPS Sensor timeouts (hardware failures).
Note, that GPS fix estimation is not a solution for navigation without GPS. Without GPS fix, position error accumulates quickly. But it is acceptable for RTH. This is not a solution for flying under spoofing also. GPS is the most trusted sensor in Inav. It's output is not validated.
# How it works ?
In normal situation, plane is receiving it's position from GPS sensor. This way it is able to hold course, RTH or navigate by waypoints.
Without GPS fix, plane has nose heading from magnetometer and height from barometer only.
To navigate without GPS fix, we make the following assumptions:
- plane is flying in the direction where nose is pointing
- (if pitot tube is not installed) plane is flying with constant airspeed, specified in settings
It is possible to roughly estimate position using theese assumptions. To increase accuracy, plane will use information about wind direction and speed, estimated before GPS fix was lost. To increase groundspeed estimation accuracy, plane will use pitot tube data(if available).
From estimated heading direction and speed, plane is able to **roughly** estimate it's position.
It is assumed, that plane will fly in roughly estimated direction to home position untill either GPS fix or RC signal is recovered.
*Plane has to acquire GPS fix and store home position before takeoff. Estimation completely without GPS fix will not work*.
# Estimation without magnetometer
Without magnetometer, navigation accuracy is very poor. The problem is heading drift.
The longer plane flies without magnetometer or GPS, the bigger is course estimation error.
After few minutes and few turns, "North" direction estimation can be completely broken.
In general, accuracy is enough to perform RTH U-turn when both RC controls and GPS are lost, and roughtly keep RTH direction in areas with occasional GPS outages.
![image](https://github.com/RomanLut/inav/assets/11955117/3d5c5d10-f43a-45f9-a647-af3cca87c4da)
(purple line - estimated position, black line - real position).
It is recommened to use GPS fix estimation without magnetometer as last resort only. For example, if plane is flying above lake, landing means loss of plane. With GPS Fix estimation, plane will try to do RTH in very rought direction, instead of landing.
It is up to user to estimate the risk of fly-away.
# Settings
GPS Fix estimation is enabled with CLI command:
```set inav_allow_gps_fix_estimation=ON```
Also you have to specify cruise airspeed of the plane.
To find out cruise airspeed, make a test flight. Enable ground speed display on OSD. Flight in CRUISE mode in two opposite directions. Take average speed.
Cruise airspeed is specified in cm/s.
To convert km/h to cm/s, multiply by 27.77.
Example: 100 km/h = 100 * 27.77 = 2777 cm/s
```set fw_reference_airspeed=2777```
*It is important, that plane fly with specified speed in CRUISE mode. If you have set option "Increase cruise speed with throttle" - do not use it without GPS Fix.*
*If pitot is available, pitot sensor data will be used instead of constant. It is not necessary to specify fw_reference_airspeed. However, it is still adviced to specify for the case of pitot failure.*
*Note related command: to continue mission without RC signal, see command ```set failsafe_mission_delay=-1```.*
**After entering CLI command, make sure that settings are saved:**
```save```
# Disabling GPS sensor from RC controller
![](Screenshots/programming_disable_gps_sensor_fix.png)
For testing purposes, it is possible to disable GPS sensor fix from RC controller in programming tab:
*GPS can be disabled only after: 1) initial GPS fix is acquired 2) in ARMED mode.*
# Allowing wp missions with GPS Fix estimation
```failsafe_gps_fix_estimation_delay```
Controls whether waypoint mission is allowed to proceed with gps fix estimation. Sets the time delay in seconds between gps fix lost event and RTH activation. Minimum delay is 7 seconds. If set to -1 the mission will continue until the end. With default setting(7), waypoint mission is aborted and switched to RTH with 7 seconds delay. RTH is done with GPS Fix estimation. RTH is trigerred regradless of failsafe procedure selected in configurator.
# Expected error (mag + baro)
Realistic expected error is up to 200m per 1km of flight path. In tests, 500m drift per 5km path was seen.
To dicrease drift:
- fly one large circle with GPS available to get good wind estimation
- use airspeed sensor. If airspeed sensor is not installed, fly in cruise mode without throttle override.
- do smooth, large turns
- make sure compass is pointing in nose direction precicely
- calibrate compass correctly
This video shows real world test where GPS was disabled occasionally. Wind is 10km/h south-west:
https://github.com/RomanLut/inav/assets/11955117/0599a3c3-df06-4d40-a32a-4d8f96140592
Purple line shows estimated position. Black line shows real position. "EST ERR" sensor shows estimation error in metters. Estimation is running when satellite icon displays "ES". Estimated position snaps to real position when GPS fix is reaquired.
# Is it possible to implement this for multirotor ?
There are some ideas, but there is no solution now. We can not make assumptions with multirotor which we can make with a fixed wing.
# Links
INAV HITL https://github.com/RomanLut/INAV-X-Plane-HITL
docs/Geozones.md
+135
View File
@@ -0,0 +1,135 @@
# Geozones
## Introduction
The Geozone feature allows pilots to define one or multiple areas on the map in Mission Control, to prevent accidental flying outside of allowed zones (Flight-Zones, FZ) or to avoid certain areas they are not allowed or not willing to fly in (No-Flight-Zone, NFZ).
This type of feature might be known to many pilots as a "Geofence" and despite providing the same core functionality, INAV Geozones are significantly more versatile and provide more safety and features.
Geozones can not only inform the Pilot on the OSD, if the aircraft is approaching a geozone border, it also gives the distance and direction to the closest border and the remaining flight distance to the breach point. Additionally, it provides autonomous avoidance features, if the Aircraft is in any kind of self-leveling flight mode.
The most important feature for safety is the automatic path planning for RTH (Start Return To Home), that automatically avoids NFZ areas if possible.
![image](https://github.com/user-attachments/assets/48e3e5cc-8517-4096-8497-399cf00ee541)
## Compatibility
- [INAV Version: 8.0 or later](https://github.com/iNavFlight/inav/releases)
- [INAV Configurator: 8.0 or Later](https://github.com/iNavFlight/inav-configurator/releases)
- [MWPTools: Snapshot 2024-11-15 or later](https://github.com/stronnag/mwptools)
- Only flight controller with more than 512k of Flash (STM32F405, STM32F765, STM32H743, etc.)
- Plane, Multirotor (Rover and Boat are untested at time of writing)
## Setup Procedure
- In the INAV Configurator, switch to the Configuration Panel and enable "Geozone" in the features.
- Switch to the Mission Control Panel and you will see a new Icon to call up the Geozone Editor. If Zones are already set up, they will be loaded automatically, as soon as you enter Mission Control.
![image](https://github.com/user-attachments/assets/23cd2149-b6a2-4945-b349-ee99863e74f0)
- Click on the "+" Symbol to add a new zone and define its parameters to your desire.
- The following Options are available:
- Shape: Configures a Zone as a Circle or a Polygon
- Type: Inclusive (FZ, green) or Exclusive (NFZ, red)
- Min. Alt (cm): lower ceiling of the Zone (0 represents the ground relative from the launch location or AMSL. No action will be taken at a minimum altitude of 0, so the aircraft can "dive out" of an Inclusive FZ on a hill. To have a Minimum Altitude action, set a negative altitude of -1 or lower)
- Max. Alt (cm): upper ceiling of the Zone (A value if 0 means no upper altitude limit)
- Action: Action to execute if an aircraft approaches the border of that Zone
- Radius: Circular Zone only, Radius of the Circle
- Move the Zone-Markers to the desired locations, to create a bordered area with the shape and size needed (Or change the radius in case of a Circular Zone)
- To add additional vertices, click on the borderline of the zone you are editing. This will add a new vertex to that line to move around.
![image](https://github.com/user-attachments/assets/eacb6d3c-62d3-4bab-8874-1543c0a6b06d)
- Add additional Zones as you like, Zones can be separated but also overlapping (See [Limitations]( ) for details)
- After finishing the zone setup, click the "Store in EEPROM" Button to save the zones on the Flight Controller. It is important that the FC reboots after storing, as the Zones can only be used after a fresh boot process.
![image](https://github.com/user-attachments/assets/4b278dd0-aa65-45f6-b914-22bdd753feaf)
## Global Settings
- In the Advanced Tuning Panel, you will find additional global settings for Geozones
![image](https://github.com/user-attachments/assets/db567521-e256-4fb6-8ca6-6e6b8b57d7a9)
- Detection Distance `geozone_detection_distance`: Defines at what distance a Geozone will be shown as a System Message if a breach is imminent.
- Avoid Altitude Range `geozone_avoid_altitude_range`: When the Aircraft approaches an NFZ that has a upper limit (can be overflown at higher altitude), INAV will climb above the Zone automatically if the altitude difference between Zone ceiling and current Aircraft altitude is less, than this value. For fixed wing, you need to consider how steep the possible climb angle is.
- Safe Altitude Distance `geozone_safe_altitude_distance`: Vertical safety margin to avoid a ceiling or floor altitude breach at high vertical speed. If your FZ Ceiling is at 100m and this value set to 10m, the aircraft will not allow you to fly above 90m and descents if the Aircraft overshoots.
- Safehome as Inclusive `geozone_safehome_as_inclusive`: Defines every Safehome location as a circular Inclusive zone with the radius of `safehome_max_distance` to allow a FZ at ground altitude (For Landings) if the general FZ around it might have a minimum altitude.
- Safehome Zone Action `geozone_safehome_zone_action`: Defines the action on zone breach if Safehome is enabled as inclusive. This is helpful for flying fields with distance or altitude restrictions for LOS Pilots.
- Multirotor Stop Distance `geozone_mr_stop_distance:`: Distance from the Border a Multirotor will stop, if the Fence Action is Avoid or Loiter (For fixed wings, this will be calculated from the Loiter-Radius of the Plane).
- No Way Home Action `geozone_no_way_home_action`: If RTH cannot find a possible route in FS or RTH modes, the Aircraft will either emergency land or fly straight back home and ignores NFZ.
## Functions and Behaviors
- Zone Type: Inclusive
- If craft is armed inside the Inclusive FZ, everything outside that zone is considered an NFZ.
- Inclusive FZ can be combined if they overlap and will be handled as one zone.
- Overlapping multiple FZ allows different upper and lower altitude limits for each zone, as long as they still overlap in 3D Space (Both overlapping zones have to have a overlapping altitude range as well).
- Arming the aircraft outside of an Inclusive Zone is prohibited within a 2km distance to the next vertex (Distance to a border between two vertex is not checked). Arming override can be used. Arming at a distance bigger than 2km is possible.
- Arming a craft outside of an Inclusive FZ will disable all Inclusive zones.
- Zone Type: Exclusive
- Arming inside an Exclusive NFZ is prohibited. Arming override can be used but not recommended. If armed inside an NFZ the Pilot keeps control until the NFZ is left, then any configured Action will be executed on re-enter.
- Exclusive Zones can be combined and overlapped as needed.
- Exclusive NFZ with an upper or lower limit other than 0 can be overflown and underflown. The Automatic avoidance will only fly above NFZ if possible and never below.
- Actions:
- Avoid: Also called “Bounce” (only airplanes): The aircraft flies away from the boundary at the same angle it approached it, like a pool ball bouncing off the table border. Multirotor will switch into "Position Hold".
- Hold: Position in front of the boundary is held. Airplances will adjust their loiter center according to the loider radius, to stay away from the border while circling.
- RTH: Triggers Return To Home. The Failsafe RTH Procedure is executed, so RTH Trackback is also used if enabled for Failsafe situations.
- None: No action (only info in OSD).
- RTH:
- If RTH is enabled by Failsafe, User Command or Zone Action, INAV will calculate a path to the Home Location that automatically avoids NFZ and tries to stay inside the current FZ.
- If no Path can be calculated (Not able to climb over a blocking NFZ, No Intersection between FZ, too tight gaps between blocking NFZ) a configurable alternative action will be executed.
- Direct RTH: Ignores Flight zones and comes back in a direct path.
- Emergency Land: Executes a GPS enabled Emergency Landing (Circle down with horizontal position hold active on Planes).
- When direct "Line of sight" with the Home location is reached (No zones blocking path), regular RTH settings are executed.
- To abort the Smart-RTH feature and come back on a direct way, disable and Re-Enable RTH within 1 Second. This temporarily ignores all FZ and NFZ borders.
- Return to Zone:
- If the Aircraft breaches into an NFZ or out of a FZ (by avoiding tight angled Zones or flown in Acro mode and then the mode switches to any Self-Level mode), RTZ is initiated and the aircraft flies back into the last permitted zone on the shortest possible course.
## OSD Elements
- Three dedicated OSD Elements have been added:
- Fence-Distance Horizontal shows the distance to the nearest Fence Border and the heading to that border. (ID 145)
- Fence-Distance Vertical shows the distance to the nearest ceiling or floor of a zone. (ID 146)
- Fence-Direction Vertical is an optional element to show if the nearest vertical border is above or below the aircraft. (ID 144)
![image](https://github.com/user-attachments/assets/87dd3c5a-1046-4bd4-93af-5f8c9078b868)
- The Flight-Mode will show AUTO if the Aircraft executes any kind of Fence-Action.
- The System-Message shows the distance to a potential fence breach point, based on the current aircraft Attitude and Heading.
- Additionally, the System Message shows the current Fence Action that is Executed.
## Limitations
- The maximum number of dedicated zones of any type is 63.
- The maximum number of vertices of all zones combined is 127. Every circular zone uses 2 vertices while every polygon has to consist of at least 3 vertices.
- INAV can only execute one border-breach action at a time. This is especially important to consider for Airplanes that cannot hover.
- Complicated Zone setups with overlaps and tight areas can cause a loiter or "bounce" into another NFZ that was not considered before.
- This can lead to a "Return to FZ" action that tries to find the shortest path into an allowed area.
- All Geozone Actions are disabled when in Waypoint Mode. The Pilot is responsible for planning his mission accordingly, to not create a path that crosses NFZ areas. If a mission leads to such an area and the pilot disables WP mode, a "Return to FZ" action will be executed.
- All Geozone Actions are disabled in ACRO and MANUAL Mode. INAV will not take over control in these modes and only OSD Warnings are shown.
- Planning the Geozone as a polygon, needs to have the vertex numbering to be counter clockwise in ascending order. One vertex must not be dragged over another border to create crossing borders within one zone. INAV Configurator and MWP will check for that before uploading.
- Examples of Zones that are not allowed:
![image](https://github.com/user-attachments/assets/50f1a441-39da-4f1c-9128-7375bc593fa5)
- To properly combine multiple Inclusion FZ into one area, the Zones need to overlap at 2 borders and the points where the borders touch, must be at least 2.5x Loiter-Radius apart from Airplanes at least 2.5x Multirotor Stop Distance apart for Multirotor.
- Example:
![image](https://github.com/user-attachments/assets/cc50e24b-dc83-4408-bcba-90d6da33eb63)
- If multiple zones with different minimum and maximum altitudes are combined, they need to vertically overlap at least 50m.
- There is a chance that Smart RTH cannot find a path around NFZ areas, if there are multiple very big zones blocking the path. Due to hardware limitations, the amount of waypoints that Smart RTH can create are limited. Many Zones with very long border lines (>500m) cause additional waypoints.
- It is not recommended to edit geozones in CLI by hand as this bypasses a lot of sanity checks. Potential errors in zones will disable them or can lead to unexpected behaviors. Transferring Geozones with a DIFF between aircraft is fine.
## CLI
The Geozone Information are stored in two separate data arrays. The first array holds the main Geozone Information and settings. The second array holds the Geozone vertices.
The following commands are available for users:
- `geozone` without argument lists the current settings
- `geozone reset <id>` resets a specific geozone and all related vertices. If no ID proveded, all geozones and vertices will be deleted.
- `geozone vertex` - lists all vertices.
- `geozone vertex reset` - deletes all vertices.
- `geozone vertex reset <zone id>` - Deletes all vertices of the zone.
- `geozone vertex reset <zone id> <vertex id>` - Deletes the vertex with the corresponding id from a zone.
The following information are for app-developers. _DO NOT EDIT GEOZONES MANUALLY CLI_!
`geozone <id> <shape> <type> <minimum altitude> <maximum altitude> <is_amsl> <fence action> <vertices count>`
- id: 0 - 63
- shape: 0 = Circular, 1 = Polygonal
- type: 0 = Exclusive, 1 = Inclusive
- minimum altitude: In centimetres, 0 = ground
- maximum altitude: In centimetres, 0 = infinity
- is_amsl: 0 = relative, 1 = AMSL
- fence action: 0 = None, 1 = Avoid, 2 = Position hold, 3 = Return To Home
- vertices count: 0-126 - Sanity check if number of vertices matches with configured zones
`geozone vertex <zone id> <vertex idx> <latitude> <logitude>`
- zone id: (0-63) The zone id to which this vertex belongs
- vertex idx: Index of the vertex (0-126)
- latitude/ logitude: Longitude and latitude of the vertex. Values in decimal degrees * 1e7. Example:the value 47.562004o becomes 475620040
docs/Getting Started.md
+107
View File
@@ -0,0 +1,107 @@
# Getting Started
This is a step-by-step guide that can help a person that has never used INAV before set up a flight controller and the aircraft around it for flight. Basic RC knowledge is required, though. A total beginner should first familiarize themselves with concepts and techniques of RC before using this (e.g. basic controls, soldering, transmitter operation etc). One could use [RCGroups](http://www.rcgroups.com/forums/index.php) and/or [the Youtube show FliteTest](https://www.youtube.com/user/flitetest) for this.
DISCLAIMER: This documents is a work in progress. We cannot guarantee the safety or success of your project. At this point the document is only meant to be a helping guide, not an authoritative checklist of everything you should do to be safe and successful. Always exercise common sense, critical thinking and caution.
Read the [Introduction](Introduction.md) chapter for an overview of INAV and how the community works.
## Hardware
NOTE: Flight Controllers are typically equipped with accelerometers. These devices are sensitive to shocks. When the device is not yet installed to an aircraft, it has very little mass by itself. If you drop or bump the controller, a big force will be applied on its accelerometers, which could potentially damage them. Bottom line: Handle the board very carefully until it's installed on an aircraft!
For an overview of the hardware INAV (hereby CF) can run on, see [Boards.md](Boards.md). For information about specific boards, see the board specific documentation.
* Assuming that you have a flight controller board (hereby FC) in hand, you should first read through the manual that it came with. You can skip the details about software setup, as we'll cover that here.
* Decide how you'll connect your receiver by reading the [receiver](Rx.md) chapter, and how many pins you need on the outputs (to connect ESCs and servos) by reading about [Mixers](Mixer.md).
* If you're interested in monitoring your flight battery with CF, see [Battery Monitoring](Battery.md).
* You may want audible feedback from your copter so skim through [Buzzer](Buzzer.md) and mark the pins that will be used.
* Do you want your RC Receiver's RSSI to be sent to the board? [The RSSI chapter](Rssi.md) explains how. You may or may not need to make an additional connection from your Receiver to the FC.
* Would you like to try using a GPS unit to get your aircraft to Loiter or Return-To-Launch? Take a look at the [GPS](Gps.md) and [GPS Tested Hardware](Gps.md#hardware) chapters.
* You may also want to read the [Serial](Serial.md) chapter to determine what extra devices (such as Blackbox, OSD, Telemetry) you may want to use, and how they should be connected.
* Now that you know what features you are going to use, and which pins you need, you can go ahead and solder them to your board, if they are not soldered already. Soldering only the pins required for the application may save weight and contribute to a neater looking setup, but if you need to use a new feature later you may have to unmount the board from the craft and solder missing pins, so plan accordingly. Before soldering your FC please review a how-to-solder tutorial to avoid expensive mistakes, practice soldering on some scrap before soldering your FC.
* If you are going to use [Oneshot125](Oneshot.md), you may need to enable that on your ESCs using a jumper or flashing them with the latest stable firmware and enable Damped Light in their settings, if it's supported. Refer to the ESCs' documentation or online discussions to determine this.
## Software setup
Now that your board has pins on it, you are ready to connect it to your PC and flash it with CF. Install the Chromium browser or Google Chrome to your PC, if you don't have it already, add the [INAV Configurator](https://chrome.google.com/webstore/detail/inav-configurator/fmaidjmgkdkpafmbnmigkpdnpdhopgel) to it, and start it.
Then follow these instructions for [Installation](Installation.md) of the firmware to the FC.
## INAV Configuration
Your FC should now be running CF, and you should be able to connect to it using the Configurator. If that is not the case, please go back to the previous sections and follow the steps carefully.
<!--- This next paragraph should probably contain less info, as this info already exists in Configuration.md -->
Now, there are two ways to [configure CF](Configuration.md); via the Configurator's tabs (in a "graphical" way, clicking through and selecting/changing values and tickboxes) and using the [Command Line Interface (CLI)](Cli.md). Some settings may only be configurable using the CLI and some settings are best configured using the GUI (particularly the ports settings, which aren't documented for the CLI as they're not human friendly).
* It is now a good time to setup your RC Receiver and Transmitter. Set the Tx so that it outputs at least 4 channels (Aileron, Elevator, Throttle, Rudder) but preferably more. E.g. you can set channels 5 and 6 to be controlled by 3-position switches, to be used later. Maybe set up EXPO on AIL/ELE/RUD, but you should know that it can also be done in CF's software later. If using RSSI over PPM or PWM, it's now time to configure your Rx to output it on a spare channel.
* Connect the Rx to the FC, and the FC to the PC. You may need to power the Rx through a BEC (its 5V rail - observe polarity!).
* On your PC, connect to the Configurator, and go to the first tab. Check that the board animation is moving properly when you move the actual board. Do an accelerometer calibration.
* Configuration tab: Select your aircraft configuration (e.g. Quad X), and go through each option in the tab to check if relevant for you.
* E.g. you may want to enable ONESHOT125 for Oneshot-capable ESCs.
* You may need RX_PPM if you're using an RC Receiver with PPM output etc.
* If planning to use the battery measurement feature of the FC, check VBAT under Battery Voltage.
* If using analog RSSI, enable that under RSSI. Do not enable this setting if using RSSI injected into the PPM stream.
* Motors will spin by default when the FC is armed. If you don't like this, enable MOTOR_STOP.
* Also, adjust the minimum, middle and maximum throttle according to these guidelines:
* Minimum Throttle - Set this to the minimum throttle level that enables all motors to start reliably. If this is too low, some motors may not start properly after spindowns, which can cause loss of stability and control. A typical value would be 1100.
* Middle Throttle - The throttle level for middle stick position. Many radios use 1500, but some (e.g. Futaba) may use 1520 or other values.
* Maximum Throttle - The maximum throttle level that the ESCs should receive. A typical value would be 2000.
* Minimum Command - This is the "idle" signal level that will be sent to the ESCs when the craft is disarmed, which should not cause the motors to spin. A typical value would be 1000.
* Finally, click Save and Reboot.
* Receiver tab:
* Check that the channel inputs move according to your Tx inputs.
* Check that the Channel map is correct along with the RSSI Channel, if you use that.
* Verify the range of each channel goes from ~1000 to ~2000. See also [controls](Controls.md). and `rx_min_usec` and `rx_max_usec`.
* You can also set EXPO here instead of your Tx.
* Click Save!
* Modes tab: Setup the desired modes. See the [Modes in the wiki](https://github.com/iNavFlight/inav/wiki/Modes) for what each mode does.
* Before finishing this section, you should calibrate the ESCs, install the FC to the frame, and connect the RSSI cable, buzzer and battery if you have chosen to use those.
## Final testing and safety
It's important that you have configured CF properly, so that your aircraft does not fly away, or even worse fly into property and people! This is an important step that you should NOT postpone until after your maiden flight. Please do this now, before you head off to the flying field.
* First, learn how to arm your FC, and about other [controls](Controls.md).
* Next up, setup [Failsafe](Failsafe.md). Take your time, do it properly.
* Now, on the bench, without props, test that failsafe works properly, according to the above doc.
* Additionally, test the effect of AIL/ELE input of your Tx. Is the aircraft responding properly? Do the same for RUD input.
* Test the direction of AIL/ELE auto correction. Raise throttle at 30% (no blades!); when you tilt the aircraft, do the motors try to compensate momentarily? This should simulate random wind forces that the FC should counteract
* Test the direction of AIL/ELE auto correction in HORIZON mode. With throttle at 30%, if you tilt the aircraft so that one motor is lowered towards the ground, does it spin up and stay at high RPM until you level it off again? This tests the auto-leveling direction.
If one of these tests fail, do not attempt to fly, but go back to the configuration phase instead. Some channel may need reversing, or the direction of the board is wrong.
## Using it (AKA: Flying)
Go to the field, turn Tx on, place aircraft on the ground, connect flight battery and wait. Arm and fly. Good luck!
## Advanced Matters
Some advanced configurations and features are documented in the following pages, but have not been touched-upon earlier:
* [Profiles](Profiles.md)
* [PID tuning](PID%20tuning.md)
* [In-flight Adjustments](Inflight%20Adjustments.md)
* [Blackbox logging](Blackbox.md)
* [Using a Sonar](Sonar.md)
* [Spektrum Bind](Spektrum%20bind.md)
* [Telemetry](Telemetry.md)
* [Using a Display](Display.md)
* [Using a LED strip](LedStrip.md)
docs/INAV PID Controller.md
+25
View File
@@ -0,0 +1,25 @@
# INAV PID Controller
What you have to know about INAV PID/PIFF/PIDCD controllers:
1. INAV PID uses floating-point math
1. Rate/Angular Velocity controllers work in dps [degrees per second]
1. P, I, D and Multirotor CD gains are scaled like Betafligfht equivalents, but actual mechanics are different, and PID response might be different
1. Depending on platform type, different controllers are used
1. Fixed-wing uses **PIFF**:
1. Error is computed with a formula `const float rateError = pidState->rateTarget - pidState->gyroRate;`
1. P-term with a formula `rateError * pidState->kP`
1. Simple I-term without Iterm Relax. I-term limit based on stick position is used instead. I-term is no allowed to grow if stick (roll/pitch/yaw) is deflected above threshold defined in `fw_iterm_limit_stick_position`. `pidState->errorGyroIf += rateError * pidState->kI * dT;`
1. No D-term
1. FF-term (Feed Forward) is computed from the controller input with a formula `pidState->rateTarget * pidState->kFF`. Bear in mind, this is not a **FeedForward** from Betaflight!
1. Multirotor uses **PIDCD**:
1. Error is computed with a formula `const float rateError = pidState->rateTarget - pidState->gyroRate;`
1. P-term with a formula `rateError * pidState->kP`
1. I-term
1. Iterm Relax is used to dynamically attenuate I-term during fast stick movements
1. I-term formula `pidState->errorGyroIf += (itermErrorRate * pidState->kI * antiWindupScaler * dT) + ((newOutputLimited - newOutput) * pidState->kT * antiWindupScaler * dT);`
1. I-term can be limited when motor output is saturated
1. D-term is computed only from gyro measurement
1. There are 2 LPF filters on D-term
1. D-term can by boosted during fast maneuvers using D-Boost. D-Boost is an equivalent of Betaflight D_min
1. **Control Derivative**, CD, or CD-term is a derivative computed from the setpoint that helps to boost PIDCD controller during fast stick movements. `newCDTerm = rateTargetDeltaFiltered * (pidState->kCD / dT);` It is an equivalent of Betaflight Feed Forward
docs/INAV_Autolaunch.pdf
BIN
View File
Binary file not shown.
docs/INAV_Fixed_Wing_Setup_Guide.pdf
BIN
View File
Binary file not shown.
docs/INAV_Modes.pdf
BIN
View File
Binary file not shown.
docs/INAV_Wing_Tuning_Masterclass.pdf
BIN
View File
Binary file not shown.
docs/Inflight Adjustments.md
+255
View File
@@ -0,0 +1,255 @@
# In-flight Adjustments
With INAV it's possible to make adjustments to various settings by using AUX channels from your transmitter while the aircraft is flying.
## Warning
Changing settings during flight can make your aircraft unstable and crash if you are not careful.
## Recommendations
* Always make adjustments while flying in a large open area.
* Make small adjustments and fly carefully to test your adjustment.
* Give yourself enough flying space and time to adjust to how your changes affect the behaviour of the aircraft.
* Remember to set adjustment channel switches/pots to the center position before powering on your TX and your aircraft.
* If possible configure switch warnings on your transitter for dedicated adjustment switches.
* A momentary 3 position switch is the best choice of switch for this - i.e. one that re-centers itself when you let go of it.
## Overview
Up to 4 RX channels can be used to make different adjustments at the same time.
The adjustment a channel makes can be controlled by another channel.
The following adjustments can be made in flight as well as on the ground.
* RC Rate
* RC Expo
* Throttle Expo
* Pitch, Roll, Yaw Rates
* Pitch, Roll, Yaw PIDs
* Manual rates
* FW cruise_throttle, pitch2thr, min_throttle_down_pitch_angle
* Board alignment
* Level PIDs
* PosHold, AltHold PIDs
* PIDs profile
Example scenarios:
Up to 4 3-position switches or pots can be used to adjust 4 different settings at the same time.
A single 2/3/4/5/6/x position switch can be used to make one 3 position switch adjust one setting at a time.
Any combination of switches and pots can be used. So you could have 6 POS switch.
Settings are not saved automatically, connect a GUI, refresh and save or save using stick position when disarmed.
Powering off without saving will discard the adjustments.
Settings can be saved when disarmed using stick positions: Throttle Low, Yaw Left, Pitch Low, Roll Right.
## Adjustment switches
The switch can be a ON-OFF-ON, POT or momentary ON-OFF-ON switch. The latter is recommended.
When the switch is returned to the center position the value will not be increased/decreased.
Each time you can press the switch high/low and then return it to the middle the value will change at least once, you do not have to wait before pressing the switch again if you want to increase/decrease at a faster rate. While the adjustment switch held is high/low, the adjustment function applies and increases/decreases the value being adjusted twice a second and the flight controller will beep shorter/longer, respectively. The system works similar to how a keyboard repeat delay works.
Hint: With OpenTX transmitters you can combine two momentary OFF-ON switches to control a single channel. You could make it so that a momentary switch on the left of your transmitter decreases the value and a momentary switch on the right increases the value. Experiment with your mixer!
## Configuration
The CLI command `adjrange` is used to configure adjustment ranges.
20 adjustment ranges can be defined.
4 adjustments can be made at the same time, each simultaneous adjustment requires an adjustment slot.
Show the current ranges using:
`adjrange`
Configure a range using:
`adjrange <index> <slot> <range channel> <range start> <range end> <adjustment function> <adjustment channel>`
| Argument | Value | Meaning |
| -------- | ----- |-------- |
| Index | 0 - 19 | Select the adjustment range to configure |
| Slot | 0 - 3 | Select the adjustment slot to use |
| Range Channel | 0 based index, AUX1 = 0, AUX2 = 1 | The AUX channel to use to select an adjustment for a switch/pot |
| Range Start | 900 - 2100. Steps of 25, e.g. 900, 925, 950... | Start of range |
| Range End | 900 - 2100 | End of range |
| Adjustment function | 0 - 56 | See Adjustment function table |
| Adjustment channel | 0 based index, AUX1 = 0, AUX2 = 1 | The channel that is controlled by a 3 Position switch/Pot |
Range Start/End values should match the values sent by your receiver.
Normally Range Channel and Slot values are grouped together over multiple adjustment ranges.
The Range Channel and the Adjustment Channel can be the same channel. This is useful when you want a single 3 Position switch to be dedicated
to a single adjustment function regardless of other switch positions.
The adjustment function is applied to the adjustment channel when range channel is between the range values.
The adjustment is made when the adjustment channel is in the high or low position. high = mid_rc + 200, low = mid_rc - 200. by default this is 1700 and 1300 respectively.
When the Range Channel does not fall into Start/End range the assigned slot will retain it's state and will continue to apply the adjustment. For
this reason ensure that you define enough ranges to cover the range channel's usable range.
### Adjustment function
| Value | Adjustment |
| ----- | ---------- |
| 0 | None |
| 1 | RC RATE |
| 2 | RC_EXPO |
| 3 | THROTTLE_EXPO |
| 4 | PITCH_ROLL_RATE |
| 5 | YAW_RATE |
| 6 | PITCH_ROLL_P |
| 7 | PITCH_ROLL_I |
| 8 | PITCH_ROLL_D |
| 9 | PITCH_ROLL_FF |
| 10 | PITCH_P |
| 11 | PITCH_I |
| 12 | PITCH_D |
| 13 | PITCH_FF |
| 14 | ROLL_P |
| 15 | ROLL_I |
| 16 | ROLL_D |
| 17 | ROL_FF |
| 18 | YAW_P |
| 19 | YAW_I |
| 20 | YAW_D |
| 21 | YAW_FF
| 22 | Unused |
| 23 | PITCH_RATE |
| 24 | ROLL_RATE |
| 25 | RC_YAW_EXPO |
| 26 | MANUAL_RC_EXPO |
| 27 | MANUAL_RC_YAW_EXPO |
| 28 | MANUAL_PITCH_ROLL_RATE |
| 29 | MANUAL_ROLL_RATE |
| 30 | MANUAL_PITCH_RATE |
| 31 | MANUAL_YAW_RATE |
| 32 | NAV_FW_CRUISE_THROTTLE |
| 33 | NAV_FW_PITCH2THR |
| 34 | ROLL_BOARD_ALIGNMENT |
| 35 | PITCH_BOARD_ALIGNMENT |
| 36 | LEVEL_P |
| 37 | LEVEL_I |
| 38 | LEVEL_D |
| 39 | POS_XY_P |
| 40 | POS_XY_I |
| 41 | POS_XY_D |
| 42 | POS_Z_P |
| 43 | POS_Z_I |
| 44 | POS_Z_D |
| 45 | HEADING_P |
| 46 | VEL_XY_P |
| 47 | VEL_XY_I |
| 48 | VEL_XY_D |
| 49 | VEL_Z_P |
| 50 | VEL_Z_I |
| 51 | VEL_Z_D |
| 52 | FW_MIN_THROTTLE_DOWN_PITCH_ANGLE |
| 53 | ADJUSTMENT_VTX_POWER_LEVEL |
| 54 | TPA |
| 55 | TPA_BREAKPOINT |
| 56 | NAV_FW_CONTROL_SMOOTHNESS |
| 57 | FW_TPA_TIME_CONSTANT |
| 58 | FW_LEVEL_TRIM |
## Examples
### Example 1 - 3 Position switch used to adjust pitch/roll rate
```
adjrange 0 0 3 900 2100 4 3
```
explained:
* configure adjrange 0 to use adjustment slot 1 (0) so that when aux4
(3) in the range 900-2100 then use adjustment 4 (pitch/roll rate) when aux 4 (3)
is in the appropriate position.
### Example 2 - 2 Position switch used to enable adjustment of RC rate via a 3 position switch
```
adjrange 1 1 0 900 1700 0 2
adjrange 2 1 0 1700 2100 1 2
```
explained:
* configure adjrange 1 to use adjustment slot 2 (1) so that when aux1
(0) in the range 900-1700 then do nothing (0) when aux 3 (2) is in any
position.
* configure adjrange 2 to use adjustment slot 2 (1) so that when aux1
(0) in the range 1700-2100 then use adjustment rc rate (1) when aux 3
(2) is in the appropriate position.
Without the entire range of aux1 being defined there is nothing that
would stop aux 3 adjusting the pitch/roll rate once aux 1 wasn't in the higher
range.
### Example 3 - 6 Position switch used to select PID tuning adjustments via a 3 position switch
```
adjrange 3 2 1 900 1150 6 3
adjrange 4 2 1 1150 1300 7 3
adjrange 5 2 1 1300 1500 8 3
adjrange 6 2 1 1500 1700 18 3
adjrange 7 2 1 1700 1850 19 3
adjrange 8 2 1 1850 2100 20 3
```
explained:
* configure adjrange 3 to use adjustment slot 3 (2) so that when aux2
(1) in the range 900-1150 then use adjustment Pitch/Roll P (6) when aux 4
(3) is in the appropriate position.
* configure adjrange 4 to use adjustment slot 3 (2) so that when aux2
(1) in the range 1150-1300 then use adjustment Pitch/Roll I (7) when aux 4
(3) is in the appropriate position.
* configure adjrange 5 to use adjustment slot 3 (2) so that when aux2
(1) in the range 1300-1500 then use adjustment Pitch/Roll D (8) when aux 4
(3) is in the appropriate position.
* configure adjrange 6 to use adjustment slot 3 (2) so that when aux2
(1) in the range 1500-1700 then use adjustment Yaw P (18) when aux 4
(3) is in the appropriate position.
* configure adjrange 7 to use adjustment slot 3 (2) so that when aux2
(1) in the range 1700-1850 then use adjustment Yaw I (19) when aux 4
(3) is in the appropriate position.
* configure adjrange 8 to use adjustment slot 3 (2) so that when aux2
(1) in the range 1850-2100 then use adjustment Yaw D (20) when aux 4
(3) is in the appropriate position.
### Configurator examples
The following 5 images show valid configurations. In all cases the entire usable range for the Range Channel is used.
![Configurator example 2](Screenshots/adjustments-pitch-and-roll-rate-adjustment-via-3pos.png)
---
![Configurator example 3](Screenshots/adjustments-pid-via-two-3pos.png)
---
![Configurator example 4](Screenshots/adjustments-pid-via-6pos-and-3pos.png)
---
![Configurator example 5](Screenshots/adjustments-rates-via-a-2pos-and-3pos.png)
The following examples shows __incorrect__ configurations - the entire usable range for the Range Channel is not used in both cases.
![Configurator example 6](Screenshots/adjustments-incorrect-config-1.png)
![Configurator example 7](Screenshots/adjustments-incorrect-config-2.png)
In the following example, the incorrect configuraton (above) has been corrected by adding a range that makes 'No changes'.
![Configurator example 7](Screenshots/adjustments-incorrect-config-2-corrected.png)
docs/Installation.md
+34
View File
@@ -0,0 +1,34 @@
# Installation
## Using the configurator
This is a generic procedure to flash a board using the configurator. The configurator does not yet support all boards, so please check the documentation corresponding to your board before proceeding.
Make sure you have the [INAV Configurator](https://github.com/iNavFlight/inav-configurator) installed, then:
* Connect the flight controller to the PC.
* Start the INAV Configurator.
* Click on "Disconnect" if the configurator connected to the board automatically.
* Click on the "Firmware Flasher" tab.
* Make sure you have internet connectivity and click on the "Load Firmware [Online]" button.
* Click on the "Choose a Firmware / Board" dropdown menu, and select the latest stable version for your flight controller.
* IMPORTANT: Read and understand the release notes that are displayed. When upgrading review all release notes since your current firmware.
* If this is the first time INAV is flashed to the board, tick the "Full Chip Erase" checkbox.
* Connect the flight controller board to the PC. Ensure the correct serial port is selected.
* Click on the "Flash Firmware" button and hold still (do not breathe, too).
* When the progress bar becomes green and reads "Programming: SUCCESSFUL" you are done!
## Manually
See the board specific flashing instructions.
# Upgrading
When upgrading be sure to backup / dump your existing settings. Some firmware releases are not backwards compatible and default settings are restored when the FC detects an out of date configuration.
## Backup/Restore process
The INAV Configurator (after version 9.0.x) automatically backs up your configuration before flashing and offers to restore it afterwards (when Full Chip Erase is enabled) — including automatic settings migration when upgrading across major versions.
For details on automatic and manual backup/restore, see [Backup and Restore](Backup%20and%20Restore.md).
For CLI-based backup and restore, see the [CLI documentation](Cli.md#backup-via-cli).
docs/Introduction.md
+35
View File
@@ -0,0 +1,35 @@
# INAV
![INAV](http://static.rcgroups.net/forums/attachments/6/1/0/3/7/6/a9088858-102-inav.png)
Welcome to INAV!
INAV is an community project which attempts to deliver flight controller firmware and related tools.
## Primary Goals
* Community driven.
* Friendly project atmosphere.
* Focus on the needs of users.
* Great flight performance.
* Understandable and maintainable code.
## Hardware
See the flight controller hardware chapter for details.
## Software
There are two primary components, the firmware and the configuration tool. The firmware is the code that runs on the flight controller board. The GUI configuration tool (configurator) is used to configure the flight controller, it runs on Windows, OSX and Linux.
## Feedback & Contributing
We welcome all feedback. If you love it we want to hear from you, if you have problems please tell us how we could improve things so we can make it better for everyone.
If you want to contribute please see the notes here:
https://github.com/iNavFlight/inav#contributing
Developers should read this:
https://github.com/iNavFlight/inav/blob/master/CONTRIBUTING.md
docs/LED pin PWM.md
+96
View File
@@ -0,0 +1,96 @@
# LED pin PWM
Normally LED pin is used to drive WS2812 led strip. LED pin is held low, and every 10ms or 20ms a set of pulses is sent to change color of the 32 LEDs:
![alt text](/docs/assets/images/ws2811_packets.png "ws2811 packets")
![alt text](/docs/assets/images/ws2811_data.png "ws2811 data")
As alternative function, it is possible to generate PWM signal with specified duty ratio on the LED pin.
Feature can be used to drive external devices such as a VTX power switch. Setting the PWM duty cycle to 100% or 0% can
provide an extra PINIO pin. It is also used to simulate [OSD joystick](OSD%20Joystick.md) to control cameras.
PWM frequency is fixed to 24kHz with duty ratio between 0 and 100%:
![alt text](/docs/assets/images/led_pin_pwm.png "led pin pwm")
Note that the LED feature needs to be enabled when using the PIN in this mode (feature LED_STRIP).
There are four modes of operation:
- low
- high
- shared_low
- shared_high
Mode is configured using ```led_pin_pwm_mode``` setting: ```LOW```, ```HIGH```, ```SHARED_LOW```, ```SHARED_HIGH```
*Note that in any mode, there will be ~2 seconds LOW pulse on boot.*
## LOW
LED Pin is initialized to output low level by default and can be used to generate PWM signal.
ws2812 strip can not be controlled.
## HIGH
LED Pin is initialized to output high level by default and can be used to generate PWM signal.
ws2812 strip can not be controlled.
## SHARED_LOW (default)
LED Pin is used to drive WS2812 strip. Pauses between pulses are low:
![alt text](/docs/assets/images/ws2811_packets.png "ws2811 packets")
It is possible to generate PWM signal with duty ratio >0...100%.
While PWM signal is generated, ws2811 strip is not updated.
When PWM generation is disabled, LED pin is used to drive ws2812 strip.
Total ws2812 pulses duration is ~1ms with ~9ms pauses. Thus connected device should ignore PWM signal with duty ratio < ~10%.
## SHARED_HIGH
LED Pin is used to drive WS2812 strip. Pauses between pulses are high. ws2812 pulses are prefixed with 50us low 'reset' pulse:
![alt text](/docs/assets/images/ws2811_packets_high.png "ws2811 packets_high")
![alt text](/docs/assets/images/ws2811_data_high.png "ws2811 data_high")
It is possible to generate PWM signal with duty ratio 0...<100%.
While PWM signal is generated, ws2811 strip is not updated.
When PWM generation is disabled, LED pin is used to drive ws2812 strip. Total ws2812 pulses duration is ~1ms with ~9ms pauses. Thus connected device should ignore PWM signal with duty ratio > ~90%.
After sending ws2812 protocol pulses for 32 LEDS, we held line high for 9ms, then send 50us low 'reset' pulse. Datasheet for ws2812 protocol does not describe behavior for long high pulse, but in practice it works the same as 'reset' pulse. To be safe, we also send correct low 'reset' pulse before starting next LEDs update sequence.
This mode is used to simulate OSD joystick. It is Ok that effectively voltage level is held >90% while driving LEDs, because OSD joystick keypress voltages are below 90%.
See [OSD Joystick](OSD%20Joystick.md) for more information.
# Generating PWM signal with programming framework
See "LED Pin PWM" operation in [Programming Framework](Programming%20Framework.md)
# Generating PWM signal from CLI
```ledpinpwm <value>``` - value = 0...100 - enable PWM generation with specified duty cycle
```ledpinpwm``` - disable PWM generation ( disable to allow ws2812 LEDs updates in shared modes )
# Example of driving LED
It is possible to drive single color LED with brightness control. Current consumption should not be greater then 1-2ma, thus LED can be used for indication only.
![alt text](/docs/assets/images/ledpinpwmled.png "led pin pwm led")
# Example of driving powerfull white LED
To drive power LED with brightness control, Mosfet should be used:
![alt text](/docs/assets/images/ledpinpwmpowerled.png "led pin pwm power_led")
# Programming tab example for using the LED pin as a PINIO, such as for turning a VTX or camera on and off
![screenshot of programming tab using led as pinio](/docs/assets/images/led-as-pinio.png)
docs/LedStrip.md
+608
View File
@@ -0,0 +1,608 @@
# LED Strip
INAV supports the use of addressable LED strips. Addressable LED strips allow each LED in the strip to
be programmed with a unique and independant color. This is far more advanced than the normal RGB strips which
require that all the LEDs in the strip show the same color.
Addressable LED strips can be used to show information from the flight controller system, the current implementation
supports the following:
* Up to 128 LEDs. _If using more than 20 LEDs, you should look to use a separate power supply._
* Indicators showing pitch/roll stick positions.
* Heading/Orientation lights.
* Flight mode specific color schemes.
* Low battery warning.
* AUX operated on/off switch.
* GPS state.
* RSSI level.
* Battery level.
Support for more than 128 LEDs is possible, it just requires additional development.
## Supported hardware
Only strips of 128 WS2811/WS2812 LEDs are supported currently. If the strip is longer than 128 LEDs it does not matter,
but only the first 128 are used.
WS2812 LEDs require an 800khz signal and precise timings and thus requires the use of a dedicated hardware timer.
Note: Not all WS2812 ICs use the same timings, some batches use different timings.
It could be possible to be able to specify the timings required via CLI if users request it.
### Tested Hardware
* [Adafruit NeoPixel Jewel 7](https://www.adafruit.com/products/2226) (preliminary testing)
* Measured current consumption in all white mode ~ 350 mA.
* Fits well under motors on mini 250 quads.
* [Adafruit NeoPixel Stick](https://www.adafruit.com/products/1426) (works well)
* Measured current consumption in all white mode ~ 350 mA.
## Connections
WS2812 LED strips generally require a single data line, 5V and GND.
WS2812 LEDs on full brightness can consume quite a bit of current. **It is recommended to verify the current draw of you LEDs and ensure your supply can cope with the load. Remember, your flight controller will likely be using the same BEC to operate.** Check the specs of the LED chips. Some are more power hungry than others. Remember that if using the flight controller's 5v supply. This is also powering other components on your flight controller. Make sure there is enough overhead so that they don't brownout.
On a multirotor that uses multiple BEC ESC's you can try use a different BEC to the one the FC uses. e.g. ESC1/BEC1 -> FC, ESC2/BEC2 -> LED strip. It's also possible to power one half of the strip from one BEC and the other half from another BEC. Just ensure that the GROUND is the same for all BEC outputs and LEDs.
If using a large number of LEDs. It would be more efficient to use 12v LEDs and power them with a separate regulated supply. Especially if using long strips. You would use the data line (LED pad) from the flight controller. Make sure there is continuity between the ground on the LEDS and the ground on the flight controller.
| Target | Pin | LED Strip | Signal |
| --------------------- | ---- | --------- | -------|
| F3Discovery | PB8 | Data In | PB8 |
| Sparky | PWM5 | Data In | PA6 |
If you have LEDs that are intermittent, flicker or show the wrong colors then drop the VIN to less than 4.7v, e.g. by using an inline
diode on the VIN to the LED strip. The problem occurs because of the difference in voltage between the data signal and the power
signal. The WS2811 LED's require the data signal (Din) to be between 0.3 * Vin (Max) and 0.7 * VIN (Min) to register valid logic
low/high signals. The LED pin on the CPU will always be between 0v to ~3.3v, so the Vin should be 4.7v (3.3v / 0.7 = 4.71v).
Some LEDs are more tolerant of this than others.
The datasheet can be found here: http://www.adafruit.com/datasheets/WS2812.pdf
## Configuration
The led strip feature can be configured via the GUI.
GUI:
Enable the Led Strip feature via the GUI under setup.
Configure the leds from the Led Strip tab in the INAV GUI.
First setup how the led's are laid out so that you can visualize it later as you configure and so the flight controller knows how many led's there are available.
There is a step by step guide on how to use the GUI to configure the Led Strip feature using the GUI https://oscarliang.com/setup-led-betaflight/ which was published early 2015 by Oscar Liang which may or may not be up-to-date by the time you read this.
CLI:
Enable the `LED_STRIP` feature via the cli:
```
feature LED_STRIP
```
If you enable LED_STRIP feature and the feature is turned off again after a reboot then check your config does not conflict with other features, as above.
Configure the LEDs using the `led` command.
The `led` command takes either zero or two arguments - an zero-based led number and a sequence which indicates pair of coordinates, direction flags and mode flags and a color.
If used with zero arguments it prints out the led configuration which can be copied for future reference.
Each led is configured using the following template: `x,y:ddd:mmm:cc`
`x` and `y` are grid coordinates of a 0 based 16x16 grid, north west is 0,0, south east is 15,15
`ddd` specifies the directions, since an led can face in any direction it can have multiple directions. Directions are:
`N` - North
`E` - East
`S` - South
`W` - West
`U` - Up
`D` - Down
For instance, an LED that faces South-east at a 45 degree downwards angle could be configured as `SED`.
Note: It is perfectly possible to configure an LED to have all directions `NESWUD` but probably doesn't make sense.
`mmm` specifies the modes that should be applied an LED.
Each LED has one base function:
* `C` - `C`olor.
* `F` - `F`light mode & Orientation
* `A` - `A`rmed state.
* `R` - `R`ing thrust state.
* `G` - `G`PS state.
* `S` - R`S`SSI level.
* `L` - Battery `L`evel.
* `H` - C`H`annel.
And each LED has overlays:
* `W` - `W`warnings.
* `I` - `I`ndicator.
* `T` - `T`hrust state.
* `B` - `B`link (flash twice) mode.
* `O` - Lars`O`n Scanner (Cylon Effect).
* `N` - Blink on la`N`ding (throttle < 50%).
* `E` - Strob`E` Blink white on top of selected color.
`cc` specifies the color number (0 based index), or Channel number to adjust Hue
Example:
```
led 0 0,15:SD:AWI:0
led 1 15,0:ND:AWI:0
led 2 0,0:ND:AWI:0
led 3 0,15:SD:AWI:0
led 4 7,7::C:1
led 5 8,8::C:2
led 6 8,9::B:1
led 7 8,10::H:6
```
To erase an led, and to mark the end of the chain, use `0,0::` as the second argument, like this:
```
led 4 0,0:::
```
It is best to erase all LEDs that you do not have connected.
### Modes
#### Warning
This mode simply uses the LEDs to flash when warnings occur.
| Warning | LED Pattern | Notes |
|---------|-------------|-------|
| Arm-lock enabled | flash between green and off | occurs calibration or when unarmed and the aircraft is tilted too much |
| Low Battery | flash red and off | battery monitoring must be enabled. May trigger temporarily under high-throttle due to voltage drop |
| Hardware Error | flash blue and off | indicates that at least one of hardware components is not working correctly |
| Failsafe | flash between light blue and yellow | Failsafe must be enabled |
Flash patterns appear in order, so that it's clear which warnings are enabled.
#### GPS state
This mode shows the GPS state and satellite count.
No fix = red LED
3D fix = green LED
The LEDs will blink as many times as the satellite count, then pause and start again.
#### RSSI level
This mode binds the LED color to RSSI level.
| Color | RSSI |
| ---------- | ---------|
| Green | 100% |
| Lime green | 80% |
| Yellow | 60% |
| Orange | 40% |
| Red | 20% |
| Deep pink | 0% |
When RSSI is below 50% is reached, LEDs will blink slowly, and they will blink fast when under 20%.
#### Battery level
This mode binds the LED color to remaining battery capacity.
| Color | Capacity |
| ---------- | ---------|
| Green | 100% |
| Lime green | 80% |
| Yellow | 60% |
| Orange | 40% |
| Red | 20% |
| Deep pink | 0% |
When Warning or Critial voltage is reached, LEDs will blink slowly or fast.
Note: this mode requires a current sensor. If you don't have the actual device you can set up a virtual current sensor (see [Battery](Battery.md)).
#### Blink
This mode blinks the current LED, alternatively from black to the current active color.
#### Blink on landing
This mode blinks the current LED, alternatively from black to the current active color, when throttle is below 50% and the craft is armed.
#### Larson Scanner (Cylon Effect)
The Larson Scanner replicates the scanning "eye" effect seen on the mechanical Cylons and on Kitt from Knight Rider.
This overlay merely varies the brightness of each LED's current color.
#### Flight Mode & Orientation
This mode shows the flight mode and orientation.
When flight modes are active then the LEDs are updated to show different colors depending on the mode, placement on the grid and direction.
LEDs are set in a specific order:
* LEDs that marked as facing up or down.
* LEDs that marked as facing west or east AND are on the west or east side of the grid.
* LEDs that marked as facing north or south AND are on the north or south side of the grid.
That is, south facing LEDs have priority.
The mapping between modes led placement and colors is currently fixed and cannot be changed.
#### Indicator
##### For fixed wing (INAV 6.1 onwards)
This mode flashes LEDs that correspond to the roll stick position. Rolling left will flash any `indicator` LED on the left half of the grid. Rolling right will flash any `indicator` on the right side of the grid.
##### For other platforms (all platforms pre INAV 6.1)
This mode flashes LEDs that correspond to roll and pitch stick positions. i.e. they indicate the direction the craft is going to turn.
| Mode | Direction | LED Color |
|------------|--------|---------------------|
|Orientation | North | WHITE |
|Orientation | East | DARK VIOLET |
|Orientation | South | RED |
|Orientation | West | DEEP PINK |
|Orientation | Up | BLUE |
|Orientation | Down | ORANGE |
| | | |
|Head Free | North | LIME GREEN |
|Head Free | East | DARK VIOLET |
|Head Free | South | ORANGE |
|Head Free | West | DEEP PINK |
|Head Free | Up | BLUE |
|Head Free | Down | ORANGE |
| | | |
|Horizon | North | BLUE |
|Horizon | East | DARK VIOLET |
|Horizon | South | YELLOW |
|Horizon | West | DEEP PINK |
|Horizon | Up | BLUE |
|Horizon | Down | ORANGE |
| | | |
|Angle | North | CYAN |
|Angle | East | DARK VIOLET |
|Angle | South | YELLOW |
|Angle | West | DEEP PINK |
|Angle | Up | BLUE |
|Angle | Down | ORANGE |
| | | |
|Mag | North | MINT GREEN |
|Mag | East | DARK VIOLET |
|Mag | South | ORANGE |
|Mag | West | DEEP PINK |
|Mag | Up | BLUE |
|Mag | Down | ORANGE |
| | | |
|Baro | North | LIGHT BLUE |
|Baro | East | DARK VIOLET |
|Baro | South | RED |
|Baro | West | DEEP PINK |
|Baro | Up | BLUE |
|Baro | Down | ORANGE |
#### Armed state
This mode toggles LEDs between green and blue when disarmed and armed, respectively.
Note: Armed State cannot be used with Flight Mode.
#### Thrust state
This mode fades the LED current LED color to the previous/next color in the HSB color space depending on throttle stick position. When the
throttle is in the middle position the color is unaffected, thus it can be mixed with orientation colors to indicate orientation and throttle at
the same time. Thrust should normally be combined with Color or Mode/Orientation.
#### Thrust ring state
This mode is allows you to use one or multiple led rings (e.g. NeoPixel ring) for an afterburner effect. The light pattern rotates clockwise as throttle increases.
A better effect is acheived when LEDs configured for thrust ring have no other functions.
LED direction and X/Y positions are irrelevant for thrust ring LED state. The order of the LEDs that have the state determines how the LED behaves.
Each LED of the ring can be a different color. The color can be selected between the 16 colors availables.
For example, led 0 is set as a `R`ing thrust state led in color 13 as follow.
```
led 0 2,2::R:13
```
LED strips and rings can be combined.
#### Solid Color
The mode allows you to set an LED to be permanently on and set to a specific color.
x,y position and directions are ignored when using this mode.
Other modes will override or combine with the color mode.
For example, to set led 0 to always use color 10 you would issue this command.
```
led 0 0,0::C:10
```
### Colors
Colors can be configured using the cli `color` command.
The `color` command takes either zero or two arguments - an zero-based color number and a sequence which indicates pair of hue, saturation and value (HSV).
See http://en.wikipedia.org/wiki/HSL_and_HSV
If used with zero arguments it prints out the color configuration which can be copied for future reference.
The default color configuration is as follows:
| Index | Color |
| ----- | ----------- |
| 0 | black |
| 1 | white |
| 2 | red |
| 3 | orange |
| 4 | yellow |
| 5 | lime green |
| 6 | green |
| 7 | mint green |
| 8 | cyan |
| 9 | light blue |
| 10 | blue |
| 11 | dark violet |
| 12 | magenta |
| 13 | deep pink |
| 14 | black |
| 15 | black |
```
color 0 0,0,0
color 1 0,255,255
color 2 0,0,255
color 3 30,0,255
color 4 60,0,255
color 5 90,0,255
color 6 120,0,255
color 7 150,0,255
color 8 180,0,255
color 9 210,0,255
color 10 240,0,255
color 11 270,0,255
color 12 300,0,255
color 13 330,0,255
color 14 0,0,0
color 15 0,0,0
```
### Mode Colors Assignement
Mode Colors can be configured using the cli `mode_color` command.
- No arguments: lists all mode colors
- arguments: mode, function, color
First 6 groups of ModeIndexes are :
| mode | name |
|------|-------------|
| 0 | orientation |
| 1 | headfree |
| 2 | horizon |
| 3 | angle |
| 4 | mag |
| 5 | baro |
| 6 | special |
Modes 0 to 5 functions:
| function | name |
|----------|-------|
| 0 | north |
| 1 | east |
| 2 | south |
| 3 | west |
| 4 | up |
| 5 | down |
Mode 6 use these functions:
| function | name |
|----------|--------------------|
| 0 | disarmed |
| 1 | armed |
| 2 | animation |
| 3 | background |
| 4 | blink background |
| 5 | gps: no satellites |
| 6 | gps: no fix |
| 7 | gps: 3D fix |
The ColorIndex is picked from the colors array ("palette").
Examples (using the default colors):
- set armed color to red: ```mode_color 6 1 2```
- set disarmed color to yellow: ```mode_color 6 0 4```
- set Headfree mode 'south' to Cyan: ```mode_color 1 2 8```
## Positioning
Cut the strip into sections as per diagrams below. When the strips are cut ensure you reconnect each output to each input with cable where the break is made.
e.g. connect 5V out to 5V in, GND to GND and Data Out to Data In.
Orientation is when viewed with the front of the aircraft facing away from you and viewed from above.
### Example 12 LED config
The default configuration is as follows
```
led 0 15,15:ES:IA:0
led 1 15,8:E:WF:0
led 2 15,7:E:WF:0
led 3 15,0:NE:IA:0
led 4 8,0:N:F:0
led 5 7,0:N:F:0
led 6 0,0:NW:IA:0
led 7 0,7:W:WF:0
led 8 0,8:W:WF:0
led 9 0,15:SW:IA:0
led 10 7,15:S:WF:0
led 11 8,15:S:WF:0
led 12 7,7:U:WF:0
led 13 8,7:U:WF:0
led 14 7,8:D:WF:0
led 15 8,8:D:WF:0
led 16 8,9::R:3
led 17 9,10::R:3
led 18 10,11::R:3
led 19 10,12::R:3
led 20 9,13::R:3
led 21 8,14::R:3
led 22 7,14::R:3
led 23 6,13::R:3
led 24 5,12::R:3
led 25 5,11::R:3
led 26 6,10::R:3
led 27 7,9::R:3
led 28 0,0:::0
led 29 0,0:::0
led 30 0,0:::0
led 31 0,0:::0
```
Which translates into the following positions:
```
6 3
\ /
\ 5-4 /
\ FRONT /
7,8 | 12-15 | 1,2
/ BACK \
/ 10,11 \
/ \
9 0
RING 16-27
```
LEDs 0,3,6 and 9 should be placed underneath the quad, facing downwards.
LEDs 1-2, 4-5, 7-8 and 10-11 should be positioned so the face east/north/west/south, respectively.
LEDs 12-13 should be placed facing down, in the middle
LEDs 14-15 should be placed facing up, in the middle
LEDs 16-17 should be placed in a ring and positioned at the rear facing south.
This is the default so that if you don't want to place LEDs top and bottom in the middle just connect the first 12 LEDs.
### Example 16 LED config
```
led 0 15,15:SD:IA:0
led 1 8,8:E:FW:0
led 2 8,7:E:FW:0
led 3 15,0:ND:IA:0
led 4 7,7:N:FW:0
led 5 8,7:N:FW:0
led 6 0,0:ND:IA:0
led 7 7,7:W:FW:0
led 8 7,8:W:FW:0
led 9 0,15:SD:IA:0
led 10 7,8:S:FW:0
led 11 8,8:S:FW:0
led 12 7,7:D:FW:0
led 13 8,7:D:FW:0
led 14 7,7:U:FW:0
led 15 8,7:U:FW:0
```
Which translates into the following positions:
```
6 3
\ /
\ 5-4 /
7 \ FRONT / 2
| 12-15 |
8 / BACK \ 1
/ 10-11 \
/ \
9 0
```
LEDs 0,3,6 and 9 should be placed underneath the quad, facing downwards.
LEDs 1-2, 4-5, 7-8 and 10-11 should be positioned so the face east/north/west/south, respectively.
LEDs 12-13 should be placed facing down, in the middle
LEDs 14-15 should be placed facing up, in the middle
### Exmple 28 LED config
```
# right rear cluster
led 0 9,9:S:FWT:0
led 1 10,10:S:FWT:0
led 2 11,11:S:IA:0
led 3 11,11:E:IA:0
led 4 10,10:E:AT:0
led 5 9,9:E:AT:0
# right front cluster
led 6 10,5:S:F:0
led 7 11,4:S:F:0
led 8 12,3:S:IA:0
led 9 12,2:N:IA:0
led 10 11,1:N:F:0
led 11 10,0:N:F:0
# center front cluster
led 12 7,0:N:FW:0
led 13 6,0:N:FW:0
led 14 5,0:N:FW:0
led 15 4,0:N:FW:0
# left front cluster
led 16 2,0:N:F:0
led 17 1,1:N:F:0
led 18 0,2:N:IA:0
led 19 0,3:W:IA:0
led 20 1,4:S:F:0
led 21 2,5:S:F:0
# left rear cluster
led 22 2,9:W:AT:0
led 23 1,10:W:AT:0
led 24 0,11:W:IA:0
led 25 0,11:S:IA:0
led 26 1,10:S:FWT:0
led 27 2,9:S:FWT:0
```
```
16-18 9-11
19-21 \ / 6-8
\ 12-15 /
\ FRONT /
/ BACK \
/ \
22-24 / \ 3-5
25-27 0-2
```
All LEDs should face outwards from the chassis in this configuration.
Note:
This configuration is specifically designed for the [Alien Spider AQ50D PRO 250mm frame](http://www.goodluckbuy.com/alien-spider-aq50d-pro-250mm-mini-quadcopter-carbon-fiber-micro-multicopter-frame.html).
## Troubleshooting
On initial power up the LEDs on the strip will be set to WHITE. This means you can attach a current meter to verify
the current draw if your measurement equipment is fast enough. Most 5050 LEDs will draw 0.3 Watts a piece.
This also means that you can make sure that each R,G and B LED in each LED module on the strip is also functioning.
After a short delay the LEDs will show the unarmed color sequence and or low-battery warning sequence.
Also check that the feature `LED_STRIP` was correctly enabled and that it does not conflict with other features, as above.
docs/Lights.md
+33
View File
@@ -0,0 +1,33 @@
# Digital output for controlling lights
This features allows the control of generic non adressable lights with the `LIGHTS` flight mode. It also allows the FC to turn on or flash the lights in the case of a failsafe event.
## Custom firmware build
A custom build is required. The `USE_LIGHTS` macro must be defined in the `target.h` file corresponding to the FC this feature should be enabled on. Also the MCU pin to use as output for controlling the electronic power switch must be defined: `LIGHTS_PIN`.
Example:
```
#define USE_LIGHTS
#define LIGHTS_PIN PA1 // Use PA1 pin as output
```
## Run-time configuration
Once a flight controller board is flashed with a custom build including the previously decribed changes a new `LIGHTS` flight mode will be available. When this mode is enabled the output pin will switch to a high state and output 3.3V otherwise the pin is in the low state and connected to ground.
The default settings will also make the lights flash in the case of a failsafe event. By default a 100ms flash every second (1Hz).
Settings associated with this feature:
- `failsafe_lights` can be `ON` or `OFF`
- `failsafe_lights_flash_period` in milliseconds
- `failsafe_lights_on_time` duration of the flash for every period in milliseconds
If `failsafe_lights_on_time` is greater or equal to `failsafe_lights_flash_period` the lights will stay continuously on during the failsafe event.
## Power driver
The MCU output pins cannot drive loads greater than a few milliamperes. You will need an electronic power switch to drive the lights like the following example circuit (Don't forget the current limiting resistor(s) if you are using LEDs which don't have built-in current limiting, not included in this schematic).
### Example schematic of a N-FET based power switch capable of driving higher than 10A loads
![Example schematic](assets/images/lights_power_schematic.png)
docs/Mixer.md
+106
View File
@@ -0,0 +1,106 @@
# Mixer and platform type
Mixing rules determine how servos and motors react to user and FC inputs. INAV supports various preset mixer configurations as well as custom mixing rules.
## Configuration
The mixer can be configured through the `Mixer` tab of the graphical user interface or using the CLI commands `mmix` and `smix`. `mmix` to define motor mixing rules and `smix` to define servo mixing rules.
To use a mixer preset first select the platform type then the mixer preset matching your aircraft and either press the `Load and apply` or `Load mixer` buttons. The `Load and apply` button will load the mixer, save it and ask to reboot the flight controller. The `Load mixer` button only loads the preset mixing rules, you can then edit them to suit your needs and when you are done you need to press the `Save and Reboot` button to save the rules.
Watch [this video](https://www.youtube.com/watch?v=0cLFu-5syi0) for a detailed description of the GUI and the documentation bellow for more details.
## Platform type
The platform type determines what features will be available to match the type of aircraft: available flight modes, flight modes behaviour, availability of flaps and displayed types of mixer presets. It can be set through the GUI's `Mixer tab` or through the CLI's `platform_type` setting.
Currently, following platform types are supported:
* MULTIROTOR
* AIRPLANE
* TRICOPTER
## Writing custom mixing rules
## Motor Mixing
A motor mixing rule is needed for each motor. Each rule defines weights that determine how the motor it applies to will change its speed relative to the requested throttle and flight dynamics: roll rate, pitch rate and yaw rate. The heigher a weight the more the input will have an impact on the speed of the motor. Refer to the following table for the meaning of each weight.
| Weight | Definition |
| ---------------------- | ---------- |
| THROTTLE | Speed of the motor relative to throttle. Range [0.0, 1.0]. A motor with a weight of 0.5 will receive a command that will half of a motor with a 1.0 weight |
| ROLL | Indicates how much roll authority this motor imparts to the roll rate of the aircraft. Range [-1.0, 1.0]. For fixed wing models this is usually set to 0. A positive value means that the motor needs to accelerate for a positive roll rate request (rolling right). A negative value means that the motor needs to decelerate. |
| PITCH | Indicates how much pitch authority this motor imparts to the pitch rate of the aircraft. Range [-1.0, 1.0]. For fixed wing models this is usually set to 0. A positive value means that the motor needs to accelerate for a positive pitch rate request (pitching down). A negative value means that the motor needs to decelerate. |
| YAW | Indicates how much yaw authority this motor imparts to the yaw rate of the aircraft. Range [-1.0, 1.0]. For fixed wing models with more than one motor this weight can be used to setup differential thrust. For fixed wing models with only one motor this is usually set to 0. A positive value means that the motor needs to accelerate for a positive yaw rate request (clockwise yaw seen from the top of the model). A negative value means that the motor needs to decelerate |
CLI commands to configure motor mixing rules:
The `mmix reset` command removes all the existing motor mixing rules.
The `mmix` command is used to list, create or modify rules. To list the currently defined rules run the `mmix` command without parameters.
To create or modify rules use the `mmix` command with the following syntax: `mmix <n> <throttle> <roll> <pitch> <yaw>`. `<n>` is representing the index of the motor output pin (integer). The other parameters are decimal weights for each of the inputs. To disable a mixing rule set the `throttle` weight to 0.
## Servo Mixing
At least one servo mixing rule is needed for each servo. Each rule defines how a servo will move relative to a specific input like a RC channel, or a requested flight dynamics rate or position from the flight controller.
Each servo mixing rule has the following parameters:
* Servo index: defines which servo the rule will apply to. The absolute value of the index is not important, what matters is only the relative difference between the used indexes. The rule with the smaller servo index will apply to the first servo, the next higher servo index to the second servo, etc. More than one rule can use the same servo index. The output of the rules with the same servo index are added together to give the final output for the specified servo.
* Input: the input for the mixing rule, see a summary of the input types table bellow.
* Weight: percentage of the input to forward to the servo. Range [-1000, 1000]. Mixing rule output = input * weight. If the output of a set of mixing rules is lower/higher than the defined servo min/max the output is clipped (the servo will never travel farther than the set min/max).
* Speed: maximum rate of change of the mixing rule output. Used to limit the servo speed. 1 corresponds to maximum 10µs/s output rate of change. Set to 0 for no speed limit. For example: 10 = full sweep (1000 to 2000) in 10s, 100 = full sweep in 1s.
| CLI input ID | Mixer input | Description |
|----|--------------------------|------------------------------------------------------------------------------|
| 0 | Stabilised ROLL | Roll command from the flight controller. Depends on the selected flight mode(s) |
| 1 | Stabilised PITCH | Pitch command from the flight controller. Depends on the selected flight mode(s) |
| 2 | Stabilised YAW | Yaw command from the flight controller. Depends on the selected flight mode(s) |
| 3 | Stabilised THROTTLE | Throttle command from the flight controller. Depends on the selected flight mode(s) |
| 4 | RC ROLL | Raw roll RC channel |
| 5 | RC PITCH | Raw pitch RC channel |
| 6 | RC YAW | Raw yaw RC channel |
| 7 | RC THROTTLE | Raw throttle RC channel |
| 8 | RC channel 5 | Raw RC channel 5 |
| 9 | RC channel 6 | Raw RC channel 6 |
| 10 | RC channel 7 | Raw RC channel 7 |
| 11 | RC channel 8 | Raw RC channel 8 |
| 12 | GIMBAL PITCH | Scaled pitch attitude of the aircraft [-90°, 90°] => [-500, 500] |
| 13 | GIMBAL ROLL | Scaled roll attitude of the aircraft [-180°, 180°] => [-500, 500] |
| 14 | FEATURE FLAPS | This input value is equal to the `flaperon_throw_offset` setting when the `FLAPERON` flight mode is enabled, 0 otherwise |
| 15 | RC channel 9 | Raw RC channel 9 |
| 16 | RC channel 10 | Raw RC channel 10 |
| 17 | RC channel 11 | Raw RC channel 11 |
| 18 | RC channel 12 | Raw RC channel 12 |
| 19 | RC channel 13 | Raw RC channel 13 |
| 20 | RC channel 14 | Raw RC channel 14 |
| 21 | RC channel 15 | Raw RC channel 15 |
| 22 | RC channel 16 | Raw RC channel 16 |
| 23 | Stabilized ROLL+ | Clipped between 0 and 1000 |
| 24 | Stabilized ROLL- | Clipped between -1000 and 0 |
| 25 | Stabilized PITCH+ | Clipped between 0 and 1000 |
| 26 | Stabilized PITCH- | Clipped between -1000 and 0 |
| 27 | Stabilized YAW+ | Clipped between 0 and 1000 |
| 28 | Stabilized YAW- | Clipped between -1000 and 0 |
| 29 | FIXED-VALUE (MAX) | Fixed percentage of total range |
The `smix reset` command removes all the existing motor mixing rules.
The `smix` command is used to list, create or modify rules. To list the currently defined rules run the `smix` command without parameters.
To create or modify rules use the `smix` command with the following syntax: `smix <n> <servo_index> <input_id> <weight> <speed> <logic_condition_id>`. `<n>` is representing the index of the servo mixing rule to create or modify (integer). To disable a mixing rule set the weight to 0.
`logic_condition_id` default value is `-1` for rules that should be always executed.
### Logic Conditions
[Logic Conditions](Logic%20Conditions.md) allows to activate/deactivate `smix` rules based on user input and flight parameters. If Logic Condition evaluates as `false`, smix rule connected with with LC will not be active and used inside the Mixer.
This mechanism allows to move servos when desired conditions are met. For example, if an airplane is equipped with a pitot tube and flaps, flaps can be automatically deployed when airspeed goes below a threshold.
Other usages can be:
* automatic parachute deployment
* VTOL and especially tail-sitters that require change in mixings during flight mode transition
* crowbar airbrakes
* any kind of servo mixings that should be changed during flight
docs/MixerProfile.md
+118
View File
@@ -0,0 +1,118 @@
# MixerProfile
A MixerProfile is a set of motor mixer, servo-mixer and platform type configuration settings. It is designed for experienced inav users.
### For a tutorial of vtol setup, Read https://github.com/iNavFlight/inav/blob/master/docs/VTOL.md
Not limited to VTOL. air/land/sea mixed vehicle is also achievable with this feature. Model behaves according to current mixer_profile's platform_type and configured custom motor/servo mixer
Currently two profiles are supported on targets other than F411(due to resource constraints on F411). i.e VTOL transition is not available on F411.
For VTOL setup. one mixer_profile is used for multi-rotor(MR) and the other is used for fixed-wing(FW)
By default, switching between profiles requires reboot to take affect. However, using the RC mode: `MIXER PROFILE 2` will allow in flight switching for things like VTOL operation
. And will re-initialize pid and navigation controllers for current MC or FW flying mode.
Please note that this is an emerging / experimental capability that will require some effort by the pilot to implement.
## Mixer Transition input
Typically, 'transition input' will be useful in MR mode to gain airspeed.
The associated motor or servo will then move accordingly when transition mode is activated.
Transition input is disabled when navigation mode is activate
The use of Transition Mode is recommended to enable further features and future developments like fail-safe support. Mapping motor to servo output, or servo with logic conditions is **not** recommended
## Servo
`Mixer Transition` is the input source for transition input; use this to tilt motor to gain airspeed.
Example: Increase servo 1 output by +45 with speed of 150 when transition mode is activated for tilted motor setup:
```
# rule no; servo index; input source; rate; speed; activate logic function number
smix 6 1 38 45 150 -1
```
## Motor
The default `mmix` throttle value is 0.0, It will not show in `diff` command when throttle value is 0.0 (unused);
- 0.0<throttle<=1.0 : normal mapping
- -1.0<throttle<=0.0 : motor stop, default value 0, set to -1 to use a place holder for subsequent motor rules
- -2.0<throttle<-1.0 : spin regardless of throttle position at speed `abs(throttle)-1` when Mixer Transition is activated.
Airmode type should be set to "STICK_CENTER". Airmode type must NOT be set to "THROTTLE_THRESHOLD". If set to throttle threshold the (-) motor will spin till throttle threshold is passed.
Example: This will spin motor number 5 (counting from 1) at 20%, in transition mode only, to gain speed for a "4 rotor 1 pusher" setup:
```
# motor number; throttle; roll; pitch; yaw
mmix 4 -1.200 0.000 0.000 0.000
```
## RC mode settings
It is recommend that the pilot uses a RC mode switch to activate modes or switch profiles.
Profile files Switching is not available until the runtime sensor calibration is done. Switching is NOT available when navigation mode is activate.
`mixer_profile` 1 will be used as default, `mixer_profile` 2 will be used when the `MIXER PROFILE 2` mode box is activated.
Set `MIXER TRANSITION` accordingly when you want to use `MIXER TRANSITION` input for motors and servos. Here is sample of using these RC modes:
![Alt text](Screenshots/mixer_profile.png)
| 1000~1300 | 1300~1700 | 1700~2000 |
| :-- | :-- | :-- |
| FW(profile1) with transition off | MC(profile2) with transition on | MC(profile2) with transition off |
It is also possible to set it as 4 state switch by adding FW(profile1) with transition on.
## Automated Transition
This feature is mainly for RTH in a failsafe event. When set properly, model will use the FW mode to fly home efficiently, And land in the MC mode for easier landing.
`ON` for a mixer_profile\`s `mixer_automated_switch` means to schedule a Automated Transition when RTH head home(applies for MC mixer_profile) or RTH Land(applies for FW mixer_profile) is requested by navigation controller.
Set `mixer_automated_switch` to `ON` in mixer_profile for MC mode. Set `mixer_switch_trans_timer` in mixer_profile for MC mode for the time required to gain airspeed for your model before entering to FW mode.
When `mixer_automated_switch`:`OFF` is set for all mixer_profiles(defaults). Model will not perform automated transition at all.
## TailSitter (planned for INAV 7.1)
TailSitter is supported by add a 90deg offset to the board alignment. Set the board aliment normally in the mixer_profile for FW mode(`set platform_type = AIRPLANE`), The motor trust axis should be same direction as the airplane nose. Then, in the mixer_profile for takeoff and landing set `tailsitter_orientation_offset = ON ` to apply orientation offset. orientation offset will also add a 45deg orientation offset.
## Parameter list (Partial List)
#### Please be aware of what parameter is shared among FW/MC modes and what isn't.
### Shared Parameters
- **Timer Overrides**
- **Outputs [Servo]:**
- Servo min-point, mid-point, max-point settings
- **Motor Configuration:**
- motor_pwm_protocol
- motor_poles
- **Servo Configuration:**
- servo_protocol
- servo_pwm_rate
- **Board Alignment**
- ·······
### Profile-Specific Parameters in VTOL
- **Mixer Profile**
- **Mixer Configuration:**
- platform_type
- motor_stop_on_low
- tailsitter_orientation_offset
- motor_direction_inverted, and more·······
- **Motor Mixing (mmix)**
- **Servo Mixing (smix)**
- **Control Profile**
- PIDs for Roll, Pitch, Yaw
- PIDs for Navigation Modes
- TPA (Throttle PID Attenuation) Settings
- Rate Settings
- ·······
### TailSitter support
TailSitter is supported by add a 90deg offset to the board alignment. Set the board aliment normally in the mixer_profile for FW mode(`set platform_type = AIRPLANE`), The motor trust axis should be same direction as the airplane nose. Then, in the mixer_profile for takeoff and landing `set platform_type = TAILSITTER`. The `TAILSITTER` platform type is same as `MULTIROTOR` platform type, expect for a 90 deg board alignment offset. In `TAILSITTER` mixer_profile, when motor trust/airplane nose is pointing to the sky, 'airplane bottom'/'multi rotor front' should facing forward in model preview. Set the motor/servo mixer according to multirotor orientation, Model should roll around geography's longitudinal axis, the roll axis of `TAILSITTER` will be yaw axis of `AIRPLANE`. In addition, When `MIXER TRANSITION` input is activated, a 45deg offset will be add to the target angle for angle mode.
## Happy flying
Remember that this is currently an emerging capability:
* Test every thing on bench first.
* Try MR or FW mode separately see if there are any problems.
* Use the INAV Discord for help and setup questions; use the Github Issues for reporting bugs and unexpected behaviors. For reporting on Github, a CLI `diff all`, a DVR and a Blackbox log of the incident will assist investigation.
docs/Navigation.md
Executable
+177
View File
@@ -0,0 +1,177 @@
# Navigation
The navigation system in INAV is responsible for assisting the pilot allowing altitude and position hold, return-to-home and waypoint flight.
## NAV ALTHOLD mode - altitude hold
Altitude hold requires a valid source of altitude - barometer, GPS or rangefinder. The best source is chosen automatically.
In this mode THROTTLE stick controls climb rate (vertical velocity). When pilot moves stick up - aircraft goes up, pilot moves stick down -
aircraft descends, you keep stick at neutral position - aircraft maintains current altitude.
### CLI parameters affecting ALTHOLD mode:
* *nav_use_midthr_for_althold* - when set to "0", firmware will remember where your throttle stick was when ALTHOLD was activated - this will be considered neutral position. When set to "1" - 50% throttle will be considered neutral position.
### Related PIDs
PIDs affecting altitude hold: ALT & VEL
PID meaning:
* ALT - translates altitude error to desired climb rate and acceleration. Tune P for altitude-to-velocity regulator and I for velocity-to-acceleration regulator
* VEL - translated Z-acceleration error to throttle adjustment
## Throttle tilt compensation
Throttle tilt compensation attempts to maintain constant vertical thrust when copter is tilted giving additional throttle if tilt angle (pitch/roll) is not zero. Controlled by *throttle_tilt_comp_str* CLI variable.
## NAV POSHOLD mode - position hold
Position hold requires GPS, accelerometer and compass sensors. Multirotor requires barometer, unless is enabled. Flight modes that require a compass (POSHOLD, RTH) are locked until compass is properly calibrated.
When activated, this mode will attempt to keep copter where it is (based on GPS coordinates). From INAV 2.0, POSHOLD is a full 3D position hold. Heading hold in this mode is assumed and activated automatically.
### CLI parameters affecting POSHOLD mode:
* *nav_user_control_mode* - can be set to "0" (GPS_ATTI) or "1" (GPS_CRUISE), controls how firmware will respond to roll/pitch stick movement. When in GPS_ATTI mode, right stick controls attitude, when it is released, new position is recorded and held. When in GPS_CRUISE mode right stick controls velocity and firmware calculates required attitude on its own.
### Related PIDs
PIDs affecting position hold: POS, POSR
PID meaning:
* POS - translated position error to desired velocity, uses P term only
* POSR - translates velocity error to desired acceleration
## NAV RTH - return to home mode
Home for RTH is the position where vehicle was first armed. This position may be offset by the CLI settings `nav_rth_home_offset_distance` and `nav_rth_home_offset_direction`. This position may also be overridden with Safehomes. RTH requires accelerometer, compass and GPS sensors.
RTH requires barometer for multirotor.
RTH will maintain altitude during the return. When home is reached, a copter will attempt automated landing. An airplane will either loiter around the home position, or attempt an automated landing, depending on your settings.
When deciding what altitude to maintain, RTH has 6 different modes of operation (controlled by *nav_rth_alt_mode* and *nav_rth_altitude* cli variables):
* 0 (NAV_RTH_NO_ALT) - keep current altitude during whole RTH sequence (*nav_rth_altitude* is ignored)
* 1 (NAV_RTH_EXTRA_ALT) - climb to current altitude plus extra margin prior to heading home (*nav_rth_altitude* defines the extra altitude (cm))
* 2 (NAV_RTH_CONST_ALT) - climb/descend to predefined altitude before heading home (*nav_rth_altitude* defined altitude above launch point (cm))
* 3 (NAV_RTH_MAX_ALT) - track maximum altitude of the whole flight, climb to that altitude prior to the return (*nav_rth_altitude* is ignored)
* 4 (NAV_RTH_AT_LEAST_ALT) - same as 2 (NAV_RTH_CONST_ALT), but only climb, do not descend
* 5 (NAV_RTH_AT_LEAST_ALT_LINEAR_DESCENT) - Same as 4 (NAV_RTH_AT_LEAST_ALT). But, if above the RTH Altitude, the aircraft will gradually descend to the RTH Altitude. The target is to reach the RTH Altitude as it arrives at the home point. This is to save energy during the RTH.
## NAV WP - Waypoint mode
NAV WP allows the craft to autonomously navigate a set route defined by waypoints that are loaded into the FC as a predefined mission.
## CLI command `wp` to manage waypoints
`wp` - List all waypoints.
`wp load` - Load list of waypoints from EEPROM to FC.
`wp <n> <action> <lat> <lon> <alt> <p1> <p2> <p3> <flag>` - Set parameters of waypoint with index `<n>`. Note that prior to INAV 2.5, the `p2` and `p3` parameters were not required. From 2.5, INAV will accept either version but always saves and lists the later full version.
Parameters:
* `<action>` - The action to be taken at the WP. The following are enumerations are available in INAV 2.6 and later:
* 0 - Unused / Unassigned
* 1 - WAYPOINT
* 3 - POSHOLD_TIME
* 4 - RTH
* 5 - SET_POI
* 6 - JUMP
* 7 - SET_HEAD
* 8 - LAND
* `<lat>` - Latitude (WGS84), in degrees * 1E7 (for example 123456789 means 12.3456789).
* `<lon>` - Longitude.
* `<alt>` - Altitude in cm. See `p3` bit 0 for datum definition.
* `<p1>` - For a RTH waypoint, p1 > 0 enables landing. For a normal waypoint it is the speed to this waypoint (cm/s), it is taken into account only for multicopters and when > 50 and < nav_auto_speed. For POSHOLD TIME waypoint it is time to loiter in seconds. For JUMP it is the target WP **index** (not number). For SET_HEAD, it is the desired heading (0-359) or -1 to cancel a previous SET_HEAD or SET_POI.
* `<p2>` - For a POSHOLD TIME it is the speed to this waypoint (cm/s), it is taken into account only for multicopters and when > 50 and < nav_auto_speed. For JUMP it is the number of iterations of the JUMP.
* `<p3>` - A bitfield with four bits reserved for user specified actions. It is anticipated that these actions will be exposed through the logic conditions.
* Bit 0 - Altitude (`alt`) : Relative (to home altitude) (0) or Absolute (AMSL) (1).
* Bit 1 - WP Action 1
* Bit 2 - WP Action 2
* Bit 3 - WP Action 3
* Bit 4 - WP Action 4
* Bits 5 - 15 : undefined / reserved.
Note:
* If `p2` is specified, then `p3` is also required.
* `p3` is only defined for navigable WP types (WAYPOINT, POSHOLD_TIME, LAND). The affect of specifying a non-zero `p3` for other WP types is undefined.
* `<flag>` - Last waypoint must have `flag` set to 165 (0xA5).
`wp save` - Checks list of waypoints and save from FC to EEPROM (warning: it also saves all unsaved CLI settings like normal `save`).
`wp reset` - Resets the list, sets the number of waypoints to 0 and marks the list as invalid (but doesn't delete the waypoint definitions).
### `wp` example
```
# wp load
# wp
# wp 11 valid
wp 0 1 543533193 -45179273 3500 0 0 0 0
wp 1 1 543535723 -45193913 3500 0 0 0 0
wp 2 1 543544541 -45196617 5000 0 0 0 0
wp 3 1 543546578 -45186895 5000 0 0 0 0
wp 4 6 0 0 0 1 2 0 0
wp 5 1 543546688 -45176009 3500 0 0 0 0
wp 6 1 543541225 -45172673 3500 0 0 0 0
wp 7 6 0 0 0 0 1 0 0
wp 8 3 543531383 -45190405 3500 45 0 0 0
wp 9 1 543548470 -45182104 3500 0 0 0 0
wp 10 8 543540521 -45178091 6000 0 0 0 165
wp 11 0 0 0 0 0 0 0 0
...
wp 59 0 0 0 0 0 0 0 0
```
Note that the `wp` CLI command shows waypoint list indices, while the MW-XML definition used by mwp, ezgui and the configurator use WP numbers.
## Multi-missions
Multi-missions allows up to 9 missions to be stored in the FC at the same time. It is possible to load them into the FC using the CLI. This is acheived by entering single missions into the CLI followed by `wp save` **after** the final mission has been entered (the single missions can be entered one after the other or as a single block entry, it doesn't matter). All missions will then be saved as a Multi Mission in the FC. Saved multi missions display consecutive WP indices from 0 to the last WP in the last mission when displayed using the `wp` command.
E.g. to enter 3 missions in the CLI enter each mission as a single mission (start WP index for each mission must be 0).
```
wp 0 1 545722109 -32869291 5000 0 0 0 0
wp 1 1 545708178 -32642698 5000 0 0 0 0
wp 2 1 545698227 -32385206 5000 0 0 0 165
...
wp 0 1 545599696 -32958555 5000 0 0 0 0
wp 1 1 545537978 -32958555 5000 0 0 0 0
wp 2 1 545547933 -32864141 5000 0 0 0 0
wp 3 1 545597705 -32695913 5000 0 0 0 0
wp 4 1 545552910 -32598066 5000 0 0 0 0
wp 5 6 0 0 0 0 0 0 165
...
wp 0 1 545714148 -32501936 5000 0 0 0 165
# wp save
```
Multi Mission after saving:
```
# wp
# wp 10 valid
wp 0 1 545722109 -32869291 5000 0 0 0 0
wp 1 1 545708178 -32642698 5000 0 0 0 0
wp 2 1 545698227 -32385206 5000 0 0 0 165
wp 3 1 545599696 -32958555 5000 0 0 0 0
wp 4 1 545537978 -32958555 5000 0 0 0 0
wp 5 1 545547933 -32864141 5000 0 0 0 0
wp 6 1 545597705 -32695913 5000 0 0 0 0
wp 7 1 545552910 -32598066 5000 0 0 0 0
wp 8 6 0 0 0 0 0 0 165
wp 9 1 545714148 -32501936 5000 0 0 0 165
wp 10 0 0 0 0 0 0 0 0
wp 11 0 0 0 0 0 0 0 0
wp 12 0 0 0 0 0 0 0 0
...
wp 59 0 0 0 0 0 0 0 0
```
### Changing Mission-Index in flight
The MISSION CHANGE mode allows to switch between multiple stored missions in flight. With mode active the required mission index can be selected by cycling through missions using the WP mode switch. Selected mission is loaded when mission change mode is switched off. Mission index can also be changed through addition of a new Mission Index adjustment function which should be useful for DJI users unable to use the normal OSD mission related fields.
docs/OSD Joystick.md
+94
View File
@@ -0,0 +1,94 @@
# OSD joystick
LED pin can be used to emulate 5key OSD joystick for OSD camera pin, while still driving ws2812 LEDs (shared functionality).
See [LED pin PWM](LED%20pin%20PWM.md) for more details.
Note that for cameras which support RuncamDevice protocol, there is alternative functionality using serial communication: [Runcam device](Runcam%20device.md)
Also special adapters exist to convert RuncamDevice protocol to OSD Joystick: [Runcam control adapter](https://www.runcam.com/download/runcam_control_adapter_manual.pdf)
# OSD Joystick schematics
![alt text](/docs/assets/images/osd_joystick_keys.png "osd jystick keys")
Camera internal resistance seems to be 47kOhm or 9kOhm depending on camera model.
Each key effectively turns on voltage divider. Voltage is sensed by the camera and is compared to the list of keys voltages with some threshold.
Key voltage has to be held for at least 200ms.
To simulate 5key joystick, it is sufficient to generate correct voltage on camera OSD pin.
# Enabling OSD Joystick emulation
```set led_pin_pwm_mode=shared_high```
```set osd_joystick_enabled=on```
Also enable "Multi-color RGB LED Strip support" in Configuration tab.
# Connection diagram
We use LED pin PWM functionality with RC filter to generate voltage:
![alt text](/docs/assets/images/ledpinpwmfilter.png "led pin pwm filter")
# Example PCB layout (SMD components)
RC Filter can be soldered on a small piece of PCB:
![alt text](/docs/assets/images/osd_joystick.jpg "osd joystick")
# Configuring keys voltages
If default voltages does not work with your camera model, then you have to measure voltages and find out corresponding PWM duty ratios.
1. Connect 5keys joystick to camera.
2. Measure voltages on OSD pin while each key is pressed.
3. Connect camera to FC throught RC filter as shown on schematix above.
4. Enable OSD Joystick emulation (see "Enabling OSD Joystick emulation" above)
4. Use cli command ```led_pin_pwm <value>```, value = 0...100 to find out PWM values for each voltage.
5. Specify PWM values in configuration and save:
```set osd_joystick_down=0```
```set osd_joystick_up=48```
```set osd_joystick_left=63```
```set osd_joystick_right=28```
```set osd_joystick_enter=75```
```save```
# Entering OSD Joystick emulation mode
Emulation can be enabled in unarmed state only.
OSD Joystick emulation mode is enabled using the following stick combination:
```Throttle:CENTER Yaw:RIGHT```
Than camera OSD can be navigated using right stick. See [Controls](Controls.md) for all stick combinations.
*Note that the same stick combination is used to enable 5keys joystick emulation with RuncamDevice protocol.*
Mode is exited using stick combination:
```Throttle:CENTER Yaw:LEFT```
# RC Box
There are 3 RC Boxes which can be used in armed and unarmed state:
- Camera 1 - Enter
- Camera 2 - Up
- Camera 3 - Down
Other keys can be emulated using Programming framework ( see [LED pin PWM](LED%20pin%20PWM.md) for more details ).
# Behavior on boot
There is ~2 seconds LOW pulse during boot sequence, which corresponds to DOWN key. Fortunately, cameras seem to ignore any key events few seconds after statup.
docs/OSD.md
+267
View File
@@ -0,0 +1,267 @@
# On Screen Display
The On Screen Display, or OSD, is a feature that overlays flight data over the video image. This can be done on the flight controller, using the analogue MAX7456 chip. Digital systems take the OSD data, via MSP DisplayPort, send it to the video receiver; which combines the data with the image. You can specify what elements are displayed, and their locations on the image. Most systems are character based, and use the MAX7456 analogue setup, or MSP DisplayPort. However, there are some different systems which are also supported. Such as the canvas based FrSKY PixelOSD on analogue. Canvas OSDs draw shapes on the image. Whereas character based OSDs use font characters to display the data.
General OSD information is in this document. Other documents cover specific OSD-related topics:
* [Custom OSD Elements](https://github.com/iNavFlight/inav/wiki/Custom-OSD-Elements)
* [OSD Hud and ESP32 radars](https://github.com/iNavFlight/inav/wiki/OSD-Hud-and-ESP32-radars)
* [OSD Joystick](https://github.com/iNavFlight/inav/blob/master/docs/OSD%20Joystick.md)
* [DJI compatible OSD.md](https://github.com/iNavFlight/inav/blob/master/docs/DJI%20compatible%20OSD.md)
* [Pixel OSD FAQ](https://github.com/iNavFlight/inav/wiki/Pixel-OSD-FAQs)
## Features and Limitations
Not all OSDs are created equally. This table shows the differences between the different systems available.
| OSD System | Character grid | Character | Canvas | MSP DisplayPort | All elements supported |
|-----------------------------|----------------|-----------|--------|-----------------|-------------------------|
| Analogue PAL | 30 x 16 | X | | | YES |
| Analogue NTSC | 30 x 13 | X | | | YES |
| PixelOSD | As PAL or NTSC | | X | | YES |
| DJI OSD | 30 x 16 | X | | | NO - BF Characters only |
| DJI WTFOS | 60 x 22 | X | | X | YES |
| HDZero | 50 x 18 | X | | X | YES |
| Avatar | 53 x 20 | X | | X | YES |
| DJI O3 Goggles V2 + WTFOS | 53 x 20 | X | | X | YES |
| DJI Goggles 2 and newer | 53 x 20 (HD) | X | | X | YES (no custom fonts) |
## OSD Elements
Here are the OSD Elements provided by INAV.
| ID | Element | Added | Notes |
|-----|--------------------------------------------------|--------|-------|
| 0 | OSD_RSSI_VALUE | 1.0.0 | |
| 1 | OSD_MAIN_BATT_VOLTAGE | 1.0.0 | |
| 2 | OSD_CROSSHAIRS | 1.0.0 | |
| 3 | OSD_ARTIFICIAL_HORIZON | 1.0.0 | |
| 4 | OSD_HORIZON_SIDEBARS | 1.0.0 | |
| 5 | OSD_ONTIME | 1.0.0 | |
| 6 | OSD_FLYTIME | 1.0.0 | |
| 7 | OSD_FLYMODE | 1.0.0 | |
| 8 | OSD_CRAFT_NAME | 1.0.0 | |
| 9 | OSD_THROTTLE_POS | 1.0.0 | |
| 10 | OSD_VTX_CHANNEL | 1.0.0 | |
| 11 | OSD_CURRENT_DRAW | 1.0.0 | |
| 12 | OSD_MAH_DRAWN | 1.0.0 | |
| 13 | OSD_GPS_SPEED | 1.0.0 | |
| 14 | OSD_GPS_SATS | 1.0.0 | |
| 15 | OSD_ALTITUDE | 1.0.0 | |
| 16 | OSD_ROLL_PIDS | 1.6.0 | |
| 17 | OSD_PITCH_PIDS | 1.6.0 | |
| 18 | OSD_YAW_PIDS | 1.6.0 | |
| 19 | OSD_POWER | 1.6.0 | |
| 20 | OSD_GPS_LON | 1.6.0 | |
| 21 | OSD_GPS_LAT | 1.6.0 | |
| 22 | OSD_HOME_DIR | 1.6.0 | |
| 23 | OSD_HOME_DIST | 1.6.0 | |
| 24 | OSD_HEADING | 1.6.0 | |
| 25 | OSD_VARIO | 1.6.0 | |
| 26 | OSD_VERTICAL_SPEED_INDICATOR | 1.6.0 | |
| 27 | OSD_AIR_SPEED | 1.7.3 | |
| 28 | OSD_ONTIME_FLYTIME | 1.8.0 | |
| 29 | OSD_RTC_TIME | 1.8.0 | |
| 30 | OSD_MESSAGES | 1.8.0 | |
| 31 | OSD_GPS_HDOP | 1.8.0 | |
| 32 | OSD_MAIN_BATT_CELL_VOLTAGE | 1.8.0 | |
| 33 | OSD_SCALED_THROTTLE_POS | 1.8.0 | |
| 34 | OSD_HEADING_GRAPH | 1.8.0 | |
| 35 | OSD_EFFICIENCY_MAH_PER_KM | 1.9.0 | |
| 36 | OSD_WH_DRAWN | 1.9.0 | |
| 37 | OSD_BATTERY_REMAINING_CAPACITY | 1.9.0 | |
| 38 | OSD_BATTERY_REMAINING_PERCENT | 1.9.0 | |
| 39 | OSD_EFFICIENCY_WH_PER_KM | 1.9.0 | |
| 40 | OSD_TRIP_DIST | 1.9.1 | |
| 41 | OSD_ATTITUDE_PITCH | 2.0.0 | |
| 42 | OSD_ATTITUDE_ROLL | 2.0.0 | |
| 43 | OSD_MAP_NORTH | 2.0.0 | |
| 44 | OSD_MAP_TAKEOFF | 2.0.0 | |
| 45 | OSD_RADAR | 2.0.0 | |
| 46 | OSD_WIND_SPEED_HORIZONTAL | 2.0.0 | |
| 47 | OSD_WIND_SPEED_VERTICAL | 2.0.0 | |
| 48 | OSD_REMAINING_FLIGHT_TIME_BEFORE_RTH | 2.0.0 | |
| 49 | OSD_REMAINING_DISTANCE_BEFORE_RTH | 2.0.0 | |
| 50 | OSD_HOME_HEADING_ERROR | 2.0.0 | |
| 51 | OSD_COURSE_HOLD_ERROR | 2.0.0 | |
| 52 | OSD_COURSE_HOLD_ADJUSTMENT | 2.0.0 | |
| 53 | OSD_SAG_COMPENSATED_MAIN_BATT_VOLTAGE | 2.0.0 | |
| 54 | OSD_MAIN_BATT_SAG_COMPENSATED_CELL_VOLTAGE | 2.0.0 | |
| 55 | OSD_POWER_SUPPLY_IMPEDANCE | 2.0.0 | |
| 56 | OSD_LEVEL_PIDS | 2.0.0 | |
| 57 | OSD_POS_XY_PIDS | 2.0.0 | |
| 58 | OSD_POS_Z_PIDS | 2.0.0 | |
| 59 | OSD_VEL_XY_PIDS | 2.0.0 | |
| 60 | OSD_VEL_Z_PIDS | 2.0.0 | |
| 61 | OSD_HEADING_P | 2.0.0 | |
| 62 | OSD_BOARD_ALIGN_ROLL | 2.0.0 | |
| 63 | OSD_BOARD_ALIGN_PITCH | 2.0.0 | |
| 64 | OSD_RC_EXPO | 2.0.0 | |
| 65 | OSD_RC_YAW_EXPO | 2.0.0 | |
| 66 | OSD_THROTTLE_EXPO | 2.0.0 | |
| 67 | OSD_PITCH_RATE | 2.0.0 | |
| 68 | OSD_ROLL_RATE | 2.0.0 | |
| 69 | OSD_YAW_RATE | 2.0.0 | |
| 70 | OSD_MANUAL_RC_EXPO | 2.0.0 | |
| 71 | OSD_MANUAL_RC_YAW_EXPO | 2.0.0 | |
| 72 | OSD_MANUAL_PITCH_RATE | 2.0.0 | |
| 73 | OSD_MANUAL_ROLL_RATE | 2.0.0 | |
| 74 | OSD_MANUAL_YAW_RATE | 2.0.0 | |
| 75 | OSD_NAV_FW_CRUISE_THR | 2.0.0 | |
| 76 | OSD_NAV_FW_PITCH2THR | 2.0.0 | |
| 77 | OSD_FW_MIN_THROTTLE_DOWN_PITCH_ANGLE | 2.0.0 | |
| 78 | OSD_DEBUG | 2.0.0 | |
| 79 | OSD_FW_ALT_PID_OUTPUTS | 2.0.0 | |
| 80 | OSD_FW_POS_PID_OUTPUTS | 2.0.0 | |
| 81 | OSD_MC_VEL_X_PID_OUTPUTS | 2.0.0 | |
| 82 | OSD_MC_VEL_Y_PID_OUTPUTS | 2.0.0 | |
| 83 | OSD_MC_VEL_Z_PID_OUTPUTS | 2.0.0 | |
| 84 | OSD_MC_POS_XYZ_P_OUTPUTS | 2.0.0 | |
| 85 | OSD_3D_SPEED | 2.1.0 | |
| 86 | OSD_IMU_TEMPERATURE | 2.1.0 | |
| 87 | OSD_BARO_TEMPERATURE | 2.1.0 | |
| 88 | OSD_TEMP_SENSOR_0_TEMPERATURE | 2.1.0 | |
| 89 | OSD_TEMP_SENSOR_1_TEMPERATURE | 2.1.0 | |
| 90 | OSD_TEMP_SENSOR_2_TEMPERATURE | 2.1.0 | |
| 91 | OSD_TEMP_SENSOR_3_TEMPERATURE | 2.1.0 | |
| 92 | OSD_TEMP_SENSOR_4_TEMPERATURE | 2.1.0 | |
| 93 | OSD_TEMP_SENSOR_5_TEMPERATURE | 2.1.0 | |
| 94 | OSD_TEMP_SENSOR_6_TEMPERATURE | 2.1.0 | |
| 95 | OSD_TEMP_SENSOR_7_TEMPERATURE | 2.1.0 | |
| 96 | OSD_ALTITUDE_MSL | 2.1.0 | |
| 97 | OSD_PLUS_CODE | 2.1.0 | |
| 98 | OSD_MAP_SCALE | 2.2.0 | |
| 99 | OSD_MAP_REFERENCE | 2.2.0 | |
| 100 | OSD_GFORCE | 2.2.0 | |
| 101 | OSD_GFORCE_X | 2.2.0 | |
| 102 | OSD_GFORCE_Y | 2.2.0 | |
| 103 | OSD_GFORCE_Z | 2.2.0 | |
| 104 | OSD_RC_SOURCE | 2.2.0 | |
| 105 | OSD_VTX_POWER | 2.2.0 | |
| 106 | OSD_ESC_RPM | 2.3.0 | |
| 107 | OSD_ESC_TEMPERATURE | 2.5.0 | |
| 108 | OSD_AZIMUTH | 2.6.0 | |
| 109 | OSD_CRSF_RSSI_DBM | 2.6.0 | |
| 110 | OSD_CRSF_LQ | 2.6.0 | |
| 111 | OSD_CRSF_SNR_DB | 2.6.0 | |
| 112 | OSD_CRSF_TX_POWER | 2.6.0 | |
| 113 | OSD_GVAR_0 | 2.6.0 | |
| 114 | OSD_GVAR_1 | 2.6.0 | |
| 115 | OSD_GVAR_2 | 2.6.0 | |
| 116 | OSD_GVAR_3 | 2.6.0 | |
| 117 | OSD_TPA | 2.6.0 | |
| 118 | OSD_NAV_FW_CONTROL_SMOOTHNESS | 2.6.0 | |
| 119 | OSD_VERSION | 3.0.0 | |
| 120 | OSD_RANGEFINDER | 3.0.0 | |
| 121 | OSD_PLIMIT_REMAINING_BURST_TIME | 3.0.0 | |
| 122 | OSD_PLIMIT_ACTIVE_CURRENT_LIMIT | 3.0.0 | |
| 123 | OSD_PLIMIT_ACTIVE_POWER_LIMIT | 3.0.0 | |
| 124 | OSD_GLIDESLOPE | 3.0.1 | |
| 125 | OSD_GPS_MAX_SPEED | 4.0.0 | |
| 126 | OSD_3D_MAX_SPEED | 4.0.0 | |
| 127 | OSD_AIR_MAX_SPEED | 4.0.0 | |
| 128 | OSD_ACTIVE_PROFILE | 4.0.0 | |
| 129 | OSD_MISSION | 4.0.0 | |
| 130 | OSD_SWITCH_INDICATOR_0 | 5.0.0 | |
| 131 | OSD_SWITCH_INDICATOR_1 | 5.0.0 | |
| 132 | OSD_SWITCH_INDICATOR_2 | 5.0.0 | |
| 133 | OSD_SWITCH_INDICATOR_3 | 5.0.0 | |
| 134 | OSD_TPA_TIME_CONSTANT | 5.0.0 | |
| 135 | OSD_FW_LEVEL_TRIM | 5.0.0 | |
| 136 | OSD_GLIDE_TIME_REMAINING | 6.0.0 | |
| 137 | OSD_GLIDE_RANGE | 6.0.0 | |
| 138 | OSD_CLIMB_EFFICIENCY | 6.0.0 | |
| 139 | OSD_NAV_WP_MULTI_MISSION_INDEX | 6.0.0 | |
| 140 | OSD_GROUND_COURSE | 6.0.0 | |
| 141 | OSD_CROSS_TRACK_ERROR | 6.0.0 | |
| 142 | OSD_PILOT_NAME | 6.0.0 | |
| 143 | OSD_PAN_SERVO_CENTRED | 6.0.0 | |
| 144 | OSD_MULTI_FUNCTION | 7.0.0 | |
| 145 | OSD_ODOMETER | 7.0.0 | For this to work correctly, stats must be enabled (`set stats=ON`). Otherwise, this will show the total flight distance. |
| 146 | OSD_PILOT_LOGO | 7.0.0 | |
| 147 | OSD_CUSTOM_ELEMENT_1 | 7.0.0 | |
| 148 | OSD_CUSTOM_ELEMENT_2 | 7.0.0 | |
| 149 | OSD_CUSTOM_ELEMENT_3 | 7.0.0 | |
| 150 | OSD_ADSB_WARNING | 7.0.0 | |
| 151 | OSD_ADSB_INFO | 7.0.0 | |
| 152 | OSD_BLACKBOX | 8.0.0 | The element will be hidden unless blackbox recording is attempted. |
| 153 | OSD_FORMATION_FLIGHT | 8.0.0 | |
| 154 | OSD_CUSTOM_ELEMENT_4 | 8.0.0 | |
| 155 | OSD_CUSTOM_ELEMENT_5 | 8.0.0 | |
| 156 | OSD_CUSTOM_ELEMENT_6 | 8.0.0 | |
| 157 | OSD_CUSTOM_ELEMENT_7 | 8.0.0 | |
| 158 | OSD_CUSTOM_ELEMENT_8 | 8.0.0 | |
| 159 | OSD_LQ_DOWNLINK | 8.0.0 | |
| 160 | OSD_RX_POWER_DOWNLINK | 8.0.0 | |
| 161 | OSD_RX_BAND | 8.0.0 | |
| 162 | OSD_RX_MODE | 8.0.0 | |
| 163 | OSD_COURSE_TO_FENCE | 8.0.0 | |
| 164 | OSD_H_DIST_TO_FENCE | 8.0.0 | |
| 165 | OSD_V_DIST_TO_FENCE | 8.0.0 | |
| 166 | OSD_NAV_FW_ALT_CONTROL_RESPONSE | 8.0.0 | |
| 167 | OSD_NAV_MIN_GROUND_SPEED | 9.0.0 | |
| 168 | OSD_THROTTLE_GAUGE | 9.0.0 | |
# Pilot Logos
From INAV 7.0.0, pilots can add their own logos to the OSD. These can appear in 2 places: the power on/arming screens or as an element on the standard OSD. Please note that the power on/arming screen large pilot logos are only available on HD systems.
To use the pilot logos, you will need to make a custom font for your OSD system. Base fonts and information can be found in the [OSD folder](https://github.com/iNavFlight/inav-configurator/tree/master/resources/osd) in the Configurator resources. Each system will need a specific method to create the font image files. So they will not be covered here. There are two pilot logos.
<img alt="Default small INAV Pilot logo" src="https://github.com/iNavFlight/inav-configurator/raw/master/resources/osd/digital/default/24x36/469_471.png" align="right" />The small pilot logo appears on standard OSD layouts, when you add the elemement to the OSD screen. This is a 3 character wide symbol (characters 469-471).
<img alt="Default large INAV Pilot logo" src="https://github.com/iNavFlight/inav-configurator/raw/master/resources/osd/digital/default/24x36/472_511.png" align="right" />The large pilot logo appears on the power on and arming screens, when you enable the feature in the CLI. To do this, set the `osd_use_pilot_logo` parameter to `on`. This is a 10 character wide, 4 character high symbol (characters 472-511).
## Settings
* `osd_arm_screen_display_time` The amount of time the arming screen is displayed.
* `osd_inav_to_pilot_logo_spacing` The spacing between two logos. This can be set to `0`, so the original INAV logo and Pilot Logo can be combined in to a larger logo. Any non-0 value will be adjusted to best align the logos. For example, the Avatar system has an odd number of columns. If you set the spacing to 8, the logos would look misaligned. So the even number will be changed to an odd number for better alignment.
* `osd_use_pilot_logo` Enable to use the large pilot logo.
## Examples
This is an example of the arming screen with the pilot logo enabled. This is using the default settings.
![Arming screen example using default settings with osd_use_pilot_logo set to on](https://user-images.githubusercontent.com/17590174/271817487-eb18da4d-0911-44b2-b670-ea5940f79176.png)
This is an example of setting the `osd_inav_to_pilot_logo_spacing` to 0. This will allow a larger, single logo.
![Power on screen example with 0 spacing between logos](https://user-images.githubusercontent.com/17590174/271817352-6206402c-9da4-4682-9d83-790cc2396b00.png)
# Post Flight Statistics
The post flight statistcs are set in the firmware. Statistics are only hidden if the supporting hardware is not present. Due to size contraints. The post flight statistics are spread over 2 pages on analogue systems.
## Statistics shown
| Statistic | Requirement | Page | |
|-------------------------------|-----------------------|-------|-|
| Flight Time | | 1 | The total time from arm to disarm. |
| Flight Distance | | 1 | |
| Maximum Distance From Home | GPS | 1 | |
| Maximum Speed | GPS | 1 | |
| Average Speed | GPS | 1 | |
| Maximum Altitude | Baro/GPS | 1 | |
| Minimum Average Cell Voltage | | 1 | |
| Minimum Pack Voltage | | 1 | |
| Maximum Current | Current Sensor | 1 | |
| Maximum Power | Current Sensor | 1 | |
| Energy Used (Flight) | Current Sensor | 1 | |
| Energy Used (Battery Total) | Current Sensor | 1 | This data is not reset on arming. |
| Average Efficiency | Current Sensor & GPS | 1 | |
| Minimum RSSI | | 2 | |
| Minimum LQ | CRSF | 2 | |
| Minmum dBm | CRSF | 2 | |
| Minimum Satellites | GPS | 2 | |
| Maximum Satellites | GPS | 2 | |
| Minimum ESC Temperature | ESC Telemetry | 2 | |
| Maximum ESC Temperature | ESC Telemetry | 2 | |
| Maximum G-Force | | 2 | |
| Minimum Z axis G-Force | | 2 | |
| Maximum Z axis G-Force | | 2 | |
| Blackbox file number | Blackbox recording | 2 | |
| Disarm method | | 1 & 2 | |
| Settings save status | | 1 & 2 | Shows a message if the settings are being saved or have been saved on disarm. |
## Configuration
There are a couple of settings that allow you to adjust parts of the post flights statistics.
- `osd_stats_page_auto_swap_time` allows you to specify how long each stats page is displayed [seconds]. Reverts to manual control when Roll stick used to change pages. Disabled when set to 0.
- `osd_stats_energy_unit` allows you to choose the unit used for the drawn energy in the OSD stats [MAH/WH] (milliAmpere hour/ Watt hour). Default is MAH.
- `osd_stats_show_metric_efficiency` if you use non-metric units on your OSD. Enabling this option will also show the efficiency in metric.
docs/PID tuning.md
+79
View File
@@ -0,0 +1,79 @@
# PID tuning
Every aspect of flight dynamics is controlled by the selected "PID controller". This is an algorithm which is
responsible for reacting to your stick inputs and keeping the craft stable in the air by using the gyroscopes and/or
accelerometers (depending on your flight mode).
The "PIDs" are a set of tuning parameters which control the operation of the PID controller. The optimal PID settings
to use are different on every craft, so if you can't find someone with your exact setup who will share their settings
with you, some trial and error is required to find the best performing PID settings.
A video on how to recognise and correct different flight problems caused by PID settings is available here:
https://www.youtube.com/watch?v=YNzqTGEl2xQ
Basically, the goal of the PID controller is to bring the craft's rotation rate in all three axes to the rate that
you're commanding with your sticks. An error is computed which is the difference between your target rotation rate and
the actual one measured by the gyroscopes, and the controller tries to bring this error to zero.
Note that:
* For fixed wing, a PIFF controller is used. Some documentation is available in the wiki and legacy release notes.
* The INAV Configurator provides conservative example PID settings for various aircraft types. These will require tuning to a particular machine.
## PIDs
**The P term** controls the strength of the correction that is applied to bring the craft toward the target angle or
rotation rate. If the P term is too low, the craft will be difficult to control as it won't respond quickly enough to
keep itself stable. If it is set too high, the craft will rapidly oscillate/shake as it continually overshoots its
target.
**The I term** corrects small, long term errors. If it is set too low, the craft's attitude will slowly drift. If it is
set too high, the craft will oscillate (but with slower oscillations than with P being set too high).
**The D term** attempts to increase system stability by monitoring the rate of change in the error. If the error is rapidly converging to zero, the D term causes the strength of the correction to be backed off in order to avoid overshooting the target.
## TPA and TPA Breakpoint
TPA stands for Throttle PID Attenuation and according to [AlexYork.net](http://blog.alexyorke.net/what-is-tpa/):
> "TPA basically allows an aggressively tuned multi-rotor (one that feels very locked in) to reduce its PID gains when throttle is applied beyond the TPA threshold/breakpoint in order to eliminate fast oscillations.."
Note that TPA is set via CLI or on the PID TUNING tab of the GUI. tpa_breakpoint is set via CLI
Also note that TPA and tpa_breakpoint may not be used in certain PID Controllers. Check the description on the individual controller.
TPA applies a PID value reduction in relation to full Throttle. It is used to apply dampening of PID values as full throttle is reached.
**TPA** = % of dampening that will occur at full throttle.
**tpa_breakpoint** = the point in the throttle curve at which TPA will begin to be applied.
An Example: With TPA = 50 (or .5 in the GUI) and tpa_breakpoint = 1500 (assumed throttle range 1000 - 2000)
* At 1500 on the throttle channel, the PIDs will begin to be dampened.
* At 3/4 throttle (1750), PIDs are reduced by approximately 25% (half way between 1500 and 2000 the dampening will be 50% of the total TPA value of 50% in this example)
* At full throttle (2000) the full amount of dampening set in TPA is applied. (50% reduction in this example)
* TPA can lead into increase of rotation rate when more throttle applied.
![tpa example chart](https://cloud.githubusercontent.com/assets/1668170/6053290/655255dc-ac92-11e4-9491-1a58d868c131.png "TPA Example Chart")
**How and Why to use this?**
If you are getting oscillations starting at say 3/4 throttle, set tpa breakpoint = 1750 or lower (remember, this is assuming your throttle range is 1000-2000), and then slowly increase TPA until your oscillations are gone. Usually, you will want tpa breakpoint to start a little sooner then when your oscillations start so you'll want to experiment with the values to reduce/remove the oscillations.
## PID controllers
INAV has a single built-in PID controller. The PID controller scaling
means that Betaflight PIDs should be comparable.
Note that very old INAV versions had more PID controllers. These have been removed.
## RC rate, Pitch and Roll Rates (P/R rate before they were separated), and Yaw rate
### RC Rate
An overall multiplier on the RC stick inputs for pitch, rol;, and yaw.
docs/Programming Framework.md
+380
View File
@@ -0,0 +1,380 @@
# INAV Programming Framework
INAV Programming Framework (IPF) is a mechanism that allows you to to create
custom functionality in INAV. You can choose for certain actions to be done,
based on custom conditions you select.
Logic conditions can be based on things such as RC channel values, switches, altitude,
distance, timers, etc. The conditions you create can also make use of other conditions
you've entered previously.
The results can be used in:
* [Servo mixer](Mixer.md) to activate/deactivate certain servo mix rulers
* To activate/deactivate system overrides
INAV Programming Framework consists of:
* Logic Conditions - each Logic Condition can be understood as a single command, a single line of code. Each logic condition consists of:
* an operator (action), such as "plus" or "set vtx power"
* one or two operands (nouns), which the action acts upon. Operands are often numbers, such as a channel value or the distance to home.
* "activator" condition - optional. This condition is only active when another condition is true
* Global Variables - variables that can store values from and for Logic Conditions and servo mixer
* Programming PID - general purpose, user configurable PID controllers
IPF can be edited using INAV Configurator user interface, or via CLI. To use COnfigurator, click the tab labeled
"Programming". The various options shown in Configurator are described below.
**Note:** IPF uses integer math. If your programming line returns a decimal, it will be truncated to an integer. So if your math is `1` / `3` = , IPF will truncate the decimal and return `0`.
## JavaScript-Based Programming (Alternative)
INAV also supports a JavaScript-based programming interface that provides a more
familiar syntax for those comfortable with JavaScript. The JavaScript code is transpiled
(converted) into traditional logic conditions, so both methods ultimately use the same
underlying system.
See the [JavaScript Programming Guide](javascript_programming/JAVASCRIPT_PROGRAMMING_GUIDE.md)
for complete documentation on using JavaScript to program your flight controller.
**Benefits of JavaScript programming:**
- Modern code editor with IntelliSense autocomplete
- Real-time syntax validation and error messages
- Familiar programming constructs (if statements, functions, variables)
- Automatic conversion to logic conditions
## Logic Conditions
### CLI
`logic <rule> <enabled> <activatorId> <operation> <operand A type> <operand A value> <operand B type> <operand B value> <flags>`
* `<rule>` - ID of Logic Condition rule
* `<enabled>` - `0` evaluates as disabled, `1` evaluates as enabled
* `<activatorId>` - the ID of _LogicCondition_ used to activate this _Condition_. _Logic Condition_ will be evaluated only then Activator evaluates as `true`. `-1` evaluates as `true`
* `<operation>` - See `Operations` paragraph
* `<operand A type>` - See `Operands` paragraph
* `<operand A value>` - See `Operands` paragraph
* `<operand B type>` - See `Operands` paragraph
* `<operand B value>` - See `Operands` paragraph
* `<flags>` - See `Flags` paragraph
### Operations
| Operation ID | Name | Notes |
|---------------|-------------------------------|-------|
| 0 | True | Always evaluates as true |
| 1 | Equal (A=B) | Evaluates `false` if `false` or `0` |
| 2 | Greater Than (A>B) | `true` if `Operand A` is a higher value than `Operand B` |
| 3 | Lower Than (A<B) | `true` if `Operand A` is a lower value than `Operand B` |
| 4 | Low | `true` if `<1333` |
| 5 | Mid | `true` if `>=1333 and <=1666` |
| 6 | High | `true` if `>1666` |
| 7 | AND | `true` if `Operand A` and `Operand B` are the same value or both `true` |
| 8 | OR | `true` if `Operand A` and/or `OperandB` is `true` |
| 9 | XOR | `true` if `Operand A` or `Operand B` is `true`, but not both |
| 10 | NAND | `false` if `Operand A` and `Operand B` are both `true`|
| 11 | NOR | `true` if `Operand A` and `Operand B` are both `false` |
| 12 | NOT | The boolean opposite to `Operand A` |
| 13 | Sticky | `Operand A` is the activation operator, `Operand B` is the deactivation operator. After the activation is `true`, the operator will return `true` until Operand B is evaluated as `true`|
| 14 | Basic: Add | Add `Operand A` to `Operand B` and returns the result |
| 15 | Basic: Subtract | Substract `Operand B` from `Operand A` and returns the result |
| 16 | Basic: Multiply | Multiply `Operand A` by `Operand B` and returns the result |
| 17 | Basic: Divide | Divide `Operand A` by `Operand B` and returns the result. NOTE: If `Operand B` = `0`, the `Divide` operation will simply return `Operand A`|
| 18 | Set GVAR | Store value from `Operand B` into the Global Variable addressed by `Operand A`. Bear in mind, that operand `Global Variable` means: Value stored in Global Variable of an index! To store in GVAR 1 use `Value 1` not `Global Variable 1` |
| 19 | Increase GVAR | Increase the GVAR indexed by `Operand A` (use `Value 1` for Global Variable 1) with value from `Operand B` |
| 20 | Decrease GVAR | Decrease the GVAR indexed by `Operand A` (use `Value 1` for Global Variable 1) with value from `Operand B` |
| 21 | Set IO Port | Set I2C IO Expander pin `Operand A` to value of `Operand B`. `Operand A` accepts values `0-7` and `Operand B` accepts `0` and `1` |
| 22 | Override Arming Safety | Allows the craft to arm on any angle even without GPS fix. WARNING: This bypasses all safety checks, even that the throttle is low, so use with caution. If you only want to check for certain conditions, such as arm without GPS fix. You will need to add logic conditions to check the throttle is low. |
| 23 | Override Throttle Scale | Override throttle scale to the value defined by operand. Operand type `0` and value `50` means throttle will be scaled by 50%. |
| 24 | Swap Roll & Yaw | basically, when activated, yaw stick will control roll and roll stick will control yaw. Required for tail-sitters VTOL during vertical-horizonral transition when body frame changes |
| 25 | Set VTx Power Level | Sets VTX power level. Accepted values are `0-3` for SmartAudio and `0-4` for Tramp protocol |
| 26 | Invert Roll | Inverts ROLL axis input for PID/PIFF controller |
| 27 | Invert Pitch | Inverts PITCH axis input for PID/PIFF controller |
| 28 | Invert Yaw | Inverts YAW axis input for PID/PIFF controller |
| 29 | Override Throttle | Override throttle value that is fed to the motors by mixer. Operand is scaled in us. `1000` means throttle cut, `1500` means half throttle |
| 30 | Set VTx Band | Sets VTX band. Accepted values are `1-5` |
| 31 | Set VTx Channel | Sets VTX channel. Accepted values are `1-8` |
| 32 | Set OSD Layout | Sets OSD layout. Accepted values are `0-3` |
| 33 | Trigonometry: Sine | Computes SIN of `Operand A` value in degrees. Output is multiplied by `Operand B` value. If `Operand B` is `0`, result is multiplied by `500` |
| 34 | Trigonometry: Cosine | Computes COS of `Operand A` value in degrees. Output is multiplied by `Operand B` value. If `Operand B` is `0`, result is multiplied by `500` |
| 35 | Trigonometry: Tangent | Computes TAN of `Operand A` value in degrees. Output is multiplied by `Operand B` value. If `Operand B` is `0`, result is multiplied by `500` |
| 36 | Map Input | Scales `Operand A` from [`0` : `Operand B`] to [`0` : `1000`]. Note: input will be constrained and then scaled |
| 37 | Map Output | Scales `Operand A` from [`0` : `1000`] to [`0` : `Operand B`]. Note: input will be constrained and then scaled |
| 38 | Override RC Channel | Overrides channel set by `Operand A` to value of `Operand B`. Note operand A should normally be set as a "Value", NOT as "Get RC Channel"|
| 39 | Set Heading Target | Sets heading-hold target to `Operand A`, in centidegrees. Value wraps-around. |
| 40 | Modulo | Modulo. Divide `Operand A` by `Operand B` and returns the remainder |
| 41 | Override Loiter Radius | Sets the loiter radius to `Operand A` [`0` : `100000`] in cm. Must be larger than the loiter radius set in the **Advanced Tuning**. |
| 42 | Set Control Profile | Sets the active config profile (PIDFF/Rates/Filters/etc) to `Operand A`. `Operand A` must be a valid profile number, currently from 1 to 3. If not, the profile will not change |
| 43 | Use Lowest Value | Finds the lowest value of `Operand A` and `Operand B` |
| 44 | Use Highest Value | Finds the highest value of `Operand A` and `Operand B` |
| 45 | Flight Axis Angle Override | Sets the target attitude angle for axis. In other words, when active, it enforces Angle mode (Heading Hold for Yaw) on this axis (Angle mode does not have to be active). `Operand A` defines the axis: `0` - Roll, `1` - Pitch, `2` - Yaw. `Operand B` defines the angle in degrees |
| 46 | Flight Axis Rate Override | Sets the target rate (rotation speed) for axis. `Operand A` defines the axis: `0` - Roll, `1` - Pitch, `2` - Yaw. `Operand B` defines the rate in degrees per second |
| 47 | Edge | Momentarily true when triggered by `Operand A`. `Operand A` is the activation operator [`boolean`], `Operand B` _(Optional)_ is the time for the edge to stay active [ms]. After activation, operator will return `true` until the time in Operand B is reached. If a pure momentary edge is wanted. Just leave `Operand B` as the default `Value: 0` setting. |
| 48 | Delay | Delays activation after being triggered. This will return `true` when `Operand A` _is_ true, and has been true for the last `Operand B` [ms]. |
| 49 | Timer | A simple on - off timer. `true` for the duration of `Operand A` [ms]. Then `false` for the duration of `Operand B` [ms]. |
| 50 | Delta | This returns `true` when the value of `Operand A` has changed by the value of `Operand B` or greater within 100ms. ( \|ΔA\| >= B ) |
| 51 | Approx Equals (A ~ B) | `true` if `Operand B` is within 1% of `Operand A`. |
| 52 | LED Pin PWM | Value `Operand A` from [`0` : `100`] PWM / PINIO generation on LED Pin. See [LED pin PWM](LED%20pin%20PWM.md). Any other value stops PWM generation (stop to allow ws2812 LEDs updates in shared modes). |
| 53 | Disable GPS Sensor Fix | Disables the GNSS sensor fix. For testing GNSS failure. |
| 54 | Mag calibration | Trigger a magnetometer calibration. |
| 55 | Set Gimbal Sensitivity | Scales `Operand A` from [`-16` : `15`]
| 56 | Override Minimum Ground Speed | When active, sets the minimum ground speed to the value specified in `Operand A` [m/s]. Minimum allowed value is set in `nav_min_ground_speed`. Maximum value is `150` |
### Operands
| Operand Type | Name | Notes |
|---------------|-----------------------|-------|
| 0 | Value | Value derived from `value` field |
| 1 | Get RC Channel | `value` points to RC channel number, indexed from 1 |
| 2 | Flight | `value` points to **Flight** Parameters table |
| 3 | Flight Mode | `value` points to **Flight_Mode** table |
| 4 | Logic Condition | `value` points to other logic condition ID |
| 5 | Get Global Variable | Value stored in Global Variable indexed by `value`. `GVAR 1` means: value in GVAR 1 |
| 5 | Programming PID | Output of a Programming PID indexed by `value`. `PID 1` means: value in PID 1 |
| 6 | Waypoints | `value` points to the **Waypoint** parameter table |
#### Flight Parameters
| Operand Value | Name | Notes |
|---------------|---------------------------------------|-------|
| 0 | ARM Timer [s] | Time since armed in `seconds` |
| 1 | Home Distance [m] | distance from home in `meters` |
| 2 | Trip distance [m] | Trip distance in `meters` |
| 3 | RSSI | |
| 4 | Vbat [centi-Volt] [1V = 100] | VBAT Voltage in `Volts * 100`, eg. `12.1V` is `1210` |
| 5 | Cell voltage [centi-Volt] [1V = 100] | Average cell voltage in `Volts * 100`, eg. `12.1V` is `1210` |
| 6 | Current [centi-Amp] [1A = 100] | Current in `Amps * 100`, eg. `9A` is `900` |
| 7 | Current drawn [mAh] | Total used current in `mAh` |
| 8 | GPS Sats | |
| 9 | Ground speed [cm/s] | Ground speed in `cm/s` |
| 10 | 3D speed [cm/s] | 3D speed in `cm/s` |
| 11 | Air speed [cm/s] | Air speed in `cm/s` |
| 12 | Altitude [cm] | Altitude in `cm` |
| 13 | Vertical speed [cm/s] | Vertical speed in `cm/s` |
| 14 | Throttle position [%] | Throttle position in `%` |
| 15 | Roll [deg] | Roll attitude in `degrees` |
| 16 | Pitch [deg] | Pitch attitude in `degrees` |
| 17 | Is Armed | Is the system armed? boolean `0`/`1` |
| 18 | Is Autolaunch | Is auto launch active? boolean `0`/`1` |
| 19 | Is Controlling Altitude | Is altitude being controlled? boolean `0`/`1` |
| 20 | Is Controlling Position | Is the position being controlled? boolean `0`/`1` |
| 21 | Is Emergency Landing | Is the aircraft emergency landing? boolean `0`/`1` |
| 22 | Is RTH | Is RTH active? boolean `0`/`1` |
| 23 | Is Landing | Is the aircaft automatically landing? boolean `0`/`1` |
| 24 | Is Failsafe | Is the flight controller in a failsafe? boolean `0`/`1` |
| 25 | Stabilized Roll | Roll PID controller output `[-500:500]` |
| 26 | Stabilized Pitch | Pitch PID controller output `[-500:500]` |
| 27 | Stabilized Yaw | Yaw PID controller output `[-500:500]` |
| 28 | 3D home distance [m] | 3D distance to home in `meters`. Calculated from Home distance and Altitude using Pythagorean theorem |
| 29 | CRSF LQ | Link quality as returned by the CRSF protocol |
| 30 | CRSF SNR | SNR as returned by the CRSF protocol |
| 31 | GPS Valid Fix | Boolean `0`/`1`. True when the GPS has a valid 3D Fix |
| 32 | Loiter Radius [cm] | The current loiter radius in cm. |
| 33 | Active Control Profile | Integer for the active config profile `[1..MAX_PROFILE_COUNT]` |
| 34 | Battery cells | Number of battery cells detected |
| 35 | AGL status [0/1] | Boolean `1` when AGL can be trusted, `0` when AGL estimate can not be trusted |
| 36 | AGL [cm] | Integer altitude above The Groud Altitude in `cm` |
| 37 | Rangefinder [cm] | Integer raw distance provided by the rangefinder in `cm` |
| 38 | Active Mixer Profile | Which mixer is currently active (for vtol etc) |
| 39 | Mixer Transition Active | Boolean `0`/`1`. Are we currently switching between mixers (quad to plane etc) |
| 40 | Yaw [deg] | Current heading (yaw) in `degrees` |
| 41 | FW Land Sate | Integer `1` - `5`, indicates the status of the FW landing, 0 Idle, 1 Downwind, 2 Base Leg, 3 Final Approach, 4 Glide, 5 Flare |
| 42 | Current battery profile | The active battery profile. Integer `[1..MAX_PROFILE_COUNT]` |
| 43 | Flown Loiter Radius [m] | The actual loiter radius flown by a fixed wing during hold modes, in `meters` |
| 44 | Downlink Link Quality | |
| 45 | Uplink RSSI [dBm] | |
| 46 | Minimum Ground Speed [m/s] | The current minimum ground speed allowed in navigation flight modes |
| 47 | Horizontal Wind Speed [cm/s] | Estimated wind speed. If the wind estimator is unavailble or the wind estimation is invalid, -1 is returned |
| 48 | Wind Direction [deg] | Estimated wind direction. If the wind estimator is unavailble or the wind estimation is invalid, -1 is returned |
| 49 | Relative Wind Offset [deg] | The relative offset between the heading of the aircraft and the heading of the wind. 0 indicates flying directly into a headwing. Negative numbers are a left offset. For example, if -20° is shown, turning right will correct towards 0. If the wind estimator is unavailble or the wind estimation is invalid, 0 is returned |
#### FLIGHT_MODE
The flight mode operands return `true` when the mode is active. These are modes that you will see in the **Modes** tab. Note: the `USER*` modes are used by camera switchers, PINIO etc. They are not the Waypoint User Actions. See the [Waypoints](#waypoints) section to access those.
| Operand Value | Name | Notes |
|---------------|-------------------|-------|
| 0 | Failsafe | `true` when a **Failsafe** state has been triggered. |
| 1 | Manual | `true` when you are in the **Manual** flight mode. |
| 2 | RTH | `true` when you are in the **Return to Home** flight mode. |
| 3 | Position Hold | `true` when you are in the **Position Hold** or **Loiter** flight modes. |
| 4 | Cruise | `true` when you are in the **Cruise** flight mode. |
| 5 | Altitude Hold | `true` when you the **Altitude Hold** flight mode modifier is active. |
| 6 | Angle | `true` when you are in the **Angle** flight mode. |
| 7 | Horizon | `true` when you are in the **Horizon** flight mode. |
| 8 | Air | `true` when you the **Airmode** flight mode modifier is active. |
| 9 | USER 1 | `true` when the **USER 1** mode is active. |
| 10 | USER 2 | `true` when the **USER 2** mode is active. |
| 11 | Course Hold | `true` when you are in the **Course Hold** flight mode. |
| 12 | USER 3 | `true` when the **USER 3** mode is active. |
| 13 | USER 4 | `true` when the **USER 4** mode is active. |
| 14 | Acro | `true` when you are in the **Acro** flight mode. |
| 15 | Waypoint Mission | `true` when you are in the **WP Mission** flight mode. |
#### WAYPOINTS
| Operand Value | Name | Notes |
|---------------|-------------------------------|-------|
| 0 | Is WP | Boolean `0`/`1` |
| 1 | Current Waypoint Index | Current waypoint leg. Indexed from `1`. To verify WP is in progress, use `Is WP` |
| 2 | Current Waypoint Action | `true` when Action active in current leg. See ACTIVE_WAYPOINT_ACTION table |
| 3 | Next Waypoint Action | `true` when Action active in next leg. See ACTIVE_WAYPOINT_ACTION table |
| 4 | Distance to next Waypoint | Distance to next WP in metres |
| 5 | Distance from Waypoint | Distance from the last WP in metres |
| 6 | User Action 1 | `true` when User Action 1 is active on this waypoint leg [boolean `0`/`1`] |
| 7 | User Action 2 | `true` when User Action 2 is active on this waypoint leg [boolean `0`/`1`] |
| 8 | User Action 3 | `true` when User Action 3 is active on this waypoint leg [boolean `0`/`1`] |
| 9 | User Action 4 | `true` when User Action 4 is active on this waypoint leg [boolean `0`/`1`] |
| 10 | Next Waypoint User Action 1 | `true` when User Action 1 is active on the next waypoint leg [boolean `0`/`1`] |
| 11 | Next Waypoint User Action 2 | `true` when User Action 2 is active on the next waypoint leg [boolean `0`/`1`] |
| 12 | Next Waypoint User Action 3 | `true` when User Action 3 is active on the next waypoint leg [boolean `0`/`1`] |
| 13 | Next Waypoint User Action 4 | `true` when User Action 4 is active on the next waypoint leg [boolean `0`/`1`] |
#### ACTIVE_WAYPOINT_ACTION
| Action | Value |
|---------------|-------|
| WAYPOINT | 1 |
| HOLD_TIME | 3 |
| RTH | 4 |
| SET_POI | 5 |
| JUMP | 6 |
| SET_HEAD | 7 |
| LAND | 8 |
### Flags
All flags are reseted on ARM and DISARM event.
| bit | Decimal | Function |
|-------|-----------|-----------|
| 0 | 1 | Latch - after activation LC will stay active until LATCH flag is reset |
| 1 | 2 | Timeout satisfied - Used in timed operands to determine if the timeout has been met |
## Global variables
### CLI
`gvar <index> <default value> <min> <max>`
**Note:** Global Variables (GVARs) are limited to integers between negative `-32768` and positive `32767`.
## Programming PID
IPF makes a set of general user PIDFF controllers avaliable for use in your program. These PIDFF controllers are not tied to any roll/pitch/yaw profiles or other controls.
The output of these controllers can be used in an IPF program by using the `Programming PID` operand.
The `<setpoint value>` of the controller is the target value for the controller to hit. The `<measurement value>` is the measurement of the current value. For instance, `<setpoint value>` could be the speed you want to go, and `<measurement value>` is the current speed.
P, I, D, and FF values will need to be manually adjusted to determine the appropriate value for the program and controller.
`pid <index> <enabled> <setpoint type> <setpoint value> <measurement type> <measurement value> <P gain> <I gain> <D gain> <FF gain>`
* `<index>` - ID of PID Controller, starting from `0`
* `<enabled>` - `0` evaluates as disabled, `1` evaluates as enabled
* `<setpoint type>` - See `Operands` paragraph
* `<setpoint value>` - See `Operands` paragraph
* `<measurement type>` - See `Operands` paragraph
* `<measurement value>` - See `Operands` paragraph
* `<P gain>` - P-gain, scaled to `1/1000`
* `<I gain>` - I-gain, scaled to `1/1000`
* `<D gain>` - D-gain, scaled to `1/1000`
* `<FF gain>` - FF-gain, scaled to `1/1000`
## Examples
### When more than 100 meters away, increase VTX power
![screenshot of vtx home distance](./assets/images/vtx_home_distance.png)
### When more than 600 meters away, engage return-to-home by setting the matching RC channel
![screenshot of rth home distance](./assets/images/rth_home_distance.jpg)
### Dynamic THROTTLE scale
`logic 0 1 0 23 0 50 0 0 0`
Limits the THROTTLE output to 50% when Logic Condition `0` evaluates as `true`
### Set VTX power level via Smart Audio
`logic 0 1 0 25 0 3 0 0 0`
Sets VTX power level to `3` when Logic Condition `0` evaluates as `true`
### Invert ROLL and PITCH when rear facing camera FPV is used
Solves the problem from [https://github.com/iNavFlight/inav/issues/4439](https://github.com/iNavFlight/inav/issues/4439)
```
logic 0 1 0 26 0 0 0 0 0
logic 1 1 0 27 0 0 0 0 0
```
Inverts ROLL and PITCH input when Logic Condition `0` evaluates as `true`. Moving Pitch stick up will cause pitch down (up for rear facing camera). Moving Roll stick right will cause roll left of a quad (right in rear facing camera)
### Cut motors but keep other throttle bindings active
`logic 0 1 0 29 0 1000 0 0 0`
Sets throttle output to `0%` when Logic Condition `0` evaluates as `true`
### Set throttle to 50% and keep other throttle bindings active
`logic 0 1 0 29 0 1500 0 0 0`
Sets throttle output to about `50%` when Logic Condition `0` evaluates as `true`
### Set throttle control to different RC channel
`logic 0 1 0 29 1 7 0 0 0`
If Logic Condition `0` evaluates as `true`, motor throttle control is bound to RC channel 7 instead of throttle channel
### Set VTX channel with a POT
Set VTX channel with a POT on the radio assigned to RC channel 6
```
logic 0 1 -1 15 1 6 0 1000 0
logic 1 1 -1 37 4 0 0 7 0
logic 2 1 -1 14 4 1 0 1 0
logic 3 1 -1 31 4 2 0 0 0
```
Steps:
1. Normalize range `[1000:2000]` to `[0:1000]` by substracting `1000`
2. Scale range `[0:1000]` to `[0:7]`
3. Increase range by `1` to have the range of `[1:8]`
4. Assign LC#2 to VTX channel function
### Set VTX power with a POT
Set VTX power with a POT on the radio assigned to RC channel 6. In this example we scale POT to 4 power level `[1:4]`
```
logic 0 1 -1 15 1 6 0 1000 0
logic 1 1 -1 37 4 0 0 3 0
logic 2 1 -1 14 4 1 0 1 0
logic 3 1 -1 25 4 2 0 0 0
```
Steps:
1. Normalize range [1000:2000] to [0:1000] by substracting `1000`
2. Scale range [0:1000] to [0:3]
3. Increase range by `1` to have the range of [1:4]
4. Assign LC#2 to VTX power function
## Common issues / questions about IPF
One common mistake involves setting RC channel values. To override (set) the
value of a specific RC channel, choose "Override RC value", then for operand A
choose *value* and enter the channel number. Choosing "get RC value" is a common mistake,
which does something other than what you probably want.
![screenshot of override an RC channel with a value](./assets/images/ipf_set_get_rc_channel.png)
## Related Documentation
- [JavaScript Programming Guide](javascript_programming/JAVASCRIPT_PROGRAMMING_GUIDE.md) - Alternative JavaScript-based syntax for programming logic conditions
- [Operations Reference](javascript_programming/OPERATIONS_REFERENCE.md) - Complete reference for all supported operations in JavaScript
- [Timer and Change Detection Examples](javascript_programming/TIMER_WHENCHANGED_EXAMPLES.md) - Practical examples for time-based patterns
docs/Rangefinder.md
+161
View File
@@ -0,0 +1,161 @@
# Rangefinder
Rangefinders are devices used to measure altitude Above Ground Level (AGL), the distance to the ground directly beneath the aircraft.
## Features
Rangefinders in INAV are used for:
* **Landing detection** for multirotors - precise touchdown detection
* **Automated landing support** for fixed wings - smooth descent control
* **Terrain following (Surface mode)** - maintain constant height above ground (multirotors only)
* **Position estimation** - when combined with optical flow sensors, enables GPS-free navigation
## Hardware
INAV supports the following rangefinder types:
### Time-of-Flight (ToF) Laser Sensors
* **VL53L0X** - STMicroelectronics laser rangefinder, 0-75cm range (I2C)
* **VL53L1X** - STMicroelectronics laser rangefinder, 0-400cm range (I2C)
* **TOF10120** - Small & lightweight laser sensor, 0-200cm range (I2C)
* **TERARANGER_EVO** - TeraRanger Evo series, 30-600cm range depending on model (I2C/UART)
- https://www.terabee.com/sensors-modules/lidar-tof-range-finders/#individual-distance-measurement-sensors
### Ultrasonic Sensors
* **SRF10** - Devantech SRF10, 0-600cm range (I2C)
* **US42** - Maxbotix US-42, 0-645cm range (I2C)
* **USD1_V0** - USD1 ultrasonic sensor variant (UART)
### Radar Sensors
* **NRA** - NanoRadar NRA15/NRA24 millimeter-wave radar (UART)
NRA15/NRA24 sensors can use US-D1_V0 or NRA protocol depending on firmware configuration:
| Radar | Protocol | Resolution | Name in configurator |
|-------|----------|-----------------|----------------------|
| NRA15 | US-D1_V0 | 0-30m (±4cm) | USD1_V0 |
| NRA15 | NRA | 0-30m (±4cm) | NRA |
| NRA15 | NRA | 0-100m (±10cm) | NRA |
| NRA24 | US-D1_V0 | 0-50m (±4cm) | USD1_V0 |
| NRA24 | US-D1_V0 | 0-200m (±10cm) | USD1_V0 |
| NRA24 | NRA | 0-50m (±4cm) | NRA |
| NRA24 | NRA | 0-200m (±10cm) | NRA |
### Serial/External Sensors
* **MSP** - External rangefinder via MSP protocol (UART/MSP)
* **BENEWAKE** - Benewake LIDAR modules (TFmini, etc.) via serial protocol (UART)
### Development/Testing
* **FAKE** - Simulated rangefinder for testing without hardware
## Configuration
Enable rangefinder in CLI:
```
set rangefinder_hardware = VL53L0X # or your sensor type
save
```
Optional median filtering for smoother readings:
```
set rangefinder_median_filter = ON
save
```
### Position Estimation Weights
Control how rangefinder data is fused into altitude estimates:
```
set inav_max_surface_altitude = 200 # Max rangefinder range to use (cm)
set inav_w_z_surface_p = 3.5 # Position weight
set inav_w_z_surface_v = 6.1 # Velocity weight
```
## Surface Mode (Terrain Following)
Surface mode enables terrain following on **multirotors only** by maintaining constant altitude above ground instead of absolute altitude.
**Activation:** Enable SURFACE mode via RC switch (requires rangefinder configured)
**Compatible with:**
- ALTHOLD - Maintains height above ground
- POSHOLD - Holds position with terrain-relative altitude
- CRUISE - Velocity control with terrain following
**Settings:**
```
set nav_max_terrain_follow_alt = 100 # Max altitude in Surface mode (cm)
```
**Important:** Always set `nav_max_terrain_follow_alt` **less than** `inav_max_surface_altitude` to prevent attempting to use the sensor beyond its reliable range. For example, if your rangefinder is reliable up to 200cm, set `inav_max_surface_altitude = 200` and `nav_max_terrain_follow_alt = 100` (or lower).
**Note:** Surface mode is NOT available on fixed wing aircraft.
## Connections
### I2C Rangefinders
I2C sensors (VL53L0X, VL53L1X, TOF10120, SRF10, US42, TERARANGER_EVO) connect to the flight controller's I2C port and are auto-detected when configured.
### Serial Rangefinders
UART-based sensors (MSP, BENEWAKE, NRA, USD1_V0) require:
1. Assign UART port in Ports tab
2. Configure `rangefinder_hardware` setting
3. Set appropriate baud rate
## Optical Flow Integration
When a rangefinder is combined with an optical flow sensor:
- Rangefinder provides altitude (Z-axis)
- Optical flow provides horizontal movement (X/Y axes)
- Together they enable GPS-free position hold indoors
See wiki for optical flow setup: https://github.com/iNavFlight/inav/wiki/Optic-Flow-and-Rangefinder
## Constraints
**Not Supported:**
- HC-SR04 ultrasonic sensors
- US-100 ultrasonic sensors
**Limitations:**
- Surface mode: Multirotors only
- Tilt angle: Rangefinder disabled if aircraft tilt exceeds sensor detection cone
- Range: Set `inav_max_surface_altitude` to sensor's reliable range, not maximum range
## Troubleshooting
**No rangefinder readings:**
- Verify correct `rangefinder_hardware` selection
- Check wiring and power (3.3V or 5V depending on sensor)
- Ensure I2C address is unique (no conflicts)
- Check sensor has clear line of sight to ground
**Erratic readings:**
- Enable `rangefinder_median_filter = ON`
- Check for vibration - mount sensor rigidly
- Verify sensor is not affected by propeller wash
- Ensure ground surface has sufficient texture (not smooth/reflective)
**Surface mode not working:**
- Verify SURFACE mode is enabled via switch
- Check rangefinder is providing valid data
- Ensure altitude is below `nav_max_terrain_follow_alt` (operational limit)
- Ensure altitude is within sensor's reliable range (set by `inav_max_surface_altitude`)
- Confirm platform is multirotor (fixed wings not supported)
## References
- [INAV Wiki: Optic Flow and Rangefinder Setup](https://github.com/iNavFlight/inav/wiki/Optic-Flow-and-Rangefinder)
- [Settings Reference](Settings.md)
docs/Rssi.md
+43
View File
@@ -0,0 +1,43 @@
# RSSI
RSSI is a measurement of signal strength and is very handy so you know when your aircraft isw going out of range or if it is suffering RF interference.
Some receivers have RSSI outputs. 3 types are supported.
1. RSSI via PPM channel
1. RSSI via Parallel PWM channel
1. RSSI via ADC with PPM RC that has an RSSI output - aka RSSI ADC
## RSSI via PPM
Configure your receiver to output RSSI on a spare channel, then select the channel used via the CLI.
e.g. if you used channel 9 then you would set:
```
set rssi_channel = 9
```
Note: Some systems such as EZUHF invert the RSSI ( 0 = Full signal / 100 = Lost signal). To correct this problem you can invert the RSSI scale so you will get a correct reading by using these commands:
```
set rssi_min = 100
set rssi_max = 0
```
Default is set to "0" for normal operation ( 100 = Full signal / 0 = Lost signal).
## RSSI via Parallel PWM channel
Connect the RSSI signal to any PWM input channel then set the RSSI channel as you would for RSSI via PPM
## RSSI ADC
Connect the RSSI signal to the RC2/CH2 input. The signal must be between 0v and 3.3v.
Use inline resistors to lower voltage if required; inline smoothing capacitors may also help.
A simple PPM->RSSI conditioner can easily be made. See the PPM-RSSI conditioning.pdf for details.
Under CLI :
- enable using the RSSI_ADC feature : `feature RSSI_ADC`
- set the RSSI_SCALE parameter (between 1 and 255) to adjust RSSI level according to your configuration.
FrSky D4R-II and X8R supported.
docs/Runcam device.md
+32
View File
@@ -0,0 +1,32 @@
# Runcam device
Cameras which support [Runcam device protocol](https://support.runcam.com/hc/en-us/articles/360014537794-RunCam-Device-Protocol), can be configured using sticks.
Note that for cameras which has OSD pin, there is alternative functionality: [OSD Joystick](OSD%20Joystick.md).
Camera's RX/TX should be connected to FC's UART, which has "Runcam device" option selected.
# Entering Joystick emulation mode
Emulation can be enabled in unarmed state only.
Joystick emulation mode is enabled using the following stick combination:
```RIGHT CENTER```
Than camera OSD can be navigated using right stick. See [Controls](Controls.md) for all stick combinations.
*Note that the same stick combination is used to enable [OSD Joystick](OSD%20Joystick.md).*
Mode is exited using stick combination:
```LEFT CENTER```
# RC Box
There are 3 RC Boxes which can be used in armed and unarmed state:
- Camera 1 - Simulate Wifi button
- Camera 2 - Simulate POWER button
- Camera 3 - Simulate Change Mode button.
docs/Rx.md
+347
View File
@@ -0,0 +1,347 @@
# Receivers (RX)
A receiver is used to receive radio control signals from your transmitter and convert them into signals that the flight controller can understand.
There are a number of types of receivers:
* PPM Receivers (obsolete)
* Serial Receivers
* MSP RX
## PPM Receivers
**Only supported in INAV 3.x and below**
PPM is sometimes known as PPM SUM or CPPM.
12 channels via a single input pin, not as accurate or jitter free as methods that use serial communications, but readily available.
These receivers are reported working:
FrSky D4R-II
http://www.frsky-rc.com/product/pro.php?pro_id=24
Graupner GR24
http://www.graupner.de/en/products/33512/product.aspx
R615X Spektrum/JR DSM2/DSMX Compatible 6Ch 2.4GHz Receiver w/CPPM
http://orangerx.com/2014/05/20/r615x-spektrumjr-dsm2dsmx-compatible-6ch-2-4ghz-receiver-wcppm-2/
FrSky D8R-XP 8ch telemetry receiver, or CPPM and RSSI enabled receiver
http://www.frsky-rc.com/product/pro.php?pro_id=21
## Serial Receivers
*Connect the receivers to UARTs and not to Software Serial ports. Using software serial for RX input can cause unexpected behaviours beacause the port cannot handle reliably the bit rate needed by the most common protocols*
### Spektrum
This section describes the legacy Spektrum satellite capability; the newer SRXL2 protocol is described [later in this document](#srxl2) .
8 channels via serial currently supported.
These receivers are reported working:
Lemon Rx DSMX Compatible PPM 8-Channel Receiver + Lemon DSMX Compatible Satellite with Failsafe
http://www.lemon-rx.com/shop/index.php?route=product/product&product_id=118
#### Spektrum pesudo RSSI
As of INAV 1.6, a pseudo RSSI, based on satellite fade count is supported and reported as normal INAV RSSI (0-1023 range). In order to use this feature, the following is necessary:
* Bind the satellite receiver using a physical RX; the bind function provided by the flight controller is not sufficient.
* The CLI variable `rssi_channel` is set to channel 9:
```
set rssi_channel = 9
```
This pseudo-RSSI should work on all makes of Spektrum satellite RX; it is tested as working on [Lemon RX satellites](http://www.lemon-rx.com/index.php?route=product/product&path=72&product_id=109 and http://www.lemon-rx.com/index.php?route=product/product&path=72&product_id=135) (recommended).
### S.BUS
16 channels via serial currently supported. See below how to set up your transmitter.
* You probably need an inverter between the receiver output and the flight controller. However, some flight controllers have this built in and doesn't need one.
* Some OpenLRS receivers produce a non-inverted SBUS signal. It is possible to switch SBUS inversion off using CLI command `set sbus_inversion = OFF` when using an F3 based flight controller.
* Softserial ports cannot be used with SBUS because it runs at too high of a bitrate (1Mbps). Refer to the chapter specific to your board to determine which port(s) may be used.
* You will need to configure the channel mapping in the GUI (Receiver tab) or CLI (`map` command). Note that channels above 8 are mapped "straight", with no remapping.
These receivers are reported working:
FrSky X4RSB 3/16ch Telemetry Receiver
http://www.frsky-rc.com/product/pro.php?pro_id=135
FrSky X8R 8/16ch Telemetry Receiver
http://www.frsky-rc.com/product/pro.php?pro_id=105
Futaba R2008SB 2.4GHz S-FHSS
http://www.futaba-rc.com/systems/futk8100-8j/
#### OpenTX S.BUS configuration
If using OpenTX set the transmitter module to D16 mode and ALSO select CH1-16 on the transmitter before binding to allow reception
of all 16 channels.
OpenTX 2.09, which is shipped on some Taranis X9D Plus transmitters, has a bug - [issue:1701](https://github.com/opentx/opentx/issues/1701).
The bug prevents use of all 16 channels. Upgrade to the latest OpenTX version to allow correct reception of all 16 channels,
without the fix you are limited to 8 channels regardless of the CH1-16/D16 settings.
### F.Port
F.Port is a protocol running on async serial allowing 16 controls channels and telemetry on a single UART.
Supported receivers include FrSky R-XSR, X4R, X4R-SB, XSR, XSR-M, R9M Slim, R9M Slim+, R9 Mini. For ACCST receivers you need to flash the corresponding firmware for it to output F.Port. For ACCESS receivers the protocol output from the receiver can be switched between S.Bus and F.Port from the model's setup page in the RX options.
#### Connection
Just connect the S.Port wire from the receiver to the TX pad of a free UART on your flight controller
#### Configuration
For INAV 2.6 and newer versions, the default configuration should just work. However, if you're
upgrading from a previous version you might need to set the following settings to their
default values:
```
set serialrx_inverted = OFF
set serialrx_halfduplex = AUTO
```
For INAV versions prior to 2.6, you need to change the following settings:
```
set serialrx_inverted = ON
set serialrx_halfduplex = ON
```
### SUMD
16 channels via serial currently supported.
These receivers are reported working:
GR-24 receiver HoTT
http://www.graupner.de/en/products/33512/product.aspx
Graupner receiver GR-12SH+ HoTT
http://www.graupner.de/en/products/870ade17-ace8-427f-943b-657040579906/33565/product.aspx
### IBUS
10 channels via serial currently supported.
IBUS is the FlySky digital serial protocol and is available with the FS-IA6B, FS-X6B and FS-IA10 receivers.
The Turnigy TGY-IA6B and TGY-IA10 are the same devices with a different label, therefore they also work.
IBUS can provide up to 120Hz refresh rate, more than double compared to standard 50Hz of PPM.
FlySky FS-I6X TX natively supports 10ch.
If you are using a 6ch TX such as the FS-I6 or TGY-I6 then you must flash a 10ch
firmware on the TX to make use of these extra channels.
The flash is avaliable here: https://github.com/benb0jangles/FlySky-i6-Mod-
```
_______
/ \ /------------\
| STM32 |-->UART RX-->[115200 baud]---->| Flysky RX |
| uC |- UART TX--x[not connected] | IBUS-Servo |
\_______/ \------------/
```
After flash "10ch Timer Mod i6 Updater", it is passible to get RSSI signal on selected Aux channel from FS-i6 Err sensor.
It is possible to use IBUS RX and IBUS telemetry on only one port of the hardware UART. More information in Telemetry.md.
### SRXL2
SRXL2 is a newer Spektrum protocol that provides a bidirectional link between the FC and the receiver, allowing the user to get FC telemetry data and basic settings on Spektrum Gen 2 airware TX. SRXL2 is supported in INAV 2.6 and later. It offers improved performance and features compared to earlier Spektrum RX.
#### Wiring
Signal pin on receiver (labeled "S") must be wired to a **UART TX** pin on the FC. Voltage can be 3.3V (4.0V for SPM4651T) to 8.4V. On some F4 FCs, the TX pin may have a signal inverter (such as for S.Port). Make sure this isn't the case for the pin you intend to use.
#### Configuration
Selection of SXRL2 is provided in the INAV 2.6 and later configurators. It is necessary to complete the configuration via the CLI; the following settings are recommended:
```
feature TELEMETRY
feature -RSSI_ADC
map TAER
set receiver_type = SERIAL
set serialrx_provider = SRXL2
set serialrx_inverted = OFF
set srxl2_unit_id = 1
set srxl2_baud_fast = ON
set rssi_source = PROTOCOL
set rssi_channel = 0
```
#### Notes:
* RSSI_ADC is disabled, as this would override the value provided through SRXL2
* `rssi_channel = 0` is required, unlike earlier Spektrum devices (e.g. SPM4649T).
Setting these values differently may have an adverse effects on RSSI readings.
#### CLI Bind Commands
This command will put the receiver into bind mode without the need to reboot the FC as it was required with the older `spektrum_sat_bind` command.
```
bind_rx
```
This command will send a bind request to an MSP receiver on the specified port.
```
bind_msp_rx <port>
```
## MultiWii serial protocol (MSP RX)
Allows you to use MSP commands as the RC input. Up to 34 channels are supported.
Note:
* It is necessary to update `MSP_SET_RAW_RC` at 5Hz or faster.
* `MSP_SET_RAW_RC` uses the defined RC channel map
* `MSP_RC` returns `AERT` regardless of channel map
* You can combine "real" RC radio and MSP RX by using `msp_override_channels` to set the channels to be overridden.
* The [wiki Remote Control and Management article](https://github.com/iNavFlight/inav/wiki/INAV-Remote-Management,-Control-and-Telemetry) provides more information, including links to 3rd party projects that exercise `MSP_SET_RAW_RC` and `USE_MSP_RC_OVERRIDE`
## SIM (SITL) Joystick
Enables the use of a joystick in the INAV SITL with a flight simulator. See the [SITL documentation](SITL/SITL.md).
## MSP Auxiliary RC Channel Overlay (MSP2_INAV_SET_AUX_RC)
Allows extending the available RC channel count beyond the native RC link capacity using `MSP2_INAV_SET_AUX_RC` (`0x2230`). This is a lightweight, bandwidth-efficient alternative to `MSP_SET_RAW_RC` for auxiliary channels only.
**Key properties:**
- Controls **CH13–CH32** only (CH1–CH12 are protected and rejected)
- Configurable resolution: 2-bit (3 positions), 4-bit (~71µs steps), 8-bit (~3.9µs steps), or 16-bit (raw PWM)
- Value `0` = skip (no update) — previous value persists indefinitely
- No flight mode or special configuration required — always active
- Does **not** affect failsafe detection
- Recommended to send with `MSP_FLAG_DONT_REPLY` (`flags=0x01`) on telemetry passthrough links
**Typical use case:** A Lua script on the radio sends `MSP2_INAV_SET_AUX_RC` via SmartPort/CRSF/ELRS telemetry passthrough to control auxiliary functions (lights, camera triggers, gimbal modes) on channels beyond the RC link's native capacity.
**Priority order** (last writer wins):
1. Primary RX (SBUS, CRSF, FPort, etc.)
2. MSP RC Override (if active)
3. **MSP AUX Overlay** (CH13–CH32)
**Important:** For serial RX protocols, the firmware cannot detect which channels the sender actively uses. If AUX_RC targets a channel that the RX link also sends, AUX_RC will override it. Configure the start channel above your RC link's active channel range.
When MSP is the primary RX provider (`receiver_type = MSP`), channels covered by `MSP_SET_RAW_RC` are automatically protected. Channels in the `msp_override_channels` bitmask are also protected when MSP RC Override mode is active.
See the [MSP documentation](development/msp/README.md) for the full message format.
## Configuration
The receiver type can be set from the configurator or CLI.
```
# get receiver_type
receiver_type = NONE
Allowed values: NONE, SERIAL, MSP, SIM (SITL)
```
### RX signal-loss detection
The software has signal loss detection which is always enabled. Signal loss detection is used for safety and failsafe reasons.
The `rx_min_usec` and `rx_max_usec` settings helps detect when your RX stops sending any data, enters failsafe mode or when the RX loses signal.
By default, when the signal loss is detected the FC will set pitch/roll/yaw to the value configured for `mid_rc`. The throttle will be set to the value configured for `rx_min_usec` or `mid_rc` if using 3D feature.
Signal loss can be detected when:
1. no rx data is received (due to radio reception, recevier configuration or cabling issues).
2. using Serial RX and receiver indicates failsafe condition.
3. using any of the first 4 stick channels do not have a value in the range specified by `rx_min_usec` and `rx_max_usec`.
#### `rx_min_usec`
The lowest channel value considered valid. e.g. PWM/PPM pulse length
#### `rx_max_usec`
The highest channel value considered valid. e.g. PWM/PPM pulse length
### Serial RX
See the Serial chapter for some some RX configuration examples.
To setup spectrum in the GUI:
1. Start on the "Ports" tab make sure that teh required has serial RX. If not set the checkbox, save and reboot.
2. Move to the "Configuration" page and in the upper lefthand corner choose Serial RX as the receiver type.
3. Below that choose the type of serial receiver that you are using. Save and reboot.
#### Using CLI:
For Serial RX set the `receiver_type` and `serialrx_provider` setting as appropriate for your RX.
```
# get rec
receiver_type = SERIAL
Allowed values: NONE, SERIAL, MSP, SIM (SITL)
# get serialrx
serialrx_provider = SBUS
Allowed values: SPEK1024, SPEK2048, SBUS, SUMD, IBUS, JETIEXBUS, CRSF, FPORT, SBUS_FAST, FPORT2, SRXL2, GHST, MAVLINK, FBUS
```
## Receiver configuration.
### FrSky D4R-II
Set the RX for 'No Pulses'. Turn OFF TX and RX, Turn ON RX. Press and release F/S button on RX. Turn off RX.
### Graupner GR-24 PWM
Set failsafe on the throttle channel in the receiver settings (via transmitter menu) to a value below `rx_min_usec` using channel mode FAILSAFE.
This is the prefered way, since this is *much faster* detected by the FC then a channel that sends no pulses (OFF).
__NOTE:__
One or more control channels may be set to OFF to signal a failsafe condition to the FC, all other channels *must* be set to either HOLD or OFF.
Do __NOT USE__ the mode indicated with FAILSAFE instead, as this combination is NOT handled correctly by the FC.
## Receiver Channel Range Configuration.
If you have a transmitter/receiver, that output a non-standard pulse range (i.e. 1070-1930 as some Spektrum receivers)
you could use rx channel range configuration to map actual range of your transmitter to 1000-2000 as expected by INAV.
The low and high value of a channel range are often referred to as 'End-points'. e.g. 'End-point adjustments / EPA'.
All attempts should be made to configure your transmitter/receiver to use the range 1000-2000 *before* using this feature
as you will have less preceise control if it is used.
To do this you should figure out what range your transmitter outputs and use these values for rx range configuration.
You can do this in a few simple steps:
If you have used rc range configuration previously you should reset it to prevent it from altering rc input. Do so
by entering the following command in CLI:
```
rxrange reset
save
```
Now reboot your FC, connect the configurator, go to the `Receiver` tab move sticks on your transmitter and note min and
max values of first 4 channels. Take caution as you can accidentally arm your craft. Best way is to move one channel at
a time.
Go to CLI and set the min and max values with the following command:
```
rxrange <channel_number> <min> <max>
```
For example, if you have the range 1070-1930 for the first channel you should use `rxrange 0 1070 1930` in
the CLI. Be sure to enter the `save` command to save the settings.
After configuring channel ranges use the sub-trim on your transmitter to set the middle point of pitch, roll, yaw and throttle.
You can also use rxrange to reverse the direction of an input channel, e.g. `rxrange 0 2000 1000`.
docs/SBUS2_Telemetry.md
+25
View File
@@ -0,0 +1,25 @@
# Futaba SBUS2 Telemetry
Basic experimental support for SBUS2 telemetry has been added to INAV 8.0.0. Currently it is limited to F7 and H7 mcus only. The main reason it is limited to those MCUs is due to the requirement for an inverted UART signal and the SBUS pads in F405 usually are not bi-directional.
The basic sensors have been tested with a Futaba T16IZ running software version 6.0E.
An alternative to using INAV's SBUS2 support is to use SBS-01ML MAVlink Telemetry Drone Sensor instead. (not tested and not supported with older futaba radios, including my 16IZ).
# Wiring
The SBUS2 signal should be connected to the TX PIN, not the RX PIN, like on a traditional SBUS setup.
# Sensor mapping
The following fixed sensor mapping is used:
| Slot | Sensort Type | Info |
| --- | --- | --- |
| 1 | Voltage | Pack voltage and cell voltage |
| 3 | Current | Capacity = used mAh |
| 6 | rpm sensor | motor rpm. Need to set geat ratio to 1.0 |
| 7 | Temperature | ESC Temperature |
| 8 | GPS | |
| 16 | Temperature | IMU Temperature |
| 17 | Temperature | Baro Temperature |
| 18-25 | Temperature | Temperature sensor 0-7 |
docs/SITL/RealFlight.md
+31
View File
@@ -0,0 +1,31 @@
# RealFlight
Supported are RealFlight 9.5S and RealFlight Evolution, NOT RealFlight-X.
RealFlight is very well suited to simulate the model flight specific aspects. Autolaunch and the mixers can be used.
The RealFlight 3D sceneries are based on real topographic data of the Sierra Nevada in Southern Spain.
INAV uses as reference the scenery "RealFlight Ranch" which is located at the coordinates Lat: 37.118949°, Lon: -2.772960.
Use these scenery to use the mission planner and other GPS features.
> [!CAUTION]:
> The immediate surroundings of the airfield have been levelled in the scenery. If, for example, Autoland is to be tested here, do not use "Sea level ref" and the automatically determined heights of the Configurator.
> Either use relarive elevations or correct the elevation manually.
> The altitude of the airfield is exactly 1300 metres.
## Joystick
In the settings, calibrate the joystick, set it up and assign the axes in the same order as in INAV.
Channel 1 (Aileron) in RealFlight is Cannel 1 (Aileron in INAV) and so on.
## General settings
Under Settings / Physics / Quality Switch on "RealFlight Link enabled".
As a command line option for SITL, the port does not need to be specified, the port is fixed.
For better results, set the difficulty level to "Realistic".
## Prepare the models
All mixer and servo influencing settings should be deactivated.
In the model editor under "Electronis" all mixers should be deleted and the servos should be connected directly to the virtual receiver output.
In the "Radio" tab also deactivate Expo and low rates: "Activadd when: Never".
Configure the model in the same way as a real model would be set up in INAV including Mixer, Expo, etc. depending on the selected model in RealFlight.
Then adjust the channelmap im the Configurator or via command line accordingly.
docs/SITL/SITL.md
+195
View File
@@ -0,0 +1,195 @@
# SITL
![INAV-SIM-OSD](assets/INAV-SIM-OSD.png)
## ATTENTION!
SITL is currently still under development.
SITL (Software in the loop) allows to run INAV completely in software on the PC without using a flight controller and simulate complete FPV flights.
For this, INAV is compiled with a normal PC compiler.
The sensors are replaced by data provided by a simulator.
Currently supported are
- RealFlight https://www.realflight.com/
- X-Plane https://www.x-plane.com/
- fl2sim [replay Blackbox Log via SITL](https://github.com/stronnag/bbl2kml/wiki/fl2sitl), uses the X-Plane protocol.
INAV SITL communicates for sensor data and control directly with the corresponding simulator, see the documentation of the individual simulators and the Configurator or the command line options.
AS SITL is still an inav software, but running on PC, it is possible to use HITL interface for communication.
[INAV-X-Plane-HITL](https://github.com/RomanLut/INAV-X-Plane-HITL) or [INAV-X-Plane-XITL](https://github.com/Scavanger/INAV-X-Plane-XITL) plugin can be used with SITL.
## Sensors
The following sensors are emulated:
- IMU (Gyro, Accelerometer)
- GPS
- Pitot
- Magnetometer (Compass)
- Rangefinder
- Barometer
- Battery (current and voltage), depending on simulator
![SITL-Fake-Sensors](assets/SITL-Fake-Sensors.png)
Select "FAKE" as type for all mentioned, so that they receive the data from the simulator.
## Serial ports
UARTs are replaced by TCP starting with port 5760 ascending. UART1 is mapped to port 5760, UART2 to 5761, etc.
By default, UART1 and UART2 are configured for MSP connections. Other UARTs will have TCP listeners if they have an INAV function assigned.
To connect the Configurator to SITL, select "SITL".
Alternativelly, select "TCP" and connect to ```localhost:5760``` (or ```127.0.0.1:5760``` if your OS doesn't understand `localhost`) (if SITL is running on the same machine).
IPv4 and IPv6 are supported, either raw addresses or host-name lookup.
The assignment and status of used UART/TCP connections is displayed on the console.
```
INAV 6.1.0 SITL
[SYSTEM] Init...
[SIM] No interface specified. Configurator only.
[EEPROM] Loaded 'eeprom.bin' (32768 of 32768 bytes)
[SOCKET] Bind TCP :: port 5760 to UART1
[SOCKET] Bind TCP :: port 5761 to UART2
[SOCKET] ::1 connected to UART1
```
All other interfaces (I2C, SPI, etc.) are not emulated.
## Remote control
Multiple methods for connecting RC Controllers are available:
- MSP_RX (TCP/IP)
- joystick / radio attached via USB (via simulator)
- serial receiver via USB to serial converter
- any receiver with proxy flight controller
### MSP_RX
MSP_RX is the default, 18 channels are supported over TCP/IP connection.
### Joystick interface
Only 8 channels are supported.
Select "SIM (SITL)" as the receiver and set up a joystick in the simulator.
Many RC transmittters (radios) can function as a joystick by plugging them in to the computer via USB, making this the simplest option in many cases.
*Not available with INAV-X-Plane-HITL plugin.*
### Serial Receiver via USB
- Connect a serial receiver to the PC via a USB-to-serial adapter
- Configure the receiver in the SITL as usual
- While starting SITL from configurator, enable "Serial receiver" option
The SITL offers a built-in option for forwarding the host's serial port to the SITL UART.
Please note that 100000(SBUS) and 420000(CRSF) are non-standart baud rates which may not be supported by some USB-to-serial adapters. FDTI and CH340 should work. CP2102/9 does not work.
#### Example SBUS:
For this you need a USB-to-serial adapter, receiver with inverter, or receiver which can output inverted SBUS (normal UART).
SBUS protocol is inverted UART.
Receiver's SBUS output should be connected to the USB-to-serial adapter's RX pin (via inverter).
With FT-Prog (https://ftdichip.com/utilities/) the signal can be inverted by adapter: Devices->Scan and Parse, then Hardware Specific -> Invert RS232 Signals -> Invert RXD.
![SITL-SBUS-FT232](assets/SITL-SBUS-FT232.png)
![SITL-SBUS](assets/serial_receiver_sbus.png)
### Telemetry
In the SITL configuration, enable serial receiver on some port and configure receiver type "Serial", "SBUS".
#### Example CRSF:
On receiver side, CRSF is normal UART.
Connect receiver's RX/TX pins (and GND, 5V of course) to USB-To-Serial adapter's TX/RX pins (RX to TX, TX to RX).
![SITL-SBUS](assets/serial_receiver_crsf.png)
In the SITL configuration, enable serial receiver on some port and configure receiver type "Serial", "CRSF".
### Proxy Flight controller
The last, but probably the most easiest way to connect receiver to the SITL, is to use any inav/betaflight Flight controler as proxy.
Connect receiver of any type to FC and configure FC to the point where channels are correctly updated in the "Receiver" tab. Inav and Betaflight are supported.
You also can use your plane/quad ( if receiver is powered from USB).
![SITL-SBUS](assets/serial_receiver_proxy.png)
In the SITL configuration, select "Receiver type: SIM" regardles of the kind of receiver used.
## OSD
For the OSD the program INAV-Sim-OSD is available: https://github.com/Scavanger/INAV-SIM-OSD.
For this, activate MSP-Displayport on a UART/TCP port and connect to the corresponding port.
Note: INAV-Sim-OSD only works if the simulator is in window mode.
*With INAV-X-Plane-HITL plugin, OSD is supported natively.*
## Command line
The command line options are only necessary if the SITL executable is started by hand.
There is also a SITL tab in the INAV Configurator (6.1.0 and later).
The following SITL specific command line options are available:
If SITL is started without command line options, only a serial MSP / CLI connection can be used (e.g. Configurator or other application) can be used.
```--path``` Path and file name to config file. If not present, eeprom.bin in the current directory is used. Example: ```C:\INAV_SITL\flying-wing.bin```, ```/home/user/sitl-eeproms/test-eeprom.bin```.
```--sim=[sim]``` Select the simulator. xp = X-Plane, rf = RealFlight. Example: ```--sim=xp```. If not specified, configurator-only mode is started. Omit for usage with INAV-X-Plane-HITL plugin.
```--simip=[ip]``` Hostname or IP address of the simulator, if you specify a simulator with "--sim" and omit this option IPv4 localhost (`127.0.0.1`) will be used. Example: ```--simip=172.65.21.15```, ```--simip acme-sims.org```, ```--sim ::1```.
```--simport=[port]``` Port number of the simulator, not necessary for all simulators. Example: ```--simport=4900```. For the X-Plane protocol, the default port is `49000`.
```--useimu``` Use IMU sensor data from the simulator instead of using attitude data directly from the simulator. Not recommended, use only for debugging.
```--chanmap=[chanmap]``` The channelmap to map the motor and servo outputs from INAV to the virtual receiver channel or control surfaces around simulator.
Syntax: (M(otor)|S(ervo)<INAV-OUT>-<RECEIVER_OUT>),..., all numbers must have two digits.
Example:
To assign motor1 to virtual receiver channel 1, servo 1 to channel 2, and servo2 to channel 3:
```--chanmap:M01-01,S01-02,S02-03```
Please also read the documentation of the individual simulators.
```--serialport``` Use serial receiver or proxy FC connected to host's serial port, f.e. ```--serialportCOM5``` or ```--serialportdev/ttyACM3```
```--serialuart``` Map serial receiver to SITL UART, f.e. ```--serialuart=3``` for UART3. Omit if using ```--fcproxy```.
```--baudrate``` Serial receiver baudrate (default: 115200)
```--stopbits=[None|One|Two]``` Serial receiver stopbits (default: One)
```--parity=[Even|None|Odd]``` Serial receiver parity (default: None)
```--fcproxy``` Use inav/betaflight FC as a proxy for serial receiver.
```--help``` Displays help for the command line options.
For options that take an argument, either form `--flag=value` or `--flag value` may be used.
## Running SITL
It is recommended to start the tools in the following order:
1. Simulator, aircraft should be ready for take-off
2. SITL
3. OSD
For INav-X-Plane-HITL plugin:
1. SITL (Run in configurator-only mode)
2. X-Plane
# #Forwarding serial data for other UART
Other UARTs can then be mapped to host's serial port using external tool, which can be found in directories ```inav-configurator\resources\sitl\linux\Ser2TCP```, ```inav-configurator\resources\sitl\windows\Ser2TCP.exe```
docs/SITL/X-Plane.md
+47
View File
@@ -0,0 +1,47 @@
# X-Plane
Tested on X-Plane 11, 12 should(!) work but not tested.
X-Plane is not a model flight simulator, but is based on real world data and is therefore suitable for GPS missions with waypoints.
## Aircraft
It is recommended to use the "AR Wing" of the INAV HITL project: https://github.com/RomanLut/INAV-X-Plane-HITL
## INAV Plugin
For advanced SITL features (like OSD, virtual RX, simulated hardware failures, power train simulation) you can use the [INAV-X-Plane-XITL plugin](https://github.com/Scavanger/INAV-X-Plane-XITL)
## General settings
In Settings / Network select "Accept incoming connections".
The port can be found under "UDP PORTS", "Port we receive on". If no connection is established, the port can be changed.
You may want to incease the "Flight model per frame" value under "General"
## Joystick
In the settings, calibrate the joystick, set it up and assign the axes as follows:
| INAV | X-Plane |
|------|---------|
| Roll | Roll |
| Pitch | Pitch |
| Throttle | Cowl Flap 1 |
| Yaw | Yaw |
| Channel 5 | Cowl Flap 2 |
| Channel 6 | Cowl Flap 3 |
| Channel 7 | Cowl Flap 4 |
| Channel 8 | Cowl Flap 5 |
Reverse axis in X-Plane if necessary.
## Channelmap:
The assignment of the "virtual receiver" is fixed:
1 - Throttle
2 - Roll
3 - Pitch
4 - Yaw
The internal mixer (e.g. for flying wings) cannot be deactivated without further ado, therefore always select "Aircraft with tail" in INAV.
For the standard Aircraft preset the channelmap is:
```--chanmap=M01-01,S01-03,S03-02,S04-04```
## Other applications
[fl2sitl](https://github.com/stronnag/bbl2kml/wiki/fl2sitl) is an open source application to replay an INAV Blackbox log through the INAV SITL via `blackbox_decode`. The output may be visualised in any MSP capable application, such as the INAV Configurator or [mwp](https://github.com/stronnag/mwptools). fl2sitl uses the X-plane protocol.
docs/SITL/assets/INAV-SIM-OSD.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 346 KiB

docs/SITL/assets/SITL-Fake-Sensors.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

docs/SITL/assets/SITL-SBUS-FT232.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

docs/SITL/assets/SITL-UART-TCP-Connecion.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.8 KiB

docs/SITL/assets/serial_receiver_crsf.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.8 KiB

docs/SITL/assets/serial_receiver_proxy.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.9 KiB

docs/SITL/assets/serial_receiver_sbus.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.6 KiB

docs/Safehomes.md
+86
View File
@@ -0,0 +1,86 @@
# INav - Safehomes
## Introduction
The "Home" position is used for the landing point when landing is enabled or in an emergency situation. It is usually determined by the GPS location where the aircraft is armed.
For airplanes, the landing procedure is explained very well by Pawel Spychalski [here.](https://quadmeup.com/inav-1-8-automated-landing-for-fixed-wings/)
![Fixed wing loiter and descend](assets/images/loiter_and_descend.png)
One potential risk when landing is that there might be buildings, trees and other obstacles in the way as the airplance circles lower toward the ground at the arming point. Most people don't go the middle of the field when arming their airplanes.
## Safehome
Safehomes are a list of GPS coordinates that identify safe landing points. You can define up to 8 safehomes for different locations you fly at. When the flight controller is armed, it checks the list of safehomes. The nearest safehome that is enabled and within ```safehome_max_distance``` (default 200m) of the current position is identified. The arming home location remains as home.
When RTH is activated, whether by radio failsafe, or using the RTH radio control mode, the safehome identified during arming will replace the home location. If RTH is turned off, either by regaining radio control or turning off the RTH radio control mode, the home location will return back to arming point.
The safehome operating mode is set using ```safehome_usage_mode```. If ```OFF```, safehomes will not be used. If ```RTH```, the safehome will replace the arming location when RTH is activated, either manually or because of RX failsafe. If ```RTH_FS```, the safehome will only be used for RX failsafe. This option can be changed using the OSD menu.
If you frequently use RTH to return back to the arming point, you may not want the aircraft to fly to the safehome. Let it do this at least once to confirm safehomes is working as expected. Afterward, `set safehome_usage_mode = RTH_FS` and the safehome will only be used for failsafe.
When using mode `RTH_FS`, you should confirm that your radio's failsafe configuration triggers the INAV failsafe mode. With many receivers, you have the ability to specify what signal to output during failsafe conditions.
When you are choosing safehome locations, ensure that the location is clear of obstructions for a radius more than 50m (`nav_fw_loiter_radius`). As the plane descends, the circles aren't always symmetrical, as wind direction could result in some wider or tighter turns. Also, the direction and length of the final landing stage is also unknown. You want to choose a point that has provides a margin for variation and the final landing.
If your safehome is not visible from your current location, use extra caution. A visual check of the safehome is recommend prior to flying. If the safehome is in use, you can use the OSD menu to disable safehome usage prior to your flight.
## OSD Message when Armed
When the aircraft is armed, the OSD briefly shows `ARMED` and the current GPS position and current date and time.
If a safehome is selected, an additional message appears:
```
H - DIST -> SAFEHOME n <- New message
n is the Safehome index (0-7)
ARMED DIST is the distance from
GPS LATITUDE your current position to this safehome
GPS LONGITUDE
GPS PLUS CODE
CURRENT DATE
CURRENT TIME
```
The GPS details are those of the arming location, not the safehome.
To draw your attention to a safehome being selected, the message flashes and stays visible longer.
If a safehome was found, but ``safehome_usage_mode``` is ```OFF```, the message ```SAFEHOME FOUND; MODE OFF``` will appear.
## OSD Message during RTH
If RTH is in progress to a safehome, the message "DIVERTING TO SAFEHOME" will be displayed.
## CLI command `safehome` to manage safehomes
`safehome` - List all safehomes
`safehome reset` - Clears all safehomes.
`safehome <n> <enabled> <lat> <lon>` - Set the parameters of a safehome with index `<n>`.
Parameters:
* `<enabled>` - 0 is disabled, 1 is enabled.
* `<lat>` - Latitude (WGS84), in degrees * 1E7 (for example 123456789 means 12.3456789).
* `<lon>` - Longitude.
Note that coordinates from Google Maps only have five or six decimals, so you need to pad zero decimals until you have seven before removing the decimal period to set the correct safehome location. For example, coordinates 54.353319 -4.517927 obtained from Google Maps need to be entered as 543533190 -45179270, coordiniates 43.54648 -7.86545 as 435464800 -78654500 and 51.309842 -0.095651 as 513098420 -00956510.
Safehomes are saved along with your regular settings and will appear in `diff` and `dump` output. Use `save` to save any changes, as with other settings.
### `safehome` example
```
# safehome
safehome 0 1 543533190 -45179270
safehome 1 1 435464800 -78654500
safehome 2 1 513098420 -00956510
safehome 3 0 0 0
safehome 4 0 0 0
safehome 5 0 0 0
safehome 6 0 0 0
safehome 7 0 0 0
```
docs/Safety.md
+29
View File
@@ -0,0 +1,29 @@
# Safety
As many can attest, multirotors and RC models in general can be very dangerous, particularly on the test bench. Here are some simple golden rules to save you a trip to the local ER:
* **NEVER** arm your model with propellers fitted unless you intend to fly!
* **Always** remove your propellers if you are setting up for the first time, flashing firmware, or if in any doubt.
## Before Installing
Please consult the [Cli](Cli.md), [Controls](Controls.md), [Failsafe](Failsafe.md) and [Modes](https://github.com/iNavFlight/inav/wiki/Modes)
pages for further important information.
You are highly advised to use the Receiver tab in the INAV Configurator, making sure your Rx channel
values are centered at 1500 (1520 for Futaba RC) with minimum & maximums of 1000 and 2000 (respectively)
are reached when controls are operated. Failure to configure these ranges properly can create
problems, such as inability to arm (because you can't reach the endpoints) or immediate activation of
[failsafe](Failsafe.md).
You may have to adjust your channel endpoints and trims/sub-trims on your RC transmitter to achieve the
expected range of 1000 to 2000.
The referenced values for each channel have marked impact on the operation of the flight controller and the
different flight modes.
## Props Spinning When Armed
With the default configuration, when the controller is armed, the propellers *WILL* begin spinning at low speed.
We recommend keeping this setting as it provides a good visual indication the craft is armed.
If you wish to change this behavior, see the MOTOR_STOP feature in the Configurator and relevant docuemntation pages.
Enabling this feature will stop the props from spinning when armed.
docs/Screenshots/ADSB_TTSC01_settings.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 94 KiB

docs/Screenshots/adjustments-incorrect-config-1.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB

docs/Screenshots/adjustments-incorrect-config-2-corrected.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 76 KiB

docs/Screenshots/adjustments-incorrect-config-2.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 73 KiB

docs/Screenshots/adjustments-pid-via-6pos-and-3pos.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 49 KiB

docs/Screenshots/adjustments-pid-via-two-3pos.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 89 KiB

docs/Screenshots/adjustments-pitch-and-roll-rate-adjustment-via-3pos.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 27 KiB

docs/Screenshots/adjustments-rate-profile-selection-via-3pos.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 27 KiB

docs/Screenshots/adjustments-rates-via-a-2pos-and-3pos.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB

docs/Screenshots/blackbox-dataflash.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 53 KiB

docs/Screenshots/blackbox-screenshot-1.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 242 KiB

docs/Screenshots/cleanflight-gui.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 70 KiB

docs/Screenshots/mixer_profile.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

docs/Screenshots/mixerprofile_4puls1_mix.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB

docs/Screenshots/mixerprofile_flow.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

docs/Screenshots/mixerprofile_fw_mixer.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 314 KiB

docs/Screenshots/mixerprofile_mc_mixer.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 394 KiB

docs/Screenshots/mixerprofile_servo_transition_mix.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 19 KiB

docs/Screenshots/programming_disable_gps_sensor_fix.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

docs/Sensors.md
+17
View File
@@ -0,0 +1,17 @@
# Sensors
## Temperature Correction
Temperature related drift for the Nav Accelerometer Z axis and Barometer can be corrected using settings `acc_temp_correction` and `baro_temp_correction`. The settings are temperature correction factor in cms-2/K and cm/K respectively, limited to -50 to +50, and are based on a linear correction characteristic. It is possible to perform an auto calibration of the required correction value using a setting of 51 with the auto calibration ending after a 5 minute timeout or on first arm. It's also possible to simply enter a value and see how the sensor drifts as the FC warms up, e.g. a BMP280 barometer requires a value around 20 cm/K for the `baro_temp_correction` setting.
### Barometer Calibration
Best calibrated by checking barometer altitude in the Configurator Sensor tab, powered just from USB or the main battery. First check Barometer altitude drift with `baro_temp_correction` set to 0 starting with a cold FC. Then change the setting to 51, power off and allow the FC to cool then power on again and recheck the barometer altitude in the Configurator Sensors tab. The barometer altitude will drift as before until 5 mins after bootup at which point, if the calibration has worked, the barometer altitude should fall close to 0. This will be accompanied by a "success" beep (may need battery power for this rather than just USB). The calibrated setting can be saved by switching to the CLI and hitting "Save Settings" (or use the Save stick command or CMS). Power off and allow the FC to cool down then recheck barometer altitude again, it should show much reduced altitude drift as it warms up.
### Nav Acceleromter Z Axis Calibration
The Nav accelerometer Z axis is calibrated in a similar way to the Barometer except it isn't so easy to check while calibrating given the lack of direct feedback. The acc Z value in the Configurator Sensors tab isn't the corrected value so can't be used. Instead set `debug_mode` to `ALTITUDE` and check the behaviour of `Debug 3` in the Configurator Sensors Tab for Debug output. It will drift during calibration then show a sudden change when calibration is finished. After saving and rebooting check `Debug 3` in the Configurator Sensors tab, it should show much less drift from zero if the calibration was successful. Successful calibration can also be checked by making sure `acc_temp_correction` shows a value other than 0 or 51.
docs/Serial Gimbal.md
+56
View File
@@ -0,0 +1,56 @@
# Serial Gimbal
INAV 8.0 introduces support for serial Gimbals. Currently, it is compatible with the protocol used by the Walksnail GM series gimbals.
While these gimbals also support PWM as input, using the Serial protocol gives it more flexibility and saves up to 4 PWM channels. The downside of the Serial protocol vs PWM input is that you don't have access to the full power of INAV's mixers. The main advantage is that you gain easy control of gimbal functions using INAV's modes.
# Axis Input
The Serial Gimbal supports 2 differents inputs.
## PWM Channels
This is the simplest way to control the Gimbal, as you can use your radio mixer and sliders to Control the gimbal by assigning RC channels to functions in the ```Configuration``` tab. You can control all 3 gimbal axis and unlike the raw PWM input, gimbal modes are controlled by INAV modes and you can control roll channel as well, instead of wiring 4 servo outputs. If an rc channel is set to 0, that input will be ignore and will be equivalent to a centered RC channel. So, if you setup the serial gimbal and don't assign any rc channels, it will stay centered, with default sensitivity and will obey the Gimbal MODES setup in the Modes tab.
## Headtracker Input
Headtracker input is only used when you have a Headtracker device configured and the ```Gimbal Headtracker``` mode is active.
A Headtracker device is a device that transmits headtracker information by a side channel, instead of relying on your rc link.
In head tracker mode, the Serial Gimbal will ignore the axis rc channel inputs and replace it with the inputs coming from the Headtracker device.
# Gimbal Modes
## No Gimbal mode selected
Like ACRO is the default mode for flight modes, the Gimbal will default to ```FPV Mode``` or ```Follow Mode``` when no mode is selected. The gimbal will try to stablized the footage and will follow the aircraft pitch, roll and yaw movements and use user inputs to point the camera where the user wants.
## Gimbal Center
This locks the gimbal camera to the center position and ignores any user input. Useful to reset the camera if you loose orientation.
## Gimbal Headtracker
Switches inputs to the configured Headtracker device. If no device is configured it will behave like Gimbal Center.
## Gimbal Level Tilt
This mode locks the camera tilt (pitch axis) and keeps it level with the horizon. Pitching the aircraft up and down, will move the camera so it stays pointing at the horizon. It can be combined with ```Gimbal Level Roll```.
## Gimbal Level Roll
This mode locks the camera roll and keeps it level with the horizon. Rolling the aircraft will move the camera so it stays level with the horizon. It can be combined with ```Gimbal Level Tilt```.
# Advanced settings
The gimbal also supports some advanced settings not exposed in the configurator.
## Gimbal Trim
You can set a trim setting for the gimbal, the idea is that it will shift the notion of center of the gimbal, like a trim and let you setup a fixed camera up tilt, like you would have in a traditional fpv quad setup.
```
gimbal_pan_trim = 0
Allowed range: -500 - 500
gimbal_tilt_trim = 0
Allowed range: -500 - 500
gimbal_roll_trim = 0
Allowed range: -500 - 500
```
## Gimbal and Headtracker on a single uart
As INAV does not process any inputs from the Walksnail Gimbal, it is possible to share the uart with the Walksnail Headtracking output by connect the fc TX to the gimbal and RX to receive the headtracker input.
```
gimbal_serial_single_uart = OFF
Allowed values: OFF, ON
```
docs/Serial.md
+125
View File
@@ -0,0 +1,125 @@
# Serial
INAV has enhanced serial port flexibility but configuration is slightly more complex as a result.
INAV has the concept of a function (MSP, GPS, Serial RX, etc) and a port (VCP, UARTx, SoftSerial x).
Not all functions can be used on all ports due to hardware pin mapping, conflicting features, hardware, and software
constraints.
## Serial port types
* USB Virtual Com Port (VCP) - USB pins on a USB port connected directly to the processor without requiring
a dedicated USB to UART adapter. VCP does not 'use' a physical UART port.
* UART - A pair of dedicated hardware transmit and receive pins with signal detection and generation done in hardware.
* SoftSerial - A pair of hardware transmit and receive pins with signal detection and generation done in software.
UART is the most efficient in terms of CPU usage.
SoftSerial is the least efficient and slowest, SoftSerial should only be used for low-bandwidth usages, such as telemetry transmission.
UART ports are sometimes exposed via on-board USB to UART converters, such as the CP2102.
If the flight controller does not have an on-board USB to UART converter and doesn't support VCP then an external USB to UART board is required.
These are sometimes referred to as FTDI boards. FTDI is just a common manufacturer of a chip (the FT232RL) used on USB to UART boards.
When selecting a USB to UART converter choose one that has DTR exposed as well as a selector for 3.3v and 5v since they are more useful.
Examples:
* [FT232RL FTDI USB To TTL Serial Converter Adapter](https://inavflight.com/shop/s/bg/917226)
* [USB To TTL / COM Converter Module buildin-in CP2102](https://inavflight.com/shop/s/bg/27989)
Both SoftSerial and UART ports can be connected to your computer via USB to UART converter boards.
## Serial Configuration
Serial port configuration is best done via the configurator.
Configure serial ports first, then enable/disable features that use the ports. To configure SoftSerial ports the SOFTSERIAL feature must be also be enabled.
### Constraints
If the configuration is invalid the serial port configuration will reset to its defaults and features may be disabled.
* There must always be a port available to use for MSP/CLI.
* There is a maximum of 3 MSP ports.
* To use a port for a function, the function's corresponding feature must be also be enabled.
e.g. after configuring a port for GPS enable the GPS feature.
* If SoftSerial is used, then all SoftSerial ports must use the same baudrate.
* Softserial is limited to 19200 buad.
* All telemetry systems except MSP will ignore any attempts to override the baudrate.
* MSP/CLI can be shared with EITHER Blackbox OR telemetry (LTM or MAVlink, not RX telemetry). In shared mode blackbox or telemetry will be output only when armed.
* Smartport telemetry cannot be shared with MSP.
* No other serial port sharing combinations are valid.
* You can use as many different telemetry systems as you like at the same time.
* You can only use each telemetry system once. e.g. FrSky telemetry cannot be used on two port, but LTN Telemetry and FrSky on two different ports is fine.
### Configuration via CLI
You can use the CLI for configuration but the commands are reserved for developers and advanced users.
The `serial` CLI command takes 6 arguments.
1. Identifier
2. Function bitmask (see serialPortFunction_e in the source)
3. MSP baud rate
4. GPS baud rate
5. Telemetry baud rate (auto baud allowed)
6. Blackbox baud rate
### Baud Rates
The allowable baud rates are as follows:
| Identifier | Baud rate |
| ---------- | --------- |
| 0 | Auto |
| 1 | 1200 |
| 2 | 2400 |
| 3 | 4800 |
| 4 | 9600 |
| 5 | 19200 |
| 6 | 38400 |
| 7 | 57600 |
| 8 | 115200 |
| 9 | 230400 |
| 10 | 250000 |
| 11 | 460800 |
| 12 | 921600 |
| 13 | 1000000 |
| 14 | 1500000 |
| 15 | 2000000 |
| 16 | 2470000 |
### Function numbers as of 2025
| Function | Number |
| -------------------------- | -------------------------------------------------- |
| NONE | 0, |
| MSP | (1 << 0), // 1 |
| GPS | (1 << 1), // 2 |
| UNUSED_3 | (1 << 2), // 4 //Was FUNCTION_TELEMETRY_FRSKY |
| TELEMETRY_HOTT | (1 << 3), // 8 |
| TELEMETRY_LTM | (1 << 4), // 16 |
| TELEMETRY_SMARTPORT | (1 << 5), // 32 |
| RX_SERIAL | (1 << 6), // 64 |
| BLACKBOX | (1 << 7), // 128 |
| TELEMETRY_MAVLINK | (1 << 8), // 256 |
| TELEMETRY_IBUS | (1 << 9), // 512 |
| RCDEVICE | (1 << 10), // 1024 |
| VTX_SMARTAUDIO | (1 << 11), // 2048 |
| VTX_TRAMP | (1 << 12), // 4096 |
| UNUSED_1 | (1 << 13), // 8192: former\ UAV_INTERCONNECT |
| OPTICAL_FLOW | (1 << 14), // 16384 |
| LOG | (1 << 15), // 32768 |
| RANGEFINDER | (1 << 16), // 65536 |
| VTX_FFPV | (1 << 17), // 131072 |
| ESCSERIAL | (1 << 18), // 262144: this is used for both SERIALSHOT and ESC_SENSOR telemetry |
| TELEMETRY_SIM | (1 << 19), // 524288 |
| FRSKY_OSD | (1 << 20), // 1048576 |
| DJI_HD_OSD | (1 << 21), // 2097152 |
| SERVO_SERIAL | (1 << 22), // 4194304 |
| TELEMETRY_SMARTPORT_MASTER | (1 << 23), // 8388608 |
| UNUSED_2 | (1 << 24), // 16777216 |
| MSP_OSD | (1 << 25), // 33554432 |
docs/Servo Gimbal.md
+17
View File
@@ -0,0 +1,17 @@
# Servo Gimbal
Starting from INAV 2.0, _servo gimbal_ (aka _SERVO_TILT_) feature is removed. This functionality can be configured using _Mixer Configurator Tab_ instead.
Servo gimbal using mixer works for all flight controllers that supports servos in either multirotor or airplane configuration. Bear in mind, that some boards might not have any servo outputs in multirotor configuration. In this case, servo gimbal will just not work. Refer to the board documentation to find out if servos are available in multirotor configuration.
## How to setup _Servo Gimbal_
1. Open Mixer tab
1. Add new _servo rule_ for given servo index
1. Choose source as one of _Gimbal Pitch_ and _Gimbal Roll_
1. When required, apply scaling of the output by modyfing weight
1. When required, servo direction can be modified by applying negative weight
### MIXTILT option
In rare cases, when gimbal required pitch mixed with roll, it is possible to use mixer to do it. In this case, mix roll and pitch exis are required. Refer to gimbal documentation for more details.
docs/Servo.md
+37
View File
@@ -0,0 +1,37 @@
# Servo configuration
Servos can be configured from the graphical user interface's `Outputs` tab.
* MID: middle/neutral point of the servo
* MIN: the minimum value that can be sent to the servo is MIN * Rate
* MAX: the maximum value that can be sent to the servo is MAX * Rate
* Rate: servo command = servo rate * mixer output
* Reverse: if enabled the servo output is reversed
CLI commands to configure servos:
The `servo` command is used to list or modify servo's configuration. To list the current servo's configuration run the `servo` command without parameters.
To change the configuration of a servo use the `servo` command with the following syntax: `servo <n> <min> <max> <mid> <rate>`. `<n>` is representing the index of the servo output defined by a servo mixer (See (mixer documentation)[https://github.com/iNavFlight/inav/blob/master/docs/Mixer.md]). The other parameters must be positive integers apart from the rate wich valid range is [-125, 125].
## Servo filtering
A low-pass filter can be enabled for the servos. It may be useful for avoiding structural modes in the airframe, for example.
### Configuration
Currently, it can only be configured via the CLI:
Use `set servo_lpf_hz=20` to enable filtering. This will set servo low pass filter to 20Hz.
### Tuning
One method for tuning the filter cutoff is as follows:
1. Ensure your vehicle can move at least somewhat freely in the troublesome axis. For example, if you are having yaw oscillations on a tricopter, ensure that the copter is supported in a way that allows it to rotate left and right to at least some degree. Suspension near the CG is ideal. Alternatively, you can just fly the vehicle and trigger the problematic condition you are trying to eliminate, although tuning will be more tedious.
2. Tap the vehicle at its end in the axis under evaluation. Directly commanding the servo in question to move may also be used. In the tricopter example, tap the end of the tail boom from the side, or command a yaw using your transmitter.
3. If your vehicle oscillates for several seconds or even continues oscillating indefinitely, then the filter cutoff frequency should be reduced. Reduce the value of `servo_lowpass_freq` by half its current value and repeat the previous step.
4. If the oscillations are dampened within roughly a second or are no longer present, then you are done. Be sure to run `save`.
docs/Settings.md
+6774
View File
File diff suppressed because it is too large Load Diff
docs/Spektrum bind.md
+88
View File
@@ -0,0 +1,88 @@
# Spektrum bind support
Spektrum bind with hardware bind plug support.
The Spektrum bind code is enabled for the boards listed in the section [Supported firmware and hardware ports](#Supported firmware and hardware ports)
## Developement - configuring the bind code
The following parameters can be used to enable and configure this in the related target.h file:
SPEKTRUM_BIND Enables the Spektrum bind code
BIND_PORT GPIOA Defines the port for the bind pin
BIND_PIN Pin_3 Defines the bind pin (the satellite receiver is connected to)
This is to activate the hardware bind plug feature
HARDWARE_BIND_PLUG Enables the hardware bind plug feature
BINDPLUG_PORT GPIOB Defines the port for the hardware bind plug
BINDPLUG_PIN Pin_5 Defines the hardware bind plug pin
## Hardware
The hardware bind plug will be enabled via defining HARDWARE_BIND_PLUG during building of the firmware. BINDPLUG_PORT and BINDPLUG_PIN also need to be defined (please see above). The hardware bind plug is expected between the defined bind pin and ground.
## Supported firmware and hardware ports
Note that the bind pin *may* not be the UART pin normally associated with the serial RX.
| Board | Bind Pin | UART Pin |
| ----- | -------- | -------- |
| AIRBOTF4 | PB11 | UART3 RX |
| AIRHEROF3 | PB11 | UART3 RX |
| ALIENFLIGHTF3 | PA3 | UART2 RX |
| BETAFLIGHTF4 | PB11 | UART3 RX |
| BLUEJAYF4 | PB11 | UART3 RX |
| FALCORE | PA3 | UART2 RX |
| FURYF3 | PB11 | UART3 RX |
| LUX_RACE | PC5 | UART1 RX |
| MATEKF405 | PA3 | UART2 RX |
| MATEKF405SE | PA3 | UART2 RX |
| MATEKF411 | PA10 | UART1 RX |
| MATEKF411SE | PA3 | UART2 RX |
| MATEKF722 | PA3 | UART2 RX |
| MOTOLAB | PB4 | UART2 RX |
| OMNIBUS | PB11 | UART3 RX |
| OMNIBUSF4 | PB11 | UART3 RX |
| PIKOBLX | PB11 | UART3 RX |
| RCEXPLORERF3 | PA3 | UART2 RX |
| REVO | PB11 | UART3 RX |
| RMDO | PB11 | UART3 RX |
| SPARKY | PA3 | UART2 RX |
| SPEEDYBEEF4 | PC11 | UART3 RX |
| SPRACINGF3 | PB11 | UART3 RX |
| SPRACINGF3EVO | PB11 | UART3 RX |
| SPRACINGF3MINI | PB11 | UART3 RX |
*Table automagically generated by `mwptools/samples/spkbind.rb` 2019-08-16. E&OE, update at your own convenience.*
## Function
The spektrum_sat_bind CLI parameter is defining the number of bind impulses (1-10) send to the satellite receiver. Setting spektrum_sat_bind to zero will disable the bind mode in any case. The bind mode will only be activated after an power on or hard reset. Please refer to the table below for the different possible values.
If the hardware bind plug is configured the bind mode will only be activated if the plug is set during the firmware start-up. The value of the spektrum_sat_bind parameter will be permanently preserved. The bind plug should be always removed for normal flying.
If no hardware bind plug is used the spektrum_sat_bind parameter will trigger the bind process during the next hardware reset and will be automatically reset to "0" after this.
Please refer to the satellite receiver documentation for more details of the specific receiver in bind mode. Usually the bind mode will be indicated with some flashing LEDs.
## Table with spektrum_sat_bind parameter value
| Value | Receiver mode |
| ----- | ------------------|
| 3 | DSM2 1024bit/22ms |
| 5 | DSM2 2048bit/11ms |
| 7 | DSMX 1024bit/22ms |
| 9 | DSMX 2048bit/11ms |
More detailed information regarding the satellite binding process can be found here:
http://wiki.openpilot.org/display/Doc/Spektrum+Satellite
#### Tested satellite transmitter combinations
| Satellite | Remote | Remark |
| -------------------- | -------------- | -------------------------------------------------------- |
| Orange R100 | Spektrum DX6i | Bind value 3 |
| Lemon RX DSM2/DSMX | Spektrum DX8 | Bind value 5 |
| Lemon RX DSMX | Walkera Devo10 | Bind value 9, Deviation firmware 4.01 up to 12 channels |
| Lemon RX DSM2 | Walkera Devo7 | Bind value 9, Deviation firmware |
docs/Telemetry.md
+416
View File
@@ -0,0 +1,416 @@
# Telemetry
Telemetry allows you to know what is happening on your aircraft while you are flying it. Among other things you can receive battery voltages and GPS positions on your transmitter.
Telemetry can be either always on, or enabled when armed. If a serial port for telemetry is shared with other functionality then then telemetry will only be enabled when armed on that port.
Telemetry is enabled using the 'TELEMETRY' feature.
```
feature TELEMETRY
```
Multiple telemetry providers are currently supported, FrSky, Graupner HoTT V4, SmartPort (S.Port), LightTelemetry (LTM). MAVLink, IBUS, Crossfire and GSM SMS.
All telemetry systems use serial ports, configure serial ports to use the telemetry system required. Multiple telemetry streams may be enabled, but only one of each type, e.g. Smartport + LTM or MAVLink + CRSF.
## SmartPort (S.Port) telemetry
Smartport is a telemetry system used by newer FrSky transmitters such as the Taranis Q X7, X9D, X9D+, X9E or XJR paired with X-series receivers such as the X4R(SB), X8R, XSR, R-XSR, XSR-M or XSR-E. For older D-series receivers see FrSky telemetry below.
More information about the implementation can be found here: https://github.com/frank26080115/cleanflight/wiki/Using-Smart-Port
Smartport devices are using _inverted_ serial protocol and as such can not be directly connected to all flight controllers. Depending on flight controller CPU family:
| CPU family | Direct connection | Receiver _uninverted_ hack | SoftwareSerial | Additional hardware inverter |
| ----- | ----- | ----- | ----- | ----- |
| STM32F4 | not possible (*) | possible | possible | possible |
| STM32F7 | possible | not required | possible | not required |
| STM32H7 | possible | not required | possible | not required |
> * possible if flight controller has dedicated, additional, hardware inverter
Smartport uses _57600bps_ serial speed.
### Direct connection for F7/H7
Only TX serial pin has to be connected to Smartport receiver.
```
set telemetry_inverted = OFF
set telemetry_halfduplex = ON
```
### Receiver uninverted hack
Some receivers (X4R, XSR and so on) can be hacked to get _uninverted_ Smartport signal. In this case connect uninverted signal to TX pad of chosen serial port and enable `telemetry_inverted`.
```
set telemetry_inverted = ON
set telemetry_halfduplex = ON
```
### Software Serial
Software emulated serial port allows to connect to Smartport receivers without any hacks. Only `TX` has to be connected to the receiver.
```
set telemetry_inverted = OFF
set telemetry_halfduplex = ON
```
If the solution above is not working, there is an alternative RX and TX lines have to be bridged using
1kOhm resistor (confirmed working with 100Ohm, 1kOhm and 10kOhm)
```
SmartPort ---> RX (CH5 pad) ---> 1kOhm resistor ---> TX (CH6 pad)
```
```
set telemetry_inverted = OFF
```
### SmartPort (S.Port) with external hardware inverter
It is possible to use DIY UART inverter to connect SmartPort receivers to F1 and F4 based flight controllers. This method does not require a hardware hack of S.Port receiver.
#### SmartPort inverter using bipolar transistors
![Inverter](assets/images/smartport_inverter.png)
#### SmartPort inverter using unipolar transistors
![Inverter](assets/images/smartport_inverter_2n7000.png)
**Warning** Chosen UART has to be 5V tolerant. If not, use 3.3V power supply instead (not tested)
When the external inverter is used, following configuration has to be applied:
```
set telemetry_halfduplex = OFF
set telemetry_inverted = ON
```
### Available SmartPort (S.Port) sensors
The following sensors are transmitted
* **GSpd** : current horizontal ground speed, calculated by GPS.
* **VFAS** : actual vbat value.
* **Curr** : actual current comsuption, in amps.
* **Alt** : barometer based altitude, relative to home location.
* **Fuel** : if `smartport_fuel_unit = PERCENT` remaining battery percentage sent, MAH drawn otherwise.
* **GPS** : GPS coordinates.
* **VSpd** : vertical speed, unit is cm/s.
* **Hdg** : heading, North is 0°, South is 180°.
* **AccX,Y,Z** : accelerometer values (not sent if `frsky_pitch_roll = ON`).
* **470** : flight mode, sent as 7 digits. Number is sent as **ABCDEFG** detailed below. The numbers are additives (for example: if digit C is 6, it means both position hold and altitude hold are active) :
* **A** : 1 = WRTH mode, 2 = Angle hold mode
* **B** : 1 = Fixed Wing Auto-land, 2 = Turtle mode, 4 = Geofence action mode, 8 = Loiter mode
* **C** : 1 = flaperon mode, 2 = auto tune mode, 4 = failsafe mode
* **D** : 1 = return to home, 2 = waypoint mode, 4 = headfree mode, 8 = Course Hold
* **E** : 1 = heading hold, 2 = altitude hold, 4 = position hold
* **F** : 1 = angle mode, 2 = horizon mode, 4 = passthru mode
* **G** : 1 = ok to arm, 2 = arming is prevented, 4 = armed
_NOTE_ This sensor used to be **Tmp1**. The ID has been reassigned in INAV 8.0. The old ID of **Tmp1** can still be used, by using `set frsky_use_legacy_gps_mode_sensor_ids = ON`. This is deprecated and will be removed in INAV 10.0. All tools and scripts using the old IDs should be updated to use the new ID.
* **480** : GPS lock status, accuracy, home reset trigger, and number of satellites. Number is sent as **ABCD** detailed below. Typical minimum GPS 3D lock value is 3906 (GPS locked and home fixed, HDOP highest accuracy, 6 satellites).
* **A** : 1 = GPS fix, 2 = GPS home fix, 4 = home reset (numbers are additive)
* **B** : GPS accuracy based on HDOP (0 = lowest to 9 = highest accuracy)
* **C** : number of satellites locked (digit C & D are the number of locked satellites)
* **D** : number of satellites locked (if 14 satellites are locked, C = 1 & D = 4)
_NOTE_ This sensor used to be **Tmp2**. The ID has been reassigned in INAV 8.0. The old ID of **Tmp2** can still be used, by using `set frsky_use_legacy_gps_mode_sensor_ids = ON`. This is deprecated and will be removed in INAV 10.0. All tools and scripts using the old IDs should be updated to use the new ID.
* **GAlt** : GPS altitude, sea level is zero.
* **ASpd** : true air speed, from pitot sensor. This is _Knots * 10_
* **A4** : average cell value. Warning : unlike FLVSS and MLVSS sensors, you do not get actual lowest value of a cell, but an average : (total lipo voltage) / (number of cells)
* **0420** : distance to GPS home fix, in meters
* **0430** : if `frsky_pitch_roll = ON` set this will be pitch degrees*10
* **0440** : if `frsky_pitch_roll = ON` set this will be roll degrees*10
* **0450** : 'Flight Path Vector' or 'Course over ground' in degrees*10
* **0460** : Azimuth in degrees*10
### Compatible SmartPort/INAV telemetry flight status
To quickly and easily monitor these SmartPort sensors and flight modes, install [OpenTX Telemetry Widget](https://github.com/iNavFlight/OpenTX-Telemetry-Widget) to your Taranis Q X7, X9D, X9D+ or X9E transmitter.
### Notes
Many of the same SmartPort telemetry values listed above are also sent with FrSky D-Series telemetry.
RPM shows throttle output when armed.
RPM shows when disarmed.
RPM requires that the 'blades' setting is set to 12 on your receiver/display - tested with Taranis/OpenTX.
## HoTT telemetry
Only Electric Air Modules and GPS Modules are emulated.
Use the latest Graupner firmware for your transmitter and receiver.
Older HoTT transmitters required the EAM and GPS modules to be enabled in the telemetry menu of the transmitter. (e.g. on MX-20)
You can use a single connection, connect HoTT RX/TX only to serial TX, leave serial RX open and make sure the setting `telemetry_halfduplex` is OFF.
The following information is deprecated, use only for compatibility:
Serial ports use two wires but HoTT uses a single wire so some electronics are required so that the signals don't get mixed up. The TX and RX pins of
a serial port should be connected using a diode and a single wire to the `T` port on a HoTT receiver.
Connect as follows:
* HoTT TX/RX `T` -> Serial RX (connect directly)
* HoTT TX/RX `T` -> Diode `-( |)-` > Serial TX (connect via diode)
The diode should be arranged to allow the data signals to flow the right way
```
-( |)- == Diode, | indicates cathode marker.
```
1N4148 diodes have been tested and work with the GR-24.
When using the diode enable `telemetry_halfduplex`, go to CLI and type `set telemetry_halfduplex = ON`, don't forget a `save` afterwards.
As noticed by Skrebber the GR-12 (and probably GR-16/24, too) are based on a PIC 24FJ64GA-002, which has 5V tolerant digital pins.
Note: The SoftSerial ports may not be 5V tolerant on your board. Verify if you require a 5v/3.3v level shifters.
## LightTelemetry (LTM)
LTM is a lightweight streaming telemetry protocol supported by a number of OSDs, ground stations and antenna trackers.
The INAV implementation of LTM implements the following frames:
* G-FRAME: GPS information (lat, long, ground speed, altitude, sat info)
* A-FRAME: Attitude (pitch, roll, heading)
* S-FRAME: Status (voltage, current+, RSSI, airspeed+, status). Item suffixed '+' not implemented in INAV.
* O-FRAME: Origin (home position, lat, long, altitude, fix)
In addition, in INAV:
* N-FRAME: Navigation information (GPS mode, Nav mode, Nav action, Waypoint number, Nav Error, Nav Flags).
* X-FRAME: Extra information. Currently HDOP is reported.
LTM is transmit only, and can work at any supported baud rate. It is designed to operate over 2400 baud (9600 in INAV) and does not benefit from higher rates. It is thus usable on soft serial.
A CLI variable `ltm_update_rate` may be used to configure the update rate and hence band-width used by LTM, with the following enumerations:
* NORMAL: Legacy rate, currently 303 bytes/second (requires 4800 bps)
* MEDIUM: 164 bytes/second (requires 2400 bps)
* SLOW: 105 bytes/second (requires 1200 bps)
For many telemetry devices, there is direction correlation between the air-speed of the radio link and range; thus a lower value may facilitate longer range links.
More information about the fields, encoding and enumerations may be found [on the wiki](https://github.com/iNavFlight/inav/wiki/Lightweight-Telemetry-(LTM)).
## MAVLink telemetry
MAVLink is a lightweight header-only message marshalling library for micro air vehicles. INAV supports MAVLink for compatibility with ground stations, OSDs and antenna trackers built for PX4, PIXHAWK, APM and Parrot AR.Drone platforms.
MAVLink implementation in INAV is transmit-only and usable on low baud rates and can be used over soft serial (requires 19200 baud). MAVLink V1 and V2 are supported.
## Cellular telemetry via text messages
INAV can use a SimCom SIM800 series cellular module to provide telemetry via text messages. Telemetry messages can be requested by calling the module's number or sending it a text message. The module can be set to transmit messages at regular intervals, or when an acceleration event is detected. A text message command can be used to put the flight controller into RTH mode.
The telemetry message looks like this:
```
12.34V 2.0A ALT:5 SPD:10/13.6 DIS:78/19833 HDG:16 SAT:21 SIG:9 ANG maps.google.com/?q=6FG22222%2B222
```
giving battery voltage, current, altitude (m), speed / average speed (m/s), distance to home / total traveled distance (m), heading (degrees), number of satellites, cellular signal strength, flight mode and GPS coordinates as a Google Maps link. `SIG` has a range of 0 -- 31, with a value of 10 or higher indicating a usable signal quality.
Transmission at regular intervals can be set by giving a string of flags in the CLI variable `sim_transmit_flags`: `T` - transmit continuously, `F` - transmit in failsafe mode, `A` - transmit when altitude is lower than `sim_low_altitude`, `G` - transmit when GPS signal quality is low. `A` only transmits in ALT HOLD, WAYPOINT, RTH, and FAILSAFE flight modes. The transmission interval is given by `sim_transmit_interval` and is 60 seconds by default.
Text messages sent to the module can be used to set the transmission flags during flight, or to issue a RTH command to the flight controller. If a message begins with `RTH` it toggles forced RTH on / off, otherwise it is taken as a value for `sim_transmit_flags`. Note that an empty message turns transmission off, setting all flags to zero.
Acceleration events are indicated at the beginning of the message as follows: `HIT!` indicates impact / high g event, `HIT` indicates landing / backwards acceleration event, `DROP` indicates freefall / low g event.
To receive acceleration event messages, set one or more of the acceleration event threshold CLI variables to a nonzero value, and use the `A` flag in `sim_transmit_flags`. `acc_event_threshold_high` is the threshold (in cm/s/s) for impact detection by high magnitude of acceleration. `acc_event_threshold_low` is the threshold for freefall detection by low magnitude of acceleration. `acc_event_threshold_neg_x` is the threshold for landing detection (for fixed wing models) by high magnitude of negative x axis acceleration.
## Ibus telemetry
Ibus telemetry requires a single connection from the TX pin of a bidirectional serial port to the Ibus sens pin on an FlySky telemetry receiver. (tested with fs-iA6B receiver, iA10 should work)
It shares 1 line for both TX and RX, the rx pin cannot be used for other serial port stuff.
It runs at a fixed baud rate of 115200, so it need hardware uart (softserial is limit to 19200).
```
_______
/ \ /-------------\
| STM32 |-->UART TX-->[Bi-directional @ 115200 baud]-->| Flysky RX |
| uC |- UART RX--x[not connected] | IBUS-Sensor |
\_______/ \-------------/
```
It is possible to daisy chain multiple sensors with ibus, but telemetry sensor will be overwrite by value sensor.
In this case sensor should be connected to RX and FC to sensor.
```
_______
/ \ /---------\ /-------------\ /-------------\
| STM32 |-->UART TX-->[Bi-directional @ 115200 baud]-->| CVT-01 |-->|others sensor|-->| Flysky RX |
| uC |- UART RX--x[not connected] \---------/ \-------------/ | IBUS-Sensor |
\_______/ \-------------/
```
### Configuration
Ibus telemetry is default enabled in the all firmware.
IBUS telemetry is disabled on ALIENWIIF3, RMDO at build time using defines in target.h.
```
#undef TELEMETRY_IBUS
```
### Available sensors
The following sensors are transmitted :
Sensors number:
1.Internal voltage in volts (not usable).
2.Valtage sensor in volts (Voltage type).
3.If baro sensor is avaliable then return temperature from baro sensor in °C else return temperature from gyro sensor in °C (Temperatyre type).
4.Status (Rpm type).
5.Course in degree (Rpm type).
6.Current in ampers (Voltage type).
7.Altitude in meters (Voltage type).
8.Direction to home in degree (Rpm type).
9.Distance to home in meters(Rpm type).
10.GPS course in degree (Rpm type).
11.GPS altitude in meters (Rpm type).
12.Second part of Lattitude (Rpm type), for example 5678 (-12.3456789 N).
13.Second part of Longitude (Rpm type), for example 6789 (-123.4567891 E).
14.First part of Lattitude (Voltage type), for example -12.45 (-12.3456789 N).
15.First part of Longitude (Voltage type), for example -123.45 (-123.4567890 E).
16.GPS speed in km/h (Rpm type).
1.Transmitter voltage in volts (not usable).
1.Error percent in % (not usable).
Sensors from 8 to 16 are avaliable only if GPS is at built time.
STATUS (number of satelites AS #0, FIX AS 0, HDOP AS 0, Mode AS 0)
FIX: 1 is No, 2 is 2D, 3 is 3D, 6 is No+FixHome, 7 is 2D+FixHome, 8 is 3D+FixHome
HDOP: 0 is 0-9m, 8 is 80-90m, 9 is >90m
Mode: 0 - Passthrough, 1-Armed(rate), 2-Horizon, 3-Angle, 4-Waypoint, 5-AltHold, 6-PosHold, 7-Rth, 8-Launch, 9-Failsafe
Example: 12803 is 12 satelites, Fix3D, FixHome, 0-9m HDOP, Angle Mode
### CLI command
ibus_telemetry_type
0.Standard sensor type are used (Temp,Rpm,ExtV). Each transmitter should support this. (FS-i6, FS-i6S).
1.This same as 0, but GPS ground speed (sensor 16) is of type Speed in km/h. (FS-i6 10ch_MOD_i6_Programmer_V1_5.exe from https://github.com/benb0jangles/FlySky-i6-Mod-).
2.This same as 1, but GPS altitude (sensor 11) is of type ALT in m. (FS-i6 10ch_Timer_MOD_i6_Programmer_V1_4.exe from https://github.com/benb0jangles/FlySky-i6-Mod-).
3.This same as 2, but each sensor have its own sensor id. (FS-i6 10ch_Mavlink_MOD_i6_Programmer_V1_.exe from https://github.com/benb0jangles/FlySky-i6-Mod-):
sensor 4 is of type S85,
sensor 5 is of type ACC_Z,
sensor 6 is of type CURRENT,
sensor 7 is of type ALT,
sensor 8 is of type HEADING,
sensor 9 is of type DIST,
sensor 10 is of type COG,
sensor 10 is of type GALT,
sensor 12 is of type GPS_LON,
sensor 13 is of type GPS_LAT,
sensor 14 is of type ACC_X,
sensor 15 is of type ACC_Y,
sensor 16 is of type SPEED.
4.This same as 3, but support 4 byte sensors. (fix_updater_03_16_21_33_1 from https://github.com/qba667/FlySkyI6/tree/master/release):
sensor 7 is 4byte ALT, 12 is PRESURE or PITOT_SPEED if avaliable, 13 is GPS_STATUS, 14 is 4byte GPS_LON, 15 is 4byte GPS_LAT.
This required a receiver with new firmware that support SNR, RSSI and long frames (For FS-IA6B since August 2016 or need upgrade to wersion 1.6 https://github.com/povlhp/FlySkyRxFirmware).
5.This same as 4, but sensor 3 is ARMED, 4 is MODE, 12 is CLIMB.
6.For hali9_updater_04_21_23_13.bin from https://www.rcgroups.com/forums/showthread.php?2486545-FlySky-FS-i6-8-channels-firmware-patch%21/page118 or https://github.com/benb0jangles/FlySky-i6-Mod-/tree/master/10ch%20qba667_hali9%20Updater sensor 4 is of type CURRENT, sensor 5 is of type HEADING, sensor 6 is of type COG, sensor 7 is of type CLIMB, sensor 8 is of type YAW, sensor 9 is of type DIST, sensor 10 is of type PRESURE or PITOT_SPEED if avaliable, sensor 11 is of type SPEED, sensor 12 is of type GPS_LAT, sensor 13 is of type GPS_LON, sensor 14 is of type GALT, sensor 15 is of type ALT, sensor 16 is of type S85.
7.This same as 6, but sensor 3 is GPS_STATUS, 10 is ARMED, 16 is MODE.
8.This same as 7, but sensor 10 (ARMED) is reversed.
131.This same as 3, but sensor 16 (type SPEED) is in m/s.
132.This same as 4, but sensor 16 (type SPEED) is in m/s.
133.This same as 5, but sensor 16 (type SPEED) is in m/s.
134.This same as 6, but sensor 11 (type SPEED) is in m/s.
135.This same as 7, but sensor 11 (type SPEED) is in m/s.
136.This same as 8, but sensor 11 (type SPEED) is in m/s.
### RX hardware
These receivers are reported to work with i-bus telemetry:
- FlySky/Turnigy FS-iA6B 6-Channel Receiver (http://www.flysky-cn.com/products_detail/&productId=51.html)
- FlySky/Turnigy FS-iA10B 10-Channel Receiver (http://www.flysky-cn.com/products_detail/productId=52.html)
Note that the FlySky/Turnigy FS-iA4B 4-Channel Receiver (http://www.flysky-cn.com/products_detail/productId=46.html) seems to work but has a bug that might lose the binding, DO NOT FLY the FS-iA4B!
### Use ibus RX and ibus telemetry on only one port.
Case:
A. For use only IBUS RX connect directly Flysky IBUS-SERVO to FC-UART-RX.
In configurator set RX on selected port, set receiver mode to RX_SERIAL and Receiver provider to IBUS.
B. For use only IBUS telemetry connect directly Flysky IBUS-SENS to FC-UART-TX.
In configurator set IBUS telemetry on selected port and enable telemetry feature.
C. For use RX IBUS and telemetry IBUS together connect Flysky IBUS-SERVO and IBUS-SENS to FC-UART-TX using schematic:
```
+---------+
| FS-iA6B |
| |
| Servo |---|<---\ +------------+
| | | | FC |
| Sensor |---[R]--*-------| Serial TX |
+---------+ +------------+
```
R = 10Kohm, Diode 1N4148 (connect cathode to IBUS-Servo of Flysky receiver).
In configurator set IBUS telemetry and RX on this same port, enable telemetry feature, set receiver mode to RX_SERIAL and Receiver provider to IBUS.
Warning:
Schematic above work also for connect telemetry only, but not work for connect rx only - will stop FC.
## Futaba SBUS2 telemetry
SBUS2 telemetry requires a single connection from the TX pin of a bidirectional serial port to the SBUS2 pin on a Futaba T-FHSS or FASSTest telemetry receiver. (tested T16IZ radio and R7108SB and R3204SB receivers)
It shares 1 line for both TX and RX, the rx pin cannot be used for other serial port stuff.
It runs at a fixed baud rate of 100000, so it needs a hardware uart capable of inverted signals. It is not available on F4 mcus.
```
_______
/ \ /-------------\
| STM32 |-->UART TX-->[Bi-directional @ 100000 baud]-->| Futaba RX |
| uC |- UART RX--x[not connected] | SBUS2 port |
\_______/ \-------------/
```
For more information and sensor slot numbering, refer to [SBUS2 Documentation](SBUS2_Telemetry.md)
docs/Temperature sensors.md
+106
View File
@@ -0,0 +1,106 @@
# Temperature sensors
It is now possible to measure temperatures with the help of the I²C LM75 and 1-Wire DS18B20 chips. The temperature values can be displayed on the OSD and they are also logged. A total maximum of 8 temperature sensors can be connected. The support is enabled by default on F4 and F7 FCs. To use with F3 FCs you need to build a custom firmware.
## LM75
Up to 8 can be connected to the flight controller.
* Package: SOP-8, breakout boards can be found easily
* Interface: I²C (**max 400kHz**)
* Supply: 2.7 to 5.5V
* Temperature range: -55 to +125°C
On the purple LM75 (CJMCU-75), address line pins on the bottom of the PCB need to be bridged either to ground or VCC (to define I2C address)
![image](assets/images/CJMCU-75_address.png)
Pin definition:
| A2 | A1 | A0 |Address|INAV add|
|-----|-----|-----|-------|--------|
| GND | GND | GND | 0x48 | 0 |
| GND | GND | VCC | 0x49 | 1 |
| GND | VCC | GND | 0x4A | 2 |
| GND | VCC | VCC | 0x4B | 3 |
| VCC | GND | GND | 0x4C | 4 |
| VCC | GND | VCC | 0x4D | 5 |
| VCC | VCC | GND | 0x4E | 6 |
| VCC | VCC | VCC | 0x4F | 7 |
If more than one sensor is used, each sensor must have different address.
## DS18B20
* Package: TO-92, SO-8, µSOP-8
* Interface: 1-Wire
* Supply: 3.0 to 5.5V (parasitic power not supported)
* Temperature range: -55 to +125°C
None of the flight controllers on the market at the time this documentation is written supports 1-Wire directly. To use these sensors a I²C to 1-Wire interface chip needs to be used, the DS2482. Connect the DS2482 SCL and SDA lines to your FC, add a 4.7kohm pull-up resistor between VCC and the DQ pin then connect all the sensors DQ pin to the DS2482 DQ pin.
## Configuring temperature sensors
The `temp_sensor` CLI command can be used to display and change the temperature sensors configuration. When a new temperature sensor is connected it is automatically detected and will appear in the output of the `temp_sensor` command.
* `temp_sensor` without any argument displays all the sensors configuration
* `temp_sensor reset` deletes all the sensors
* `temp_sensor index type address alarm_min alarm_max osd_symbol label` to configure a new sensor or modify the configuration of an existing one.
### Parameters description
* `index` is the index of the configuration slot you want to change
* `type` can be `1` for LM75 or `2` for DS18B20
* `address` is the address of the device on the bus. 0 to 7 for a LM75 or the full 64bit ROM in hex format for a 18B20
* `alarm_min` is the temperature under which the corresponding OSD element will start blinking (decidegrees centigrade)
* `alarm_max` is the temperature above which the corresponding OSD element will start blinking (decidegrees centigrade)
* `osd_symbol` is the ID of a symbol to display on the OSD to the left of the temperature value. Use 0 to display a label instead (see next parameter). See the table bellow for the available IDs
* `label` is a 4 characters maximum label that is displayed on the OSD next to the temperature value
| Symbol ID | Description |
|-----------|-----------------------------|
| 1 | Generic temperature symbol |
| 2 | ESC temperature symbol |
| 3 | VTX temperature symbol |
| 4 | Motor temperature symbol |
| 5 | Battery temperature symbol |
| 6 | Exterior temperature symbol |
### Example output
Example output of the `temp_sensor` command on a system with two LM75 and four DS18B20 sensors connected
```
temp_sensor 0 1 0 -200 600 0
temp_sensor 1 1 1 -200 600 0
temp_sensor 2 2 7c0118681e1cff28 -200 600 0
temp_sensor 3 2 7d01186838f2ff28 -200 600 0
temp_sensor 4 2 210118684001ff28 -200 600 0
temp_sensor 5 2 f801186750c7ff28 -200 600 0
temp_sensor 6 0 0 0 0
temp_sensor 7 0 0 0 0
```
To set for example the OSD symbol of the first temperature sensor to the ESC symbol:
`temp_sensor 0 1 0 -200 600 2`
To change for example the configuration of the fourth sensor to label `BATT`, minimum value alarm 0.5°C and maximum value alarm 45°C
`temp_sensor 3 2 7d01186838f2ff28 5 450 0 BATT`
## Configuring the way OSD temperature labels are displayed
You can use the `osd_temp_label_align` setting to chose how the labels for the temperature sensor's values are displayed. Possible alignment values are `LEFT` and `RIGHT`.
### Example
```
LEFT alignment:
T1 xxx°C
ESC xxx°C
RIGHT alignment:
T1 xxx°C
ESC xxx°C
```
docs/USB Flashing.md
+135
View File
@@ -0,0 +1,135 @@
# USB Flashing
Modern flight controllers are typically flashed in USB DFU mode. This is a straight-forward process in Configurator. The standard flashing procedure should work successfully with the caveat of some platform specific matters as noted below.
* If the board is placed in DFU mode manually (by hardware button), then check "No reboot sequence"
* Baudrate is not relevant for DFU flashing.
* For version upgrades, enable "Full chip erase"
## Platform Specific: Linux
Linux requires `udev` rules to allow write access to USB devices for users.
### Simple unconditional rule
The simplest rule is to allow DFU access unconditionally; this avoids having to set up specific groups which may be distro independent. If you have previously flashed OpenTX or EdgeTX you will already have such a rule as `/etc/udev/rules.d/45-companion-taranis.rules` and no further action is required. Otherwise, you can add (as root) a file for example `/etc/udev/rules.d/45-stdfu-permissions.rules` containing the single line:
```
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE:="0666"
```
### More complex group example
As an alternative, you can make a distro specific rule restricting DFU a group; an example shell command to achieve this on Ubuntu is:
```
(echo '# DFU (Internal bootloader for STM32 MCUs)'
echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE="0664", GROUP="plugdev"') | sudo tee /etc/udev/rules.d/45-stdfu-permissions.rules > /dev/null
```
This assigns the device to the `plugdev` group(a standard group in Ubuntu). To check that your account is in the `plugdev` group type `groups` in the shell and ensure `plugdev` is listed. If not you can add yourself as shown (replacing `<username>` with your username):
```
sudo usermod -a -G plugdev <username>
```
Then log out and back again to acquire the new group.
On Arch and its derivatives the group would be `uucp` (in the rule and the `usermod` command:
```
sudo usermod -a -G uucp <username>
```
## Platform Specific: Windows
The Configurator can have problems accessing USB devices on Windows. A driver should be automatically installed by Windows for the ST Device in DFU Mode but this doesn't always allow access. One solution is to replace the ST driver with a libusb driver. The easiest way to do that is to download [Zadig](http://zadig.akeo.ie/).
With the board connected and in bootloader mode (reset it by sending the character R via serial, or simply attempt to flash it with the correct serial port selected in Configurator):
* Open Zadig
* Choose Options > List All Devices
* Select `STM32 BOOTLOADER` in the device list
* Choose `WinUSB (v6.x.x.x)` in the right hand box
![Zadig Driver Procedure](assets/images/zadig-dfu.png)
* Click Replace Driver
* Restart the Configurator (make sure it is completely closed, logout and login if unsure)
* Now the DFU device should be seen by Configurator
## While Using USB-C cables
* If you are using a device with only USB-C ports such as a Mac-OS device, you will need a dongle.
* A USB-C to USB-C cable is identical on both ends and thus requires extra hardware to let them be auto detected as devices instead of hosts.
* Using either a hub with USB-A ports, or a USB-A to C cable or dongle is usually the easiest way to get a working connection but an USB-OTG adapter also works.
## Using `dfu-util`
`dfu-util` is a command line tool to flash ARM devices via DFU. It is available via the package manager on most Linux systems or from [source forge](http://sourceforge.net/p/dfu-util).
Put the device into DFU mode by **one** of the following:
* **Hardware button:** Press and hold the DFU/BOOT button while plugging in USB
* **Serial CLI sequence:** Send `####\r\n`, wait for CLI prompt, then send `dfu\r\n`
```bash
# Enter CLI mode
echo -ne '####\r\n' > /dev/ttyACM0
# Wait for "CLI" prompt (important - don't skip!)
# Recommended: use a proper script that reads serial response
# Send DFU command
echo -ne 'dfu\r\n' > /dev/ttyACM0
```
**Note:** The simple single 'R' character method shown in older documentation is unreliable. The above sequence is required for proper CLI entry.
* **CLI command:** If already connected to CLI via configurator or terminal: type `dfu`
* **MSP command:** Use MSP_REBOOT with DFU parameter (INAV 9.x+) - most reliable programmatic method
It is necessary to convert the `.hex` file into `Intel binary`. This can be done using the GCC `objcopy` command; e.g. for the notional `inav_x.y.z_NNNNNN.hex`.
```
objcopy -I ihex inav_x.y.z_NNNNNN.hex -O binary inav_x.y.z_NNNNNN.bin
```
You can now DFU flash the `.bin` file:
```
dfu-util -d 0483:df11 --alt 0 -s 0x08000000:force:leave -D inav_x.y.z_NNNNNN.bin
```
or with full erase
```
dfu-util -d 0483:df11 --alt 0 -s 0x08000000:mass-erase:force:leave -D inav_x.y.z_NNNNNN.bin
```
## Caveats
Once the board is placed in DFU mode, the hardware boot loader polls for activity on the USB device and *some MCU dependent* UARTS (often UART1 and UART3). If you have a device on one of these UARTS that transmits unconditionally (GPS, RX for example), then that port may win the "active device" race, and DFU flashing will fail.
Ensure that such devices are either disconnected or not powered during flashing.
## Older devices / broken USB ports
If you have a older (unsupported) FC that does not support DFU, or a modern board with a broken USB port, it is possible to flash the board via a UART (typically UART1) using the ST serial flashing protocol.
This is supported by (very) old Configurators, the open source [stm32flash](https://sourceforge.net/projects/stm32flash/) tool and some ST proprietary tools.
Examples:
* Erase the device (assumed `/dev/ttyUSB0`)
```
stm32flash -o -b 57600 /dev/ttyUSB0
```
* Flash a HEX file (notionally `inav_x.y.z_NNNNNN.hex`)
```
stm32flash -w inav_x.y.z_NNNNNN.hex -v -g 0x0 -b 57600 /dev/ttyUSB0
```
replace `/dev/ttyUSB0` as appropriate for your OS. You will probably be more successful at 57600 baud than 115200. The speed is auto-detected by the FC.
docs/USB_Mass_Storage_(MSC)_mode.md
+87
View File
@@ -0,0 +1,87 @@
## Overview
INAV (after 2.3.0) offers USB MSC (mass storage device class) SD card and internal flash access, meaning you can mount the FC (SD card / internal flash) as an OS file system via USB to read BB logs (and delete them from an SD card).
When MSC mode is used with **internal flash** there are a few differences compared to **SD card** as it's a virtual file system:
* The file system is read-only. In order to delete logs it is necessary to erase the flash as usual (configurator, CLI or other tool).
* The logs are presented as a single, consolidated file (`inav_all.bbl`) as well as individual logs (`inav_001.bbl` etc.).
* Other informative files (e.g. `readme.txt`) may also exist in the virtual file system.
## Usage
To put the FC in MSC mode:
* Enter the CLI
* Enter the CLI command `msc` ; the FC will reboot
* Close the CLI tool (`cliterm`, configurator etc.)
* Wait for the device to be recognised as USB storage device by the operating system (may take some time, 10-15 seconds perhaps).
* Copy files off the MSC mounted FC (sd card) (`cp`, file manager)
* Dismount / eject the FC (sd card) card using the standard OS method
* Power-cycle the FC to exit MSC mode.
## Performance
Internal flash is quite fast.
For an SD card, reading is quite slow, typically c. 340kBs, for example:
```
####################
## Using MSC mode ##
####################
# FC is automounted to /run/media/jrh/BBOX-QUAD by the OS
$ rsync -P /run/media/jrh/BBOX-QUAD/LOGS/LOG00035.TXT /tmp/msclogs/
LOG00035.TXT
55,856,827 100% 339.15kB/s 0:02:40 (xfr#1, to-chk=0/1)
```
```
#########################
## Using a card-reader ##
#########################
# SD Card is automounted to /run/media/jrh/BBOX-QUAD by the OS
$ rsync -P /run/media/jrh/BBOX-QUAD/LOGS/LOG00035.TXT /tmp/sdclogs/
LOG00035.TXT
55,856,827 100% 19.26MB/s 0:00:02 (xfr#1, to-chk=0/1)
```
i.e c. 2.5 seconds for the card reader, 2 minutes 40 seconds for MSC (60 times slower). However, if the card is relatively inaccessible, this is a reasonable trade-off
## Comparison and Integrity
The same file (`LOG00035.TXT`, c 55MB) is copied by MSC to `/tmp/msclogs` and directly (SD Card Reader) to `/tmp/sdclogs`.
```
$ cmp /tmp/{msc,sdc}logs/LOG00035.TXT
# no differences reported ...
```
```
$ md5sum /tmp/{msc,sdc}logs/LOG00035.TXT
7cd259777ba4f29ecbde2f76882b1840 /tmp/msclogs/LOG00035.TXT
7cd259777ba4f29ecbde2f76882b1840 /tmp/sdclogs/LOG00035.TXT
```
You should also be able to run blackbox utilities (e.g. the INAV specific `blackbox_decode`) without errors on the files, e.g.
```
$ blackbox_decode --stdout --merge-gps > /dev/null /tmp/msclogs/LOG00035.TXT
Log 1 of 1, start 36:00.888, end 62:00.851, duration 25:59.963
Statistics
Looptime 1006 avg 9.2 std dev (0.9%)
I frames 48405 104.6 bytes avg 5062215 bytes total
P frames 726064 69.2 bytes avg 50246994 bytes total
H frames 380 10.0 bytes avg 3800 bytes total
G frames 15674 21.4 bytes avg 334701 bytes total
S frames 6198 33.0 bytes avg 204534 bytes total
Frames 774469 71.4 bytes avg 55309209 bytes total
Data rate 496Hz 35806 bytes/s 358100 baud
3 frames failed to decode, rendering 4 loop iterations unreadable. 4 iterations are missing in total (4ms, 0.00%)
774472 loop iterations weren't logged because of your blackbox_rate settings (779980ms, 50.00%)
```
## Developer Notes
Providing MSC is automatically enabled for all F4 and up targets that support
`ONBOARDFLASH` and /or `SDCARD`.
docs/VTOL.md
+299
View File
@@ -0,0 +1,299 @@
# Welcome to INAV VTOL
Thank you for trying the INAV VTOL. Read every line in this tutorial. Your patience can save both time and potential repair costs for the model.
## Who Should Use This Tutorial?
This tutorial is designed for individuals who
- have prior experience with **both INAV multi-rotor and INAV fixed-wing configurations/operations.**
- know how to create a custom mixer for their model.
- know basic physics of vtol operation
## Firmware Status
The firmware is in a flyable state, but it hasn't undergone extensive testing yet. This means there may be potential issues that have not yet been discovered.
## Future Changes
Please be aware that both the setup procedure and firmware may change in response to user feedback and testing results.
## Your Feedback Matters
We highly value your feedback as it plays a crucial role in the development and refinement of INAV VTOL capabilities. Please share your experiences, suggestions, and any issues you encounter during testing. Your insights are invaluable in making INAV VTOL better for everyone.
# VTOL Configuration Steps
### The VTOL functionality is achieved by switching/transitioning between two configurations stored in the FC. VTOL specific configurations are Mixer Profiles with associated control profiles. One profile set is for fixed-wing(FW) mode, One is for multi-copter(MC) mode. Configuration/Settings other than Mixer/control profiles are shared among two modes
![Alt text](Screenshots/mixerprofile_flow.png)
0. **Find a DIFF ALL file for your model and start from there if possible**
- Be aware that `MIXER PROFILE 2` RC mode setting introduced by diff file can get your stuck in a mixer_profile. remove or change channel to proceed
1. **Setup Profile 1:**
- Configure it as a normal fixed-wing/multi-copter.
2. **Setup Profile 2:**
- Configure it as a normal multi-copter/fixed-wing.
3. **Mode Tab Settings:**
- Set up switching in the mode tab.
4. *(Recommended)* **Transition Mixing (Multi-Rotor Profile):**
- Configure transition mixing to gain airspeed in the multi-rotor profile.
5. *(Optional)* **Automated Switching (RTH):**
- Optionally, set up automated switching in case of failsafe.
# STEP 0: Load parameter preset/templates
Find a working diff file if you can and start from there. If not, select keep current settings and apply following parameter in cli but read description about which one to apply.
```
set small_angle = 180
set gyro_main_lpf_hz = 80
set dynamic_gyro_notch_min_hz = 50
set dynamic_gyro_notch_mode = 3D
set motor_pwm_protocol = DSHOT300 #Try dshot first and see if it works
set airmode_type = STICK_CENTER_ONCE
set nav_disarm_on_landing = OFF #band-aid for false landing detection in NAV landing of multi-copter
set nav_rth_allow_landing = FS_ONLY
set nav_wp_max_safe_distance = 500
set nav_fw_control_smoothness = 2
set nav_fw_launch_max_altitude = 5000
set servo_pwm_rate = 160 #If model using servo for stabilization in MC mode and servo can tolerate it
set servo_lpf_hz = 30 #If model using servo for stabilization in MC mode
## profile 1 as airplane and profile 2 as multi rotor
mixer_profile 1
set platform_type = AIRPLANE
set model_preview_type = 26
set motorstop_on_low = ON
set mixer_pid_profile_linking = ON
mixer_profile 2
set platform_type = TRICOPTER
set model_preview_type = 1
set mixer_pid_profile_linking = ON
profile 1 #control profile
set dterm_lpf_hz = 10
set d_boost_min = 1.000
set d_boost_max = 1.000
set fw_level_pitch_trim = 5.000
set roll_rate = 18
set pitch_rate = 9
set yaw_rate = 3
set fw_turn_assist_pitch_gain = 0.4
set max_angle_inclination_rll = 450
set fw_ff_pitch = 80
set fw_ff_roll = 50
set fw_p_pitch = 15
set fw_p_roll = 15
profile 2
set dterm_lpf_hz = 60
set dterm_lpf_type = PT3
set d_boost_min = 0.800
set d_boost_max = 1.200
set d_boost_gyro_delta_lpf_hz = 60
set antigravity_gain = 2.000
set antigravity_accelerator = 5.000
set smith_predictor_delay = 1.500
set tpa_rate = 20
set tpa_breakpoint = 1200
set tpa_on_yaw = ON #If model using control surface/tilt mechanism for stabilization in MC mode
set roll_rate = 18
set pitch_rate = 18
set yaw_rate = 9
set mc_iterm_relax = RPY
save
```
# STEP 1: Configuring as a normal fixed-wing in Profile 1
1. **Select the first Mixer Profile and Control Profile:**
- In the CLI, switch to the mixer_profile and control_profile you wish to set first. You can also switch
mixer_profile/control_profile through gui with aforementioned presets loaded.
```
mixer_profile 1 #in this example, we set profile 1 first
set mixer_pid_profile_linking = ON # Let the mixer_profile handle the control profile (formerly pid_profile) switch on this mixer_profile
set platform_type = AIRPLANE
save
```
2. **Configure the fixed-wing/Multi-Copter:**
- Configure your fixed-wing/Multi-Copter as you normally would, or you can copy and paste default settings to expedite the process.
- Dshot esc protocol availability might be limited depends on outputs and fc board you are using. change the motor wiring or use oneshot/multishot esc protocol and calibrate throttle range.
- You can use throttle = -1 as a placeholder for the motor you wish to stop if the motor isn't the last motor
- Consider conducting a test flight to ensure that everything operates as expected. And tune the settings, trim the servos.
![Alt text](Screenshots/mixerprofile_fw_mixer.png)
You must also assign the tilting servos values using the Fixed Value values (formerly called "MAX"). If you don't do this the motors will point in the direction assigned by the transition mode.
# STEP 2: Configuring as a Multi-Copter in Profile 2
1. **Switch to Another Mixer Profile with Control Profile:**
- In the CLI, switch to another mixer_profile along with the appropriate control profile. You can also switch
mixer_profile/control_profile through gui with aforementioned presets loaded.
```
mixer_profile 2
set mixer_pid_profile_linking = ON
set platform_type = MULTIROTOR/TRICOPTER
save
```
2. **Configure the Multicopter/tricopter:**
- Set up your multi-copter/fixed-wing as usual, this time for mixer_profile 2 and control_profile 2.
- Utilize the Fixed Value values (formerly called "MAX") input in the servo mixer to tilt the motors without altering the servo midpoint.
- At this stage, focus on configuring profile-specific settings. You can streamline this process by copying and pasting the default PID settings.
- you can set -1 in motor mixer throttle as a place holder: this will disable that motor but will load following the motor rules
- compass is required to enable navigation modes for multi-rotor profile.
- Consider conducting a test flight to ensure that everything operates as expected. And tune the settings.
- It is advisable to have a certain degree of control surface (elevon / elevator) mapping for stabilization even in multi-copter mode. This helps improve control authority when airspeed is high. It might be unable to recover from a dive without them.
![Alt text](Screenshots/mixerprofile_mc_mixer.png)
5. **Tailsitters:planned for INAV 7.1**
- Configure the fixed-wing mode/profile sets normally. Use MultiCopter platform type for tail_sitting flying mode/profile sets.
- The baseline board aliment is FW mode (ROLL axis is the thrust axis). Set `tailsitter_orientation_offset = ON ` in the tail_sitting MC mode.
- Configure mixer ROLL/YAW mixing according to tail_sitting orientation in the tail_sitting MC mode. YAW axis is the thrust axis.
- Conduct a bench test and see the orientation of the model changes in inav-configurator setup tab
# STEP 3: Mode Tab Settings:
### We recommend using an 3-pos switch on you radio to activate these modes, So the pilot can jump in or bail out at any moment.
### Here is a example, in the bottom of inav-configurator Modes tab:
![Alt text](Screenshots/mixer_profile.png)
| 1000~1300 | 1300~1700 | 1700~2000 |
| :-- | :-- | :-- |
| Profile1(FW) with transition off | Profile2(MC) with transition on | Profile2(MC) with transition off |
- Profile file switching becomes available after completing the runtime sensor calibration (15-30s after booting). And It is **not available** when a navigation mode or position hold is active.
- By default, `mixer_profile 1` is used. `mixer_profile 2` is used when the `MIXER PROFILE 2` mode is activate. Once configured successfully, you will notice that the profiles and model preview changes accordingly when you refresh the relevant INAV Configurator tabs.
- Use the `MIXER TRANSITION` mode to gain airspeed in MC profile, set `MIXER TRANSITION` accordingly.
Conduct a bench test on the model (without props attached). The model can now switch between fixed-wing and multi-copter modes while armed. Furthermore, it is capable of mid-air switching, resulting in an immediate stall upon entering fixed-wing profile
# STEP 4: Tilting Servo Setup (Recommended)
### Setting up the tilting servos to operate correctly is crucial for correct yaw control of the craft. Using the default setup works, but will most likely result in your craft crawling forward with evey yaw input.
The steps below describe how you can fine-tune the tilting servos to obtian the optimum result.
1. **Set the tilt servos at 45 degrees:**
- Connect and power the tilting servos with your flight controller.
- Enter transition mode (your switch should be in the mid-position).
- Check the Outputs tab and make sure that the tilt servo channels are exactly at 1500μs.
- In this mode, your tilt servos should be at the 45-degree position and you can now mount the motor and prop to your tilt servo such that the angle of the motor mounting plate is at 45 degrees upwards.
- NOTE 1: If you have dedicated tilt servos, you may have engraved indices on the servos and tilting motor assembly to help you with this step. If the servos don't end up exactly at 45 degrees due to the teeth on the servo and the control arm/plate, don't worry, this will be automatically adjusted after completing the other steps below.
- NOTE 2: If you are using control rods to adjust the tilt of the servos, adjust the lenth of your control rod and the position of the control arm to position the control arm as close as possible to the mid position. It will depend on the oriatation of the servo, but generally speaking, the control arm of the servo should be pointed perpendicular to the fuselage when the motor mounts are at the 45 degree setting.
2. **Switch to Multicopter/Tricopter:**
- Assuming that you have set up your mixer similar to STEP1 and STEP2, you can now switch to the tricopter/multicopter mode and your servos should be tilting the motors upwards. If this is not the case, reverse the servo(s) in the Outputs tab such that the servo(s) is/are pointed upwards.
- It is OK for the servos not to point exactly 90 degrees upwards, but they should be as close as possible to that position.
- Also, ensure that your Fixed Value values (formerly called "MAX") values in the Mixer tab are at 100 and -100, so that your servo will move to the maximum position, as shown in the screenshots in STEP1 and STEP2.
3. **Adjust the maximum throws for the Multicopter/Tricopter mode:**
- While in tricopter mode, navigate to the Outputs tab and adjust the MIN and MAX endpoint values to position the motors slightly backward.
- Rotate the prop such that it is pointed backwards towards the wing/motor mount and ensure that the gap is the same on both sides by adjusting the MIN and MAX values for the tilt servo channels.
- NOTE: You can check the distance with calipers or gauge blocks. Alternatively, you can adjust the MIN and MAX for your tilting servos such that the props are just touching the top of the wing or motor mount, and then you can increase/decrease the MIN and MAX values for each channel by the same ammount for both servos. This should ensure that you have the same gap between the tip of the prop and the wing or motor mount for both sides.
4. **Adjust the minimum position for the Fixed-wing mode:**
- Repeat the same step as point 3 with the model in fixed-wing mode, where the servos are tilted forwards.
- For this step, you just have to make sure that the motors are pointed exactly forwards.
- You can do this by adjusting the respective MIN and MAX values in the Output tab for the tilt servo channels while in fixed-wing mode.
- NOTE: Ensuring that your servos are tilted exactly forward is a crucial step as it can cause the plane to roll slightly if that it is not the case. However, ensuring the exact aligment will depend on your specific setup. If you are using dedicated tilting motor servos rather than standard servos with control arms and pushrods, you can make sure that you are exact by measuring the distance between the front edge of the tilting servo and the of the motor mounting plate. If the disances are the uniform across each mount and same on both motors, your servos are pointed forwads correctly.
5. **Adjsut the vertival position of the tilt servos:**
- Switch back to multicopter/tricopter mode and open the Mixer tab.
- Start adjusting the `Fixed Value` mixer lines from STEP2 such that the servos are pointed exactly upwards. In other words, start reducing the values of 100 and -100 to something like 80 and -80 until the motors are are pointed exaxctly upwards.
- You will have to `Save & reboot` for adjustement for the changes to take effect, so be patient, take your time and don't forget to `Save & reboot`.
- Move the YAW stick to either extreme position and ensure that the servos are tilting the motors both forwards and backwards.
- NOTE: When yawing fully left, the left motor should tilt backwards and the right motor should tilt forwards.
6. **Adjsut the throws of the tilt servos:**
- The final step is to adjust the throws of the servos such that they are the same in both directions.
- To do this, move back to the Mixer tab while in multicopter/tricopter mode and start adjusting the previously set up 50 and -50 values from the Stabilised Yaw lines.
- You can try with lower values of about 30 and -30 and then increase the values until you reach the maximum travel point.
- NOTE: The maximum is reached when both servos are moving the same ammount in oposite directions and one servo does not continue to move after the other has stopped.
7. **Check correct operation and direction:**
- Cycle back and forth between the plane, transition and tricopter modes to make sure that your servos are maintaining the same setting.
- For the fixed wing setting, your tilt servos should point the motors exactly forwards.
- For the multicoper/tricopter mode, the tilt servos should point the motors exactly upwards and when moving the yaw stick, both servos should tilt the motors the same ammount in opposite directions.
Optional Setup Step for Tilt Servos:
8. **Reversing tilt servos and mixer signs:**
If you have set up the mixer as suggested in STEP1 and STEP2, you may have to deal with negative values for the mixer. You may wish to reverese a servo so that you don't have to deal with the negative signs. In that case, you may have to adjust the MIN and MAX values from point 4 again, so that your tilt servos are operating correctly. Check the operation of the servos once again for the YAW control in multicopter/tricipter mode as well as the horizontal position of the tilt servos in fixed-wing mode.
# STEP 5: Transition Mixing (Multi-Rotor Profile)(Recommended)
### Transition Mixing is typically useful in multi-copter profile to gain airspeed in prior to entering the fixed-wing profile. When the `MIXER TRANSITION` mode is activated, the associated motor or servo will move according to your configured Transition Mixing.
Please note that transition input is disabled when a navigation mode is activated. The use of Transition Mixing is necessary to enable additional features such as VTOL RTH with out stalling.
## Servo 'Transition Mixing': Tilting rotor configuration.
Add new servo mixer rules, and select 'Mixer Transition' in input. Set the weight/rate according to your desired angle. This will allow tilting the motor for tilting rotor model.
![Alt text](Screenshots/mixerprofile_servo_transition_mix.png)
## Motor 'Transition Mixing': Dedicated forward motor configuration
In motor mixer set:
- -2.0 < throttle < -1.0: The motor will spin regardless of the radio's throttle position at a speed of `abs(throttle) - 1` multiplied by throttle range only when Mixer Transition is activated.
- Airmode type should be set to "STICK_CENTER". Airmode type must NOT be set to "THROTTLE_THRESHOLD". If set to throttle threshold the (-) motor will spin until the throttle threshold is passed.
![Alt text](Screenshots/mixerprofile_4puls1_mix.png)
## TailSitter 'Transition Mixing':
No additional settings needed, 45 deg offset will be added to target pitch angle for angle mode in the firmware.
### With aforementioned settings, your model should be able to enter fixed-wing profile without stalling.
# Automated Switching (RTH) (Optional):
### This is one of the least tested features. This feature is primarily designed for Return to Home (RTH) in the event of a failsafe.
When configured correctly, the model will use the Fixed-Wing (FW) mode to efficiently return home and then transition to Multi-Copter (MC) mode for easier landing.
To enable this feature, type following command in cli
1. In your MC mode mixer profile (e.g., mixer_profile 2), set `mixer_automated_switch` to `ON`. leave it to `OFF` if burning remaining battery capacity on the way home is acceptable.
```
mixer_profile 2or1
set mixer_automated_switch= ON
```
2. Set `mixer_switch_trans_timer` ds in cli in the MC mode mixer profile to specify the time required for your model to gain sufficient airspeed before transitioning to FW mode.
```
mixer_profile 2or1
set mixer_switch_trans_timer = 30 # 3s, 3000ms
```
3. In your FW mode mixer profile (e.g., mixer_profile 1), also set `mixer_automated_switch` to `ON`. leave it to `OFF` if automated landing in fixed-wing is acceptable.
```
mixer_profile 1or2
set mixer_automated_switch = ON
```
4. Save your settings. type `save` in cli.
If you set `mixer_automated_switch` to `OFF` for all mixer profiles (the default setting), the model will not perform automated transitions. You can always enable navigation modes after performing a manual transition.
# Notes and Experiences
## General
- VTOL model operating in multi-copter (MC) mode may encounter challenges in windy conditions. Please exercise caution when testing in such conditions.
- Make sure you can recover from a complete stall before trying the mid air transition
- It will be much safer if you can understand every line in diff all, read your diff all before maiden
## Tilting-rotor
- In some tilting motor models, you may experience roll/yaw coupled oscillations when `MIXER TRANSITION` is activated. To address this issue, you can try the following:
1. Use prop blade meets at top/rear prop direction for tilting motors to balance the effects of torque and P-factor.
2. In addition to 1. Add a little yaw mixing(about 0.2) in tilt motors.
- There will be a time window that tilting motors is providing up lift but rear motor isn't. Result in a sudden pitch raise on the entering of the mode. Use the max speed or faster speed in tiling servo to reduce the time window. OR lower the throttle on the entering of the FW mode to mitigate the effect.
## Dedicated forward motor
- Easiest way to setup a vtol. and efficiency can be improved by using different motor/prop for hover and forward flight
docs/VTx.md
+33
View File
@@ -0,0 +1,33 @@
## VTx Setup
### IRC Tramp
#### Matek 1G3SE Setup
To use the Matek 1G3SE with IRC Tramp. You will need to enter the CLI command `set vtx_frequency_group = FREQUENCYGROUP_1G3`. You must also make sure that the initial VTx settings in the configuration tab are in a valid range. They are:
- `vtx_band` 1 or 2
- `vtx_channel` between 1 and 8
Note: The frequencies required by the US version of the VTx are on `vtx_band` 2 (BAND B) only.
Power levels are:
- `1` 25mW
- `2` 200mW
- `3` 800 mW
##### Matek 1G3SE frequency chart
| Band | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
|------|------|------|------|------|------|------|------|------|
| A | 1080 | 1120 | 1160 | 1200 | 1240 | 1280 | 1320 | 1360 |
| B | 1080 | 1120 | 1160 | 1200 | 1258 | 1280 | 1320 | 1360 |
### Team BlackSheep SmartAudio
If you have problems getting SmartAudio working. There are a couple of CLI parameters you can try changing to see if they help.
- There is a workaround for early AKK VTx modules. This is enabled by default. You could try disabling this setting [`vtx_smartaudio_early_akk_workaround`](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#vtx_smartaudio_early_akk_workaround) to OFF.
- If you are using softserial, you can try using the alternate method by setting [`vtx_smartaudio_alternate_softserial_method`](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#vtx_smartaudio_alternate_softserial_method) to OFF.
- If you are using TBS Sixty9 VTX you may consider to set count of stop bits to 1, using [`set vtx_smartaudio_stopbits = 1`](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#vtx_smartaudio_stopbits)
docs/Wireless Connections (BLE, TCP and UDP).md
+53
View File
@@ -0,0 +1,53 @@
# Wireless connections
From INAV 5 onwards, the Configurator supports wireless connections via Bluetooth Low Energy (BLE) and Wifi (UDP and TCP).
## BLE
The following adapters are supported:
- CC2541 based modules (HM1X, HC08/09)
- Nordic Semiconductor NRF5340 (Adafruit BLE Shield)
- SpeedyBee adapter
Flightcontrollers with BLE should also work, if you have an adapter/FC that doesn't work, open an issue here on Github and we will add it.
### Configuring the BLE modules
Activate MSP in INAV on a free UART port and set the Bluetooth module to the appropriate baud rate.
Example for a HM-10 module:
Connect the module to a USB/UART adapter (remember: RX to TX, TX to RX), and connect it to a serial terminal (e.g. from the Arduino IDE),
Standard baud rate is 115200 baud, CR+LF
```
AT+BAUD4
AT+NAMEINAV
```
The baud rate values:
| Value | Baud |
|------|------|
| 1 | 9600 |
| 2 | 19200 |
| 3 | 38400 |
| 4 | 115200 |
There are many counterfeits of the HC08/09 modules on the market, which work unreliably at high baud rates.
However, it is recommended to avoid these modules and to use an original HM-10.
### SpeedyBee adapter
Just connect it to the USB port, no further configuration needed.
## TCP and UDP
Allows connections via Wifi.
Hardware:
- DIY, ESP8266 based:
This project can be used to make INAV Wifi enabled: https://github.com/Scavanger/MSPWifiBridge
A small ESP01S module should still fit anywhere.
- ExpressLRS Wifi:
Should work (via TCP, port 5761), but untested due to lack of hardware from the developer. CLI and presets do not work here, problem in ELRS, not in INAV.
docs/Wiring/CC3D - buzzer circuit.pdf
BIN
View File
Binary file not shown.
docs/Wiring/Crius CO-16 OLED diagram.png
Executable
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 214 KiB

docs/Wiring/Crius CO-16 OLED modifications.jpg
Executable
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 83 KiB

docs/Wiring/PPMRSSI conditioning.pdf
BIN
View File
Binary file not shown.
docs/Wiring/blackbox-installation-1.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 194 KiB

docs/assets/betafpvf722.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 221 KiB

docs/assets/cleanflight/cleanflight-icon_128.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.2 KiB

docs/assets/cleanflight/cleanflight-logo-light-wide-1-240px-transparent.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.7 KiB

docs/assets/cleanflight/cleanflight-logo-light-wide-1-240px.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.3 KiB

Some files were not shown because too many files have changed in this diff Show More