Merge pull request #9201 from RomanLut/osd-joystick

OSD Joystick

docs/LED pin PWM.md

@@ -0,0 +1,90 @@
+# 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. 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")
+
+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")
+

docs/OSD Joystick.md

@@ -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/Programming Framework.md

@@ -97,6 +97,7 @@ IPF can be edited using INAV Configurator user interface, or via CLI. To use COn
 | 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. |
 | 51            | APPROX_EQUAL                  | `true` if `Operand B` is within 1% of `Operand A`. |
+| 52            | LED_PIN_PWM                   | Value `Operand A` from [`0` : `100`] starts PWM 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)|
 
 ### Operands
 

docs/Runcam device.md

@@ -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/Settings.md

@@ -2012,6 +2012,16 @@ Used to prevent Iterm accumulation on during maneuvers. Iterm will be dampened w
 
 ---
 
+### led_pin_pwm_mode
+
+PWM mode of LED pin.
+
+| Default | Min | Max |
+| --- | --- | --- |
+| SHARED_LOW |  |  |
+
+---
+
 ### ledstrip_visual_beeper
 
 _// TODO_
@@ -4442,6 +4452,66 @@ The space between the INAV and pilot logos, if `osd_use_pilot_logo` is `ON`. Thi
 
 ---
 
+### osd_joystick_down
+
+PWM value for DOWN key
+
+| Default | Min | Max |
+| --- | --- | --- |
+| 0 | 0 | 100 |
+
+---
+
+### osd_joystick_enabled
+
+Enable OSD Joystick emulation
+
+| Default | Min | Max |
+| --- | --- | --- |
+| OFF | OFF | ON |
+
+---
+
+### osd_joystick_enter
+
+PWM value for ENTER key
+
+| Default | Min | Max |
+| --- | --- | --- |
+| 75 | 0 | 100 |
+
+---
+
+### osd_joystick_left
+
+PWM value for LEFT key
+
+| Default | Min | Max |
+| --- | --- | --- |
+| 63 | 0 | 100 |
+
+---
+
+### osd_joystick_right
+
+PWM value for RIGHT key
+
+| Default | Min | Max |
+| --- | --- | --- |
+| 28 | 0 | 100 |
+
+---
+
+### osd_joystick_up
+
+PWM value for UP key
+
+| Default | Min | Max |
+| --- | --- | --- |
+| 48 | 0 | 100 |
+
+---
+
 ### osd_left_sidebar_scroll
 
 _// TODO_

src/main/CMakeLists.txt

@@ -525,6 +525,8 @@ main_sources(COMMON_SRC
     io/osd_grid.h
     io/osd_hud.c
     io/osd_hud.h
+    io/osd_joystick.c
+    io/osd_joystick.h
     io/smartport_master.c
     io/smartport_master.h
     io/vtx.c

src/main/config/parameter_group_ids.h

@@ -121,7 +121,10 @@
 #define PG_OSD_COMMON_CONFIG 1031
 #define PG_TIMER_OVERRIDE_CONFIG 1032
 #define PG_EZ_TUNE 1033
-#define PG_INAV_END PG_EZ_TUNE
+#define PG_LEDPIN_CONFIG 1034
+#define PG_OSD_JOYSTICK_CONFIG 1035
+#define PG_INAV_END PG_OSD_JOYSTICK_CONFIG
+
 
 // OSD configuration (subject to change)
 //#define PG_OSD_FONT_CONFIG 2047