OSD-Hud-and-ESP32-radars.md

   1 # The Hud
   2
   3 The Hud is a feature that displays various points of interest (POI) on the OSD, in "3D", by showing a marker where the location is on the screen. For now it's capable to display :
   4
   5 - The home point
   6 - Nearby aircrafts as sent by an ESP32 LoRa modem
   7 - Next waypoints during a mission.
   8
   9 # Video Resources
  10
  11 * [This is a video demonstrating the hud for both home point and ESP32 radar tracking](https://youtu.be/zzKkcd5_cY4?t=27).
  12 * [This is a video demonstrating the display of the waypoints live during an autonomous mission](https://www.youtube.com/watch?v=CqKNGY4pogU).
  13
  14 # Configuration
  15
  16 The hud must be set from the CMS menu of the OSD or from the CLI in the Configurator.
  17
  18 **Important! The Hud is a sub-set of the crosshair, it's designed this way because the crosshair is the origin/reference for anything hud-related. So make sure you have the crosshair enabled and displayed in the OSD tab of the Configurator. It is not recommended to have any of the legacy map or 2D-view items displayed in your OSD, as this could cause overlaps on the screen.**
  19
  20 In order for the hud to display in "3D" where the POI is, it needs to know few things about your FPV camera :
  21
  22 In the CMS/OSD menu, go to OSD > Hud >...
  23
  24 ### Crosshair style
  25 To choose between 7 different types of crosshairs.
  26
  27 **CLI :**
  28 `set osd_crosshairs_style = DEFAULT`
  29
  30 **Available Values:** `"DEFAULT", "AIRCRAFT", "TYPE3", "TYPE4", "TYPE5", "TYPE6", "TYPE7"`
  31
  32 ### Camera Uptilt
  33
  34 Set the camera uptilt for the FPV camera. That's the angle in degres between the horizontal of the aircraft and the line of sight of the camera. For a multirotor with a camera usually pointing up it's a positive value, most often between 5 and 30°. For a plane with the camera pointing down it should be a negative value, often between -5 and -10°.
  35
  36 **CLI :**
  37 `set osd_camera_uptilt = 0`
  38
  39 ### Camera FOV horizontal + vertical
  40 The FOV for the FPV camera, the default values are ok for a 2.8mm lens. If your camera is a 2.5mm or 2.1mm or lower focal, try to raise both the horizontal and vertical FOVs by 5 or 10° by steps (the smaller the focal length, the larger the field of view). If the FOV is too far off, the tracking won't work well near the borders of the screen.
  41
  42 **CLI :**
  43 `set osd_camera_fov_h = 135`
  44 `set osd_camera_fov_v = 85`
  45
  46 ### Hud Margin horizontal + vertical
  47
  48 How far from the border of the screen the hud ends, so it does not overwrite the rest of your OSD datas.
  49
  50 **CLI :**
  51 `set osd_hud_margin_h = 3`
  52 `set osd_hud_margin_v = 3`
  53
  54 ### Horizon offset
  55 To vertically adjust, between -2 and +2, the whole OSD and AHI and scrolling bars, it's recommended to leave it at 0.
  56
  57 **CLI :**
  58 `set osd_horizon_offset = 0`
  59
  60 ## Displayed items:
  61 This sub menu will let you select what is displayed on the Hud :
  62
  63 ### Homing arrows
  64 To display little arrows around the crossair showing where the home point is.
  65
  66 **CLI :**
  67 `set osd_hud_homing = ON`
  68
  69 ### Home point
  70 To 3D-display the home point location (H)
  71
  72 **CLI :**
  73 `set osd_hud_homepoint = ON`
  74
  75 ### Radar max aircraft
  76 Maximum count of nearby aircrafts or POIs to display, as sent from an ESP32 LoRa  module. Set to 0 to disable (show nothing), up to 4. The nearby aircrafts will appear as markers A, B, C, D
  77
  78 **CLI :**
  79 `set osd_hud_radar_disp= 3`
  80
  81 ### Radar min range
  82 In meters, by default 10 meters, radar aircrafts closer than this will not be displayed. This setting exists mostly to unclutter the OSD view during close range pursuits.
  83
  84 **CLI :**
  85 `set osd_hud_radar_range_min = 10`
  86
  87 ### Radar max range
  88 In meters, by default 4000, radar aircrafts further away than this will not be displayed.
  89
  90 **CLI :**
  91 `set osd_hud_radar_range_max = 4000`
  92
  93 ### Next waypoints
  94 How many waypoint are displayed, from 0 to 3. Set to 0 (zero) to disable. As sample, if set to 2, and you just passed the 3rd waypoint of the mission, you'll see markers for the 4th and waypoints (marked "4' and '5')
  95
  96 [This is a video demonstrating the display of the waypoints live during an autonomous mission](https://www.youtube.com/watch?v=CqKNGY4pogU).
  97
  98 **CLI :**
  99 `set osd_hud_wp_disp= 2`
 100
 101 # CLI commands
 102
 103 All the settings are available in the CLI, defaults are :
 104 ```
 105 set osd_crosshairs_style = DEFAULT
 106 set osd_horizon_offset = 0
 107 set osd_camera_uptilt = 0
 108 set osd_camera_fov_h = 135
 109 set osd_camera_fov_v = 85
 110 set osd_hud_margin_h = 3
 111 set osd_hud_margin_v = 3
 112 set osd_hud_homing = OFF
 113 set osd_hud_homepoint = OFF
 114 set osd_hud_radar_disp = 0
 115 set osd_hud_radar_range_min = 10
 116 set osd_hud_radar_range_max = 4000
 117 set osd_hud_radar_nearest = 0
 118 set osd_hud_wp_disp = 2
 119 ```
 120
 121 #  Accuracy and limitations
 122
 123 There's a long chain of inaccuracies conspiring to make the tracking not perfectly accurate :
 124
 125 * The heading of your aircraft can be wrong by a significant margin during or right after a hard turn. The steadier the flight, the more accurate it is.
 126
 127 * The artificial horizon drift issue does not help. Accurate positioning for the POI markers depends on the actual attitude and heading of the aircraft, any slight difference of few degrees will mess up the tracking.
 128
 129 * The tracking is not taking into account the roll angle of the plane so it remains simple and fast, so it won't be accurate when the banking angle is too high.
 130
 131 * OSD is character based, it's a 30x16 grid for PAL, and 30x13 for NTSC, it's not super high-definition.
 132
 133 * The crosshair is not perfectly centered in both horizontal and vertical dimensions because of an even numbers of columns and rows
 134
 135 * The position of the other aircrafts as sent by the ESP32 modules are updated at 2Hz (every 0.5sec), so at high speed there's lag involved because of relative movements.
 136
 137
 138 ## ESP32 LoRa modem ("iNav Radar" project)
 139
 140 If you have such a module fitted on your aicraft, extra steps are required in order to display the remote aircrafts live on the Hud :
 141
 142 * Wire the ESP32 module to a free UART on your flight controller, same as you would connect a GPS (+5V, GND, TX, RX). Using a Softserial port is not supported, it's not fast enough.
 143
 144 * In the iNav Configurator, Ports tab, enable the MSP option for this UART, and set the speed to **115200**. You don't have to set anything else for the port, the ESP32 will then communicate with the flight controller using standard MSP/MSP2 messages.
 145
 146 * In the CMS, OSD > Hud > Displayed items, set **Radar max aircraft to 4**
 147
 148 * If the wiring and port configuration is correct, at boot time the ESP32 module will show the iNav/host version detected.
 149
 150 Please see this [discussion at RCGroups](https://www.rcgroups.com/forums/showthread.php?3304673-iNav-Radar-ESP32-LoRa-modems) for mode details about the ESP32 modules and the radar project.
 151
 152 [This is a video demonstrating the hud for both home point and ESP32 radar tracking](https://youtu.be/zzKkcd5_cY4?t=27).
 153
 154
 155 ## What's displayed exactly ?
 156
 157 * If the marker is the home location, then the home icon is shown, it depends of the uploaded OSD font, it's usually a little house or the H letter. Below the marker is the distance, in meters/kilometers if the OSD is set to metric or UK, and in feet/miles if imperial.
 158
 159 * If the marker is a POI sent by the optional ESP32 LoRa Module, the markers are letters A, B, C etc, and below is also the distance, same as above. Additionally left and right of the marker will be displayed the link quality (4 bars  = 100% of packets received, 3 bars = 75%, 2 bars = 50%, 1 bar = 25%, X = link lost), and the relative heading of the other aicraft : If you and the other aircraft are going in the exact same direction the relative heading arrow will point up. If your two aircrafts are going opposite directions then the arrow will point down.
 160
 161 * If the marker is a mission waypoint (WP), the markers are numbers 1, 2, 3, etc with an icon before.
 162
 163
 164 ##  Troubleshooting
 165
 166 * **The ESP32 says "NoFC", it does not see the iNav flight controller**
 167
 168 Check that all 4 wires 5V GND TX RX are connected, and check that the port/UART the ESP32 is connected to is set with MSP enabled and speed is 115200 baud.
 169
 170 * **Conditions before display**
 171
 172 The H marker and/or the A, B, C ... markers will appear on the OSD view only if the position and heading of your aircraft are known. So it needs a valid GPS lock. The home marker will show only when the home point is recorded, so once the flight controller is armed. The home lock is not required to display nearby radar POIs.
 173
 174 Since the 3D markers will only show when the heading of the plane is known, on a flying wing with no compass (no magnetometer) the 3D markers will only appear when the plane is flying/moving, so the GPS can compute the direction.
 175
 176 * **Some characters are missing in the OSD/Hud**
 177
 178 Upload a compatible OSD font with the latest version of the Configurator, from the OSD tab.