Лёгкая библиотека для адресной ленты v3.5

ОСОБЕННОСТИ

Данная библиотека нужна для проектов с лентой, в которых критичен объём занимаемой оперативной памяти: его можно уменьшить в 1.5 и 3 раза по сравнению с обычными библиотеками, а также вообще отказаться от динамического буфера и управлять лентой любой длины даже с ATtiny!! Библиотека написана очень просто, используемые в ней алгоритмы и решения очень прозрачны и могут кому-нибудь пригодиться. Единственный минус: инструменты для генерации и изменения цвета работают медленнее, чем в FastLED, поэтому для быстрых красивых эффектов на большой ленте/матрице придётся подключать фастлед для быстрой математики.

ПОДДЕРЖКА FASTLED (NEW!)

В версии 3.1 появилась полноценная поддержка совместной работы с FastLED для быстрого вычисления эффектов. Это позволяет выводить всякие шумы по палитрам даже на АТтини!! Для этого подключаем в скетч #include < FastLEDsupport.h> (смотри примеры), саму FastLED подключать не нужно, она подключится автоматически. У нас появится функция CRGBtoData(), которая переводит тип данных фастледа в микролед (конвертирует CRGB в mData при любой глубине цвета). В качестве примера работы с  палитрой можно глянуть пример FIRE_with_FastLED.

ЦВЕТОВАЯ ГЛУБИНА

Цветовая глубина задаёт количество байт, которые занимает цвет одного светодиода и может быть от 1, 2 и 3 байта (8, 16 и 24 бита на один светодиод соответственно). Все остальные библиотеки используют 24-битную глубину цвета, в microLED её можно уменьшить для экономии памяти. При уменьшении цветовой глубины пропорционально уменьшается вес ленты в оперативной памяти, но в то же время ухудшается цвет: на эффектах с плавными переходами цвета будут заметны границы между оттенками. Настройка цветовой глубины задаёт работу всей библиотеки и делается при помощи дефайна COLOR_DEBTH до подключения библиотеки:

#define COLOR_DEBTH 2 
#include < microLED.h >

По умолчанию (если не указывать дефайн) глубина настроена на 24 бита (COLOR DEBTH 3). Понижать глубину рекомендуется только в целях экономии памяти.

ГАММА КОРРЕКЦИЯ

Ещё одна настройка, которая делается дефайном и влияет на всю библиотеку сразу. Гамма коррекция позволяет получать более естественные цвета и их смеси, а также более приятные глазу переходы яркости и реализована 4мя способами:

• #define CRT_OFF - коррекция отключена для экономии памяти и ускорения вычислений.
• #define CRT_PGM - коррекция по таблице. Добавляет 256 байт во Flash память, но работает быстрее и красивее всех остальных.
• #define CRT_SQUARE - квадратная коррекция. Занимает мало памяти, выполняется гораздо дольше таблицы (около 7 мкс).
• #define CRT_CUBIC - кубическая коррекция. Выглядит приятнее квадратной, но выполняется ещё дольше.

По умолчанию включена коррекция по таблице. Остальные режимы - для продвинутого пользователя и экспериментов.

КАК РАБОТАЕТ БИБЛИОТЕКА?

Режим буфера

При инициализации указываем длину ленты, внутри библиотеки будет создан буфер типа mData, который занимает 1, 2 или 3 байта в зависимости от выбранной цветовой глубины и олицетворяет цвет в формате RGB. С данным массивом можно работать как с обычным массивом и присваивать его элементам цвет в формате mData (например, strip.leds[5] = mRed). Само собой, массив занимает место в оперативной памяти микроконтроллера пропорционально длине ленты. Забив буфер цветами, можно вызвать strip.show() и лента обновится с максимально возможной скоростью.

strip.leds[0] = mRGB(0, 230, 60);
strip.leds[5] = mRed;
strip.show();

Режим потока

В этом режиме буфер не создаётся (количество светодиодов указываем 0), оперативная память не занимается, а мы генерируем цвет пикселей "на лету". Для начала передачи нужно вызвать .begin(), для передачи цвета - .send(mData цвет) нужное количество раз и завершить вывод вызовом .end().

Тут есть некоторые ограничения: между вызовами send() должно пройти не более 50-300 мкс (в зависимости от модели ленты), иначе вывод сбросится. Для экономии времени можно заранее посчитать цвет перед выводом, например зальём всю ленту:

mData data = mHSV(0, 255, 120);
strip.begin();
  for (int i = 0; i < num; i++) {
    strip.send(data);
  }
strip.end();

ИНИЦИАЛИЗАЦИЯ ЛЕНТЫ

В библиотеке версии 3 и выше лента объявляется через шаблон: microLED< amount, pin, clock, chip, order, cli, millis> объект:

• amount - количество светодиодов в ленте. Для работы в режиме потока можно указать 0, так как длина ленты фактически ничем не ограничена.
• pin -  пин, к которому подключен дата-вход ленты (D, Din, DI).
• clock - пин, к которому подключен тактовый-вход ленты (C, CLK). Этот пин подключается только для SPI лент, например APA102.
  • Для работы с лентами серии WSxxxx нужно указать вместо этого пина параметр MLED_NO_CLOCK или минус 1 , т.е. -1
• chip - модель ленты (светодиодов), в библиотеке поддерживаются LED_WS2811, LED_WS2812, LED_WS2813, LED_WS2815, LED_WS2818, LED_WS6812, APA102, APA102_SPI. Выбор модели ленты задаёт скорость протокола (она у них разная) и настройки тока потребления для режимов ограничения (о них читай дальше).
• order - порядок цветов в ленте. В идеальном мире порядок цветов должен зависеть от модели чипа и эта настройка должна быть встроена в выбор чипа, но китайцы торгуют лентами, которые по протоколу совпадают с одним чипом, но имеют другой порядок цветов. Таким образом библиотека поддерживает больше типов лент, чем написано выше, но нужно угадать с выбором "клона" и порядок цветов. Порядок: ORDER_RGB, ORDER_RBG, ORDER_BRG, ORDER_BGR, ORDER_GRB, ORDER_GBR.

Оригинальные ленты на поддерживаемых библиотекой чипах имеют такой порядок цветов, также это готовая строка инициализации:

// microLED< NUMLEDS, STRIP_PIN, -1, LED_WS2811, ORDER_GBR> strip;
// microLED< NUMLEDS, STRIP_PIN, -1, LED_WS2812, ORDER_GRB> strip;
// microLED< NUMLEDS, STRIP_PIN, -1, LED_WS2813, ORDER_GRB> strip;
// microLED< NUMLEDS, STRIP_PIN, -1, LED_WS2815, ORDER_GRB> strip;
// microLED< NUMLEDS, STRIP_PIN, -1, LED_WS2818, ORDER_RGB> strip;
// microLED< NUMLEDS, STRIP_PIN, -1, LED_WS6812, ORDER_RGB> strip;
// microLED< NUMLEDS, STRIP_PIN, CLOCK_PIN, LED_APA102, ORDER_BGR> strip;
// microLED< NUMLEDS, MLED_NO_CLOCK, MLED_NO_CLOCK, LED_APA102_SPI, ORDER_BGR> strip;

Можно вставить прямо в свой код =) Оставшиеся две настройки не являются обязательными (можно не указывать):

• cli - выбор настроек запрета прерываний для повышения надёжности вывода данных на ленту:
  • CLI_OFF - прерывания не отключаются (возможны сбои в работе ленты даже от прерываний системного таймера)
  • CLI_LOW - прерывания отключаются на время передачи одного цвета
  • CLI_AVER - прерывания отключаются на время передачи светодиода (3 цвета)
  • CLI_HIGH - прерывания отключаются на время передачи данных на всю ленту
• millis - при отключении прерываний в режиме среднего и высокого приоритета (CLI_AVER и CLI_HIGH) неизбежно будут чуть отставать функции времени millis() и micros(). В библиотеке встроено обслуживание функций времени, для активации передаём SAVE_MILLIS 6-ым аргументом при инициализации: microLED< NUMLEDS, STRIP_PIN, LED_WS2818, ORDER_GRB, CLI_AVER, SAVE_MILLIS> strip;

ОСОБЕННОСТИ 2Х ПИНОВЫХ ЛЕНТ (NEW!)

Существует два вида лент, имеющих 2 пина для управления (помимо питания):

• Ленты моделей WS2813, WS2815, WS2818 и их копии с буквами SK и такими же цифрами. У этих лент подключается только один пин из двух, тот который DI. Пин BI (B) не подключается. При инициализации указывается только DI пин, второй пишем -1 или "заглушку" MLED_NO_CLOCK.
• Ленты моделей APA102 (она же SK9822) требуют подключения именно двух своих пинов, один из которых Data (D, DI, DAT), а второй - Clock (C, CLK, SCK). При инициализации указываем оба.

SPI ЛЕНТЫ (NEW!)

В библиотеке версии 3.1 добавлена поддержка SPI лент, в том числе аппаратная (на базе стандартной библиотеки SPI.h). Рассмотрим куски примеров.

При выборе LED_APA102 ленту можно подключить на любые два пина и указать их при инициализации. Всё

// пример работы с LED_APA102 программно
#define DATA_PIN 3      // пин дата
#define CLOCK_PIN 4     // пин клок
#define NUMLEDS 50      // кол-во светодиодов

#include    // подключаем библу
microLED< NUMLEDS, DATA_PIN, CLOCK_PIN, LED_APA102, ORDER_BGR, CLI_AVER> strip;

При выборе LED_APA102_SPI лента подключается к выводам аппаратной шины SPI микроконтроллера:

• Data пин на MOSI (D11 на Arduino Nano)
• Clock пин на SCK (D13 на Arduino Nano)

Что это даёт? Аппаратный SPI позволяет выводить данные на ленту чуть ли не в 10 раз быстрее, чем программный способ! В коде должно быть:

#define MLED_USE_SPI    // обязательный деф до библиотеки для поддержки SPI.h
//#define MLED_SPI_CLOCK 8000000 // частоту SPI можно менять из скетча

#include    // подключаем библу
microLED<NUMLEDS, -1, -1, LED_APA102_SPI, ORDER_BGR, CLI_AVER> strip;

Пины в этом случае не указываются! Ставим заглушку или -1. Это всё.

ГЕНЕРАЦИЯ ЦВЕТА

Для работы с цветом в библиотеке есть несколько инструментов, возвращающих тип данных mData для отправки на ленту или в буфер. mData - тип данных, который олицетворяет цвет светодиода в формате RGB. В зависимости от выбранной цветовой глубины является:

• 8 бит - uint8_t
• 16 бит - uint16_t
• 24 бита - struct {byte r, g, b}

Собственно инструменты и функции:

• mRGB(r, g, b) - итоговый цвет будет замешан из красного, зелёного и синего, все параметры задаются в диапазоне 0-255
• mHSV(h, s, v) - цвет из пространства hsv: цвет, насыщенность, яркость. Все параметры задаются в диапазоне 0-255. Цвет в диапазоне 0-255 совершает круг от красного к зелёному, от зелёного к синему и от синего снова к красному. Функция "тяжёлая", поэтому для генерирования "радуги" рекомендуется использовать mWheel() и mWheel8()
• mHSVfast(h, s, v) - то же самое, но выполняется быстрее и даёт менее приятные глазу цветовые переходы
• mWheel(val) - принимает значение от 0 до 1530 и возвращает цвет из цветового круга, как и hsv. Выполняется очень быстро
• mWheel(val, bright) - то же самое, но с яркостью (0-255)
• mWheel8(val) - то же самое что предыдущий, но принимает 0-255 и делает цвет постоянной яркости.
• mWheel8(val, bright) - то же самое, но с яркостью (0-255)
• mHEX(val) - принимает цвет в формате RGB888 (обычный web-формат). Например 0xFF0000 это красный
• mKelvin(temp) - выдает цвет, соответствующий цветовой температуре temp в кельвинах
• 16 предустановленных цветов: mWhite, mSilver, mGray, mBlack, mRed, mMaroon, mOrange, mYellow, mOlive, mLime, mGreen, mAqua, mTeal, mBlue, mNavy, mMagenta, mPurple
• getBlend(val, max, color1, color2) - выдает цвет в указанном месте градиента двух цветов: val - искомая точка (от 0 до max), max - размер градиента, color1 и color2 - цвета, соответствующие 0 и max позиции градиента. Например getBlend(30, 100, mRed, mBlack) вернёт красный, смешанный с черным на 30/100, то есть чуть темнее красного.
• getFade(mData data, uint8_t val) - вернёт цвет data, яркость которого понижена на val (0-255).
• uint32_t getHEX(mData data) - вернёт HEX RGB888 вне зависимости от выбранной цветовой глубины (функция распакует и вернёт в привычном представлении)
• RGB888to565(x), RGB888to323(x), RGB565to888(x), RGB323to888(x) - макросы конвертации цвета из одной кодировки в другую (принимает численное значение).
• getR(mData x) - извлечь красный канал из цвета
• getG(mData x) - извлечь зелёный канал из цвета
• getB(mData x) - извлечь синий канал из цвета
• mergeRGB(r,g,b) - объединить три цвета (0-255 каждый) в mData с учётом выбранной модели CRT гамма-коррекции
• mergeRGBraw(r,g,b) - объединить три цвета (0-255 каждый) в mData
• fade8(byte x, byte b) - уменьшить яркость x (0-255) на b (0-255)
• fade8R(mData x, byte b) - уменьшить яркость красного канала цвета x на b (0-255)
• fade8G(mData x, byte b) - уменьшить яркость зелёного канала цвета x на b (0-255)
• fade8B(mData x, byte b) - уменьшить яркость синего канала цвета x на b (0-255)
• getCRT(byte x) - получить скорректированное значение яркости x с учётом выбранной модели CRT гамма-коррекции
• getCRT_PGM(byte x) - получить CRT из прогмем (работает только если выбрана PGM модель)
• getCRT_SQUARE(byte x) - получить CRT по квадратной модели
• getCRT_QUBIC(byte x) - получить CRT по кубической модели
• RGB24to16(x) - конвертация 24-бит цвета в 16-бит
• RGB24to8(x) - конвертация 24-бит цвета в 8-бит
• RGB16to24(x) - конвертация 16-бит цвета в 24-бит
• RGB8to24(x) - конвертация 8-бит цвета в 24-бит
• RGB24toR(x) - вытащить байт R из 24-бит цвета
• RGB24toG(x) - вытащить байт G из 24-бит цвета
• RGB24toB(x) - вытащить байт B из 24-бит цвета
• RGBto24(r,g,b) - склеить 24-бит цвет
• RGBto16(r,g,b) - склеить 16-бит цвет
• RGBto8(r,g,b) - склеить 8-бит цвет

ГРАДИЕНТЫ

В библиотеке реализован инструмент для создания градиентов любого размера (количество цветных сегментов) и длины:

mGradient< 4 > myGrad;  // создать градиент с именем myGrad на 4 точки
// указываем цвет каждой точки
myGrad.colors[0] = mBlack;
myGrad.colors[1] = mRed;
myGrad.colors[2] = mYellow;
myGrad.colors[3] = mWhite;
// создали градиент чёрный-красный-жёлтый-белый с одинаковым расстоянием между точками

// при помощи .get(позиция, размер) можно получить цвет в заданном месте градиента при указанной длине

// заливаем всю ленту
for (int i = 0; i < NUMLEDS; i++) {
  strip.set(i, myGrad.get(i, NUMLEDS)); // получаем последовательно все цвета
}
strip.show();

РАБОТА С ЛЕНТОЙ ПОПИКСЕЛЬНО

Можно присвоить цвет в формате mData напрямую в буфер: strip.leds[0] = mRed. Есть функция set, которая делает то же самое:

set(num, color) - установить светодиоду под номером num цвет color. Например strip.set(0, mWheel(120));

fade(int num, byte val) - уменьшить яркость светодиода num на величину val

get(num) - вернёт цвет в формате mData. Равносильно чтению элемента массива буфера strip.leds[num]. Полученный цвет можно фейдить и применять к нему другие описанные выше модификаторы.

ЗАЛИВКА УЧАСТКОВ

• clear() - очистить все цвета в буфере (погасить светодиоды)
• fill(color) - залить всю ленту цветом color. Например fill(mRGB(120, 50 96))
• fill(from, to, color) залить цветом color, со светодиода from до to
• fillGradient(from, to, color1, color2) - залить градиентом от color1 до color2 между светодиодами from и to

Примечание: это функции для работы с буфером. Для применения нужно вызвать show(). Для потокового вывода эти функции не работают!

ЯРКОСТЬ

Яркость задаётся в setBrightness(val) в диапазоне 0-255. Установка яркости занимается дополнительным уменьшением яркости, то есть если поставить цвет mRed и максимальную яркость - это будет 255 по красному каналу цвета (максимум). Если поставить яркость 128, красный канал пропорционально уменьшится, остальные каналы останутся нулями.

РАБОТА С МАТРИЦЕЙ

Для работы с матрицей при инициализации, помимо настроек шаблона ленты, нужно указать параметры матрицы: (width, height, type, conn, dir). Где width и height - ширина и высота матрицы, type, conn и dir - тип соединения матрицы, угол и направление подключения (см. картинки к документации).

Так как матрица - это все ещё лента, у каждого пикселя помимо двух координат есть номер в ленте. Получить его можно при помощи getPixNumber(x, y). Система координат - первая четверть декартовой СК: начало (0, 0) - левый нижний угол. Вверх растёт y, вправо - x.

• set(x, y, color) - включит указанный пиксель указанным цветом в формате mData
• get(x, y) - прочитает цвет пикселя
• drawBitmap8(int X, int Y, const uint8_t *frame, int width, int height) - вывод битмапа (битмап 1мерный PROGMEM)
• drawBitmap16(int X, int Y, const uint16_t *frame, int width, int height) - вывод битмапа (битмап 1мерный PROGMEM)
• drawBitmap32(int X, int Y, const uint32_t *frame, int width, int height) - вывод битмапа (битмап 1мерный PROGMEM)

ОГРАНИЧЕНИЕ ТОКА (ЯРКОСТИ)

В библиотеке есть возможность автоматически ограничить яркость ленты по установленному току потребления при помощи setMaxCurrent(cur), где cur - ток в миллиамперах. В самой библиотеке ток каждого типа ленты уже задан, но я измерял его для своих лент, и он может отличаться от лент, купленных в другом магазине. Для наиболее точной работы ограничения нужно настроить ток ленты для своей ленты, задав в oneLedMax максимальный (белый, 255) ток одного светодиода в миллиамперах и oneLedIdle - холостой ток (светодиод выключен) в мкА.

oneLedMax = (ток ленты с одним горящим) - (ток выключенной ленты)
oneLedIdle = (ток выключенной ленты) / длина ленты * 1000

Берём кусок ленты, например WS2818, 180 диодов (3 в каждом секторе, 60 секторов):

• 160 мА когда горит один сектор из 60
• 114 мА когда лента не горит

Так как активный ток равен холостому + активному, 160-114 = 46 чистых мА на сектор имеем 114 / 60 = 1.9 мА холостых на сектор

strip.oneLedIdle = 1900; // задаём в мка
strip.oneLedMax = 46; // задаём в ма

Берём бухту ленты, например WS2812, 60*5м = 300 диодов

• 102 мА когда горит один диод
• 74 мА когда лента не горит

Так как активный ток равен холостому + активному, 102-74 = 28 чистых мА на диод имеем 74 / 300 = 0.24 мА холостых на диод

strip.oneLedIdle = 240; // задаём в мка
strip.oneLedMax = 28; // задаём в ма

ТИНИЛЕД!

НАСТРОЙКИ

#define TLED_CHIP LED_WS2811
#define TLED_CHIP LED_WS2812
#define TLED_CHIP LED_WS2813
#define TLED_CHIP LED_WS2815
#define TLED_CHIP LED_WS2818
#define TLED_CHIP LED_WS6812
#define TLED_CHIP LED_APA102
#define TLED_CHIP LED_APA102_SPI

#define TLED_ORDER ORDER_RGB
#define TLED_ORDER ORDER_RBG
#define TLED_ORDER ORDER_BRG
#define TLED_ORDER ORDER_BGR
#define TLED_ORDER ORDER_GRB
#define TLED_ORDER ORDER_GBR

• LED_WS2811 - ORDER_GBR
• LED_WS2812 - ORDER_GRB
• LED_WS2813 - ORDER_GRB
• LED_WS2815 - ORDER_GRB
• LED_WS2818 - ORDER_RGB
• LED_WS6812 - ORDER_RGB
• LED_APA102 - ORDER_BGR
• LED_APA102_SPI - ORDER_BGR

// #define TLED_CLI CLI_OFF  // прерывания не запрещаются
// #define TLED_CLI CLI_LOW  // запрещаются на время передачи байта (стоит по умолчанию)
// #define TLED_CLI CLI_AVER // запрещаются на время передачи светодиода (3 байта)
// #define TLED_CLI CLI_HIGH // запрещаются на время передачи всей ленты

// #define TLED_STATIC_BRIGHT

// по умолчанию задефайнен PORTB (для ATtiny)
// можно указать свой порт, если у тиньки больше 8 ног или это вообще атмега
// #define TLED_PORT PORTB
// #define TLED_DDR DDRB

#include "tinyLED.h"
tinyLED< 3> strip;  // например пин 3

// программный SPI, например LED_APA102
// по умолчанию PORTB
// можно указать свой порт, если у тиньки больше 8 ног или это вообще атмега
// #define TLED_CLK_PORT PORTB
// #define TLED_CLK_DDR DDRB
// #define TLED_DAT_PORT PORTB
// #define TLED_DAT_DDR DDRB

#include "tinyLED.h"
tinyLED< 3, 4> strip; // < DATA, CLOCK > для 2-пин лент

tinyLED strip;

// #define TLED_SPI_CLOCK 8000000

ПРОГРАММИРОВАНИЕ

// залить 50 ледов жёлтым цветом
strip.begin();
for (byte i = 0; i < 50; i++) strip.send(mYellow);
strip.end();

const int numleds = 100;
strip.begin();
for (int i = 0; i < numleds; i++) strip.send(mWheel8(i * 255 / numleds)); // выводим радугу  
strip.end();

• setBrightness(0-255) - установка яркости всего вывода (отключается дефайном)
• sendRGBW(r,g,b,w) - для RGBW ленты (например WS6812)
• sendBuffer(buf, size) - выводит буфер типа mData длиной size. Смотри пример tinyled_buffer
• clear(size) - гасит указанное количество ледов (там внутри бегин-цикл-енд и всё, просто для удобства сделал)

#include < FastLEDsupport.h> // вкл поддержку FL
DEFINE_GRADIENT_PALETTE( heatmap_gp ) {   // делаем палитру огня
  0,     0,  0,  0,     // black
  128,   255,  0,  0,   // red
  224,   255, 255,  0,  // bright yellow
  255,   255, 255, 255  // full white
};
CRGBPalette16 fire_p = heatmap_gp;

#define TLED_CHIP LED_WS2812
#define TLED_ORDER ORDER_GRB
#define numleds 100
#include < tinyLED.h>
tinyLED< 3> strip;

void setup() {
  strip.setBrightness(100);
}

void loop() {
  static int count = 0;
  count += 10;
  for (int i = 0; i < numleds; i++)
    strip.send(CRGBtoData(ColorFromPalette(fire_p, inoise8(i * 25, count), 255, LINEARBLEND)));
  delay(30);
}