Module: j5e/rgb

Description

A module for controlling RGB LED's using PWM on 3 pins, one for each color.

A light-emitting diode (LED) is a semiconductor light source that emits light when current flows through it. Electrons in the semiconductor recombine with electron holes, releasing energy in the form of photons. The color of the light is determined by the energy required for electrons to cross the band gap of the semiconductor. White light is obtained by using multiple semiconductors or a layer of light-emitting phosphor on the semiconductor device.Read more on Wikipedia

Pulse-width modulation (PWM), or pulse-duration modulation (PDM), is a method of reducing the average power delivered by an electrical signal, by effectively chopping it up into discrete parts. The average value of voltage fed to the load is controlled by turning the switch between supply and load on and off at a fast rate. The longer the switch is on compared to the off periods, the higher the total power supplied to the load. Along with maximum power point tracking (MPPT), it is one of the primary methods of reducing the output of solar panels to that which can be utilized by a battery. PWM is particularly suited for running inertial loads such as motors, which are not as easily affected by this discrete switching, because their inertia causes them to react slowly. The PWM switching frequency has to be high enough not to affect the load, which is to say that the resultant waveform perceived by the load must be as smooth as possible.Read more on Wikipedia

The RGB color model is an additive color model in which the red, green, and blue primary colors of light are added together in various ways to reproduce a broad array of colors. The name of the model comes from the initials of the three additive primary colors, red, green, and blue.Read more on Wikipedia

Requires

Class: RGB

The RGB class allows for control of RGB LED's

Constructor

new RGB(io, io.red, io.green, io.blue)

Parameters

Name
Type
Description
io
(required)
Array.<number>, Array.<string>, Array.<object>, or object

Description:
 An array of pin identifiers or IO Options in RGB order, or an RGB IO options object (See instantiation)

io.red
object

Description:
 Pin identifier or IO Options for the red channel

io.green
object

Description:
 Pin identifier or IO Options for the green channel

io.blue
object

Description:
 Pin identifier or IO Options for the blue channel

Examples

// Using an array of pin numbers
import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.color("#663399");
rgb.blink();
// Using an array of pin identifiers
import RGB from "j5e/rgb";

const rgb = await new RGB(["A1", "A3", "A4"]);
rgb.color("#663399");
rgb.blink();
// Using an array of option objects
import RGB from "j5e/rgb";
import PCA9685 from "PCA9685Expander"

const rgb = await new RGB([
  { pin: 0, io: PCA9685 },
  { pin: 1, io: PCA9685 },
  { pin: 2, io: PCA9685 }
]);
rgb.color("#663399");
rgb.blink();
// Using an RGB options object
import RGB from "j5e/rgb";
import PCA9685 from "PCA9685Expander"

const rgb = await new RGB({
  red: 0,
  green: {
    io: PCA9685
    pin: 1
  },
  blue: 3
});
rgb.color("#663399");
rgb.blink();

Properties

Name
Type
Description
isOn
(read only)
boolean
If the RGB is on
isRunning
(read only)
boolean
If the RGB is pulsing, blinking or running an animation
isAnode
(read only)
boolean
If the RGB is wired for common anode
values
(read only)
Array.<number>
The current RGB values

Methods

RGB.configure

Configure an RGB LED

rgb.configure(options);

Returns: The instance on which the method was called

Parameters

Name
Type
Description
options
(required)
object

Description:
 Device configuration options

options.sink
number

Description:
 True if an element is common anode

Example

import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.color("#663399");
rgb.blink();

RGB.color

Control an RGB LED's color value. Accepts Hexadecimal strings, an array of color values, and RGB object or a separate argument for each color.

rgb.color(red, green, blue);

Returns:

Parameters

Name
Type
Description
red
(required)
String, Array, Object, or Number

Description:
 Hexadecimal color string, Array of color values, RGB object {red, green, blue}, or the value of the red channel [0, 1]

green
Number

Description:
 The value of the green channel [0, 1]

blue
Number

Description:
 The value of the blue channel [0, 1]

Example

// Use a hex value to make it purple
import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.color("#663399");

Example

// Use an RGB String to make it purple
import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.color("rgb(0.4, 0.2, 0.6)");

Example

// Use an RGBA String to make it darker purple
import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.color("rgba(0.4, 0.2, 0.6, 50%)");

Example

// Use an array to make it purple
import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.color([0.4, 0.2, 0.6]);

Example

// Use an object to make it purple
import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.color({
  red: 0.4,
  green: 0.2,
  blue: 0.6
});

Example

// Use seperate Red, Green, and Blue arguments to make it purple
import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.color(0.4, 0.2, 0.6);

RGB.on

Turn an RGB LED on with whatever the current color value is

rgb.on();

Returns:

Example

// Make it on
import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.on(); // Default color is white

RGB.off

Turn an RGB LED off

rgb.off();

Returns:

Example

// Make it purple for five seconds
import RGB from "j5e/rgb";
import {timer} from "j5e/fn";

const rgb = await new RGB([13, 12, 14]);
rgb.color("#663399");

time.setTimeout(function() {
  rgb.off();
}, 5000);

RGB.toggle

Toggle the on/off state of an RGB LED

rgb.toggle();

Returns:

Example

// Make it purple for five seconds
import RGB from "j5e/rgb";
import {timer} from "j5e/fn";

const rgb = await new RGB([13, 12, 14]);
rgb.toggle(); // Turns RGB LED on

time.setTimeout(function() {
  rgb.toggle(); // Turns it off
}, 5000);

Blink an RGB LED on a fixed interval

rgb.blink(duration, callback);

Returns:

Parameters

Name
Type
Description
duration
(required)
Number

Description:
 Time in ms on, time in ms off
Default: 100

callback
(required)
function

Description:
 Method to call on blink

Example

// Make it blink
import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.color("#663399");
rgb.blink();

Example

// Make it blink slowly
import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.color("#663399");
rgb.blink(5000);

RGB.fade

fade Fade an RGB LED from its current value to a new value

rgb.fade(val, time, callback);

Returns:

Parameters

Name
Type
Description
val
(required)
Array.<Number>, String, or Object

Description:
 Hexadecimal color string, CSS color name, Array of color values, RGB object {red, green, blue}

time
Number

Description:
 Time in ms that a fade will take
Default: 1000

callback
function

Description:
 A function to run when the fade is complete

Example

// Fade on to purple
import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.fade("#663399");

Example

// Fade on to purple over 3 seconds
import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.fade("#663399", 3000);

Example

// Fade on to purple over 3 seconds and then blink
import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.fade("#663399", 3000, function() {
  rgb.blink();
});

RGB.fadeIn

Fade an RGB LED to full brightness

rgb.fadeIn(time, callback);

Returns:

Parameters

Name
Type
Description
time
Number

Description:
 Time in ms that a fade will take
Default: 1000

callback
function

Description:
 A function to run when the fade is complete

Example

// Fade an RGB LED to white over half a second
import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.fadeIn(500);

RGB.fadeOut

Fade an RGB LED off

rgb.fadeOut(time, callback);

Returns:

Parameters

Name
Type
Description
time
Number

Description:
 Time in ms that a fade will take
Default: 1000

callback
function

Description:
 A function to run when the fade is complete

Example

// Fade out an RGB LED over half a second
import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.color("#663399");
rgb.fadeOut(500);

RGB.pulse

Pulse an RGB LED on a fixed interval

rgb.pulse(duration, callback);

Returns:

Parameters

Name
Type
Description
duration
(required)
Number

Description:
 Time in ms on, time in ms off
Default: 1000

callback
(required)
function

Description:
 Method to call on pulse

Example

// Make it pulse
import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.color("#663399");
rgb.pulse();

Example

// Make it pulse slowly
import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.color("#663399");
rgb.pulse(5000);

RGB.animate

Animate an RGB LED

rgb.animate(options);

Returns:

Parameters

Name
Type
Description
options
(required)
Object

Description:
 (See animation)

Example

// Animate an RGB LED using an animation segment options object
import RGB from "j5e/rgb";

const rgb = await new RGB([13, 12, 14]);
rgb.animate({
  duration: 4000,
  cuePoints: [0,  0.33, 0.66, 1],
  keyFrames: ["#000000", "#FF0000", "#00FFFF", "#FFFFFF"],
  loop: true,
  metronomic: true
});

RGB.stop

Stop the RGB LED from pulsing, blinking, fading, or animating

rgb.stop();

Returns:

Example

// Make it pulse for five seconds and then stop
import RGB from "j5e/rgb";
import {timer} from "j5e/fn";

const rgb = await new RGB([13, 12, 14]);
rgb.color("#663399");
rgb.pulse(250);
timer.setTimeout(function() {
  rgb.stop();
}, 5000);