Programming LED Patterns on the MetaWear Board

portfoliocitem4

This post uses the methods in Android API v1.3.7. To use the on-board LED, you must have a battery soldered onto the board; powering the board with only a USB cable will not work.

Overview

The MetaWear board comes with an ultra bright, 20mA LED. It is programmed to function like a square wave with each segment of the wave configurable, allowing users to create custom LED patterns.

Square Wave

The 4 time attributes you can modify are outlined in the below table:

Attribute Description
Rise Time Time to transition from low to high intensity
High Time Time to stay at the high intensity
Fall Time Time to transition from high to low intensity
Duration The total time of one pulse. If rise + high + fall < duration, the LED will remain at the low intensity for the leftover time

In addition to configuring the pulse timings, you can also modify the intensity levels (brightness) of the LED.

API Calls

Interacting with the LED module is done with the LED interface. You can use the interface to program your own LED patterns and play/pause/stop them.

Setting up Patterns

The aforementioned attributes configured by calling setColorChannel. The method will return a ChannelDataWriter, which builds and writes the pattern to one of the LEDs. The typical use case of ChannelDataWriter will be to call the withHighIntensity method along with any combination of: withHighTime, withRiseTime, withFallTime, and withPulseDuration. Not calling a writer method will leave its respective bytes set to 0. When you are done configuring your pattern, call the commit to write the settings to the board.

Each call to setColorChannel will set the attributes for one color. You can mix colors attributes to get different color blends.

Controlling Pattern State

Once the patterns have been programmed in, you can then play them with the play method, passing in “false”. When the patterns are playing, you have the option of pausing them mid pattern with the pause method, and resuming them by calling play. Stopping patterns is done with the stop method. The stop method is also used to clear LED patterns. If you wish to clear LED patterns, pass in “true” to the stop method, otherwise, use “false”.

Sample Patterns

Three simple LED patterns (blink, flashlight, and pulse) have been provided to demonstrate usage of the ChannelDataWriter class.

Blink

A blink pattern can be thought of as very quick burst of light. In other words, the LED quickly turns on, then quickly turns off. We achieve this effect by setting the rise and fall time be 0 and setting the high time to be 50ms. For our example, we have a duration of 500ms, but you may lessen this value for more frequent blinks.
blink

private LED ledCtrllr;

private void setupBlink() {
    ledCtrllr.setColorChannel(ColorChannel.GREEN).withHighIntensity((byte) 31)
            .withHighTime((short) 50).withPulseDuration((short) 500)
            .withRepeatCount((byte) -1).commit();
    ledCtrllr.start(false);
}

Flashlight

The flashlight pattern is simply keeping the LED on for the entire duration of a pulse. We can be accomplished by either having the high time equal the pulse duration, or having both high and low intensities match.

solid

private LED ledCtrllr;
private short pulseWidth= 2000;

private void setupFlashlight() {
    ledCtrllr.setColorChannel(ColorChannel.RED).withHighIntensity((byte) 31)
            .withHighTime(pulseWidth).withPulseDuration(pulseWidth)
            .withRepeatCount((byte) -1).commit();

    /*
    ///< Can alternatively achieve the same effect with this configuration
    ledCtrllr.setColorChannel(ColorChannel.RED)
            .withHighIntensity((byte) 31).withLowIntensity((byte) 31)
            .withHighTime(pulseWidth / 2).withPulseDuration(pulseWidth)
            .withRepeatCount((byte) -1).commit();
    */
    ledCtrllr.start(false);
}

Pulse

For the pulse pattern, we leverage the fall and rise times to have smoother transitions between the high and low states. To keep the pulse effect continuous, the entire pulse duration will be spent either rising, falling, or displaying the high intensity.

pulse_trap

private LED ledCtrllr;

private void setupPulse() {
    ledCtrllr.setColorChannel(ColorChannel.BLUE).withHighIntensity((byte) 31)
            .withRiseTime((short) 750).withFallTime((short) 750)
            .withHighTime((short) 500).withPulseDuration((short) 2000)
            .withRepeatCount((byte) -1).commit();
    ledCtrllr.start(false);
}

Notes

  • Intensity level can be between [0, 31]
  • Passing in 0xff (unsigned 255, signed -1) into withRepeatCount will have the pattern repeat indefinitely
  • Calling play with “true” will automatically start playing a pattern as soon as its written