pinio/pwm: better integrate LED pin, simplify

Author: sensei-hacker

docs/Cli.md

@@ -100,6 +100,7 @@ While connected to the CLI, all Logical Switches are temporarily disabled (5.1.0
 | `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 |
+| `piniopwm` | Set PINIO PWM duty cycle. See [PINIO PWM](PINIO%20PWM.md) |
 | `play_sound` | `<index>`, or none for next item |
 | `control_profile` | Change profile |
 | `resource` | View currently used resources |

docs/PINIO PWM.md

@@ -2,16 +2,22 @@
 
 INAV provides two mechanisms for generating output signals on GPIO pins:
 
-1. **PINIO channels (0-3)** — Any PWM-capable timer output defined as `PINIOx_PIN` in the target. Supports full 0-100% duty cycle PWM at 24 kHz.
-2. **LED strip idle level (channel 4)** — The WS2812 LED strip pin can be switched between idle-LOW and idle-HIGH between LED update bursts. Binary on/off only.
+1. **PINIO channels (1-4)** — PWM-capable timer outputs, either defined in the target (`PINIOx_PIN`) or assigned by the user in the configurator's Output tab. Supports full 0-100% duty cycle PWM at 24 kHz.
+2. **LED strip idle level (channel 0)** — The WS2812 LED strip pin can be switched between idle-LOW and idle-HIGH between LED update bursts. Binary on/off only.
 
 ## PINIO PWM channels
 
-PINIO channels are configured per-target in `target.h` using `PINIO1_PIN` through `PINIO4_PIN`. When a PINIO pin has a timer, it is automatically configured as a 24 kHz PWM output.
+PINIO channels can come from two sources:
+
+1. **Target-defined:** `PINIO1_PIN` through `PINIO4_PIN` in `target.h`. These are always available on supported boards.
+2. **User-assigned:** Any timer output pad can be set to PINIO mode in the configurator's Output tab (timer_output_mode = PINIO). No target.h changes needed.
+
+When a PINIO pin has a hardware timer, it is automatically configured as a 24 kHz PWM output. Pins without a timer fall back to GPIO on/off.
 
 PWM duty cycle can be controlled via:
-- **CLI:** `piniopwm [channel] <duty>` (duty = 0-100)
-- **Programming framework:** Operation 52, Operand A = channel (0-3), Operand B = duty (0-100)
+- **CLI:** `piniopwm <channel> <duty>` (channel = 1-4, duty = 0-100)
+- **Programming framework:** Operation 52, Operand A = duty (0-100), Operand B = channel (1-4)
+- **Mode boxes:** USER1-USER4 in the Modes tab toggle the channel on/off
 
 Setting duty to 0 stops PWM generation (pin goes LOW, or HIGH if `PINIO_FLAGS_INVERTED` is set in target.h).
 
@@ -21,14 +27,25 @@ PWM frequency is fixed to 24kHz with duty ratio between 0 and 100%:
 
 ![alt text](/docs/assets/images/led_pin_pwm.png  "PINIO PWM signal")
 
-## LED strip idle level (channel 4)
+## Mode box and programming framework interaction
+
+PINIO channels can be controlled by both mode boxes (Modes tab) and the programming framework (Programming tab). When both are used:
+
+- The **programming framework** sets the duty cycle (0-100%).
+- The **mode box** gates the output on or off. When the mode is active, the programmed duty is output. When inactive, the pin is driven to 0%.
+
+If no RC channel range is assigned to the USERx mode in the Modes tab, the programming framework has exclusive uninterrupted control — the mode box does not interfere.
+
+The default duty (before the programming framework sets a value) is 100%, so toggling a mode box without any programming gives full on/off behavior.
+
+## LED strip idle level (channel 0)
 
 When the LED strip feature is enabled, the WS2812 pin sends data bursts (~1 ms) every 10-20 ms. Between bursts, the pin idles at a configurable level.
 
-The LED strip idle level is accessible as channel `4` (the next channel after PINIO hardware channels 0-3):
+The LED strip idle level is accessible as channel `0`:
 
-- **CLI:** `piniopwm 4 <value>` — value > 0 sets idle HIGH, 0 sets idle LOW
-- **Programming framework:** Operation 52, Operand A = 4, Operand B = value (>0 = HIGH, 0 = LOW)
+- **CLI:** `piniopwm 0 <value>` — value > 0 sets idle HIGH, 0 sets idle LOW
+- **Programming framework:** Operation 52, Operand A = value (>0 = HIGH, 0 = LOW), Operand B = 0
 
 This can be used to drive a MOSFET or similar device connected to the LED pin, toggled by the programming framework based on flight mode, RC channel, GPS state, etc.
 
@@ -43,17 +60,22 @@ Normally LED pin is held low between WS2812 updates:
 
 When idle is set HIGH, the pin is held high between updates. Total ws2812 pulse duration is ~1ms with ~9ms pauses. Connected devices should be tolerant of these brief transients.
 
-# Generating PWM/output signals with programming framework
+# Channel numbering
+
+| Channel | Target | Description |
+|---------|--------|-------------|
+| 0 | LED strip | Binary idle level (HIGH/LOW) |
+| 1-4 | PINIO 1-4 | Full 0-100% PWM at 24 kHz |
 
-See operation 52 "PINIO PWM" in [Programming Framework](Programming%20Framework.md)
+This numbering is consistent across the CLI (`piniopwm`), programming framework (operation 52), and the `pinio_box1`-`pinio_box4` settings.
 
 # Generating PWM/output signals from CLI
 
 `piniopwm [channel] <duty>` — channel = 0-4, duty = 0-100
 
-- One argument: sets duty on channel 0 (backward compatible)
-- Two arguments: first is channel, second is duty
-- No arguments: stops PWM on channel 0
+- One argument: sets LED idle level (channel 0, backward compatible)
+- Two arguments: first is channel (0 = LED idle, 1-4 = PINIO), second is duty
+- No arguments: stops PWM on PINIO 1
 
 # Example of driving LED
 

docs/Programming Framework.md

@@ -114,7 +114,7 @@ for complete documentation on using JavaScript to program your flight controller
 | 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            | PINIO PWM                     | `Operand A` = channel (0-3 for PINIO hardware, 4 for LED strip idle level). `Operand B` = duty cycle (0-100). Channels 0-3 support full PWM; channel 4 is binary (>0 = HIGH). See [PINIO PWM](PINIO%20PWM.md). |
+| 52            | PINIO PWM                     | `Operand A` = duty cycle (0-100). `Operand B` = channel (0 for LED strip idle level, 1-4 for PINIO channels). Channels 1-4 support full PWM; channel 0 is binary (>0 = HIGH). See [PINIO PWM](PINIO%20PWM.md). |
 | 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`]

docs/Settings.md

@@ -5574,41 +5574,41 @@ Pilot name
 
 ### pinio_box1
 
-Mode assignment for PINIO#1
+Mode box assignment for PINIO channel 1
 
 | Default | Min | Max |
 | --- | --- | --- |
-| `BOX_PERMANENT_ID_NONE` | 0 | 255 |
+| `BOX_PERMANENT_ID_USER1` | 0 | 255 |
 
 ---
 
 ### pinio_box2
 
-Mode assignment for PINIO#1
+Mode box assignment for PINIO channel 2
 
 | Default | Min | Max |
 | --- | --- | --- |
-| `BOX_PERMANENT_ID_NONE` | 0 | 255 |
+| `BOX_PERMANENT_ID_USER2` | 0 | 255 |
 
 ---
 
 ### pinio_box3
 
-Mode assignment for PINIO#1
+Mode box assignment for PINIO channel 3
 
 | Default | Min | Max |
 | --- | --- | --- |
-| `BOX_PERMANENT_ID_NONE` | 0 | 255 |
+| `BOX_PERMANENT_ID_USER3` | 0 | 255 |
 
 ---
 
 ### pinio_box4
 
-Mode assignment for PINIO#1
+Mode box assignment for PINIO channel 4
 
 | Default | Min | Max |
 | --- | --- | --- |
-| `BOX_PERMANENT_ID_NONE` | 0 | 255 |
+| `BOX_PERMANENT_ID_USER4` | 0 | 255 |
 
 ---
 

src/main/drivers/pinio.c

@@ -28,6 +28,9 @@
 #include "common/memory.h"
 #include "drivers/io.h"
 #include "drivers/pinio.h"
+#ifdef USE_LED_STRIP
+#include "drivers/light_ws2811strip.h"
+#endif
 
 // CCR = duty% directly; 2.4 MHz / 100 = 24 kHz PWM, above audible range
 #define PINIO_PWM_PERIOD    100
@@ -74,8 +77,9 @@ const int pinioHardwareCount = ARRAYLEN(pinioHardware);
 /*** Runtime configuration ***/
 typedef struct pinioRuntime_s {
     IO_t io;
-    TCH_t *tch;         // Non-NULL when pin is configured in PWM mode
+    volatile timCCR_t *ccr; // Cached CCR register pointer (NULL for GPIO-only pins)
     bool inverted;
+    bool active;        // Mode box state; defaults to true (no RC channel = always active)
     uint8_t duty;       // Timer mode: duty level (0–100) applied by pinioSet(true);
                         // updated by pinioSetDuty(). Defaults to 100 so a mode box
                         // activating with no programming framework condition gives full on.
@@ -97,11 +101,12 @@ static bool pinioInitTimerPWM(int slot, IO_t io, const timerHardware_t *timHw, b
     timerPWMConfigChannel(tch, 0);
     timerPWMStart(tch);
     timerEnable(tch);
-    pinioRuntime[slot].tch = tch;
+    pinioRuntime[slot].ccr = timerCCR(tch);
     pinioRuntime[slot].io = io;
     pinioRuntime[slot].inverted = inverted;
+    pinioRuntime[slot].active = true;
     pinioRuntime[slot].duty = 100; // default: mode box on = full on
-    *timerCCR(tch) = pinioEffectiveDuty(0, inverted); // start off
+    *pinioRuntime[slot].ccr = pinioEffectiveDuty(0, inverted); // start off
     return true;
 }
 
@@ -155,17 +160,31 @@ void pinioInit(void)
     pinioRuntimeCount = runtimeCount;
 }
 
+int pinioGetRuntimeCount(void)
+{
+    return pinioRuntimeCount;
+}
+
 void pinioSetDuty(int index, uint8_t duty)
 {
+#ifdef USE_LED_STRIP
+    if (index == 0) {
+        ws2811SetIdleHigh(duty > 0);
+        return;
+    }
+#endif
+    index--;  // user-facing 1-4 → runtime 0-3
     if ((unsigned)index >= (unsigned)pinioRuntimeCount) {
         return;
     }
     if (duty > 100) {
         duty = 100;
     }
-    if (pinioRuntime[index].tch) {
+    if (pinioRuntime[index].ccr) {
         pinioRuntime[index].duty = duty;
-        *timerCCR(pinioRuntime[index].tch) = pinioEffectiveDuty(duty, pinioRuntime[index].inverted);
+        if (pinioRuntime[index].active) {
+            *pinioRuntime[index].ccr = pinioEffectiveDuty(duty, pinioRuntime[index].inverted);
+        }
     } else {
         IOWrite(pinioRuntime[index].io, (duty > 0) ^ pinioRuntime[index].inverted);
     }
@@ -182,9 +201,10 @@ void pinioSet(int index, bool newState)
     if ((unsigned)index >= (unsigned)pinioRuntimeCount) {
         return;
     }
-    if (pinioRuntime[index].tch) {
+    if (pinioRuntime[index].ccr) {
+        pinioRuntime[index].active = newState;
         uint8_t duty = newState ? pinioRuntime[index].duty : 0;
-        *timerCCR(pinioRuntime[index].tch) = pinioEffectiveDuty(duty, pinioRuntime[index].inverted);
+        *pinioRuntime[index].ccr = pinioEffectiveDuty(duty, pinioRuntime[index].inverted);
     } else {
         IOWrite(pinioRuntime[index].io, newState ^ pinioRuntime[index].inverted);
     }

src/main/drivers/pinio.h

@@ -41,3 +41,4 @@ extern const int pinioHardwareCount;
 void pinioInit(void);
 void pinioSet(int index, bool newState);
 void pinioSetDuty(int index, uint8_t duty);
+int pinioGetRuntimeCount(void);

src/main/fc/cli.c

@@ -2173,46 +2173,37 @@ static void cliModeColor(char *cmdline)
 #endif // USE_LED_STRIP
 
 #ifdef USE_PINIO
+// Channel numbering: 0 = LED strip idle level, 1-4 = PINIO channels (matches programming framework)
 static void cliPinioPwm(char *cmdline)
 {
     int channel = 0;
     int duty;
 
     if (isEmpty(cmdline)) {
-        pinioSetDuty(0, 0);
-        cliPrintLine("PWM stopped on channel 0");
+        pinioSetDuty(1, 0);
+        cliPrintLine("PWM stopped on PINIO 1");
         return;
     }
 
-    // Find second argument (space-separated)
-    char *dutyStr = strchr(cmdline, ' ');
+    const char *dutyStr = nextArg(cmdline);
     if (dutyStr) {
-        // Two args: channel duty
         channel = fastA2I(cmdline);
-        dutyStr++;
         duty = fastA2I(dutyStr);
     } else {
-        // One arg: duty on channel 0
+        // One arg: duty on channel 0 (LED idle, backward compat with old LED_PIN_PWM)
         duty = fastA2I(cmdline);
     }
 
-    if (channel < 0 || channel > PINIO_COUNT) {
-        cliPrintLinef("Error: channel must be 0-%d", PINIO_COUNT);
+    const int maxChannel = MAX(pinioGetRuntimeCount(), PINIO_COUNT);
+    if (channel < 0 || channel > maxChannel) {
+        cliShowArgumentRangeError("channel", 0, maxChannel);
         return;
     }
     if (duty < 0 || duty > 100) {
-        cliPrintLine("Error: duty must be 0-100");
+        cliShowArgumentRangeError("duty", 0, 100);
         return;
     }
 
-#ifdef USE_LED_STRIP
-    if (channel == PINIO_COUNT) {
-        ws2811SetIdleHigh(duty > 0);
-        cliPrintLinef("LED idle %s", duty > 0 ? "HIGH" : "LOW");
-        return;
-    }
-#endif
-
     pinioSetDuty(channel, (uint8_t)duty);
     cliPrintLinef("PWM ch %d: %d%%", channel, duty);
 }

src/main/io/osd_joystick.c

@@ -46,7 +46,7 @@ bool osdJoystickEnabled(void) {
 
 
 void osdJoystickSimulate5KeyButtonPress(uint8_t operation) {
-    const int ch = osdJoystickConfig()->pinio_channel;
+    const int ch = osdJoystickConfig()->pinio_channel + 1; // setting is 0-indexed, pinioSetDuty is 1-indexed
     switch (operation) {
         case RCDEVICE_CAM_KEY_ENTER:
             pinioSetDuty(ch, osdJoystickConfig()->osd_joystick_enter);
@@ -68,7 +68,7 @@ void osdJoystickSimulate5KeyButtonPress(uint8_t operation) {
 
 
 void osdJoystickSimulate5KeyButtonRelease(void) {
-    pinioSetDuty(osdJoystickConfig()->pinio_channel, 0);
+    pinioSetDuty(osdJoystickConfig()->pinio_channel + 1, 0);
 }
 
 

src/main/io/piniobox.c

@@ -63,7 +63,8 @@ void pinioBoxInit(void)
 void pinioBoxUpdate(void)
 {
     for (int i = 0; i < PINIO_COUNT; i++) {
-        if (pinioBoxRuntimeConfig.boxId[i] != BOXID_NONE) {
+        if (pinioBoxRuntimeConfig.boxId[i] != BOXID_NONE &&
+            isModeActivationConditionPresent(pinioBoxRuntimeConfig.boxId[i])) {
             pinioSet(i, IS_RC_MODE_ACTIVE(pinioBoxRuntimeConfig.boxId[i]));
         }
     }

src/main/programming/logic_condition.c

@@ -58,7 +58,6 @@
 
 #include "io/vtx.h"
 #include "drivers/vtx_common.h"
-#include "drivers/light_ws2811strip.h"
 #include "drivers/pinio.h"
 
 PG_REGISTER_ARRAY_WITH_RESET_FN(logicCondition_t, MAX_LOGIC_CONDITIONS, logicConditions, PG_LOGIC_CONDITIONS, 4);
@@ -509,17 +508,9 @@ static int logicConditionCompute(
 
 #ifdef USE_PINIO
         case LOGIC_CONDITION_PINIO_PWM:
-            // operandA = duty cycle (0-100), operandB = pin (0=LED pin, 1=USER1, 2=USER2, ...)
-            // operandB=0 preserves backward compatibility with old LED_PIN_PWM behavior
-            if (operandB == 0) {
-#ifdef USE_LED_STRIP
-                ws2811SetIdleHigh(operandA > 0);
-#endif
-                return operandA;
-            }
-            pinioSetDuty(operandB - 1, (uint8_t)constrain(operandA, 0, 100));
+            // operandA = duty cycle (0-100), operandB = channel (0=LED idle, 1-4=PINIO)
+            pinioSetDuty(operandB, (uint8_t)constrain(operandA, 0, 100));
             return operandA;
-            break;
 #endif
 #ifdef USE_GPS_FIX_ESTIMATION
         case LOGIC_CONDITION_DISABLE_GPS_FIX: