¶ Purpose
The purpose of this project to create a Z-wave compatible device for driving RGBW stripes. The features that this device can provide, are influenced by Fibaro's RGBW controller and by Qubino's RGBW controller, and providing additional features that are not found on those controllers like:
- association groups for R, G, B and W channels, thus allowing multiple RGBW controllers to be driven together, as well as driving other devices like dimmers and relays on each of these channels
- on PCB temperature sensor to monitor the N-MOSFETs, allowing to reduce the brightness level simultaneously on active channels to allow for cooling
- auto shutdown if temperature reaches dangerous levels. An alarm will be sent out in this case to reflect this.
- the ability to save state on power loss, and restore last state by dimming up gradually according to the settings provided in the configuration parameters
- ability to run in ECO mode (that is with a maximal brightness set in configuration parameters), allowing for less power consumption when running on backup power sources.
- more animations sets
- ability to control RGB and W with mutual exclusivity. (when W is on, turn off RGB, when RGB is controlled W goes off)
- voltage level monitoring, additionally to current, power and energy monitoring
- ability to multiply power consumption by a factor, if many stripes are driven in series with the help of an RGBW extender
¶ Setup and planning
This project is going to be fulfilled in multiple milestones:
- POC: in this milestone, a proof of concept will be prepared to provide basic functionality of
- basic hardware on breadboard to control the RGBW stripe
- basic firmware to manage the dimming mechanism
- Architecture and Design: in this milestone, the basic architecture will be laid out as well as the initial set of requirements:
- document requirements
- document architecture
- enclosure requirement
- Revision 1: in this milestone, we test the functionality of the first revision
- first revision of PCB
- first firmware working on PCB
- test working requirements
- Final Revision: in this milestone, we iterate on:
- final requirements
- final PCB revision
- optimising the firmware and fixing final bugs
- OTA update mechanism
- test working requirements
- Endurance tests: in this test, the DUT will be tested over a longer period of time and brought to its limits to check its functionality
¶ Requirements
In this section the list of requirements and the list of test-cases are provided.
¶ Requirements list
The requirements listed below will be implemented in different phases, called milestones
| Requirement | Description | Milestone | Type | Status |
| REQ_RGBW_1 | The system is running in "Always On" mode | POC | Conf | Done: #8c2f2397 |
| REQ_RGBW_2 | System is assigned Z-wave Device ID 0x200 | POC | Conf | Done: #8c2f2397 |
| REQ_RGBW_3 | Setup PWM ports as following: - Pin13 -> W - Pin14 -> B - Pin15 -> G - Pin16 -> R |
POC | Conf | Done: #c2b0c05c |
| REQ_RGBW_4 | Setup 5 dimmable channels for: - Chan1: root channel for controlling all channels together - Chan2: R channel - Chan3: G channel - Chan4: B channel - Chan5: W channel |
POC | Conf | Done: #8c2f2397 |
| REQ_RGBW_5 | Provide conversion function from percent to PWM resolution | POC | Func | Done: #7adaa393 #93dd476f |
| REQ_RGBW_6 | Setup a color channel for managing the color output | POC | Conf | Done: #8c2f2397 |
| REQ_RGBW_7 | Add a parameter for choosing between RGB, RGBWW or RGBCW | Final Rev. | Par | Under consideration |
| REQ_RGBW_8 | Add a parameter to provide the ability to switch W channel instead of mixing RGB channels to provide WW or CW colors. Depends on REQ_RGBW_7 | Final Rev. | Par | Under consideration |
| REQ_RGBW_9 | Setup 5 control groups for: - Group1: reflecting Chan1 - Group2: reflecting R channel - Group3: reflecting G channel - Group4: reflecting B channel - Group5: reflecting W channel |
POC | Conf | Done: #8c2f2397 |
| REQ_RGBW_10 | Add a parameter to select the mode: - Color mode (default): R,G,B,W channels are controlled separately. Chan1 controls all channels together relative to their last saved value - Brightness mode: R,G,B,W channels are controlled together through any of the channels (chan1 to chan5). - Mutual mode: R,G,B are controlled separately from W channel. Both are mutually exclusive and cannot be turned on at the same time. Chan1 reflects the brightness level of either groups (RGB or W). Only applicable when REQ_RGBW_7 is set to either RGBCW or RGBWW. Reverts to Color mode otherwise. |
Rev.1 | Par | Done: #89123ff4 |
| REQ_RGBW_11 | Add a parameter for max and min dim values | Rev.1 | Par | Done: #e2a36d05 |
| REQ_RGBW_12 | Add a parameter for restoring last state on power outage | Rev.1 | Par | Done: #103df3f7 |
| REQ_RGBW_13 | Provide a smooth transition algorithm when changing brightness levels | POC | Lib | Done: #a2c725fb |
| REQ_RGBW_14 | Add a parameter for manipulating the smoothing of the brightness change algorithm | POC | Par | Done: #30d23339 |
| REQ_RGBW_15 | Add a parameter to react on Notification alarms: - Fire alarm - Smoke alarm - CO/CO2 alarm - Intrusion detection - Water Level Low/Pump Failure detection - AC mains detection - Flood detection - Door/Window Open Each half-byte can be assigned one of the following values: - Do nothing: 0 - Run animation: ( 1 to 13) |
Final Rev. | Par | Done: #edbaaf32 |
- - - - |
won't implement, merged with REQ_RGBW_15 | |||
| REQ_RGBW_17 | Add a parameter to select an animation: - Rainbow - Fireplace - Thunderstorm - Police |
Rev.1 | Par | Done:#b925c94d and #4f56865d |
| REQ_RGBW_18 | Add a parameter for power notifications: - Power consumption kWh - Power W - Current A - Voltage V |
Rev.1 | Par | Done:#8ccdf62a |
| REQ_RGBW_19 | Add a parameter for LED strip extension factor (base 100). Based on this parameter, W, A and kWh will be calculated as factor to the detected values by the HW. Ex. length of strip connected directly to RGBW module = 5m. Extension by another 8m. Factor is (8 + 5) / 5 = 2.6 x 100 = 260 | Rev.1 | Par | Done: #237f8926, #7518f0e2 |
| REQ_RGBW_20 | Add a parameter for how often power reports should be sent (in seconds) | Rev.1 | Par | Done:#8ccdf62a |
| REQ_RGBW_21 | Add a parameter for sending power reports on percentage change (0..100) | Rev.1 | Par | Done:#3bc11b22 |
| REQ_RGBW_22 | Setup Meter channels (kWh, W, A , V) | POC | Conf | Done: #8c2f2397 |
| REQ_RGBW_23 | Add a parameter to enable PMOS overtemperature detection | Final Rev. | Par | |
| REQ_RGBW_24 | Add a parameter to set the max brightness on PMOS overtemperature detection (0..100). Depends on REQ_RGBW_23 | Final Rev. | Par | |
| REQ_RGBW_25 | Voltage readout function | POC | Func | Done: #938d9ac1 |
| REQ_RGBW_26 | Provide XML to support device in OH2 | POC | Conf | Done: #07a39fff |
| REQ_RGBW_27 | Algorithm to compute power consumption over time | Rev.1 | Func | Done: #4a31922e |
| REQ_RGBW_28 | Add a parameter to interpret the reception of 0xFF switch multilevel value as: - Full on: equivalent to 0x63 - Last value (default): last value between 0x1 and 0x63 |
Rev.1 | Par | Done: #1a5a46a5 |
| REQ_RGBW_28 | Use INA219 chipset for voltage, current and power consumption | Rev.1 | Func | Done: #556bdebe |
| REQ_RGBW_29 | What to do when changing from Color to Mutual mode: turn both off keep RGB on keep W on |
Rev.1 | Par | Done: #89123ff4 |
| REQ_RGBW_30 | Delay on startup, in seconds, after which the lights should be restored to their persisted values. Depends on REQ_RGBW_12 | Rev.1 | Par | Done: #3cf02fb9 |
| REQ_RGBW_31 | RGBW channels should have a non-zero value stored on the heap. |
Rev.1 | Func | Done: #1a5a46a5 |
| REQ_RGBW_32 | Add a button (push style) through which it would be possible to: - toggle between multiple colors and white in mutual mode on short press - toggle between multiple colors, white and off in color mode on short press - start color change program "Rainbow" on long press in both mutual and color modes - |
Rev. 2 | Func | Done #bc41fc6f |
| REQ_RGBW_33 | Extend current animations by: - Aurora - Breath - Flash - and other deviations from Breath and Flash |
Rev. 2 | Func | Done: #ca46bf52 |
| REQ_RGBW_34 | Play an animation or blink something to indicate that OTA is currently on-going | Rev. 2 |
¶ Test-cases list
| Test Case | Description | Milestone | Type | Status |
| TEST_RGBW_1 | Using timers in Z-uno, test the dimmability of each channel separately | POC | Conf | Done: #93dd476f |
| TEST_RGBW_2 | Test single channel control for R,G,B and W channels | POC | Conf | Done z-uno-libraries@7a7709d7 , #6ca8a845 |
| TEST_RGBW_3 | Test root channel control | POC | Conf | Done #bc41fc6f |
| TEST_RGBW_4 | Test control group functionality with the help of a Vitrum switch | POC | Conf | Done #bc41fc6f |
| TEST_RGBW_5 | Adjust voltage from power supply and read voltage from debug window | POC | Conf | Done: #938d9ac1, #a2c725fb |
| TEST_RGBW_6 | Testing RGB factors to Main brightness in Mutual Mode | POC | Conf | Done #bc41fc6f |
| TEST_RGBW_7 | Testing RGB factors to Main brightness in Color Mode | POC | Conf | Done #bc41fc6f |
¶ Architecture and Design
¶ Wiring diagram
Circuitry block diagram
¶ Voltage / Current sensing circuitry
For the purpose of measuring voltage, current and power readings, we use the INA219 SoC from TI. The INA219 communicates with the Z-Uno over I2C on pins 9 and 10 (default pins for I2C on Z-Uno), but other pins can be configured as well for this purpose.
We use the following configuration to calibrate the chip:
Expected-CurrentMax = 12A
Range = 0-32V
ShuntADC = 0xF, 128 samples with a maximum sampling time of 68.10ms
BusADC = 0xF, 128 samples with a maximum sampling time of 68.10ms
Continuous sampling mode
Rshunt = 20 mΩ
Gain = 8, leading to a 320mV VShunt-Max
CurrentMax = VShunt-Max / Rshunt = 320mV / 20mΩ = 16A
PowerMaxShunt = VShunt-Max * CurrentMax = 320mV * 16A = 5.12 W
Since neither maximum current nor maximum voltage will not be reached:
Max PowerRealisticShunt = 26V * (VShunt-Max / 32V) * Expected-CurrentMax = 0.26V * 12A = 3.12 W
A resistor rated at 3W or 4W would be adequate
Rshunt = 10 mΩ
Gain = 4, leading to a 160mV VShunt-Max
CurrentMax = VShunt-Max / Rshunt = 160mV / 10mΩ = 16A
PowerMaxShunt = VShunt-Max * CurrentMax = 160mV * 16A = 2.56 W
Since neither maximum current nor maximum voltage will not be reached:
Max PowerRealisticShunt = 26V * (VShunt-Max / 32V ) * Expected-CurrentMax = 0.13V * 12A = 1.56 W
A resistor rated at 2W or higher would be adequate
https://www.mouser.de/ProductDetail/Panasonic/ERJ-B1CFR01U?qs=4HC4owHd7HsYU5aWnBaS8Q%3D%3D
* CF = 0.1 F, depends if the sampling is not leading to many deviated values (Page 11 of the datasheet)
¶ Z-Wave Parameters
Parameters supported for this device and their corresponding functionality
| Param. | Title | Description | Values | Size | Default |
| 64 | Fading algorithm | Set the fading algorithm to use when fading between two different brightness levels | 0 = Constant time 1 = Constant speed |
1 byte | 0 |
| 65 | Fading time | Depends on parameter 64. If constant time is selected, the value in this parameter reflects the time necessary to fade from Value A to value B. If constant speed is selected, then the value in this parameter reflects the time required to fade from full OFF to full ON (or vice versa) | (min = 0, max = 10000) | 2 bytes | 3000 |
| 66 | Operating mode | - Color mode (default): R,G,B,W channels are controlled separately. Chan1 controls all channels together relative to their last saved value - Brightness mode: R,G,B,W channels are controlled together through any of the channels (chan1 to chan5). - Mutual mode: R,G,B are controlled separately from W channel. Both are mutually exclusive and cannot be turned on at the same time. Chan1 reflects the brightness level of either groups (RGB or W). |
0 = Color mode 1 = Brightness mode 2 = Mutual mode |
1 byte | 0 |
| 67 | Dimming max | Maximum dimming value (must be greater than the minimum dimming value) | 1..99 | 1 byte | 99 |
| 68 | Dimming min | Minimum dimming value (must be smaller than the maximum dimming value) | 1..99 | 1 byte | 1 |
| 69 | State on start | Determine which state should be set on startup | 0 = always off 1= last state instant 2= last state fading |
1 byte | 1 |
| 70 | RGBW Strip type | Determine which strip type is being used. This parameter is only applicable when the mode is set to Color (param 66 = 0) | 0 = RGB 1 = RGBWW 2 = RGBCW |
1 byte | 1 |
| 71 | White color generation | Provide the ability to switch W channel instead of mixing RGB channels to provide WW or CW colors. Applicable only in Color mode and for RGBWW or RGBCW stripes | 0 = don't generate 1 = generate |
1 byte | 0 |
| 72 | Power report |
Determine which information should be included in the power report. If energy report is not enabled, the module will neither compute the accumulated energy nor store it in EEPROM. Furthermore, if energy has been disabled after it was enabled, the accumulated energy will be reset and an unsolicited report will be sent out. |
bit 0 = Current in A bit 1 = Voltage in V bit 2 = Power in W bit 3 = Energy in kWh bits 4..7 = don't care |
1 byte | 15 (0x0F) |
| 73 | Power report frequency | Determine how often the report should be sent out on cyclical basis (in s) | 0 = no cyclic report 30..65535 s |
2 bytes | 0 |
| 74 | Power report on change | Determine how the report should be sent on power values change (in %) Note that a lower value will increase the number of reports sent on Z-wave, but it is no guarantee that the chip will be able to handle it (better not to set it below 15%) |
0 = no report 1..100% |
1 byte | 25% |
| 75 | Handling of 0xFF switch multilevel value | Determine how the system interprets the reception of the 0xFF switch multilevel command | 0 = Restore last value 1 = Full On |
1 byte | 0 |
| 76 | Set animation | Select an animation: - Rainbow - Fireplace - Thunderstorm - Police - Aurora - Breath - Breath red - Breath green - Breath blue - Flash - Flash red - Flash amber - Flash green |
0 = normal operation 1 = Rainbow 2 = Fireplace 3 = Thunderstorm 4 = Police 5 = Aurora 6 = Breath 7 = Breath red 8 = Breath green 9 = Breath blue 10 = Flash 11 = Flash red 12 = Flash amber 13 = Flash green |
1 byte | 0 |
| 77 | On mode change | What to do when changing from Color to Mutual mode | 0 = turn both off 1 = keep RGB 2 = keep W |
1 byte | 0 |
| 78 | Start delay | Delay on startup, in seconds, after which the lights should be restored to their persisted values. Depends on param 69 | (min = 0, max = 600 (10mn)) | 2 bytes | 0 |
| 79 | Strip extension factor | A factor that is used to allow to report A,W and kWh if the attached strip is extended by other strip using RGBW amplifiers. Based on this, W, A and kWh will be calculated as factor to the detected values by the HW. Ex. length of strip connected directly to RGBW module = 5m. Extension by another 8m. Factor is (8 + 5) / 5 = 2.6 x 100 = 260 | min = 100 (factor 1), max = 65536 (factor = 655,36) | 2 bytes | 100 |
| 80 | Animations on high priority notifications | Add a parameter to react on Notification alarms: - Fire alarm (h-byte 1) - Smoke alarm (h-byte 0) - CO/CO2 alarm (l-byte 1) - Intrusion detection (l-byte 0) Each half-byte can be assigned one of the following values: - Do nothing: 0 - Run animation: ( 1 to 13) |
1..0xFFFF | 2 bytes | 0x0000 |
| 81 | Animations on low priority notifications | Add a parameter to react on Notification alarms: - Flood detection (h-byte 1) - Door/Window Open (l-byte 1) - Water Level Low/Pump Failure detection (h-byte 0) - AC mains detection (l-byte 0) Each half-byte can be assigned one of the following values: - Do nothing: 0 - Run animation: ( 1 to 13) |
1..0xFFFF | 2 bytes | 0x0000 |
¶ Power and Energy reports flow chart
¶ Operation modes and brightness calculation
¶ Different operation modes:
- Color mode: in this mode the RGB and W channels are controlled separately, without the one excluding the other. The user will be able to set the RGB to any desired color and at the same time control the W channel. The RGB channels are controlled simultaneously through the Color Control CC or individually through the Switch Multilevel CC, and the W channel through the Switch Multilevel individually.
- Mutual mode: similar to Color mode but RGB and W are mutually exclusive. This means that the controller will turn off the W channel if any of the RGB channels is set, or it will turn off RGB channels if W is set.
- Brightness Mode: in this mode, all channels are controlled together.
¶ Brightness value of the master channel:
- Color mode: the brightness value of the Master channel is calculated based on the HSB value of the color being set. If the RGB are off, the master brightness is set to 0, even if W channel has been set to some value. Controlling the master brightness through Switch Multilevel CC will cause the RGB channels to be modified by the same factor of change of the master brightness value.
- Mutual mode: similarly to the operation in color mode, the brightness mode value will also reflect the value of the W channel if W channel is set instead of RGB. Controlling the master brightness value will affect RGB similarly to color mode. When W is set, the master brightness value will affect the W channel value 1-to-1.
- Brightness mode: since all channels are controlled together, the master brightness value is equivalent to the value of all RGBW channels. Any change in one of the RGBW channels will affect the other channels as well as the master channel. Any change to the master channel will do the same.
¶ Switching between the different operation modes:
- switching from color mode to mutual mode: will cause either the W channel or the RGB channels to be kept on, or both set to off, based on the parameter value set in parameter 77.
- switching from mutual mode to color mode: no change. Just adjust the master brightness value based on what's currently active
- switching from color/mutual modes to brightness mode: set all channels to the highest value of the currently active RGBW channels.
- switching from brightness mode to color mode: set all to off
- switching from brightness mode to mutual mode: only keep W channel on with current active value
¶ EEPROM Layout - Zuno 1st Gen
| Variable | Type | Description | Base Address | Offset | End Address | Size (in bytes) |
Factory value |
| energyWs | dword | Store the accumulated energy in Ws (WattSeconds) | 0x0000 | 0 | 4 | 0 | |
| valueBrightnessRed | byte | Red component value | 0x0000 | 4 | 1 | 0 | |
| valueBrightnessGreen | byte | Green component value | 0x0000 | 5 | 1 | 0 | |
| valueBrightnessBlue | byte | Blue component value | 0x0000 | 6 | 1 | 0 | |
| valueBrightnessWhite | byte | White component value | 0x0000 | 7 | 1 | 0 | |
| valueBrightnessAll | byte | Master brightness value | 0x0000 | 8 | 1 | 0 | |
| lastModeMutualWhite | byte | Last mode used in mutual mode | 0x0000 | 9 | 1 | 0 | |
| FadeLedGammaTable | word | The Gamma Table used | 0x0000 | 0x0032 | 0x00FA | 200 | ... |
| RainbowAnimation | byte | Rainbow animation data | 0x0000 | 0x0100 | 0x0357 | 599 | ... |
| FireplaceAnimation | byte | Fireplace animation data | 0x0000 | 0x0360 | 0x048E | 302 | ... |
| ThunderstormAnimation | byte | Thunderstorm animation data | 0x0000 | 0x05C0 | 0x0679 | 185 | ... |
| PoliceAnimation | byte | Police animation data | 0x0000 | 0x0820 | 0x08D9 | 185 | ... |
| AuroraAnimation | byte | Aurora animation data | 0x0000 | 0x0A80 | 0x0C38 | 440 | ... |
| BreathAnimation | byte | Breath animation data | 0x0000 | 0x0CE0 | 0x0DF3 | 275 | ... |
| BreathRedAnimation | byte | Breath Red animation data | 0x0000 | 0x0F40 | 0x1053 | 275 | ... |
| BreathGreenAnimation | byte | Breath Green animation data | 0x0000 | 0x11A0 | 0x12B3 | 275 | ... |
| BreathBlueAnimation | byte | Breath Blue animation data | 0x0000 | 0x1400 | 0x1513 | 275 | ... |
| FlashAnimation | byte | Flash animation data | 0x0000 | 0x1660 | 0x16BF | 95 | ... |
| FlashRedAnimation | byte | Flash Red animation data | 0x0000 | 0x18C0 | 0x18D1 | 17 | ... |
| FlashAmberAnimation | byte | Flash Amber animation data | 0x0000 | 0x1B20 | 0x1B31 | 17 | ... |
| FlashGreenAnimation | byte | Flash Green animation data | 0x0000 | 0x1D80 | 0x1D91 | 17 | ... |
| nextAnim | byte | next anim data | 0x0000 | 0x1FE0 | ... | ||
| 0x1FFF |
¶ EEPROM Layout - Zuno 2nd Gen
| Variable | Type | Description | Base Address | Offset | End Address | Size (in bytes) |
Factory value |
| energyWs | dword | Store the accumulated energy in Ws (WattSeconds) | 0x0000 | 0 | 4 | 0 | |
| valueBrightnessRed | byte | Red component value | 0x0000 | 4 | 1 | 0 | |
| valueBrightnessGreen | byte | Green component value | 0x0000 | 5 | 1 | 0 | |
| valueBrightnessBlue | byte | Blue component value | 0x0000 | 6 | 1 | 0 | |
| valueBrightnessWhite | byte | White component value | 0x0000 | 7 | 1 | 0 | |
| valueBrightnessAll | byte | Master brightness value | 0x0000 | 8 | 1 | 0 | |
| lastModeMutualWhite | byte | Last mode used in mutual mode | 0x0000 | 9 | 1 | 0 | |
| FadeLedGammaTable | word | The Gamma Table used | 0x0000 | 0xA | 0x00D2 | 200 | ... |
| RainbowAnimation | byte | Rainbow animation data | 0x0000 | 0xD3 | 0x032A | 599 | ... |
| FireplaceAnimation | byte | Fireplace animation data | 0x0000 | 0x032B | 0x0459 | 302 | ... |
| ThunderstormAnimation | byte | Thunderstorm animation data | 0x0000 | 0x045A | 0x0513 | 185 | ... |
| PoliceAnimation | byte | Police animation data | 0x0000 | 0x0514 | 0x05CD | 185 | ... |
| AuroraAnimation | byte | Aurora animation data | 0x0000 | 0x05CE | 0x0786 | 440 | ... |
| BreathAnimation | byte | Breath animation data | 0x0000 | 0x0787 | 0x089A | 275 | ... |
| BreathRedAnimation | byte | Breath Red animation data | 0x0000 | 0x089B | 0x09AE | 275 | ... |
| BreathGreenAnimation | byte | Breath Green animation data | 0x0000 | 0x09AF | 0x0AC2 | 275 | ... |
| BreathBlueAnimation | byte | Breath Blue animation data | 0x0000 | 0x0AC3 | 0x0BD6 | 275 | ... |
| FlashAnimation | byte | Flash animation data | 0x0000 | 0x0BD7 | 0x0C36 | 95 | ... |
| FlashRedAnimation | byte | Flash Red animation data | 0x0000 | 0x0C37 | 0x0C48 | 17 | ... |
| FlashAmberAnimation | byte | Flash Amber animation data | 0x0000 | 0x0C49 | 0x0C5A | 17 | ... |
| FlashGreenAnimation | byte | Flash Green animation data | 0x0000 | 0x0C5B | 0x0C6C | 17 | ... |
| nextAnim | byte | next anim data | 0x0000 | 0x0C6D | ... | ||
| 0x0E00 |