How do you properly use the functions when using a library? aka use the library

Hey

So i was looking to code some addressable rgb effects for a project of mine, and came accross this library WS2812FX, pretty cool. But while looking at the examples, i realized something.

I have no idea how people know how to properly use all the functions in a library.

Basically, A library has many useful functions, but a VERY few of them are demonstrated in the example section, how do people know the functions that are not shown?
say for example, i want to switch a variable that turns the leds off, but no example does that, the keywords.txt file has just the names ( i guess ) but how do i use them? do i need to put them inside a function container like WS2812FX(stop) or do i just type in stop?

how does this thing work??

You have identified a weakness in the library documentation. It's free open source, so you are at liberty to study the code, and volunteer to improve the documentation. Nobody was paid to do it, and you didn't pay for it, so there isn't anything else you can do.

aarg:
You have identified a weakness in the library documentation. It's free open source, so you are at liberty to study the code, and volunteer to improve the documentation. Nobody was paid to do it, and you didn't pay for it, so there isn't anything else you can do.

What i meant to ask is, there is definitely no need for someone to document every possible aspect of a code with detailed example, heck not even feasible i would guess.

what i want to know is, how do i interpret the keywords.txt file?
i see this is fairly common, but i have no idea what the labels mean. no one actually complains about this.. so i thought im the one whos in the wrong.

kaseftamjid:
what i want to know is, how do i interpret the keywords.txt file?

If you want to learn about the library's functions, read its source code. Forget the keywords.txt file.

Generally, developers prefer writing code to writing documentation. Coding is fun, writing docs is just work, so it should be no surprise that the manuals for a library provided by a volunteer are incomplete or out of date.

If challenged on it, the programmer concerned would likely mutter that the code IS the documentation. That's slightly unhelpful, but it's true - everything you need is there, examples are just a bonus. Usually, library code isn't especially long so it's not much effort.

As for keywords.txt, just ignore it. All it does is tell the IDE to highlight those words in the text, but since the IDE uses the sum of all such files, it's not especially useful.

If you’re lucky, and the author(s) has been kind, you should only really need to look at the .h file, possibly in conjunction with one or more of the example sketches.

kaseftamjid:
What i meant to ask is, there is definitely no need for someone to document every possible aspect of a code with detailed example, heck not even feasible i would guess.

what i want to know is, how do i interpret the keywords.txt file?
i see this is fairly common, but i have no idea what the labels mean. no one actually complains about this.. so i thought im the one whos in the wrong.

There may be no need to provide a detailed example of every aspect. However, every function of an API should be documented. Tools like Doxygen exist, that when used correctly, can automatically generate a function summary document from annotated source code. It's common because people aren't paid to write the libraries, and often are not professionals who are used to producing documentation as a strict requirement of their job. Of course, it's feasible.

In this case, the main complexity is just a list of effects. An example is given to show how to use an effect, so there is not much difficulty in looking up the effect to see what it does, or simply trying it out. A description of each effect might be somewhat non-technical anyway, like "runs pink dots in one direction and yellow dots in the other on a blue background" or something like that. Really, how accurate or complete does that description have to be, in order to use it?

Complaining is silly, because as I said, it's free open source, why should anyone make changes to code just to make you happy when they aren't receiving any money for it? It's provided as-is, if you want something better, move on or fix it yourself.

aarg:
There may be no need to provide a detailed example of every aspect. However, every function of an API should be documented. Tools like Doxygen exist, that when used correctly, can automatically generate a function summary document from annotated source code. It's common because people aren't paid to write the libraries, and often are not professionals who are used to producing documentation as a strict requirement of their job. Of course, it's feasible.

In this case, the main complexity is just a list of effects. An example is given to show how to use an effect, so there is not much difficulty in looking up the effect to see what it does, or simply trying it out. A description of each effect might be somewhat non-technical anyway, like "runs pink dots in one direction and yellow dots in the other on a blue background" or something like that. Really, how accurate or complete does that description have to be, in order to use it?

Complaining is silly, because as I said, it's free open source, why should anyone make changes to code just to make you happy when they aren't receiving any money for it? It's provided as-is, if you want something better, move on or fix it yourself.

I.. I wasnt complaining.. anyhow, so what now is I actually have to go through the .h files. This post arose with my doubt that the keywords.txt was meant for the user, not the IDE

Im pretty okay with the code, but what i have trouble with is the format, is there a standard somewhere that dictates how i should type in commands? or is it also strictly dictated by the authors code

Typically I look at the .h file because in reality that IS the interface your code is going to use. Its the closest thing to a "defined as correct" documentation. In your case here though.. Mighty long .h file!

Link for the .h file.

Many times if I find that the .h does not make sense, I figure it won't help me much and pass on it.

-jim lee

After FINALLY figuring things out after like 3 hours… the code is too big

#include <WS2812FX.h>
#include <ButtonEvents.h> 


#define LED_COUNT 12
#define LED_PIN 1


const byte buttonPin = 2; // our button will be connected to pin 7

WS2812FX ws2812fx = WS2812FX(LED_COUNT, LED_PIN, NEO_GRB + NEO_KHZ800);

ButtonEvents myButton; // create an instance of the ButtonEvents class to attach to our button

int modeNum = 0;
byte bright = 125;
void setup() {
  pinMode(buttonPin, INPUT_PULLUP);  

  // attach our ButtonEvents instance to the button pin
  myButton.attach(buttonPin);
  // The hold duration can be increased to require longer holds before an event is triggered, or reduced to
  // have hold events trigger more quickly.
  myButton.holdTime(1000); // require button to be held for 1000ms before triggering a hold event


  ws2812fx.init();
  ws2812fx.setBrightness(bright);
  ws2812fx.setSpeed(1000);
  ws2812fx.setColor(0x007BFF);
  ws2812fx.setMode(FX_MODE_STATIC);
  ws2812fx.start();
}


void loop() {

  // The update() method returns true if an event or state change occurred.  It serves as a passthru
  // to the Bounce2 library update() function as well, so it will stll return true if a press/release
  // is detected but has not triggered a tap/double-tap/hold event
  if (myButton.update() == true) {

    // The event() method returns tap, doubleTap, hold or none depending on which event was detected
    // the last time the update() method was called.  The following code accomplishes the same thing
    // we did in the 'Basic' example, but I personally prefer this arrangement.
    switch(myButton.event()) {
      
      // things to do if the button was tapped (single tap)
      case (tap) : 
      {
       if(modeNum < 3){++modeNum;}
       else{modeNum = 0;}           
        break;
      }

      // things to do if the button was held
      case (hold) : 
      {
  bright = bright - 5; 
  ws2812fx.setBrightness(bright);
  ws2812fx.setColor(0x007BFF);
  ws2812fx.setMode(FX_MODE_STATIC);
        
        break;
      }
      
    }
  }
  switch(modeNum)
  {

  case 0 :
  ws2812fx.stop();
  break;
  
  case 1 :
  ws2812fx.setMode(FX_MODE_SCAN);
  break;

  case 2 :
  ws2812fx.setMode(FX_MODE_RUNNING_RANDOM);
  break;
  }
}

this was intended for an attiny 45, but damn its A HUNDRED AND SEVENTY-SIX BYTES too big -_-

cant seem to make things any simpler, removing any effect has minute effect on code size.
any ideas anyone?

See if you can do without the button library.

It would never work anyway, because there is no ' ws2812fx.service(); ' in loop().

wildbill:
See if you can do without the button library.

I was having too much trouble to reliably get a hold function, thought a library should be the most efficient solution

aarg:
It would never work anyway, because there is no ' ws2812fx.service(); ' in loop().

fixed

I realized my mistake… the proper sketch is waaay to big for the attiny…

Is there no way to do this? neopixel, fastled both take up lots of space just with even 1 effect and i dont have space left to code in the hold to change brightness function.

What im trying to do is, light 12 addressable leds with as many effects as memory allows also while controling the modes with short press of button and changing brightness by holding the button.

Does anyone know of any shortened-simple library i can use for the effects?

Bitmaps, timers and an SD card.

What you have is a 12 pixel screen. Just do bitmaps or .bmp files that are 12 pix wide and N pix tall. Use your PC/Mac do develop the .bmp files. Read out one line at a time and spat them out on your LEDs from an SD card. You could do thousands.

-jim lee

jimLee:
Bitmaps, timers and an SD card.

What you have is a 12 pixel screen. Just do bitmaps or .bmp files that are 12 pix wide and N pix tall. Use your PC/Mac do develop the .bmp files. Read out one line at a time and spat them out on your LEDs from an SD card. You could do thousands.

-jim lee

Thats not a bad idea… but i doubt i need to go that far, so far i like the pixel scanning effect and rainbow effect. When i said as many as the memory allows, i meant the 4Kb limit. plus it would be lowkey waste if i had to use a usb to serial ic, or use vusb when i have the possibility of getting by with just a switch

kaseftamjid:
Thats not a bad idea.. but i doubt i need to go that far, so far i like the pixel scanning effect and rainbow effect. When i said as many as the memory allows, i meant the 4Kb limit. plus it would be lowkey waste if i had to use a usb to serial ic, or use vusb when i have the possibility of getting by with just a switch

It doesn't fit in an Arduino. At least not with my level of sloppy coding. I don't have enough RAM to run the SD card, parse the .bmp file AND run the neoPixels.

I still think its a good idea though. I'll see if I can get it running on a Teensy.

-jim lee

This topic was automatically closed 120 days after the last reply. New replies are no longer allowed.