JSON API: Support CCT for Per-segment individual LED control

[arx8x]

Is your feature request related to a problem? Please describe.
The JSON API supports setting color and brightness per LED using the "i" param. The color array and hex code currently support R, G, B and W, where the W bits control the brightness of the white color. There's no option to set the CCT value with this currently. The CCT can be set but it applies to the entire output.

Describe the solution you'd like
I propose adding one more param, which is the CCT value for the index or the range specified in the request.
Example: [0, 0, 0, 255, 0] or 000000FF00 represents warm white and [0, 0, 0, 255, 128] or 000000FF80 represents neutral white

Describe alternatives you've considered
-

Additional context
-

Thank you for your ideas for making WLED better!

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• W281x CCT support #4636
• DMX type MULTI RGBCCT #5018
• Add option to customize white LED temperature #4508

🔗 Related PRs

#4744 - CCT fix [merged]

👤 Suggested Assignees

• justr0st
• olafofta
• maganuk
• blazoncek

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[DedeHai]

there is no CCT in RGBW, CCT is a global parameter. if you want to set a per-LED white temperature, choose the correct "auto calculate white".

[arx8x]

I think you slightly misinterpreted my suggestion. I wasn't referring to lighting up white LEDs along with colors, but controlling the color temperate of the dedicated white LEDs (in something like WS2805 RGBCCT). Auto calculating white doesn't help with this.

Currently such an option doesn't exist in the API. And this isn't a hardware limitation. You can do this through defined segments.
For example: seg0 of 0 to 1 LED can be warm white, seg1 of 1 to 2 can be cool white, seg2 of 2 to 3 can be warm white and so on. But this is limited by the number of segments you can have.
The practical way around this is (at least what I can think of) to use the i param in the API and individually address LEDs. Like I suggested, a 4th param in the color array could describe the color temperature for the i th LED.

[DedeHai]

there is no underlying structure to support such an API call, it would mean a whole lot of rewriting code. I can task copilot and see what it comes up with but I have little hope it will be useful.

[DedeHai]

@coderabbitai what changes would be necessary to the code to support a persistent CCT buffer for CCT enabled LED strips? Please compile a brief summary of necessary changes and potential disadvantages.

[coderabbitai]

Coding Plan

Approach

Ticket Summary

Add per-LED CCT (Color Correlated Temperature) control to the JSON API's "i" parameter for RGBCCT LED strips. This enables setting individual LED color temperatures alongside RGBW values, eliminating the current limitation where CCT is a global parameter affecting all LEDs.

Observations

Codebase Summary

WLED is a firmware for ESP8266/ESP32 that controls addressable LED strips. The architecture uses Segments to organize LEDs, with each segment maintaining a pixel buffer for color data. The JSON API's "i" parameter currently supports per-LED RGBW control by parsing color arrays or hex strings and calling setRawPixelColor(). CCT is applied globally via Bus::_cct during bus output in BusDigital::setPixelColor(), where it's converted to warm white (WW) and cool white (CW) channel values for RGBCCT strips. The codebase already includes temporary per-LED CCT buffers (_pixelCCT) during rendering, demonstrating the memory allocation pattern.

Assumptions

Assumption 1: Per-LED CCT Precedence

Options Considered:

• Apply global CCT always (maintains current behavior)
• Apply segment CCT with per-LED override
• Apply per-LED CCT exclusively when set, with cascading fallback

Chosen Option: Cascading fallback (per-LED CCT → segment CCT → global CCT)

Rationale: This approach feels most natural to developers as it respects the existing hierarchy while adding per-LED control at the highest priority level. It maintains backward compatibility while enabling fine-grained control.

Assumption 2: Memory Allocation Strategy

Options Considered:

• Pre-allocate for all segments regardless of use
• Allocate only when "i" param with CCT is first used
• Extend existing pixel buffer to 40-bit or 48-bit values

Chosen Option: On-demand allocation per segment

Rationale: This aligns with WLED's existing pattern of lazy allocation (seen in segment data buffers) and respects memory constraints on ESP8266. The allocation happens when the JSON API first sets per-LED CCT values, making the feature zero-cost for users who don't use it.

Assumption 3: Format for CCT in JSON/Hex

Options Considered:

• 5-element arrays only: [R,G,B,W,CCT]
• Extend hex to 10 chars: RRGGBBWWCC
• Both formats for consistency

Chosen Option: Support both array and hex formats

Rationale: This maintains API consistency and follows the existing pattern where users can choose their preferred format. Array format: [0,0,0,255,128] for neutral white. Hex format: 000000FF80 (10 characters).

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Per-LED CCT Storage Infrastructure

Add per-LED CCT buffer capability to the Segment class, following the existing pattern of optional data allocation.

Task 1: Add CCT Buffer to Segment Structure

Extend the Segment class to support per-LED CCT storage.

• Add uint8_t *cctData member to Segment class in wled00/FX.h alongside the existing pixels buffer
• Add helper methods: allocateCCTData(), deallocateCCTData(), hasCCTData(), getCCT(uint16_t i), setCCT(uint16_t i, uint8_t cct)
• Follow the existing allocation pattern used for pixels buffer: prefer PSRAM, fall back to DRAM, with explicit deallocation

Task 2: Implement CCT Buffer Memory Management

Handle allocation, deallocation, and lifecycle of the CCT buffer.

• In wled00/FX_fcn.cpp, add allocateCCTData() implementation that allocates length() * sizeof(uint8_t) bytes using allocate_buffer() with PSRAM preference
• Extend deallocateData() to also free cctData if allocated
• Add CCT buffer cleanup to segment reset operations
• Update memory usage tracking in addUsedSegmentData() to account for CCT buffer size

🤖 Prompt for AI agents

Implement per-LED CCT storage infrastructure by adding a CCT buffer to the
Segment class.

In wled00/FX.h:
- Add `uint8_t *cctData` member variable to Segment class
- Add methods: `allocateCCTData()`, `deallocateCCTData()`, `hasCCTData()`,
`getCCT(uint16_t i)`, `setCCT(uint16_t i, uint8_t cct)`

In wled00/FX_fcn.cpp:
- Implement `allocateCCTData()` to allocate `length() * sizeof(uint8_t)` bytes
using `allocate_buffer()` with PSRAM preference
- Extend `deallocateData()` to free cctData when allocated
- Add CCT buffer cleanup to segment reset operations
- Update `addUsedSegmentData()` to include CCT buffer size in memory tracking

Phase 2: JSON API Extension for CCT Input

Extend the "i" parameter parsing to accept and store the 5th CCT element.

Task 1: Parse 5-Element Color Arrays

Modify JSON parsing to accept CCT as 5th element in color arrays.

• In wled00/json.cpp, locate the "i" parameter parsing logic (around JsonArray iarr = elem[F("i")])
• Change size check from sz < 5 to sz < 6 to accept 5-element arrays
• Extract 5th element as CCT value: uint8_t cct = (sz == 5) ? icol[4] : 255 (default to 255 if not provided)
• After extracting RGBW values, call seg.allocateCCTData() if not already allocated
• Store CCT value using seg.setCCT(iStart, cct) for each LED in the range

Task 2: Extend Hex String Parsing for CCT

Support 10-character hex strings that include CCT value.

• In wled00/colors.cpp, extend colorFromHexString() to handle 10-character strings (RRGGBBWWCC format)
• Add parameter to colorFromHexString() to optionally return the CCT value
• In wled00/json.cpp hex parsing section, detect 10-char strings and extract both RGBW and CCT
• Store extracted CCT value in segment's cctData buffer using the same pattern as array parsing

🤖 Prompt for AI agents

Extend JSON API "i" parameter parsing to accept 5th CCT element in both array
and hex formats.

In wled00/json.cpp:
- Locate "i" parameter parsing logic
- Update size check from `sz < 5` to `sz < 6` to accept 5-element arrays
- Extract 5th element as CCT: `uint8_t cct = (sz == 5) ? icol[4] : 255`
- Call `seg.allocateCCTData()` if not already allocated
- Store CCT using `seg.setCCT(iStart, cct)` for each LED

In wled00/colors.cpp:
- Extend `colorFromHexString()` to handle 10-character strings (RRGGBBWWCC
format)
- Add parameter to optionally return CCT value

In wled00/json.cpp hex parsing:
- Detect 10-char hex strings
- Extract both RGBW and CCT values
- Store CCT in segment's cctData buffer

Phase 3: CCT Application During Bus Output

Modify the bus output pipeline to use per-LED CCT values when available.

Task 1: Per-LED CCT Lookup in Segment Rendering

Enable segments to provide per-LED CCT during the rendering-to-bus transfer.

• In wled00/FX_fcn.cpp, modify the segment-to-bus output code (around BusManager::setPixelColor() calls)
• Before calling bus output, check if segment has CCT data: seg.hasCCTData()
• If available, retrieve per-LED CCT: uint8_t ledCCT = seg.getCCT(segmentRelativeIndex)
• Pass this value through the rendering pipeline (may need to extend intermediate function signatures)

Task 2: Apply Per-LED CCT in Bus Manager

Modify bus output to use per-LED CCT with fallback hierarchy.

• In wled00/bus_manager.cpp, extend BusDigital::setPixelColor() to accept an optional per-LED CCT parameter
• Implement CCT value resolution: use per-LED CCT if provided, else segment CCT, else global Bus::_cct
• Modify the calculateCCT() call to use the resolved CCT value instead of always using global Bus::_cct
• Ensure the calculated WW/CW values are correctly passed to PolyBus::setPixelColor()

🤖 Prompt for AI agents

Modify bus output pipeline to apply per-LED CCT values with cascading fallback.

In wled00/FX_fcn.cpp:
- Modify segment-to-bus output code around `BusManager::setPixelColor()` calls
- Check if segment has CCT data using `seg.hasCCTData()`
- Retrieve per-LED CCT: `uint8_t ledCCT = seg.getCCT(segmentRelativeIndex)`
- Pass CCT value through rendering pipeline (extend function signatures as
needed)

In wled00/bus_manager.cpp:
- Extend `BusDigital::setPixelColor()` to accept optional per-LED CCT parameter
- Implement CCT resolution: per-LED CCT → segment CCT → global `Bus::_cct`
- Update `calculateCCT()` call to use resolved CCT value
- Ensure calculated WW/CW values pass to `PolyBus::setPixelColor()`

Phase 4: Persistence Support

Enable saving and loading per-LED CCT arrays in presets.

Task 1: Serialize Per-LED CCT Arrays

Add CCT data to segment serialization in JSON format.

• In wled00/json.cpp, extend serializeSegment() to include CCT data when present
• Add a new JSON field (e.g., "cctData") containing an array of CCT values
• Only serialize if segment has allocated CCT data: if (seg.hasCCTData())
• Format as compact integer array: "cctData":[128,255,64,...] to minimize JSON size

Task 2: Deserialize Per-LED CCT Arrays

Restore per-LED CCT values when loading presets.

• In wled00/json.cpp, extend deserializeSegment() to parse the "cctData" field
• When present, allocate segment CCT buffer and populate from JSON array
• Validate array length matches segment length (or handle gracefully if mismatched)
• Ensure preset loading in wled00/presets.cpp correctly triggers CCT data restoration

🤖 Prompt for AI agents

Add persistence support for per-LED CCT arrays in presets.

In wled00/json.cpp:
- Extend `serializeSegment()` to include CCT data when present
- Add `"cctData"` field with compact integer array format
- Only serialize if `seg.hasCCTData()` returns true

- Extend `deserializeSegment()` to parse `"cctData"` field
- Allocate segment CCT buffer and populate from JSON array
- Validate array length matches segment length

In wled00/presets.cpp:
- Ensure preset loading correctly triggers CCT data restoration

Phase 5: Documentation and Edge Cases

Handle special cases and update documentation.

Task 1: Handle Segment Operations with CCT Data

Ensure CCT data is properly managed during segment lifecycle operations.

• Review segment split/merge operations in wled00/FX_fcn.cpp and ensure CCT data is handled
• Handle segment resizing: reallocate CCT buffer if segment length changes
• Clear CCT data appropriately when segment is reset or cleared
• Ensure CCT data is deallocated when segment is deleted

Task 2: API Documentation and Validation

Document the new feature and add input validation.

• Add input validation in wled00/json.cpp to ensure CCT values are in valid range (0-255)
• Handle edge cases: empty CCT arrays, mismatched array lengths, invalid hex formats
• Update JSON API error messages to provide feedback for CCT parsing failures
• Document the feature in code comments, noting the format and precedence behavior

🤖 Prompt for AI agents

Handle edge cases and add documentation for per-LED CCT feature.

In wled00/FX_fcn.cpp:
- Review segment split/merge operations to ensure CCT data is properly handled
- Handle segment resizing by reallocating CCT buffer when length changes
- Clear CCT data on segment reset or clear
- Ensure CCT data is deallocated on segment deletion

In wled00/json.cpp:
- Add input validation for CCT values (0-255 range)
- Handle edge cases: empty CCT arrays, mismatched lengths, invalid hex formats
- Update error messages for CCT parsing failures
- Add code comments documenting format and precedence behavior

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement per-LED CCT storage infrastructure by adding a CCT buffer to the
Segment class.

In wled00/FX.h:
- Add `uint8_t *cctData` member variable to Segment class
- Add methods: `allocateCCTData()`, `deallocateCCTData()`, `hasCCTData()`,
`getCCT(uint16_t i)`, `setCCT(uint16_t i, uint8_t cct)`

In wled00/FX_fcn.cpp:
- Implement `allocateCCTData()` to allocate `length() * sizeof(uint8_t)` bytes
using `allocate_buffer()` with PSRAM preference
- Extend `deallocateData()` to free cctData when allocated
- Add CCT buffer cleanup to segment reset operations
- Update `addUsedSegmentData()` to include CCT buffer size in memory tracking
===============================================================================

Task: 2

Extend JSON API "i" parameter parsing to accept 5th CCT element in both array
and hex formats.

In wled00/json.cpp:
- Locate "i" parameter parsing logic
- Update size check from `sz < 5` to `sz < 6` to accept 5-element arrays
- Extract 5th element as CCT: `uint8_t cct = (sz == 5) ? icol[4] : 255`
- Call `seg.allocateCCTData()` if not already allocated
- Store CCT using `seg.setCCT(iStart, cct)` for each LED

In wled00/colors.cpp:
- Extend `colorFromHexString()` to handle 10-character strings (RRGGBBWWCC
format)
- Add parameter to optionally return CCT value

In wled00/json.cpp hex parsing:
- Detect 10-char hex strings
- Extract both RGBW and CCT values
- Store CCT in segment's cctData buffer
===============================================================================

Task: 3

Modify bus output pipeline to apply per-LED CCT values with cascading fallback.

In wled00/FX_fcn.cpp:
- Modify segment-to-bus output code around `BusManager::setPixelColor()` calls
- Check if segment has CCT data using `seg.hasCCTData()`
- Retrieve per-LED CCT: `uint8_t ledCCT = seg.getCCT(segmentRelativeIndex)`
- Pass CCT value through rendering pipeline (extend function signatures as
needed)

In wled00/bus_manager.cpp:
- Extend `BusDigital::setPixelColor()` to accept optional per-LED CCT parameter
- Implement CCT resolution: per-LED CCT → segment CCT → global `Bus::_cct`
- Update `calculateCCT()` call to use resolved CCT value
- Ensure calculated WW/CW values pass to `PolyBus::setPixelColor()`
===============================================================================

Task: 4

Add persistence support for per-LED CCT arrays in presets.

In wled00/json.cpp:
- Extend `serializeSegment()` to include CCT data when present
- Add `"cctData"` field with compact integer array format
- Only serialize if `seg.hasCCTData()` returns true

- Extend `deserializeSegment()` to parse `"cctData"` field
- Allocate segment CCT buffer and populate from JSON array
- Validate array length matches segment length

In wled00/presets.cpp:
- Ensure preset loading correctly triggers CCT data restoration
===============================================================================

Task: 5

Handle edge cases and add documentation for per-LED CCT feature.

In wled00/FX_fcn.cpp:
- Review segment split/merge operations to ensure CCT data is properly handled
- Handle segment resizing by reallocating CCT buffer when length changes
- Clear CCT data on segment reset or clear
- Ensure CCT data is deallocated on segment deletion

In wled00/json.cpp:
- Add input validation for CCT values (0-255 range)
- Handle edge cases: empty CCT arrays, mismatched lengths, invalid hex formats
- Update error messages for CCT parsing failures
- Add code comments documenting format and precedence behavior

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[DedeHai]

@arx8x while this would be feasible to implement it puts additionl strain on the already tight RAM in 0.16. What you can do is increase the number of segments for such a use case, although there is a hard limit of 255.