feat: Add effects_v2 schema for custom effect color and speed#47
Conversation
The Hue bridge exposes an undocumented `effects_v2` property on the
Light resource that enables custom color, color temperature, and speed
parameters for firmware-level effects (candle, fire, prism, etc.).
Unlike the basic `effects` property which only accepts an effect enum,
`effects_v2` accepts an `action` object with a `parameters` field:
PUT /resource/light/{id}
{
"effects_v2": {
"action": {
"effect": "fire",
"parameters": {
"color": { "xy": { "x": 0.35, "y": 0.15 } },
"speed": 0.8
}
}
}
}
Tested against bridge firmware with color-capable lights. The status
object mirrors the action structure and reports the active effect's
parameters including the resolved color, color_temperature, and speed.
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 51 minutes and 44 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
📝 WalkthroughWalkthroughThe pull request introduces a new effects control system (V2) by adding two schema files that define effect configuration and parameters, then integrating them into the existing light get/put endpoints through schema references. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
- Fix dynamics.speed maximum: 0 → 1 (was incorrectly constrained) - Replace alert TODO stub with actual schema (action_values array) - Add product_data object (light function: functional/decorative/mixed/unknown) - Add geometry object (pixel_positions for gradient strip pixel mapping)
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/light/schemas/EffectsV2.yaml`:
- Around line 7-30: Add machine-enforceable read/write semantics: mark the
action object and its writable properties as writeOnly and the status object and
its readable properties as readOnly. Specifically, set writeOnly: true for the
action object and for action.effect and action.parameters (but remove
action.effect_values entirely since capability metadata must not be writable),
and set readOnly: true for the status object and for status.effect and
status.effect_values so capability metadata remains read-only there. Ensure the
$ref entries (effect, effect_values, parameters) remain but with the appropriate
writeOnly/readOnly flags applied to the surrounding schema nodes (action,
status, action.parameters, status.effect_values).
In `@src/light/schemas/EffectsV2Parameters.yaml`:
- Around line 11-13: The field mirek_valid in the shared schema
EffectsV2Parameters.yaml is server-derived and must be response-only; update the
mirek_valid property to include readOnly: true so it is omitted from request
payloads (action.parameters) but still present in responses (status.parameters),
preserving the existing type and description.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 353de1bb-4868-4219-ba6d-6a42b72e01fd
📒 Files selected for processing (4)
src/light/schemas/EffectsV2.yamlsrc/light/schemas/EffectsV2Parameters.yamlsrc/light/schemas/LightGet.yamlsrc/light/schemas/LightPut.yaml
| action: | ||
| type: object | ||
| description: Write-only. Set effect with optional parameters. | ||
| properties: | ||
| effect: | ||
| $ref: '../../common/SupportedEffects.yaml' | ||
| effect_values: | ||
| type: array | ||
| description: Possible effect values supported by this light. | ||
| items: | ||
| $ref: '../../common/SupportedEffects.yaml' | ||
| parameters: | ||
| $ref: './EffectsV2Parameters.yaml' | ||
| status: | ||
| type: object | ||
| description: Read-only. Current effect status and active parameters. | ||
| properties: | ||
| effect: | ||
| $ref: '../../common/SupportedEffects.yaml' | ||
| effect_values: | ||
| type: array | ||
| description: Possible effect values supported by this light. | ||
| items: | ||
| $ref: '../../common/SupportedEffects.yaml' |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
find . -name "EffectsV2.yaml" -type fRepository: openhue/openhue-api
Length of output: 97
🏁 Script executed:
cat -n ./src/light/schemas/EffectsV2.yamlRepository: openhue/openhue-api
Length of output: 1440
🏁 Script executed:
rg "EffectsV2.yaml" --type yamlRepository: openhue/openhue-api
Length of output: 188
🏁 Script executed:
cat -n ./src/light/schemas/LightGet.yamlRepository: openhue/openhue-api
Length of output: 12327
🏁 Script executed:
cat -n ./src/light/schemas/LightPut.yamlRepository: openhue/openhue-api
Length of output: 1783
🏁 Script executed:
rg "readOnly|writeOnly" --type yamlRepository: openhue/openhue-api
Length of output: 45
🏁 Script executed:
find . -name "openapi.yaml" -o -name "openapi.yml" -o -name "swagger.yaml" | head -5Repository: openhue/openhue-api
Length of output: 45
🏁 Script executed:
find . -name "*.yaml" -path "*/src/*" | head -20Repository: openhue/openhue-api
Length of output: 941
🏁 Script executed:
cat -n ./src/light/light_{lightId}.yamlRepository: openhue/openhue-api
Length of output: 4102
🏁 Script executed:
find ./src -name "*.yaml" -type f | xargs grep -l "status_values\|effect_values" | head -10Repository: openhue/openhue-api
Length of output: 131
🏁 Script executed:
cat -n ./src/light/schemas/Effects.yamlRepository: openhue/openhue-api
Length of output: 236
🏁 Script executed:
cat -n ./src/light/schemas/LightDynamics.yamlRepository: openhue/openhue-api
Length of output: 587
🏁 Script executed:
cat -n ./src/light/schemas/SupportedTimedEffects.yamlRepository: openhue/openhue-api
Length of output: 235
🏁 Script executed:
cat -n ./src/light/schemas/Powerup.yamlRepository: openhue/openhue-api
Length of output: 2909
🏁 Script executed:
ls -la ./src/light/schemas/ | grep -i "get\|put"Repository: openhue/openhue-api
Length of output: 190
🏁 Script executed:
cat -n ./src/common/On.yamlRepository: openhue/openhue-api
Length of output: 239
Add machine-enforceable read/write semantics to action and status properties.
Line 9 and 22 describe mutability only in prose. Without writeOnly and readOnly flags, OpenAPI tooling and code generators cannot enforce access semantics. Additionally, action.effect_values (lines 13-17) represents capability metadata and should not appear in the writable action object.
Proposed fix
properties:
action:
type: object
+ writeOnly: true
description: Write-only. Set effect with optional parameters.
properties:
effect:
$ref: '../../common/SupportedEffects.yaml'
- effect_values:
- type: array
- description: Possible effect values supported by this light.
- items:
- $ref: '../../common/SupportedEffects.yaml'
parameters:
$ref: './EffectsV2Parameters.yaml'
status:
type: object
+ readOnly: true
description: Read-only. Current effect status and active parameters.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| action: | |
| type: object | |
| description: Write-only. Set effect with optional parameters. | |
| properties: | |
| effect: | |
| $ref: '../../common/SupportedEffects.yaml' | |
| effect_values: | |
| type: array | |
| description: Possible effect values supported by this light. | |
| items: | |
| $ref: '../../common/SupportedEffects.yaml' | |
| parameters: | |
| $ref: './EffectsV2Parameters.yaml' | |
| status: | |
| type: object | |
| description: Read-only. Current effect status and active parameters. | |
| properties: | |
| effect: | |
| $ref: '../../common/SupportedEffects.yaml' | |
| effect_values: | |
| type: array | |
| description: Possible effect values supported by this light. | |
| items: | |
| $ref: '../../common/SupportedEffects.yaml' | |
| action: | |
| type: object | |
| writeOnly: true | |
| description: Write-only. Set effect with optional parameters. | |
| properties: | |
| effect: | |
| $ref: '../../common/SupportedEffects.yaml' | |
| parameters: | |
| $ref: './EffectsV2Parameters.yaml' | |
| status: | |
| type: object | |
| readOnly: true | |
| description: Read-only. Current effect status and active parameters. | |
| properties: | |
| effect: | |
| $ref: '../../common/SupportedEffects.yaml' | |
| effect_values: | |
| type: array | |
| description: Possible effect values supported by this light. | |
| items: | |
| $ref: '../../common/SupportedEffects.yaml' |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/light/schemas/EffectsV2.yaml` around lines 7 - 30, Add
machine-enforceable read/write semantics: mark the action object and its
writable properties as writeOnly and the status object and its readable
properties as readOnly. Specifically, set writeOnly: true for the action object
and for action.effect and action.parameters (but remove action.effect_values
entirely since capability metadata must not be writable), and set readOnly: true
for the status object and for status.effect and status.effect_values so
capability metadata remains read-only there. Ensure the $ref entries (effect,
effect_values, parameters) remain but with the appropriate writeOnly/readOnly
flags applied to the surrounding schema nodes (action, status,
action.parameters, status.effect_values).
- Add writeOnly: true to action object (request-only) - Add readOnly: true to status object and its properties (response-only) - Remove effect_values from action (capability metadata, not writable) - Add readOnly: true to mirek_valid (server-derived field)
thibauult
left a comment
There was a problem hiding this comment.
LGTM 👍🏻 Thanks for you first contribution!
Summary
The Hue bridge exposes an undocumented
effects_v2property on the Light resource that allows setting custom color, color temperature, and speed parameters on firmware-level effects (candle, fire, prism, sparkle, opal, glisten, underwater, cosmos, sunbeam, enchant).This is distinct from the existing
effectsproperty which only accepts an effect enum with no additional parameters.Payload format
Read response
When an effect is active,
effects_v2.statusreturns the resolved parameters:{ "effects_v2": { "action": { "effect_values": ["no_effect", "candle", "fire", "prism", ...] }, "status": { "effect": "fire", "effect_values": ["no_effect", "candle", "fire", "prism", ...], "parameters": { "color": { "xy": { "x": 0.35, "y": 0.15 } }, "color_temperature": { "mirek": 153, "mirek_valid": false }, "speed": 0.8016 } } } }Key behaviors observed
effects_v2is used with custom color, the effect animation runs in the specified color instead of its defaultspeeddefaults to 0.5; range is 0.0 (slowest) to 1.0 (fastest)color_temperature.mirek_validfield indicates whether the effect is operating in the CT color spacecolorproperty while an effect is active cancels the effect;effects_v2avoids this by bundling color with the effect activationChanges
EffectsV2.yaml— schema for theeffects_v2property withactionandstatusobjectsEffectsV2Parameters.yaml— shared schema for effect parameters (color, color_temperature, speed)LightGet.yaml— addedeffects_v2to the GET responseLightPut.yaml— addedeffects_v2to the PUT requestTesting
Verified against a Hue bridge with Gen 3+ color-capable lights (Gamut C). All 11 supported effects tested with custom color parameters.
Summary by CodeRabbit
New Features