/*
* Copyright (c) 2022 Jonathan Rico
*
* Adapted from the SPI driver, using the procedure in this blog post:
* https://electronut.in/nrf52-i2s-ws2812/
*
* Note: the word "word" refers to a 32-bit integer unless otherwise stated.
*
* WS/LRCK frequency:
* This refers to the "I2S word or channel select" clock.
* The I2S peripheral sends two 16-bit channel values for each clock period.
* A single LED color (8 data bits) will take up one 32-bit word or one LRCK
* period. This means a standard RGB led will take 3 LRCK periods to transmit.
*
* SPDX-License-Identifier: Apache-2.0
*/
#define DT_DRV_COMPAT worldsemi_ws2812_i2s
#include <zephyr/drivers/led_strip.h>
#define LOG_LEVEL CONFIG_LED_STRIP_LOG_LEVEL
#include <zephyr/logging/log.h>
LOG_MODULE_REGISTER(ws2812_i2s);
#include <zephyr/device.h>
#include <zephyr/drivers/i2s.h>
#include <zephyr/dt-bindings/led/led.h>
#include <zephyr/kernel.h>
#include <zephyr/sys/util.h>
#define WS2812_I2S_PRE_DELAY_WORDS 1
struct ws2812_i2s_cfg {
struct device const *dev;
size_t tx_buf_bytes;
struct k_mem_slab *mem_slab;
uint8_t num_colors;
size_t length;
const uint8_t *color_mapping;
uint16_t reset_words;
uint32_t lrck_period;
uint32_t extra_wait_time_us;
bool active_low;
uint8_t nibble_one;
uint8_t nibble_zero;
};
/* Serialize an 8-bit color channel value into two 16-bit I2S values (or 1 32-bit
* word).
*/
static inline uint32_t ws2812_i2s_ser(uint8_t color, const uint8_t sym_one, const uint8_t sym_zero)
{
uint32_t word = 0;
for (uint_fast8_t mask = 0x80; mask != 0; mask >>= 1) {
word <<= 4;
word |= (color & mask) ? sym_one : sym_zero;
}
/* Swap the two I2S values due to the (audio) channel TX order. */
return (word >> 16) | (word << 16);
}
static int ws2812_strip_update_rgb(const struct device *dev, struct led_rgb *pixels,
size_t num_pixels)
{
const struct ws2812_i2s_cfg *cfg = dev->config;
const uint8_t sym_one = cfg->nibble_one;
const uint8_t sym_zero = cfg->nibble_zero;
const uint32_t reset_word = cfg->active_low ? ~0 : 0;
uint32_t *tx_buf;
uint32_t flush_time_us;
void *mem_block;
int ret;
/* Acquire memory for the I2S payload. */
ret = k_mem_slab_alloc(cfg->mem_slab, &mem_block, K_SECONDS(10));
if (ret < 0) {
LOG_ERR("Unable to allocate mem slab for TX (err %d)", ret);
return -ENOMEM;
}
tx_buf = (uint32_t *)mem_block;
/* Add a pre-data reset, so the first pixel isn't skipped by the strip. */
for (uint16_t i = 0; i < WS2812_I2S_PRE_DELAY_WORDS; i++) {
*tx_buf = reset_word;
tx_buf++;
}
/*
* Convert pixel data into I2S frames. Each frame has pixel data
* in color mapping on-wire format (e.g. GRB, GRBW, RGB, etc).
*/
for (uint16_t i = 0; i < num_pixels; i++) {
for (uint16_t j = 0; j < cfg->num_colors; j++) {
uint8_t pixel;
switch (cfg->color_mapping[j]) {
/* White channel is not supported by LED strip API. */
case LED_COLOR_ID_WHITE:
pixel = 0;
break;
case LED_COLOR_ID_RED:
pixel = pixels[i].r;
break;
case LED_COLOR_ID_GREEN:
pixel = pixels[i].g;
break;
case LED_COLOR_ID_BLUE:
pixel = pixels[i].b;
break;
default:
return -EINVAL;
}
*tx_buf = ws2812_i2s_ser(pixel, sym_one, sym_zero) ^ reset_word;
tx_buf++;
}
}
for (uint16_t i = 0; i < cfg->reset_words; i++) {
*tx_buf = reset_word;
tx_buf++;
}
/* Flush the buffer on the wire. */
ret = i2s_write(cfg->dev, mem_block, cfg->tx_buf_bytes);
if (ret < 0) {
k_mem_slab_free(cfg->mem_slab, mem_block);
LOG_ERR("Failed to write data: %d", ret);
return ret;
}
ret = i2s_trigger(cfg->dev, I2S_DIR_TX, I2S_TRIGGER_START);
if (ret < 0) {
LOG_ERR("Failed to trigger command %d on TX: %d", I2S_TRIGGER_START, ret);
return ret;
}
ret = i2s_trigger(cfg->dev, I2S_DIR_TX, I2S_TRIGGER_DRAIN);
if (ret < 0) {
LOG_ERR("Failed to trigger command %d on TX: %d", I2S_TRIGGER_DRAIN, ret);
return ret;
}
/* Wait until transaction is over */
flush_time_us = cfg->lrck_period * cfg->tx_buf_bytes / sizeof(uint32_t);
k_usleep(flush_time_us + cfg->extra_wait_time_us);
return ret;
}
static size_t ws2812_strip_length(const struct device *dev)
{
const struct ws2812_i2s_cfg *cfg = dev->config;
return cfg->length;
}
static int ws2812_i2s_init(const struct device *dev)
{
const struct ws2812_i2s_cfg *cfg = dev->config;
struct i2s_config config;
uint32_t lrck_hz;
int ret;
lrck_hz = USEC_PER_SEC / cfg->lrck_period;
LOG_DBG("Word clock: freq %u Hz period %u us",
lrck_hz, cfg->lrck_period);
/* 16-bit stereo, 100kHz LCLK */
config.word_size = 16;
config.channels = 2;
config.format = I2S_FMT_DATA_FORMAT_I2S;
config.options = I2S_OPT_BIT_CLK_MASTER | I2S_OPT_FRAME_CLK_MASTER;
config.frame_clk_freq = lrck_hz; /* WS (or LRCK) */
config.mem_slab = cfg->mem_slab;
config.block_size = cfg->tx_buf_bytes;
config.timeout = 1000;
ret = i2s_configure(cfg->dev, I2S_DIR_TX, &config);
if (ret < 0) {
LOG_ERR("Failed to configure I2S device: %d\n", ret);
return ret;
}
for (uint16_t i = 0; i < cfg->num_colors; i++) {
switch (cfg->color_mapping[i]) {
case LED_COLOR_ID_WHITE:
case LED_COLOR_ID_RED:
case LED_COLOR_ID_GREEN:
case LED_COLOR_ID_BLUE:
break;
default:
LOG_ERR("%s: invalid channel to color mapping."
"Check the color-mapping DT property",
dev->name);
return -EINVAL;
}
}
return 0;
}
static DEVICE_API(led_strip, ws2812_i2s_api) = {
.update_rgb = ws2812_strip_update_rgb,
.length = ws2812_strip_length,
};
#define WS2812_I2S_LRCK_PERIOD_US(idx) DT_INST_PROP(idx, lrck_period)
#define WS2812_RESET_DELAY_US(idx) DT_INST_PROP(idx, reset_delay)
/* Rounds up to the next 20us. */
#define WS2812_RESET_DELAY_WORDS(idx) \
DIV_ROUND_UP(WS2812_RESET_DELAY_US(idx), WS2812_I2S_LRCK_PERIOD_US(idx))
#define WS2812_NUM_COLORS(idx) (DT_INST_PROP_LEN(idx, color_mapping))
#define WS2812_I2S_NUM_PIXELS(idx) (DT_INST_PROP(idx, chain_length))
#define WS2812_I2S_BUFSIZE(idx) \
(((WS2812_NUM_COLORS(idx) * WS2812_I2S_NUM_PIXELS(idx)) + \
WS2812_I2S_PRE_DELAY_WORDS + WS2812_RESET_DELAY_WORDS(idx)) * 4)
#define WS2812_I2S_DEVICE(idx) \
\
K_MEM_SLAB_DEFINE_STATIC(ws2812_i2s_##idx##_slab, WS2812_I2S_BUFSIZE(idx), 2, 4); \
\
static const uint8_t ws2812_i2s_##idx##_color_mapping[] = \
DT_INST_PROP(idx, color_mapping); \
\
static const struct ws2812_i2s_cfg ws2812_i2s_##idx##_cfg = { \
.dev = DEVICE_DT_GET(DT_INST_BUS(idx)), \
.tx_buf_bytes = WS2812_I2S_BUFSIZE(idx), \
.mem_slab = &ws2812_i2s_##idx##_slab, \
.num_colors = WS2812_NUM_COLORS(idx), \
.length = DT_INST_PROP(idx, chain_length), \
.color_mapping = ws2812_i2s_##idx##_color_mapping, \
.lrck_period = WS2812_I2S_LRCK_PERIOD_US(idx), \
.extra_wait_time_us = DT_INST_PROP(idx, extra_wait_time), \
.reset_words = WS2812_RESET_DELAY_WORDS(idx), \
.active_low = DT_INST_PROP(idx, out_active_low), \
.nibble_one = DT_INST_PROP(idx, nibble_one), \
.nibble_zero = DT_INST_PROP(idx, nibble_zero), \
}; \
\
DEVICE_DT_INST_DEFINE(idx, ws2812_i2s_init, NULL, NULL, &ws2812_i2s_##idx##_cfg, \
POST_KERNEL, CONFIG_LED_STRIP_INIT_PRIORITY, &ws2812_i2s_api);
DT_INST_FOREACH_STATUS_OKAY(WS2812_I2S_DEVICE)