Daniel Wiese / DD-Booster-mbed

This is a library for the DIGI-DOT-BOOSTER which can control LED stripes using the single wire protocol - ws2812 and compatible as well as RGBW LEDs like SK6812. Detailed information including the datasheet and protocol description are available here: http://www.led-genial.de/DIGI-DOT-Booster-WS2812-und-SK6812-ueber-SPI-Schnittstelle-ansteuern DIGI-DOT-BOOSTER acts as a SPI slave and waits for commands sent by a SPI master. This Library provides an easy to use abstraction layer for commands supported by the DD-Booster and adds some additional effects.

Dependents:   DD-Booster-waterdrop BLE_DD-Booster

DDBooster.h@2:4c1e47117cf8, 2017-03-08 (annotated)

Committer:
Gamadril
Date:
Wed Mar 08 08:49:00 2017 +0000
Revision:
2:4c1e47117cf8
Parent:
0:9e96b2bb1958 
docs update

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Gamadril 0:9e96b2bb1958 1 /*
Gamadril 0:9e96b2bb1958 2 * DDBoster.h - Library to control the Digi-Dot-Booster using a high-level API
Gamadril 0:9e96b2bb1958 3 *
Gamadril 0:9e96b2bb1958 4 * https://github.com/Gamadril/DD-Booster-mbed
Gamadril 0:9e96b2bb1958 5 * MIT License
Gamadril 0:9e96b2bb1958 6 */
Gamadril 0:9e96b2bb1958 7 #ifndef DD_BOOSTER_DDBOOSTER_H
Gamadril 0:9e96b2bb1958 8 #define DD_BOOSTER_DDBOOSTER_H
Gamadril 0:9e96b2bb1958 9
Gamadril 0:9e96b2bb1958 10 #include <mbed.h>
Gamadril 0:9e96b2bb1958 11
Gamadril 0:9e96b2bb1958 12 /**
Gamadril 0:9e96b2bb1958 13 * @brief Class acts as a wrapper around SPI calls to control the Digi-Dot-Booster.
Gamadril 0:9e96b2bb1958 14 *
Gamadril 0:9e96b2bb1958 15 * After creation of the class instance SPI is configured with default values (12MHz, MSB first, mode 0).
Gamadril 2:4c1e47117cf8 16 * Used SPI pins has to be passed to the constructor. RESET pin is optional. If omitted reset() call has no effect.
Gamadril 0:9e96b2bb1958 17 *
Gamadril 2:4c1e47117cf8 18 * Before calling any functions you have first to initialize the DD-Booster by calling init() with the number of the LEDs (max. 256 for RGB and max. 192 for RGBW),
Gamadril 0:9e96b2bb1958 19 * their type (RGB or RGBW) and the color order (RGB or GRB). Both last parameters are optional - DD-Booster is
Gamadril 0:9e96b2bb1958 20 * configured for the ws2812 LEDS (RGB type with GRB color order).
Gamadril 0:9e96b2bb1958 21 *
Gamadril 0:9e96b2bb1958 22 * When calling the functions the corresponding values are sent to the DD-Booster, but only
Gamadril 0:9e96b2bb1958 23 * after the show() call the LEDs are really addressed with the current state of the values buffer.
Gamadril 0:9e96b2bb1958 24 */
Gamadril 0:9e96b2bb1958 25 class DDBooster {
Gamadril 0:9e96b2bb1958 26 public:
Gamadril 0:9e96b2bb1958 27
Gamadril 0:9e96b2bb1958 28 /**
Gamadril 0:9e96b2bb1958 29 * LED type. Stores the number of bits used for the color of one LED.
Gamadril 0:9e96b2bb1958 30 * LED_RGB is the default value used by the DD-Booster
Gamadril 0:9e96b2bb1958 31 */
Gamadril 0:9e96b2bb1958 32 enum LedType {
Gamadril 0:9e96b2bb1958 33 LED_RGB = 24,
Gamadril 0:9e96b2bb1958 34 LED_RGBW = 32
Gamadril 0:9e96b2bb1958 35 };
Gamadril 0:9e96b2bb1958 36
Gamadril 0:9e96b2bb1958 37 /**
Gamadril 0:9e96b2bb1958 38 * LED color order. ws2812 is using GRB order and it's the default color order
Gamadril 0:9e96b2bb1958 39 * for the DD-Booster.
Gamadril 0:9e96b2bb1958 40 */
Gamadril 0:9e96b2bb1958 41 enum LedColorOrder {
Gamadril 0:9e96b2bb1958 42 ORDER_RGB,
Gamadril 0:9e96b2bb1958 43 ORDER_GRB
Gamadril 0:9e96b2bb1958 44 };
Gamadril 0:9e96b2bb1958 45
Gamadril 0:9e96b2bb1958 46 /**
Gamadril 0:9e96b2bb1958 47 * Default constructor. Initializes SPI interface at 12MHz, MSB first, mode 0
Gamadril 0:9e96b2bb1958 48 * Assigns used pins for SPI communication and reset pin to reset DD-Booster.
Gamadril 0:9e96b2bb1958 49 * To be able to do a hardware reset of the DD-Booster, connect a digital IO
Gamadril 0:9e96b2bb1958 50 * pin to the RESET pin of the DD-Booster.
Gamadril 0:9e96b2bb1958 51 * @param MOSI - Digital pin of SPI MOSI line
Gamadril 0:9e96b2bb1958 52 * @param SCK - Digital pin of SPI clock
Gamadril 0:9e96b2bb1958 53 * @param CS - Digital pin of SPI chip select
Gamadril 0:9e96b2bb1958 54 * @param resetPin - Digital pin connected to the RESET pin of the DD-Booster, Optional, set to NC if missing
Gamadril 0:9e96b2bb1958 55 */
Gamadril 0:9e96b2bb1958 56 DDBooster(PinName MOSI, PinName SCK, PinName CS, PinName RESET = NC);
Gamadril 0:9e96b2bb1958 57
Gamadril 0:9e96b2bb1958 58 /**
Gamadril 0:9e96b2bb1958 59 * Performs initial configuration of the DD-Booster to set the number of used LEDs and their type.
Gamadril 0:9e96b2bb1958 60 * DD-Booster supports max. 256 LEDs.
Gamadril 0:9e96b2bb1958 61 * @param ledCount - Number of used LEDs
Gamadril 0:9e96b2bb1958 62 * @param ledType - Type of LEDs used. RGB is default
Gamadril 0:9e96b2bb1958 63 * @param colorOrder - LED color order. GRB is default
Gamadril 0:9e96b2bb1958 64 */
Gamadril 0:9e96b2bb1958 65 void init(uint16_t ledCount, LedType ledType = LED_RGB, LedColorOrder colorOrder = ORDER_GRB);
Gamadril 0:9e96b2bb1958 66
Gamadril 0:9e96b2bb1958 67 /**
Gamadril 0:9e96b2bb1958 68 * Performs a hardware reset of the DD-Booster by toggling it's RESET pin.
Gamadril 2:4c1e47117cf8 69 * Does nothing if RESET pin was not configured in the constructor.
Gamadril 0:9e96b2bb1958 70 * the call of reset() does nothing.
Gamadril 0:9e96b2bb1958 71 */
Gamadril 0:9e96b2bb1958 72 void reset();
Gamadril 0:9e96b2bb1958 73
Gamadril 0:9e96b2bb1958 74 /**
Gamadril 0:9e96b2bb1958 75 * Sets a LED color for next operations using RGB format until another color
Gamadril 0:9e96b2bb1958 76 * set operation overwrites it.
Gamadril 0:9e96b2bb1958 77 * @param r - Red part of the color value (0 - 255)
Gamadril 0:9e96b2bb1958 78 * @param g - Green part of the color value (0 - 255)
Gamadril 0:9e96b2bb1958 79 * @param b - Blue part of the color value (0 - 255)
Gamadril 0:9e96b2bb1958 80 */
Gamadril 0:9e96b2bb1958 81 void setRGB(uint8_t r, uint8_t g, uint8_t b);
Gamadril 0:9e96b2bb1958 82
Gamadril 0:9e96b2bb1958 83 /**
Gamadril 0:9e96b2bb1958 84 * Sets a LED color for next operations using RGBW format until another color
Gamadril 0:9e96b2bb1958 85 * set operation overwrites it.
Gamadril 0:9e96b2bb1958 86 * @param r - Red part of the color value (0 - 255)
Gamadril 0:9e96b2bb1958 87 * @param g - Green part of the color value (0 - 255)
Gamadril 0:9e96b2bb1958 88 * @param b - Blue part of the color value (0 - 255)
Gamadril 0:9e96b2bb1958 89 * @param w - White LED level (0 - 255)
Gamadril 0:9e96b2bb1958 90 */
Gamadril 0:9e96b2bb1958 91 void setRGBW(uint8_t r, uint8_t g, uint8_t b, uint8_t w);
Gamadril 0:9e96b2bb1958 92
Gamadril 0:9e96b2bb1958 93 /**
Gamadril 0:9e96b2bb1958 94 * Sets a LED color for next operations using HSV format until another color
Gamadril 0:9e96b2bb1958 95 * set operation overwrites it.
Gamadril 0:9e96b2bb1958 96 * @param h - Hue part of the color value (0 - 359)
Gamadril 0:9e96b2bb1958 97 * @param s - Saturation part of the color value (0 - 255)
Gamadril 0:9e96b2bb1958 98 * @param v - Value part of the color value (0 - 255)
Gamadril 0:9e96b2bb1958 99 */
Gamadril 0:9e96b2bb1958 100 void setHSV(uint16_t h, uint8_t s, uint8_t v);
Gamadril 0:9e96b2bb1958 101
Gamadril 0:9e96b2bb1958 102 /**
Gamadril 0:9e96b2bb1958 103 * Assign the previously set color value to a single LED.
Gamadril 0:9e96b2bb1958 104 * @param index - Index of of the LED to set. Index starts with 0
Gamadril 0:9e96b2bb1958 105 */
Gamadril 0:9e96b2bb1958 106 void setLED(uint8_t index);
Gamadril 0:9e96b2bb1958 107
Gamadril 0:9e96b2bb1958 108 /**
Gamadril 0:9e96b2bb1958 109 * Clears a single LED by setting its color to RGB(0,0,0).
Gamadril 0:9e96b2bb1958 110 * Internally it simply sends setRGB(0,0,0) and setLED(index).
Gamadril 0:9e96b2bb1958 111 * @param index - Index of of the LED to clear. Index starts with 0
Gamadril 0:9e96b2bb1958 112 */
Gamadril 0:9e96b2bb1958 113 void clearLED(uint8_t index);
Gamadril 0:9e96b2bb1958 114
Gamadril 0:9e96b2bb1958 115 /**
Gamadril 0:9e96b2bb1958 116 * Assign the previously set color value to a all LEDs.
Gamadril 0:9e96b2bb1958 117 */
Gamadril 0:9e96b2bb1958 118 void setAll();
Gamadril 0:9e96b2bb1958 119
Gamadril 0:9e96b2bb1958 120 /**
Gamadril 0:9e96b2bb1958 121 * Clears all LEDs by setting their color to RGB(0,0,0).
Gamadril 0:9e96b2bb1958 122 * Internally it simply sends setRGB(0,0,0) and setAll().
Gamadril 0:9e96b2bb1958 123 */
Gamadril 0:9e96b2bb1958 124 void clearAll();
Gamadril 0:9e96b2bb1958 125
Gamadril 0:9e96b2bb1958 126 /**
Gamadril 0:9e96b2bb1958 127 * Assign the previously set color value to a range of LEDs.
Gamadril 0:9e96b2bb1958 128 * @param start - Index of the first LED in the range to set. Index starts with 0
Gamadril 0:9e96b2bb1958 129 * @param end - Index of the last LED in the range to set
Gamadril 0:9e96b2bb1958 130 */
Gamadril 0:9e96b2bb1958 131 void setRange(uint8_t start, uint8_t end);
Gamadril 0:9e96b2bb1958 132
Gamadril 0:9e96b2bb1958 133 /**
Gamadril 0:9e96b2bb1958 134 * Creates a rainbow effect in a range.
Gamadril 0:9e96b2bb1958 135 * @param h - Hue part of the color value (0 - 359)
Gamadril 0:9e96b2bb1958 136 * @param s - Saturation part of the color value (0 - 255)
Gamadril 0:9e96b2bb1958 137 * @param v - Value part of the color value (0 - 255)
Gamadril 0:9e96b2bb1958 138 * @param start - Index of the first LED in the range to set. Index starts with 0
Gamadril 0:9e96b2bb1958 139 * @param end - Index of the last LED in the range to set
Gamadril 0:9e96b2bb1958 140 * @param step - Step value to increment between 2 LEDs. Recommended values 2 - 20
Gamadril 0:9e96b2bb1958 141 */
Gamadril 0:9e96b2bb1958 142 void setRainbow(uint16_t h, uint8_t s, uint8_t v, uint8_t start, uint8_t end, uint8_t step);
Gamadril 0:9e96b2bb1958 143
Gamadril 0:9e96b2bb1958 144 /**
Gamadril 0:9e96b2bb1958 145 * Creates a gradient from one color to another. start and end index can have negative
Gamadril 0:9e96b2bb1958 146 * values to make a gradient starting outside the visible area showing only it's
Gamadril 0:9e96b2bb1958 147 * currently visible part considering the intermediate color values.
Gamadril 0:9e96b2bb1958 148 * @param start - Index of the first LED in the range. Can be negative.
Gamadril 0:9e96b2bb1958 149 * @param end - Index of the last LED in the range. Can be greater than the number of LEDs
Gamadril 0:9e96b2bb1958 150 * @param from - RGB value of the start color
Gamadril 0:9e96b2bb1958 151 * @param to - RGB value of the end color
Gamadril 0:9e96b2bb1958 152 */
Gamadril 0:9e96b2bb1958 153 void setGradient(int start, int end, uint8_t from[3], uint8_t to[3]);
Gamadril 0:9e96b2bb1958 154
Gamadril 0:9e96b2bb1958 155 /**
Gamadril 0:9e96b2bb1958 156 * Shifts up the color values of the LEDs in a range.
Gamadril 0:9e96b2bb1958 157 * @param start - Index of the first LED in the range. Index starts with 0
Gamadril 0:9e96b2bb1958 158 * @param end - Index of the last LED in the range
Gamadril 0:9e96b2bb1958 159 * @param count - Number of LEDs/steps to shift up
Gamadril 0:9e96b2bb1958 160 */
Gamadril 0:9e96b2bb1958 161 void shiftUp(uint8_t start, uint8_t end, uint8_t count);
Gamadril 0:9e96b2bb1958 162
Gamadril 0:9e96b2bb1958 163 /**
Gamadril 0:9e96b2bb1958 164 * Shifts down the color values of the LEDs in a range.
Gamadril 0:9e96b2bb1958 165 * @param start - Index of the first LED in the range. Index starts with 0
Gamadril 0:9e96b2bb1958 166 * @param end - Index of the last LED in the range
Gamadril 0:9e96b2bb1958 167 * @param count - Number of LEDs/steps to shift down
Gamadril 0:9e96b2bb1958 168 */
Gamadril 0:9e96b2bb1958 169 void shiftDown(uint8_t start, uint8_t end, uint8_t count);
Gamadril 0:9e96b2bb1958 170
Gamadril 0:9e96b2bb1958 171 /**
Gamadril 0:9e96b2bb1958 172 * Copies a color value of a LED to another one.
Gamadril 0:9e96b2bb1958 173 * @param from - Index of the LED to copy from
Gamadril 0:9e96b2bb1958 174 * @param to - Index of the LED to copy to
Gamadril 0:9e96b2bb1958 175 */
Gamadril 0:9e96b2bb1958 176 void copyLED(uint8_t from, uint8_t to);
Gamadril 0:9e96b2bb1958 177
Gamadril 0:9e96b2bb1958 178 /**
Gamadril 0:9e96b2bb1958 179 * Copies the whole range several times in a row.
Gamadril 0:9e96b2bb1958 180 * @param start - Index of the first LED in the range. Index starts with 0
Gamadril 0:9e96b2bb1958 181 * @param end - Index of the last LED in the range
Gamadril 0:9e96b2bb1958 182 * @param count - Number of copy operation
Gamadril 0:9e96b2bb1958 183 */
Gamadril 0:9e96b2bb1958 184 void repeat(uint8_t start, uint8_t end, uint8_t count);
Gamadril 0:9e96b2bb1958 185
Gamadril 0:9e96b2bb1958 186 /**
Gamadril 0:9e96b2bb1958 187 * Shows the changes previously made by sending all values to the LEDs.
Gamadril 0:9e96b2bb1958 188 */
Gamadril 0:9e96b2bb1958 189 void show();
Gamadril 0:9e96b2bb1958 190
Gamadril 0:9e96b2bb1958 191 /**
Gamadril 0:9e96b2bb1958 192 * Sends raw byte buffer with commands to DD-Booster. Waits 2ms after transmission.
Gamadril 0:9e96b2bb1958 193 */
Gamadril 0:9e96b2bb1958 194 void sendRawBytes(const uint8_t* buffer, uint8_t length);
Gamadril 0:9e96b2bb1958 195
Gamadril 0:9e96b2bb1958 196 public:
Gamadril 0:9e96b2bb1958 197 uint8_t _lastIndex;
Gamadril 0:9e96b2bb1958 198 SPI _device;
Gamadril 0:9e96b2bb1958 199 DigitalOut _cs;
Gamadril 0:9e96b2bb1958 200 DigitalOut _reset;
Gamadril 0:9e96b2bb1958 201 };
Gamadril 0:9e96b2bb1958 202
Gamadril 0:9e96b2bb1958 203 #endif //DD_BOOSTER_DDBOOSTER_H