Merge pull request #11205 from iNavFlight/maintenance-9.x

Merge maintenance-9.x to master

Author: sensei-hacker

.github/workflows/ci.yml

@@ -256,11 +256,15 @@ jobs:
           for f in ./build_SITL/*_SITL.exe; do
             mv $f $(echo $f | sed -e 's/_[0-9]\+\.[0-9]\+\.[0-9]\+//')
           done
+      - name: Copy cygwin1.dll
+        run: cp /bin/cygwin1.dll ./build_SITL/
       - name: Upload artifacts
         uses: actions/upload-artifact@v4
         with:
           name: ${{ env.BUILD_NAME }}_SITL-WIN
-          path: ./build_SITL/*.exe
+          path: |
+            ./build_SITL/*.exe
+            ./build_SITL/cygwin1.dll
 
   test:
     #needs: [build]

docs/Battery.md

@@ -169,6 +169,155 @@ current_meter_scale = (reported_draw_mAh / charging_data_mAh) * old_current_mete
                     = 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.

docs/Blackbox.md

@@ -120,6 +120,7 @@ These chips are also supported:
 * 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
 

docs/OSD.md

@@ -200,6 +200,7 @@ Here are the OSD Elements provided by INAV.
 | 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
 

docs/development/Development.md

@@ -107,11 +107,13 @@ The main flow for a contributing is as follows:
 7. `git add <files that have changed>`
 8. `git commit`
 9. `git push origin my-new-code`
-10. Create pull request using github UI to merge your changes from your new branch into `inav/master`
+10. Create pull request using github UI to merge your changes from your new branch into the appropriate target branch (see "Branching and release workflow" below)
 11. Repeat from step 4 for new other changes.
 
 The primary thing to remember is that separate pull requests should be created for separate branches.  Never create a pull request from your `master` branch.
 
+**Important:** Most contributions should target a maintenance branch, not `master`. See the branching section below for guidance on choosing the correct target branch.
+
 Later, you can get the changes from the INAV repo into your `master` branch by adding INAV as a git remote and merging from it as follows:
 
 1. `git remote add upstream https://github.com/iNavFlight/inav.git`
@@ -125,10 +127,105 @@ You can also perform the git commands using the git client inside Eclipse.  Refe
 
 ## Branching and release workflow
 
-Normally, all development occurs on the `master` branch. Every release will have it's own branch named `release_x.y.z`.
+INAV uses maintenance branches for active development and releases. The `master` branch receives merges from maintenance branches.
+
+### Branch Types
+
+#### Maintenance Branches (Current and Next Major Version)
+
+**Current version branch** (e.g., `maintenance-9.x`):
+- Used for backward-compatible changes
+- Bug fixes, new features, and improvements that don't break compatibility
+- Changes here will be included in the next release of the current major version (e.g., 9.1, 9.2)
+- Does not create compatibility issues between firmware and configurator within the same major version
+
+**Next major version branch** (e.g., `maintenance-10.x`):
+- Used for changes that introduce compatibility requirements
+- Breaking changes that would cause issues between different major versions
+- New features that require coordinated firmware and configurator updates
+- Changes here will be included in the next major version release (e.g., 10.0)
+
+#### Master Branch
+
+The `master` branch receives periodic merges from maintenance branches.
+
+### Choosing the Right Target Branch
+
+When creating a pull request, target the appropriate branch:
+
+**Target the current version branch** (e.g., `maintenance-9.x`) if your change:
+- Fixes a bug
+- Adds a new feature that is backward-compatible
+- Updates documentation
+- Adds or updates hardware targets
+- Makes improvements that work with existing releases
+
+**Target the next major version branch** (e.g., `maintenance-10.x`) if your change:
+- Breaks compatibility with the current major version
+- Requires coordinated firmware and configurator updates
+- Changes MSP protocol in an incompatible way
+- Modifies data structures in a breaking way
+
+### Release Workflow
+
+1. Development occurs on the current version maintenance branch (e.g., `maintenance-9.x`)
+2. When ready for release, a release candidate is tagged from the maintenance branch
+3. Bug fixes during the RC period continue on the maintenance branch
+4. After final release, the maintenance branch is periodically merged into `master`
+5. The cycle continues with the maintenance branch receiving new changes for the next release
+
+### Propagating Changes Between Maintenance Branches
+
+Changes committed to the current version branch should be merged forward to the next major version branch to prevent regressions.
 
-During release candidate cycle we will follow the process outlined below:
+**Maintainer workflow:**
+- Changes merged to `maintenance-9.x` should be regularly merged into `maintenance-10.x`
+- This ensures fixes and features aren't lost when the next major version is released
+- Prevents users from experiencing bugs in v10.0 that were already fixed in v9.x
 
-1. Create a release branch `release_x.y.z`
-2. All bug fixes found in the release candidates will be merged into `release_x.y.z` branch and not into the `master`.
-3. After final release is made, the branch `release_x.y.z` is locked, and merged into `master` bringing all of the bug fixes into the development branch. Merge conflicts that may arise at this stage are resolved manually.
+**Example:**
+```bash
+# Merge changes from current to next major version
+git checkout maintenance-10.x
+git merge maintenance-9.x
+git push upstream maintenance-10.x
+```
+
+### Example Timeline
+
+Current state (example):
+- `maintenance-9.x` - Active development for INAV 9.1, 9.2, etc.
+- `maintenance-10.x` - Breaking changes for future INAV 10.0
+- `master` - Receives periodic merges from maintenance branches
+
+After INAV 10.0 is released:
+- `maintenance-10.x` - Active development for INAV 10.1, 10.2, etc.
+- `maintenance-11.x` - Breaking changes for future INAV 11.0
+- `master` - Continues receiving merges
+
+### Working with Maintenance Branches
+
+To branch from the current maintenance branch instead of master:
+
+```bash
+# Fetch latest changes
+git fetch upstream
+
+# Create your feature branch from the maintenance branch
+git checkout -b my-new-feature upstream/maintenance-9.x
+
+# Make changes, commit, and push
+git push origin my-new-feature
+
+# Create PR targeting maintenance-9.x (not master)
+```
+
+When updating your fork:
+
+```bash
+# Get the latest maintenance branch changes
+git fetch upstream
+
+# Push directly from upstream to your fork (no local checkout needed)
+git push origin upstream/maintenance-9.x:maintenance-9.x
+```

docs/javascript_programming/GENERATE_CONSTANTS_README.md

@@ -87,6 +87,7 @@ const FLIGHT_PARAM = {
 };
 
 // ... exports
+
 ```
 
 ## Build Integration
@@ -109,21 +110,23 @@ This ensures constants are regenerated before each build.
 Currently, API definitions have hardcoded values:
 
 ```javascript
-// flight.js - WRONG (hardcoded)
+// inav.flight.js - WRONG (hardcoded)
 yaw: {
   inavOperand: { type: 2, value: 17 }  // Wrong value!
 }
+
 ```
 
 Change to reference constants:
 
 ```javascript
-// flight.js - CORRECT (references constants)
+// inav.flight.js - CORRECT (references constants)
 const { OPERAND_TYPE, FLIGHT_PARAM } = require('../../transpiler/inav_constants.js');
 
 yaw: {
   inavOperand: { type: OPERAND_TYPE.FLIGHT, value: FLIGHT_PARAM.ATTITUDE_YAW }
 }
+
 ```
 
 Benefits: