Перейти к содержанию
Материалы раздела

neopixel: адресные светодиодные ленты

Модуль neopixel контроллера С3: управление лентами WS2811, WS2812 и WS2812B на клеммах IO5–IO8, цвет и яркость пикселей, заливка, сдвиг, градиент и подключение ленты.

Модуль neopixel управляет адресными RGB-лентами WS2811, WS2812 и WS2812B. Lua задаёт цвета, а точные временные интервалы сигнала формирует аппаратура контроллера. Ленту можно подключить к любой из клемм IO5–IO8, одновременно — до четырёх лент.

local neopixel = require("neopixel")
local strip <close> = assert(neopixel.attach(neopixel.WS2811, 5, 30))
assert(strip:setBrightness(0.15))
assert(strip:fill(0, 30, 255, 0, 0, true))   -- вся лента красная

Пиксели нумеруются с нуля. Номер IO совпадает с надписью на плате. У ленты WS2811, где одна микросхема управляет группой светодиодов, пиксель — это группа, а не отдельный светодиод.

Функции и методы

Функция или методДействие
neopixel.attach(type, io, pixels [, order])создать объект ленты, занять IO и выдать низкий уровень
neopixel.setup(...)то же, что attach
strip:setPixel(index, r, g, b [, update])задать цвет одного пикселя
strip:fill(first, last, r, g, b [, update])залить пиксели от first до last, не включая last
strip:update()передать кадр на ленту
strip:setBrightness(value)яркость 0–1 для последующих изменений пикселей
strip:fade(value [, update])применить яркость 0–1 ко всем пикселям
strip:shift(right [, update])циклический сдвиг: true — вправо, false — влево
strip:gradient(first, last [, update])плавный переход между цветами пикселей first и last, оба включительно
strip:getPixel(index [, original])r, g, b; с original = true — цвет без учёта яркости
strip:close()освободить IO и перевести его во вход
neopixel.hsvToRgb(h, s, v)перевести HSV 0–1 в три целых RGB 0–255
  • Цвета задаются целыми 0–255.
  • С update = true метод сразу отправляет кадр. Без него изменения накапливаются до вызова update(): так удобно менять много пикселей за один кадр.
  • В fill значение last больше длины ленты ограничивается длиной.
  • setBrightness() влияет только на пиксели, которые меняются после вызова. fade() пересчитывает все пиксели от исходных цветов, поэтому уменьшение и последующее увеличение яркости не накапливают ошибку.
  • Длина одной ленты — до 256 пикселей. Каждый пиксель занимает 6 байт памяти программы, поэтому общая длина всех лент ограничена свободной памятью.

Успешные методы возвращают true, аппаратные ошибки — nil, errno, сообщение. Если IO уже занят, attach возвращает EBUSY. После close() методы возвращают EBADF. Пока IO принадлежит ленте, odkit.io и zephyr.gpio не могут им управлять.

Типы лент

КонстантаСкоростьПорядок цветов по умолчанию
neopixel.WS2812B800 кбит/сGRB
neopixel.WS2812800 кбит/сGRB
neopixel.WS2811800 кбит/сRGB
neopixel.WS2811_400400 кбит/сRGB

Если цвета на ленте перепутаны, передайте порядок четвёртым аргументом attach: любую перестановку букв "RGB", например "GRB" или "BRG".

Эффект «бегущая радуга»

local neopixel = require("neopixel")
local task = require("zephyr.task")
local N = 30

local strip = assert(neopixel.attach(neopixel.WS2812B, 5, N))
assert(strip:setBrightness(0.2))
for i = 0, N - 1 do
  local r, g, b = neopixel.hsvToRgb(i / N, 1, 1)
  strip:setPixel(i, r, g, b)
end
assert(strip:update())

while true do
  assert(strip:shift(true, true))
  task.sleep(50)
end

Передача кадра занимает время, пропорциональное длине ленты, и на это время останавливает другие задачи. На скорости 800 кбит/с кадр из 30 пикселей передаётся примерно за 1,2 мс, из 256 пикселей — примерно за 8 мс. Учитывайте это при выборе частоты обновления.

Подключение

  • Соедините клемму IO с входом DIN ленты, а землю контроллера — с землёй ленты.
  • Питайте ленту от отдельного источника подходящего напряжения и мощности, а не от контроллера.
  • Проверьте, какой уровень сигнала требует DIN вашей ленты, и сравните с уровнем выхода клеммы в характеристиках контроллера.
  • Провод от контроллера до ленты делайте коротким. Для длинной линии поставьте подходящий буфер или преобразователь уровня рядом с контроллером.

Если на клеммах стоят тестовые перемычки, например IO5–IO7, снимите их перед подключением ленты.