ws2812 effects library #2215

skycoders · 2018-01-02T09:24:25Z

Contributes to idea in #1352.

This PR is for the dev branch rather than for master.
This PR is compliant with the other contributing guidelines as well (if not, please describe why).
I have thoroughly tested my contribution.
The code changes are reflected in the documentation at docs/en/*.

This PR adds two new modules: A color library, extracted to an own module because it is helpful for other RGB LEDs as well (e.g. PWM) and a ws2812 effects module.

The color utils provide conversion between RGB and HSV color spaces, and a convenience function to get color wheel values based on an angle.

The ws2812 effects module provides some nice effects for ws2812 LED strips. This is an initial set, and the module itself is probably not perfect, but it does some nice stuff which might be useful for others as well. The effects have been natively implemented because LUA implementations are much too slow. In order to test the module, it must be enabled in the user_modules configuration before building the firmware.

devsaurus · 2018-01-02T13:21:24Z

app/include/user_modules.h

@@ -28,7 +28,8 @@
 //#define LUA_USE_MODULES_BME280
 //#define LUA_USE_MODULES_BME680
 //#define LUA_USE_MODULES_COAP
-//#define LUA_USE_MODULES_CRON
+//#define LUA_USE_MODULES_COLOR_UTILS
+#define LUA_USE_MODULES_CRON


Please disable module again.

devsaurus · 2018-01-02T13:21:38Z

app/include/user_modules.h

@@ -48,7 +49,7 @@
 #define LUA_USE_MODULES_MQTT
 #define LUA_USE_MODULES_NET
 #define LUA_USE_MODULES_NODE
-#define LUA_USE_MODULES_OW
+//#define LUA_USE_MODULES_OW


Please enable module again.

devsaurus · 2018-01-02T13:22:11Z

app/include/user_modules.h

@@ -68,7 +69,7 @@
 //#define LUA_USE_MODULES_SWITEC
 // #define LUA_USE_MODULES_TCS34725
 //#define LUA_USE_MODULES_TM1829
-#define LUA_USE_MODULES_TLS
+//#define LUA_USE_MODULES_TLS


Please enable module again.

devsaurus · 2018-01-02T13:25:16Z

docs/en/modules/color-utils.md

+The color_utils module provides some basic color transformations useful for color LEDs. It is used by the WS2812_EFFECTS module.
+
+
+## color\_utils.hsv2grb()


What's the purpose of the backslash here and below?

my one editor had an issue without the backslash, but Atom doesn't - I will remove them all.

devsaurus · 2018-01-02T13:29:42Z

app/modules/ws2812_effects.c

+  state->speed = SPEED_DEFAULT;
+  state->mode_delay = DELAY_DEFAULT;
+  state->brightness = BRIGHTNESS_DEFAULT;
+  state->buffer = buffer;


You'll need to luaL_ref() the buffer object to prevent it from being garbage collected after this function exits.

devsaurus · 2018-01-02T13:34:42Z

app/modules/ws2812_effects.c

+static int ws2812_effects_set_mode(lua_State* L) {
+
+  luaL_argcheck(L, state != NULL, 1, LIBRARY_NOT_INITIALIZED_ERROR_MSG);
+  const int mode = luaL_checkinteger(L, 1);


Quoting luaL_checkoption():

The usual convention in Lua libraries is to use strings instead of numbers to select options.

I know that our firmware is not 100% consistent here, but please think about turning the mode argument into string for the above reason. See file, gpio and other modules for how to use it.

I am fine with adjusting this, I just "cloned" the way it is done in the ws2812 module itself (for fading and single/dual mode). This was the closest thing to look at

devsaurus · 2018-01-02T13:35:49Z

docs/en/modules/ws2812-effects.md

+- `effect_param` is an optional effect parameter. See the effect modes for further explanations. It can be an integer value or a string.
+
+#### Returns
+`nil`


Please add an example that shows how to use the functions.

devsaurus · 2018-01-02T13:45:14Z

First of all, I like these additions to enhance the RGB capabilities of the firmware.

My main concern is that we're missing a more generic model. So far there's the buffer class being part of the ws2812 module with some basic functions and effects. Now there's another module adding effects to the buffer objects. If this is ever extended for other LED modules it probably will need refactoring on the API level.

On a more specific level: The effects are only applicable to a single stripe at the moment. Adding support for dual mode and up to 8 stripes for the ESP32 needs a different approach. Probably an own effects class where you derive objects for each buffer/stripe from. What are your thoughts here?

skycoders · 2018-01-02T13:55:34Z

I share your thoughts, however I thought, if I don't try to bring this into the firmware somewhen, I will never do so - that is why I initiated the pull request.

Right now, I don't think that the "old" PWM based strips will really need something like this, as they are just too limited. However, I also stumbled upon SK6812, which is similar to APA102, but not identical. Also, having the current buffer objects with RGB(W) values is suboptimal, as they do not allow lossless brightness adjustments. My final hope is to have a buffer object in the HSV value range and perform effects on this buffer, and then have different writers for each LED strip type, and individual strip connected to the chip.

Unfortunately, I am no LUA module pro, and also miss the time to get all this done fast enough. Maybe there is someone who wants to join? I'd also love to look at the ESP32. I have one, but so far didn't manage to build the firmware.

So, before spending too much time in trying to fix the individual comments, it maybe makes sense to get a common understanding of how and where we should go from here. Thanks!

pjsg · 2018-01-03T02:18:37Z

app/modules/ws2812.c

    }

-    val >>= 8;


I think that this was pulled out of the loop to enable smooth fading. Why move it back?

Thanks. That was probably an accident, I did not intend to change this.

marcelstoer · 2018-01-17T06:12:16Z

app/include/user_modules.h

@@ -29,7 +29,7 @@
 //#define LUA_USE_MODULES_BME680
 //#define LUA_USE_MODULES_COAP
 //#define LUA_USE_MODULES_COLOR_UTILS
-#define LUA_USE_MODULES_CRON
+//define LUA_USE_MODULES_CRON


Don't fiddle with the default modules!

marcelstoer · 2018-01-17T06:12:29Z

app/include/user_modules.h

@@ -49,7 +49,7 @@
 #define LUA_USE_MODULES_MQTT
 #define LUA_USE_MODULES_NET
 #define LUA_USE_MODULES_NODE
-//#define LUA_USE_MODULES_OW
+#define LUA_USE_MODULES_OW


marcelstoer · 2018-01-17T06:12:37Z

app/include/user_modules.h

@@ -69,7 +69,7 @@
 //#define LUA_USE_MODULES_SWITEC
 // #define LUA_USE_MODULES_TCS34725
 //#define LUA_USE_MODULES_TM1829
-//#define LUA_USE_MODULES_TLS
+#define LUA_USE_MODULES_TLS


skycoders · 2018-01-20T20:07:37Z

I copied the current DEV branch user_modules.h file and just added the two modules of this PR. This should be OK now hopefully. Never intended to change them.

devsaurus

Ok from my side and no technical concerns. I recommend to merge this if no further objections arise.

* ws2812 effects and color utils modules added * Added documentation for new modules to mkdocs.yml * changed mode option to string, documentation, default modules fixed * updated user_modules.h

Konrad Hübner added 2 commits January 2, 2018 09:53

ws2812 effects and color utils modules added

c1be841

Added documentation for new modules to mkdocs.yml

3e014e7

devsaurus reviewed Jan 2, 2018

View reviewed changes

pjsg reviewed Jan 3, 2018

View reviewed changes

changed mode option to string, documentation, default modules fixed

83891b1

marcelstoer added the new module label Jan 5, 2018

marcelstoer requested changes Jan 17, 2018

View reviewed changes

Konrad Hübner added 2 commits January 20, 2018 20:58

Merge remote-tracking branch 'upstream/dev' into ws2812-effects

bd12113

updated user_modules.h

48df48c

marcelstoer approved these changes Jan 20, 2018

View reviewed changes

devsaurus approved these changes Jan 21, 2018

View reviewed changes

marcelstoer added this to the 2.2 milestone Jan 21, 2018

devsaurus merged commit ed56d94 into nodemcu:dev Jan 23, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ws2812 effects library #2215

ws2812 effects library #2215

skycoders commented Jan 2, 2018 •

edited by marcelstoer

Loading

devsaurus Jan 2, 2018

devsaurus Jan 2, 2018

devsaurus Jan 2, 2018

devsaurus Jan 2, 2018

skycoders Jan 2, 2018

devsaurus Jan 2, 2018 •

edited

Loading

devsaurus Jan 2, 2018

skycoders Jan 2, 2018

devsaurus Jan 2, 2018

devsaurus commented Jan 2, 2018

skycoders commented Jan 2, 2018

pjsg Jan 3, 2018

skycoders Jan 3, 2018

marcelstoer Jan 17, 2018

marcelstoer Jan 17, 2018

marcelstoer Jan 17, 2018

skycoders commented Jan 20, 2018

devsaurus left a comment

		The color_utils module provides some basic color transformations useful for color LEDs. It is used by the WS2812_EFFECTS module.


		## color\_utils.hsv2grb()

ws2812 effects library #2215

ws2812 effects library #2215

Conversation

skycoders commented Jan 2, 2018 • edited by marcelstoer Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

devsaurus Jan 2, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

devsaurus commented Jan 2, 2018

skycoders commented Jan 2, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

skycoders commented Jan 20, 2018

devsaurus left a comment

Choose a reason for hiding this comment

skycoders commented Jan 2, 2018 •

edited by marcelstoer

Loading

devsaurus Jan 2, 2018 •

edited

Loading