hyperion-project
rgbw e131 support
Summary This PR primarily focuses on extending current implementation of e1.31 led device to not only support RGB data but also RGBW and hence partially covers #446 feature request for network based led device. Having RGBW implementation for e1.31 will allow in the future to extend wled led device to use not only DDP and RAW but also e1.31 and hence provide native RGBW support. During implementation I've also encountered a problem that some e1.31 (e.g. RGB WLED) doesn't use 512 DMX channels but less (510 = 170 leds*3channels) and hence current e1.31 led device implementation doesn't work correctly with WLED for >170 leds. To address this I've replaced the hardcoded value with a configurable option (see webui changes before/after).I've tested code with my WLED setup using both RGB (white_off) and RGBW (cold/neutral white).
I've started working on this with intension of vibe coding but in the end gave up and put a couple of manual commits. So some of the code has been AI generated, but was reviewed by me.
What kind of change does this PR introduce? (check at least one)
- [x] Bugfix
- [x] Feature
- [ ] Code style update
- [ ] Refactor
- [ ] Docs
- [ ] Build-related changes
- [ ] Other, please describe:
If changing the UI of web configuration, please provide the before/after screenshot:
before
after
Does this PR introduce a breaking change? (check one)
- [ ] Yes
- [x] No
If yes, please describe the impact and migration path for existing setups:
The PR fulfills these requirements:
- [ ] When resolving a specific issue, it's referenced in the PR's body (e.g.
Fixes: #xxx[,#xxx], where "xxx" is the issue number)
If adding a new feature, the PR's description includes:
- [x] A convincing reason for adding this feature
- [ ] Related documents have been updated (docs/docs/en)
- [ ] Related tests have been updated
PLEASE DON'T FORGET TO ADD YOUR CHANGES TO CHANGELOG.MD
- [x] Yes, CHANGELOG.md is also updated
To avoid wasting your time, it's best to open a feature request issue first and wait for approval before working on it.
Other information:
@lougovsk Thank you very much for your contribution and issuing a pull request. Apologies that a review took longer than normal, but too many things came into between.
I already pushed some small updates which are hopefully ok with you.
Please have a look at the additional comments and suggestion to improve the PR further.
Edit: I had some additional reading about the E1.31 protocol.
E1.31 transports lighting information in "Universes", which is a collection of up to 512 channels together. You can chose any universe number from 1-63999 and assign it to a block of channels in your sequencing software. While a Universe can contain up to 512 channels, it does not have to, and can be any number between 1-512 channels.
i.e. the number channels in one package defined for maximum number of LEDs, RGB = 170 LED, RGBW = 128 LED for one given universe, but must not exceed 512 channels.
-> There is not a need to define a new max channel parameter, but calculate the max channels by the number of LEDs and ensure it does not exceed 512 channels. Does that sound right?
We might add some validation to the UI added that the number of LEDs does not exceed the maximum number of channels which is LED# multiplied by 3 or 4 colors for the given universe?
Many thanks in advance.
@Lord-Grey thanks a lot for looking at my PR and addressing some of the issues.
Yes, you are completely right max channels per universe is a fixed number and hence can stay a constant (512), what we actually want to set is rather number of utilised channels as this is implementation dependent (e.g. WLED is using 510/512 but actually can be that 512 is always expected). Following you proposal I guess the most reasonable thing to do would be to convert DMX maximum channels supported config option to something like Number of leds per universe and then calculate channels based on the RGB/RGBW channels/led value. Does it sound feasible? And of course we need to be sure that Number leds * number channels doesn't exceed DMX_MAX.
Sounds right?
Besides I will also will address the buffer allocation optimisation. Sorry, for a delayed reply, will try to catch up on this comments next week.
@Lord-Grey I've been giving a thought to the topic with DMX_MAX. The logic to use 510/512 channels per universe IIUC is purely WLED decision. Other e1.31 server might be handling it differently. E.g. using 512 channels/universe even for RGB leds. Since, we are talking about generic e1.31 on Hyperion side, I think it would be improper to include logic that is WLED specific. My proposal I will rename current configuration item "DMX maximal number of channels" to "Usable DMX channels per universe". Setting them to 510/512 depending on RGBW/RGB in WLED case can be handled under WLED device. What do you think?
@lougovsk I do not get your point "using 512 channels/universe even for RGB leds."
RGB LEDs will be always result in a multiple of 3 channels which ends up in max 170 LED (510 channels - this is also what WLED just documents). What would you like doing with the two extra channels?
For RGBW there will be always 4 channels per LED with a maximum of 128 LEDs (512 channels). i.e. the type being either RGB or RGBW will define the max number of LEDs and max number of channels.
I do not see the need why a number of channels should be configured which is not a multiple of 3 or 4 channels?
Edit: If you would like to have more than 170 LEDs then Hyperion would need to support more than one universe (which is currently not). If there is then the need to have for example 20 LEDs for Universe 1 and 30 LEDs for Universe 2 and 10 LEDs per universe 3 then a number of LEDs per universe definition would make sense. ... but then your PR needs to look different too ... :)
@Lord-Grey what I mean is If one has let's say 200 RGB LEDs, it results in 600 channels. Obviously one will need at least 2 universes to send the data (however, maybe some e1.31 implementation will expect max 200 channels, so one will even need 3 universes, but this case aside). One has options how to do it. One can do 512 + 88 (max channels per universe=512) and yes you won't have complete RGB data for the 171st LED, but I don't think it is a problem. So from my perspective having 510/512 channels used for RGBW/RGB is a design decision WLED took and I don't think it is a general rule. In this context I think it is only reasonable to attach this logic to WLED device, but not to a generic e131 LedDevice.
Now talking about support of multiple universes. I can swear Hyperion supports it :). I use 229 RGBW LEDs without a problem. Of course having universes with different number of channels used in every is a different story.
PS: TBH I don't have a problem hardcoding RGBW/RGB logic (as per WLED) in to E131 LedDevice, I'm just wondering if it is the right thing to do.
@lougovsk Thanks for not giving up. Looks like I provided feedback on the wrong assumption that Hyperion only makes use of one universe. I now follow your thinking.
I fixed a syntax problem in the code and did another build. May I ask you testing the PR's build and provide feedback, if it works for you?
In case all good, I am happy to merge the PR.