FPS target set to 0 by default

[kilrah]

What happened?

Erase flash, flash current main, target fps in led settings ends up being the "not recommended, experimental" 0 = unlimited

To Reproduce Bug

See above

Expected Behavior

Default of 42

Install Method

Self-Compiled

What version of WLED?

b07cd45

Which microcontroller/board are you seeing the problem on?

ESP32-S3

Relevant log/trace output

Anything else?

From a quick look it seems that https://github.com/wled/WLED/blob/main/wled00/cfg.cpp#L946 could cause a circular dependency, when creating a default value the strip's current target is used, but it wasn't set first so it's 0

Code of Conduct

• I agree to follow this project's Code of Conduct

[DedeHai]

@coderabbitai please investigate

[coderabbitai]

🧩 Analysis chain

Let me fetch the specific issue directly using the GitHub CLI.

---

🏁 Script executed:

#!/bin/bash
# Fetch the details of issue `#5408` from the WLED repository
gh issue view 5408 --repo wled/WLED

Length of output: 75

---

Let me search for the issue on the web instead.

Let me try fetching the issue directly via the GitHub API.

---

🏁 Script executed:

#!/bin/bash
# Fetch issue 5408 via GitHub REST API (no auth needed for public repos)
curl -s "https://api.github.com/repos/wled/WLED/issues/5408" | python3 -c "
import json, sys
data = json.load(sys.stdin)
print('Title:', data.get('title'))
print('State:', data.get('state'))
print('Author:', data.get('user', {}).get('login'))
print('Labels:', [l['name'] for l in data.get('labels', [])])
print('Created:', data.get('created_at'))
print('Body:')
print(data.get('body', ''))
"

Length of output: 880

---

Good, now let me look at the relevant code in cfg.cpp around line 946 and the FPS-related logic.

---

🏁 Script executed:

#!/bin/bash
# Fetch cfg.cpp and look at lines around 946 and FPS-related code
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/cfg.cpp" | awk 'NR>=920 && NR<=980 {print NR": "$0}'
echo "---"
# Search for targetFps / fps references in cfg.cpp
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/cfg.cpp" | grep -n -i "targetfps\|target_fps\|fps\b" | head -60

Length of output: 2698

---

Now let me look at the setTargetFps and getTargetFps implementations, and more context around line 179.

---

🏁 Script executed:

#!/bin/bash
# Look at context around line 179 in cfg.cpp
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/cfg.cpp" | awk 'NR>=160 && NR<=200 {print NR": "$0}'
echo "==="
# Find setTargetFps and getTargetFps in the codebase
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/FX_fcn.cpp" | grep -n -i "targetfps\|getTargetFps\|setTargetFps" | head -40
echo "---"
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/WS2812FX.h" | grep -n -i "targetfps\|getTargetFps\|setTargetFps\|_targetFps\|_fps" | head -40

Length of output: 2376

---

Let me look at the setTargetFps full implementation, FPS_UNLIMITED, and _targetFps initialization.

---

🏁 Script executed:

#!/bin/bash
# Look at full setTargetFps implementation and surrounding context
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/FX_fcn.cpp" | awk 'NR>=1700 && NR<=1720 {print NR": "$0}'
echo "==="
# Look for FPS_UNLIMITED and _targetFps default initialization in WS2812FX.h
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/WS2812FX.h" | grep -n "FPS_UNLIMITED\|_targetFps\|targetFps\|getTargetFps" | head -30
echo "---"
# Look for FPS_UNLIMITED in defines / other files
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/const.h" | grep -n -i "fps" | head -20
echo "==="
# Look for where _targetFps is initialized (constructor, begin, etc.)
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/FX_fcn.cpp" | grep -n "_targetFps" | head -20

Length of output: 1341

---

Let me search for FPS_UNLIMITED and _targetFps initial value more broadly.

---

🏁 Script executed:

#!/bin/bash
# Search for FPS_UNLIMITED definition
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/WS2812FX.h" | grep -n "FPS_UNLIMITED\|_targetFps\s*=" | head -20
echo "==="
# Search all headers for FPS_UNLIMITED
for file in WS2812FX.h wled.h const.h wled_math.h; do
  echo "--- $file ---"
  curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/$file" | grep -n "FPS_UNLIMITED\|_targetFps" | head -10
done
echo "==="
# Look at the WS2812FX class member initialization
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/WS2812FX.h" | grep -n "targetFps\|_targetFps\|frametime\|_frametime" | head -20
echo "==="
# Check begin() or init() for default fps value
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/FX_fcn.cpp" | grep -n -A2 -B2 "42\|targetFps\|_targetFps" | head -40

Length of output: 1149

---

Let me look at the WS2812FX.h class definition for _targetFps and related members, and also find where FPS_UNLIMITED is defined.

---

🏁 Script executed:

#!/bin/bash
# Download WS2812FX.h and search broadly for fps and frametime  
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/WS2812FX.h" > /tmp/ws2812fx.h
grep -n "fps\|frametime\|FPS\|FRAME" /tmp/ws2812fx.h | head -40
echo "==="
# Search for 42 in WS2812FX.h (default FPS value)
grep -n "\b42\b" /tmp/ws2812fx.h | head -20
echo "==="
# Search for FPS_UNLIMITED across all cpp/h files in the repo root wled dir
for file in FX.h FX_fcn.cpp wled_math.h; do
  echo "--- $file ---"
  curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/$file" | grep -n "FPS_UNLIMITED\|FPS\|frametime\|42" | head -10
done

Length of output: 1788

---

Now I have a clear picture. Let me check where _targetFps is declared and initialized in the class, and also look at getTargetFps.

---

🏁 Script executed:

#!/bin/bash
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/WS2812FX.h" > /tmp/ws2812fx.h
# Find _targetFps declaration
grep -n "_targetFps\|_frametime\|getTargetFps" /tmp/ws2812fx.h
echo "==="
# Look at FX.h around the FPS defines for more context
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/FX.h" | awk 'NR>=65 && NR<=120 {print NR": "$0}'
echo "==="
# Check if _targetFps is set somewhere in begin() or init in FX_fcn.cpp
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/FX_fcn.cpp" | grep -n "begin\|init\|WLED_FPS\|= 42\|_targetFps" | head -30

Length of output: 4814

---

Let me check the full WS2812FX.h for _targetFps declaration and the class private members section.

---

🏁 Script executed:

#!/bin/bash
# Get full WS2812FX.h and look for private members / unsigned members / fps
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/WS2812FX.h" > /tmp/ws2812fx.h
wc -l /tmp/ws2812fx.h
echo "---"
grep -n "targetFps\|frametime\|getTarget\|unsigned.*fps\|fps.*=\|private:" /tmp/ws2812fx.h | head -30
echo "==="
# Maybe _targetFps and _frametime are in a different header - check all .h files
for f in wled.h bus_manager.h bus_wrapper.h; do
  echo "--- $f ---"
  curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/$f" | grep -n "_targetFps\|_frametime\|getTargetFps\|targetFps" | head -10
done
echo "==="
# Look at the bottom of WS2812FX.h for private member variables
tail -200 /tmp/ws2812fx.h | grep -n "unsigned\|uint\|fps\|frame\|_target"

Length of output: 88

---

The header appears to be at a different location. Let me search for the correct path.

---

🏁 Script executed:

#!/bin/bash
# Check repo structure for WS2812FX header
curl -s "https://api.github.com/repos/wled/WLED/git/trees/main?recursive=1" | python3 -c "
import json, sys
data = json.load(sys.stdin)
for item in data.get('tree', []):
    if 'WS2812' in item['path'] or 'ws2812' in item['path']:
        print(item['path'])
" 
echo "==="
# Also find all header files that might contain _targetFps
curl -s "https://api.github.com/repos/wled/WLED/git/trees/main?recursive=1" | python3 -c "
import json, sys
data = json.load(sys.stdin)
for item in data.get('tree', []):
    if item['path'].endswith('.h') and 'wled' in item['path'].lower():
        print(item['path'])
" | head -30

Length of output: 1074

---

The WS2812FX class is likely defined in FX.h. Let me check it for _targetFps and getTargetFps.

---

🏁 Script executed:

#!/bin/bash
# Fetch FX.h and search for _targetFps, getTargetFps, and class private members
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/FX.h" > /tmp/fx.h
wc -l /tmp/fx.h
echo "---"
grep -n "_targetFps\|_frametime\|getTargetFps\|setTargetFps\|getFrameTime" /tmp/fx.h
echo "==="
# Look for the WS2812FX class declaration
grep -n "class WS2812FX" /tmp/fx.h
echo "---"
# Search for private: sections within WS2812FX class
grep -n "private:\|unsigned.*fps\|uint.*fps\|WLED_FPS\|FPS_UNLIMITED" /tmp/fx.h | head -30

Length of output: 887

---

@DedeHai — here's a full breakdown of the bug.

---

Root Cause Analysis

How the bug occurs (fresh flash)

Step 1 — Load path, cfg.cpp line 179:

strip.setTargetFps(hw_led["fps"]); //NOP if 0, default 42 FPS

On a fresh flash, there is no cfg.json. ArduinoJson returns 0 for the absent "fps" key (null coerced to integer).

Step 2 — setTargetFps(0) in FX_fcn.cpp lines 1705–1709:

void WS2812FX::setTargetFps(unsigned fps) {
  if (fps <= 250) _targetFps = fps;    // ← 0 ≤ 250, so _targetFps is SET to 0 (FPS_UNLIMITED)
  if (_targetFps > 0) _frametime = 1000 / _targetFps;
  else _frametime = MIN_FRAME_DELAY;   // unlimited mode
}

The comment on line 179 says "NOP if 0, default 42 FPS" — but this comment does not match the implementation. Passing 0 actively sets _targetFps = 0, which is FPS_UNLIMITED (FX.h line 80: #define FPS_UNLIMITED 0).

Step 3 — Save path, cfg.cpp line 946:

hw_led["fps"] = strip.getTargetFps();

At this point _targetFps is already 0, so "fps": 0 is written to disk.

Step 4 — Every subsequent boot: loads "fps": 0 → setTargetFps(0) → unlimited mode is permanently stuck.

Note: The constructor in FX.h line 856 does correctly initialize _targetFps(WLED_FPS) (= 42), so the starting state is correct — it's the load path overwriting it with 0 that triggers the bug.

---

Suggested Fix

The cleanest fix is in cfg.cpp line 179: skip calling setTargetFps when the key is absent (keep the constructor's correct default of 42), while still correctly applying an explicitly saved 0 (unlimited mode):

// Before (buggy — comment says NOP but code sets to 0):
strip.setTargetFps(hw_led["fps"]); //NOP if 0, default 42 FPS

// After:
if (!hw_led["fps"].isNull()) strip.setTargetFps(hw_led["fps"]); // keep constructor default (42) if not saved

This way:

Scenario	hw_led["fps"]	Result
Fresh flash (no config)	absent (null)	Skips call → keeps constructor default 42 ✅
Saved fps = 42	42	setTargetFps(42) ✅
Saved fps = 0 (unlimited, user intentional)	0	setTargetFps(0) → unlimited ✅

Would you like me to open a PR or a follow-up issue for this fix?

[softhack007]

@DedeHai reminds me of the issue we found recently, about another default value - gamma - not being used on a fresh install. I think the solutions is the same : strip.setTargetFps(hw_led["fps"] | WLED_FPS)

[softhack007]

I'm curious why we see several issue now in 16.0 with default values not being applied when cfg.json is not yet existing (fresh install). And I'm very sure all this was working properly in previous releases, at least it did work in 0.14.3 🤔

[DedeHai]

@DedeHai reminds me of the issue we found recently, about another default value - gamma - not being used on a fresh install. I think the solutions is the same : strip.setTargetFps(hw_led["fps"] | WLED_FPS)

I did not look into it yet but very well possible.
I also remember values being set properly like not so long ago and I am clueless on why it did work before and what has changed. maybe the rabbit can do an investigation on that.

[softhack007]

@coderabbitai it seems that some changes in main caused problems with default values not being written to cfg.json after a fresh install (or cleaning the filesystem). Please investigate if there is a common root cause for this regression. In case you find a common cause, please track back the commit history to find out when/how the regression was introduced.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# 1. Get the full cfg.cpp to understand load/save flow and first-boot handling
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/cfg.cpp" > /tmp/cfg_main.cpp
wc -l /tmp/cfg_main.cpp

# 2. Look at the readFromConfig / deserializeConfig entry point and first-boot logic
grep -n "firstBoot\|first_boot\|firstTime\|EEPROM\|doInitConfig\|CONFIG_VERSION\|deserializeConfig\|serializeConfig\|saveConfig\|doSaveConfig" /tmp/cfg_main.cpp | head -60

# 3. Look at the top of the file (includes, first-boot flags)
head -80 /tmp/cfg_main.cpp | cat -n

Length of output: 3568

---

🏁 Script executed:

#!/bin/bash
# 4. Check the wled.cpp / wled_server.cpp for first-boot / init config logic
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/wled.cpp" > /tmp/wled_main.cpp
grep -n "firstBoot\|doInitConfig\|deserializeConfig\|serializeConfig\|doSaveConfig\|WLED_FS\|cfg.json\|presets.json" /tmp/wled_main.cpp | head -60

# 5. Check how doInitConfig / doSaveConfig are triggered on first boot
grep -n "doInitConfig\|doSaveConfig\|firstBoot\|!WLED_FS\|formatFS\|mountFS" /tmp/wled_main.cpp | head -30

Length of output: 474

---

🏁 Script executed:

#!/bin/bash
# 6. Check git log for cfg.cpp in the main branch - recent commits
curl -s "https://api.github.com/repos/wled/WLED/commits?path=wled00/cfg.cpp&sha=main&per_page=20" | python3 -c "
import json, sys
data = json.load(sys.stdin)
for c in data:
    print(c['sha'][:10], c['commit']['author']['date'][:10], c['commit']['message'].split('\n')[0][:100])
"

Length of output: 1443

---

🏁 Script executed:

#!/bin/bash
# 7. Check git log for wled.cpp recent commits (might contain first-boot logic changes)
curl -s "https://api.github.com/repos/wled/WLED/commits?path=wled00/wled.cpp&sha=main&per_page=20" | python3 -c "
import json, sys
data = json.load(sys.stdin)
for c in data:
    print(c['sha'][:10], c['commit']['author']['date'][:10], c['commit']['message'].split('\n')[0][:100])
"

Length of output: 1374

---

🏁 Script executed:

#!/bin/bash
# 1. Look at the EEPROM removal commit - what was removed
curl -s "https://api.github.com/repos/wled/WLED/commits/c8a03817ed" | python3 -c "
import json, sys
data = json.load(sys.stdin)
print('Message:', data['commit']['message'])
print('Files changed:')
for f in data.get('files', []):
    print(' ', f['filename'], '+'+str(f['additions']), '-'+str(f['deletions']))
"

Length of output: 233

---

🏁 Script executed:

#!/bin/bash
# 2. Look at the gamma fix commit (`#5225`) - to understand the pattern used
curl -s "https://api.github.com/repos/wled/WLED/commits/d1d9dec402" | python3 -c "
import json, sys
data = json.load(sys.stdin)
print('Message:', data['commit']['message'])
print('Files changed:')
for f in data.get('files', []):
    print(' ', f['filename'], '+'+str(f['additions']), '-'+str(f['deletions']))
    if 'cfg.cpp' in f['filename']:
        print('PATCH:')
        print(f.get('patch', '')[:3000])
"

Length of output: 796

---

🏁 Script executed:

#!/bin/bash
# 3. Look at deserializeConfigFromFS and the needsSave logic when file doesn't exist
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/cfg.cpp" | awk 'NR>=800 && NR<=840 {print NR": "$0}'
echo "==="
# 4. Look at the full deserializeConfig needsSave return and related logic
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/cfg.cpp" | awk 'NR>=45 && NR<=70 {print NR": "$0}'
echo "==="
# Search for all needsSave assignments in cfg.cpp
grep -n "needsSave" /tmp/cfg_main.cpp | head -40

Length of output: 2530

---

🏁 Script executed:

#!/bin/bash
# 5. Look at hw_led section in deserializeConfig (fps, gamma, and other hardware defaults)
grep -n "hw_led\|hw_led\[" /tmp/cfg_main.cpp | head -60

Length of output: 1512

---

🏁 Script executed:

#!/bin/bash
# 1. Get the exact lines removed from cfg.cpp and wled.cpp by the EEPROM removal commit
curl -s "https://api.github.com/repos/wled/WLED/commits/c8a03817ed" | python3 -c "
import json, sys
data = json.load(sys.stdin)
for f in data.get('files', []):
    if f['filename'] in ('wled00/cfg.cpp', 'wled00/wled.cpp', 'wled00/wled.h'):
        print('=== FILE:', f['filename'], '===')
        print(f.get('patch', '')[:2000])
"

Length of output: 902

---

🏁 Script executed:

#!/bin/bash
# 2. Scan deserializeConfig for all direct assignments that DON'T use CJSON or | operator
# These are candidates for the same fresh-install bug
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/cfg.cpp" | awk '
NR>=45 && NR<=770 {
    line = $0
    # Print lines that look like assignments from doc/json but are NOT using CJSON or | operator
    if (line ~ /strip\.[a-zA-Z]*\(/ && line !~ /CJSON/ && line !~ /\|/) print NR": "line
    if (line ~ /= [a-z_]*\[/ && line !~ /CJSON/ && line !~ /\|/ && line !~ /^[[:space:]]*\/\//) print NR": "line
    if (line ~ /getStringFromJson/ && line !~ /CJSON/ && line !~ /\|/) print NR": "line
}' | head -80

Length of output: 4187

---

🏁 Script executed:

#!/bin/bash
# 3. Look at readObjectFromFile to understand what happens when /cfg.json doesn't exist
grep -n "readObjectFromFile\|readObjectFrom" /tmp/cfg_main.cpp | head -10
# Also check json_utils or file utils for this function
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/json.cpp" 2>/dev/null | grep -n "readObjectFromFile" | head -10
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/util.cpp" 2>/dev/null | grep -n -A10 "bool readObjectFromFile" | head -30

Length of output: 132

---

🏁 Script executed:

#!/bin/bash
# 4. Fetch the deleted wled_eeprom.cpp to understand what it did on first boot
curl -s "https://api.github.com/repos/wled/WLED/contents/wled00/wled_eeprom.cpp?ref=c8a03817ed~1" | python3 -c "
import json, sys, base64
data = json.load(sys.stdin)
content = base64.b64decode(data['content']).decode('utf-8', errors='replace')
# Search for first-boot / cfg.json / fps / gamma related code
lines = content.split('\n')
for i, l in enumerate(lines):
    if any(x in l for x in ['cfg.json', 'firstBoot', 'fps', 'gamma', 'FPS', 'targetFps', 'serializeConfig', 'needsSave', 'fromFS']):
        print(f'{i+1}: {l}')
" 2>/dev/null | head -40

Length of output: 213

---

🏁 Script executed:

#!/bin/bash
# 5. Look at the broader context around line 179 (fps) and lines 165-215 in cfg.cpp
awk 'NR>=160 && NR<=215 {print NR": "$0}' /tmp/cfg_main.cpp

Length of output: 2497

---

🏁 Script executed:

#!/bin/bash
# 1. Check the big bus handling commit for fps-related changes in cfg.cpp
curl -s "https://api.github.com/repos/wled/WLED/commits/d1ed547a7c" | python3 -c "
import json, sys
data = json.load(sys.stdin)
print('Message:', data['commit']['message'][:200])
for f in data.get('files', []):
    if 'cfg.cpp' in f['filename']:
        patch = f.get('patch', '')
        # Find fps context in patch
        if 'fps' in patch.lower():
            print('=== cfg.cpp patch (fps context) ===')
            lines = patch.split('\n')
            for i, l in enumerate(lines):
                if 'fps' in l.lower():
                    start = max(0, i-3)
                    end = min(len(lines), i+4)
                    for ll in lines[start:end]:
                        print(ll)
                    print('---')
"

Length of output: 976

---

🏁 Script executed:

#!/bin/bash
# 2. Find when setTargetFps was introduced - check all commits touching FX_fcn.cpp
curl -s "https://api.github.com/repos/wled/WLED/commits?path=wled00/FX_fcn.cpp&sha=main&per_page=20" | python3 -c "
import json, sys
data = json.load(sys.stdin)
for c in data:
    print(c['sha'][:10], c['commit']['author']['date'][:10], c['commit']['message'].split('\n')[0][:100])
"

Length of output: 1500

---

🏁 Script executed:

#!/bin/bash
# 3. Search git log for the specific fps line in cfg.cpp to find when it was added/changed
# Check the ABL/FPS commit (use video scaling instead of NPB luminance - d5d7fde30f from 2025-08-29)
curl -s "https://api.github.com/repos/wled/WLED/commits/d5d7fde30f" | python3 -c "
import json, sys
data = json.load(sys.stdin)
print('Message:', data['commit']['message'][:200])
for f in data.get('files', []):
    if 'cfg.cpp' in f['filename']:
        patch = f.get('patch', '')
        if 'fps' in patch.lower() or 'targetFps' in patch:
            print('=== cfg.cpp fps patch ===')
            lines = patch.split('\n')
            for i, l in enumerate(lines):
                if 'fps' in l.lower():
                    start = max(0, i-3)
                    end = min(len(lines), i+4)
                    for ll in lines[start:end]:
                        print(ll)
                    print('---')
        else:
            print('No fps changes in cfg.cpp')
"

Length of output: 209

---

🏁 Script executed:

#!/bin/bash
# 4. Check the FX_fcn.cpp setTargetFps implementation more carefully
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/FX_fcn.cpp" | awk 'NR>=1700 && NR<=1730 {print NR": "$0}'
echo "==="
# Also look at the full FX.h for WLED_FPS define and _targetFps constructor init
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/FX.h" | grep -n "WLED_FPS\|FPS_UNLIMITED\|MIN_FRAME_DELAY\|_targetFps" | head -20
echo "==="
# Look at the constructor initialization
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/FX.h" | awk 'NR>=850 && NR<=870 {print NR": "$0}'

Length of output: 2945

---

🏁 Script executed:

#!/bin/bash
# 5. Check if needsSave ever returns true on fresh install - look at what UsermodManager::readFromConfig returns 
# Also check if there's a "cfg.json doesn't exist" branch that sets needsSave=true
curl -s "https://raw.githubusercontent.com/wled/WLED/main/wled00/cfg.cpp" | awk 'NR>=755 && NR<=820 {print NR": "$0}'

Length of output: 2108

---

🏁 Script executed:

#!/bin/bash
# Find when strip.setTargetFps first appeared in cfg.cpp by checking earlier versions
# Check the ABL commit d5d7fde30f more carefully for cfg.cpp changes
curl -s "https://api.github.com/repos/wled/WLED/commits/d5d7fde30f" | python3 -c "
import json, sys
data = json.load(sys.stdin)
for f in data.get('files', []):
    if 'cfg.cpp' in f['filename']:
        patch = f.get('patch', '')
        print('cfg.cpp patch (first 5000 chars):')
        print(patch[:5000])
" | grep -A5 -B5 "fps\|targetFps\|setTargetFps" | head -60

Length of output: 0

---

🏁 Script executed:

#!/bin/bash
# Check the cfg.cpp content at the commit just BEFORE d5d7fde30f to see what was there before
PARENT=$(curl -s "https://api.github.com/repos/wled/WLED/commits/d5d7fde30f" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['parents'][0]['sha'])")
echo "Parent commit: $PARENT"
curl -s "https://raw.githubusercontent.com/wled/WLED/$PARENT/wled00/cfg.cpp" | grep -n "fps\|targetFps\|setTargetFps" | head -20

Length of output: 167

---

🏁 Script executed:

#!/bin/bash
# Comprehensive audit: all lines in deserializeConfig (lines 45-768) that read JSON
# without CJSON or | fallback and aren't getStringFromJson (which has null check built in)
awk 'NR>=45 && NR<=768' /tmp/cfg_main.cpp | grep -v "CJSON\|getStringFromJson\|isNull\|//\|JsonObject\|JsonArray\|JsonVariant\|createNested\|reserve\|clear\|push_back\|emplace\|shrink" | grep "\[" | grep "=" | grep -v "| " | grep -v "!=" | grep -v "==" | head -50

Length of output: 1980

---

🏁 Script executed:

#!/bin/bash
# Check setTargetFps implementation BEFORE the ABL commit (d5d7fde30f)
PARENT="8aeb9e1abeebf847686a74e24d93964e01f5d4c7"
echo "=== setTargetFps in FX_fcn.cpp at parent of d5d7fde30f ==="
curl -s "https://raw.githubusercontent.com/wled/WLED/$PARENT/wled00/FX_fcn.cpp" | grep -n -A8 "setTargetFps"
echo "==="
# Check FPS_UNLIMITED and WLED_FPS defines in FX.h at that commit
curl -s "https://raw.githubusercontent.com/wled/WLED/$PARENT/wled00/FX.h" | grep -n "FPS_UNLIMITED\|WLED_FPS\|FRAMETIME\|MIN_FRAME\|_targetFps"

Length of output: 1406

---

🏁 Script executed:

#!/bin/bash
# Look at the d5d7fde30f ABL commit patch for FX_fcn.cpp - specifically setTargetFps changes
curl -s "https://api.github.com/repos/wled/WLED/commits/d5d7fde30f" | python3 -c "
import json, sys
data = json.load(sys.stdin)
for f in data.get('files', []):
    if 'FX_fcn.cpp' in f['filename'] or 'FX.h' in f['filename']:
        patch = f.get('patch', '')
        if 'fps' in patch.lower() or 'targetFps' in patch or 'FPS' in patch:
            print('=== FILE:', f['filename'], '===')
            lines = patch.split('\n')
            for i, l in enumerate(lines):
                if any(x in l for x in ['fps', 'FPS', 'targetFps', 'frametime', 'FRAMETIME', 'UNLIMITED']):
                    start = max(0, i-3)
                    end = min(len(lines), i+5)
                    for ll in lines[start:end]:
                        print(ll)
                    print('---')
" | head -80

Length of output: 1134

---

🏁 Script executed:

#!/bin/bash
# Check when FPS_UNLIMITED was introduced - look at git log for FX.h
curl -s "https://api.github.com/repos/wled/WLED/commits?path=wled00/FX.h&sha=main&per_page=10" | python3 -c "
import json, sys
data = json.load(sys.stdin)
for c in data:
    print(c['sha'][:10], c['commit']['author']['date'][:10], c['commit']['message'].split('\n')[0][:100])
"

Length of output: 689

---

@softhack007 Here is the full investigation. The root cause is common to both the FPS and gamma issues, and is structural — not tied to a single commit.

---

🔍 Root Cause: deserializeConfig() called on empty JSON, no fallback

The central problem

deserializeConfigFromFS() always calls deserializeConfig(root, true) — even when cfg.json does not exist (fresh install). In that case, root is an empty JsonObject, and the behaviour depends entirely on how each setting is read:

Pattern	Behaviour on fresh install
CJSON(a, hw_led["x"]) → a = hw_led["x"] | a	✅ hw_led["x"] is null → ArduinoJSON | fallback keeps a unchanged (correct constructor default preserved)
a = hw_led["x"] | default_val	✅ Same — correct
strip.setTargetFps(hw_led["fps"])	❌ hw_led["fps"] is null → coerces to 0 → setTargetFps(0) is called, setting _targetFps = 0 (FPS_UNLIMITED), overriding the correct constructor default of 42
float x = light["gc"]["col"] (pre-fix)	❌ null → 0.0f → 0.0f > 1.0f is false → gammaCorrectCol = false — wrong

---

Why cfg.json is never written with correct defaults on first boot

There's a second, compounding issue. In wled.cpp:

bool needsCfgSave = deserializeConfigFromFS();
...
if (needsCfgSave) serializeConfigToFS();

And in deserializeConfig() (lines 758–761):

JsonObject usermods_settings = doc["um"];
if (!usermods_settings.isNull()) {
    needsSave = !UsermodManager::readFromConfig(usermods_settings);
}

On a fresh install with no usermods: doc["um"] is null → the if block is skipped → needsSave remains false → serializeConfigToFS() is never called → cfg.json is never created at first boot.

This means that when the user eventually saves settings via the web UI, strip._targetFps is already 0 in memory (corrupted by the fresh-install deserialize), so "fps": 0 is written to disk — and the broken state is now permanently persisted.

---

Sequence on fresh install (no cfg.json)

Boot → deserializeConfigFromFS()
  → readObjectFromFile() fails (no file) → empty JsonObject
  → deserializeConfig(empty, true)
     → strip.setTargetFps(0)  ← overrides constructor default WLED_FPS(42)
     → gammaCorrectCol = false ← (fixed Jan 2026 in d1d9dec402)
     → needsSave = false       ← no usermods → no save triggered
  → strip._targetFps is now 0 (wrong)

Later: user saves settings via web UI
  → serializeConfigToFS()
  → hw_led["fps"] = strip.getTargetFps() → 0
  → cfg.json written with "fps": 0  ← broken default persisted permanently

---

Tracking the regression

The misleading comment on line 179 — "NOP if 0, default 42 FPS" — is a strong signal that setTargetFps(0) used to be a NOP. At some point the implementation was changed to treat 0 as FPS_UNLIMITED (a valid unlimited mode) without adding a null-check guard in the load path. FPS_UNLIMITED 0 and the current accepting-0 implementation of setTargetFps were already in place at the parent of the d5d7fde30f (Aug 2025) ABL commit, so the regression predates that. The gamma bug follows the identical pattern and was fixed in commit d1d9dec402 (Jan 12, 2026) as a one-off, confirming the structural issue was already present.

---

Fixes

1. Immediate fix for FPS (line 179, cfg.cpp) — as @softhack007 suggested:

// Before (broken):
strip.setTargetFps(hw_led["fps"]); //NOP if 0, default 42 FPS

// After — ArduinoJSON fallback, consistent with the CJSON pattern everywhere else:
strip.setTargetFps(hw_led["fps"] | WLED_FPS);

This correctly handles all three cases: absent key → WLED_FPS (42); saved 42 → 42; saved 0 (user-intentional unlimited) → 0.

2. Structural fix: write defaults to cfg.json on truly fresh install

needsSave should be set to true when cfg.json doesn't exist, so correct defaults are immediately written on first boot, before any user interaction:

bool deserializeConfigFromFS() {
  [[maybe_unused]] bool success = deserializeConfigSec();
  if (!requestJSONBufferLock(JSON_LOCK_CFG_DES)) return false;

  bool cfgExists = WLED_FS.exists(s_cfg_json);  // <-- check before reading
  success = readObjectFromFile(s_cfg_json, nullptr, pDoc);
  JsonObject root = pDoc->as<JsonObject>();
  bool needsSave = deserializeConfig(root, true);
  releaseJSONBufferLock();

  return needsSave || !cfgExists;  // <-- force save on fresh install
}

3. Code audit — any remaining reads in deserializeConfig() that don't use CJSON or | default for values with non-zero/non-false defaults should be audited. From the scan, the critical ones are FPS (unfixed) and gamma (fixed Jan 2026). Others like skipFirst, reversed, and colorOrder default to 0/false which is acceptable.

---

Would you like me to open a PR or issue tracking both the FPS fix and the structural needsSave fix?

---

✏️ Learnings added

Learnt from: softhack007
URL: https://github.com/wled/WLED/issues/5408

Timestamp: 2026-03-08T00:57:36.105Z
Learning: In WLED (wled00/cfg.cpp), `deserializeConfig()` is called with an empty JsonObject when cfg.json doesn't exist on fresh install. Any value read without the ArduinoJSON `|` fallback operator or CJSON macro will override correct constructor defaults with 0/null. Known affected values: `strip.setTargetFps(hw_led["fps"])` at line 179 (sets FPS to 0/unlimited instead of WLED_FPS=42). Fix: `strip.setTargetFps(hw_led["fps"] | WLED_FPS)`. The gamma issue (gammaCorrectCol/Bri) had the same root cause and was fixed in commit d1d9dec402 (Jan 2026) using inline `| default` fallbacks.

---

Learnt from: softhack007
URL: https://github.com/wled/WLED/issues/5408

Timestamp: 2026-03-08T00:57:36.105Z
Learning: In WLED (wled00/cfg.cpp), `deserializeConfigFromFS()` only sets `needsSave=true` (triggering a write of cfg.json) when usermod settings are present in the JSON (lines 758-761). On a fresh install with no usermods, `needsSave=false` so `serializeConfigToFS()` is never called at first boot. Correct defaults are never written to cfg.json until the user manually saves. Structural fix: set `needsSave = needsSave || !cfgExists` where `cfgExists = WLED_FS.exists(s_cfg_json)` checked before reading the file.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

---

🧠 Learnings used

Learnt from: DedeHai
Repo: wled/WLED PR: 4798
File: wled00/FX.cpp:7531-7533
Timestamp: 2025-08-26T11:51:21.817Z
Learning: In WLED PR `#4798`, DedeHai confirmed that certain gamma-related calls in FX.cpp/FX_fcn.cpp/particle systems are intentional for effect-level shaping (e.g., brightness curves, TV sim, Pride 2015 pre-mix), distinct from final output gamma. Do not flag or remove these in future reviews; add comments when feasible to clarify intent.

---

Learnt from: blazoncek
Repo: wled/WLED PR: 5140
File: wled00/data/settings_time.htm:66-76
Timestamp: 2025-12-01T07:01:16.949Z
Learning: In WLED PR `#5134`, the fix for macros being initialized with the enable bit set only handles new configurations, not existing ones. If there is a bug in timer/macro handling code (e.g., in settings_time.htm), it must be fixed to work correctly for existing configurations as well.

---

Learnt from: DedeHai
Repo: wled/WLED PR: 4939
File: wled00/FX_fcn.cpp:1176-1187
Timestamp: 2025-09-16T18:08:42.848Z
Learning: In WLED finalizeInit() bus creation (wled00/FX_fcn.cpp), intentionally allowing memory overruns when bus configurations exceed MAX_LED_MEMORY is a deliberate design choice. The trade-off prioritizes creating buses with reduced LED counts over completely failing to create buses, which would cause no LED output and UI failures. This approach forces users to update configurations after migrating to version 0.16 while maintaining basic functionality.

---

Learnt from: softhack007
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2025-12-28T14:06:48.772Z
Learning: In WLED post-commit ee9ac947, the rendering pipeline uses per-segment buffers and per-pixel bus updates. Unmapped (0xFFFF) mapping entries are now skipped in WS2812FX::show() (no “clear to black”), which can leave physical gap LEDs with stale/random colors unless they are explicitly cleared. This is a behavior change from pre-0.16 where a full physical buffer was effectively refreshed each frame.