INAV Custom OSD Elements

CoreWingAbout 5 minINAVINAVOSD自定义 OSD编程框架逻辑条件全局变量可视化

I. Introduction

One of INAV's most powerful and practical features is the Programming Framework, which allows users to customize flight logic to meet various needs. Starting from INAV 7.0.0, the official team further opened up Custom OSD Elements, enabling users to visualize variables or logic states from the programming framework on the OSD.
Set in the OSD tab of the Configurator (layout slightly changed in INAV 8.0.0). Each custom element supports:

INAV 7.x: 3 configurable fields (slots)
INAV 8.0.0: Expanded to 8 fields

The types for each configurable field are as follows:
| Type | Description |
| --- | --- |
| None | Do not use this field |
| Text | Display fixed text (0-15 characters, supports [A-Z0-9^!.*], note text can only be used once per element) |
| Icon Static | Select a character from the OSD font icon table to display as icon (numeric index) |
| ICON from Global Variable | Display corresponding icon based on the value of a Global Variable |
| ICON from Logic Condition (New in INAV 8.0.0) | Display corresponding icon based on logic condition |
| Global Variable # | Display the specified global variable, supports formats: 0000000, 000.0, 00.00, etc. |
| Logic Condition # (New in INAV 8.0.0) | Display the status of logic condition, same format as above |
| VISIBILITY | Set when to display this element, can choose "Always" or based on a Global Variable/Logic condition |
Notes
Currently only the first 255 characters in the custom OSD character set are supported.
If Text is used in the configuration, it can only be used once per element due to memory limitations.
Text, icons, variables, etc. can be combined in any way to achieve the desired visualization effect.

II. Detailed Explanation of Number Display Logic

In INAV's Custom OSD Elements, you may have noticed that it supports various formats for number display. These formats include not only integers with different digits but also decimal point displays. Here's the principle behind this system:
INAV's numerical calculations do not use floating-point (decimal) numbers
INAV's Programming Framework uses only integer (whole number) data and does not support floating-point numbers (i.e., decimal points).
Therefore, the decimals you see on the OSD are actually "faked" through mathematical operations.
Example explanation:
We want to display "distance to home point" on the OSD, in kilometers (km), with two decimal places.
But INAV returns an integer value in "meters" (m), for example: 7243 (which is 7243 meters).
Normal calculation (displaying decimals):

7243 ÷ 1000 = 7.243 km

However, since INAV doesn't support decimal points and cannot directly process ÷ 1000, what should we do?
Alternative method (simulating decimals with integers):

To display two decimal places (i.e., 0.00 format), we just need to divide by 10, getting 724.
Then the OSD display module will insert a decimal point at the appropriate position: 7.24
Calculation technique summary
| Desired display | Actual divisor | Example value | Display result |
| --- | --- | --- | --- |
| Display integer (km) | ÷ 1000 | 7243 | 7 |
| Display 1 decimal place | ÷ 100 | 7243 | 72.4 |
| Display 2 decimal places | ÷ 10 | 7243 | 7.24 |
| Display 3 decimal places | Original value | 7243 | 0.724 |
Note: It's only displayed as a decimal, the underlying calculation is still integer-based.

3.1 Simple Stall Warning

This logic is used to detect potential stall situations. The judgment conditions are as follows:

Pitch angle > 20°, and
Virtual airspeed < 35 km/h, or
Throttle < 48%

When any of the above combined conditions are met, a STALL WARNING is triggered to alert the pilot to pay attention to the flight attitude and avoid entering a stall.

OSD Display Information
When stall conditions are met, the OSD will display:

Text: STALL WARNING
Warning icon: Character code 221

This warning only appears when the trigger conditions are met and will not constantly remain on the screen.

Important Notes

A stall is not directly caused by speed itself, but by "insufficient airflow over the wings." This depends on airspeed + attitude (mainly pitch angle)
The OSD warning is an auxiliary tool and cannot 100% accurately identify all stall situations.
Never rely solely on automatic alerts for flight safety. When reducing throttle for energy-efficient flight, pay special attention to the flight state to ensure you don't unintentionally enter a high pitch angle + low airspeed stall zone.

3.2 Switch Status Display

Although INAV comes with basic switch display functionality, using Custom OSD Elements + Programming Framework allows you to achieve more flexible and personalized visual display effects.
Programming Logic Configuration:

LC0: Subtract 1000 from the channel you want to display (e.g., AUX1) to bring it into the 0-1000 range. For example: CH5 - 1000
LC1: Map the 0-1000 range to 3 integer values: 0, 1, 2, corresponding to the down, middle, and up positions of the switch.
LC2: Add the switch position value to the icon number (208 for down, 209 for middle, 210 for up) to form the specific icon number.
LC3 (Optional, only for INAV 7.1.x): Assign the value of LC2 to a global variable (e.g., GVAR 0). In INAV 8.0.0 and later, LC3 is no longer needed as OSD can directly read LC2's output.
OSD Page Settings
Icon settings: If using INAV 7.1.x: Select "Icon from Global Variable" and bind to variable number GVAR 0. If using INAV 8.0.0 or later: Select "Icon from Logic Condition" and bind to LC2 (i.e., the icon logic output)
Text settings: Add a line of text to explain the function of this switch, such as "Mode Switch" or "Drop Switch"
Swap icon and text positions: To reverse the display order from left to right, simply swap the positions of the icon item and text item.

Notes
INAV 8.0.0 supports OSD custom element preview functionality, but icon preview cannot read actual GV values.
In the above example, if GV 0 has a value of 209, the OSD will display the middle position icon.
Icon codes: 208: Switch down position 209: Switch middle position 210: Switch up position

3.3 Displaying Altitude in Different Measurement Units

In this example, our OSD is set to metric units. However, some of our fellow pilots only understand imperial units, so we want to add a thoughtful feature by displaying altitude in both meters and feet on the OSD.
We first use the standard Altitude OSD element to display altitude in meters. Now we want to add a second custom element to display altitude in feet.

Step 1: Logic Calculation (Programming Page)

The first logic condition LC0 multiplies the altitude (in centimeters) by 100 to improve precision in subsequent division operations.
The second logic condition LC1 divides the result of LC0 by 3048 to get the altitude in feet. Note that this method improves precision, but the maximum display value is limited to 7045 feet, which is not reached in actual flight, making this an acceptable limitation.
Step 2: Add Custom OSD Element
Return to the OSD page and enable Custom Element 1.
In the first configuration space, select logic condition LC1 (used to calculate feet altitude). Since we know the value won't exceed 7045, we can choose to display with 4-digit precision.
In the second configuration space, select Static Icon and enter character code 120 (representing the "feet" unit icon). You should now see a 4-digit altitude + feet unit icon in the preview.

Step 3: Visibility Settings (Display Only Below 400 Feet)
If you only want to display this feet unit OSD item when the flight altitude is below 400 feet, you can add a third logic condition LC2 on the Programming page:
LC2 represents "true when altitude is less than 400 feet."
Return to the OSD page:
Set the visibility of this custom element to be based on the logic condition LC2. This way, the element will only appear on the OSD when below 400 feet.

————This article is cited from the official INAV website: https://github.com/iNavFlight/inav/wiki/Custom-OSD-Elements