226 lines
13 KiB
Text
226 lines
13 KiB
Text
<<<
|
|
:sectnums:
|
|
==== Smart LED Interface (NEOLED)
|
|
|
|
[cols="<3,<3,<4"]
|
|
[frame="topbot",grid="none"]
|
|
|=======================
|
|
| Hardware source file(s): | neorv32_neoled.vhd |
|
|
| Software driver file(s): | neorv32_neoled.c |
|
|
| | neorv32_neoled.h |
|
|
| Top entity port: | `neoled_o` | 1-bit serial data output
|
|
| Configuration generics: | _IO_NEOLED_EN_ | implement NEOLED when _true_
|
|
| | _IO_NEOLED_TX_FIFO_ | TX FIFO depth (1..32k, has to be a power of two)
|
|
| CPU interrupts: | fast IRQ channel 9 | NEOLED interrupt (see <<_processor_interrupts>>)
|
|
|=======================
|
|
|
|
|
|
**Theory of Operation**
|
|
|
|
The NEOLED module provides a dedicated interface for "smart RGB LEDs" like the WS2812 or WS2811.
|
|
These LEDs provide a single interface wire that uses an asynchronous serial protocol for transmitting color
|
|
data. Basically, data is transferred via LED-internal shift registers, which allows to cascade an unlimited
|
|
number of smart LEDs. The protocol provides a RESET command to strobe the transmitted data into the
|
|
LED PWM driver registers after data has shifted throughout all LEDs in a chain.
|
|
|
|
[NOTE]
|
|
The NEOLED interface is compatible to the "Adafruit Industries NeoPixel" products, which feature
|
|
WS2812 (or older WS2811) smart LEDs (see link:https://learn.adafruit.com/adafruit-neopixel-uberguide).
|
|
|
|
The interface provides a single 1-bit output `neoled_o` to drive an arbitrary number of cascaded LEDs. Since the
|
|
NEOLED module provides 24-bit and 32-bit operating modes, a mixed setup with RGB LEDs (24-bit color)
|
|
and RGBW LEDs (32-bit color including a dedicated white LED chip) is possible.
|
|
|
|
|
|
**Theory of Operation - NEOLED Module**
|
|
|
|
The NEOLED modules provides two accessible interface registers: the control register `CTRL` and the
|
|
TX data register `DATA`. The NEOLED module is globally enabled via the control register's
|
|
_NEOLED_CTRL_EN_ bit. Clearing this bit will terminate any current operation, clear the TX buffer, reset the module
|
|
and set the `neoled_o` output to zero. The precise timing (implementing the **WS2812** protocol) and transmission
|
|
mode are fully programmable via the `CTRL` register to provide maximum flexibility.
|
|
|
|
|
|
**RGB / RGBW Configuration**
|
|
|
|
NeoPixel are available in two "color" version: LEDs with three chips providing RGB color and LEDs with
|
|
four chips providing RGB color plus a dedicated white LED chip (= RGBW). Since the intensity of every
|
|
LED chip is defined via an 8-bit value the RGB LEDs require a frame of 24-bit per module and the RGBW
|
|
LEDs require a frame of 32-bit per module.
|
|
|
|
The data transfer quantity of the NEOLED module can be configured via the _NEOLED_MODE_EN_ control
|
|
register bit. If this bit is cleared, the NEOLED interface operates in 24-bit mode and will transmit bits `23:0` of
|
|
the data written to `DATA` to the LEDs. If _NEOLED_MODE_EN_ is set, the NEOLED interface operates in 32-bit
|
|
mode and will transmit bits `31:0` of the data written to `DATA` to the LEDs.
|
|
|
|
The mode bit can be configured before writing each new data word in order to support
|
|
an arbitrary setup of RGB and RGBW LEDs.
|
|
|
|
|
|
**Protocol**
|
|
|
|
The interface of the WS2812 LEDs uses an 800kHz carrier signal. Data is transmitted in a serial manner
|
|
starting with LSB-first. The intensity for each R, G & B (& W) LED chip (= color code) is defined via an 8-bit
|
|
value. The actual data bits are transferred by modifying the duty cycle of the signal (the timings for the
|
|
WS2812 are shown below). A RESET command is "send" by pulling the data line LOW for at least 50μs.
|
|
|
|
.WS2812 bit-level protocol - taken from the "Adafruit NeoPixel Überguide"
|
|
image::neopixel.png[align=center]
|
|
|
|
.WS2812 interface timing
|
|
[cols="<2,<2,<6"]
|
|
[grid="all"]
|
|
|=======================
|
|
| T~total~ (T~carrier~) | 1.25μs +/- 300ns | period for a single bit
|
|
| T~0H~ | 0.4μs +/- 150ns | high-time for sending a `1`
|
|
| T~0L~ | 0.8μs +/- 150ns | low-time for sending a `1`
|
|
| T~1H~ | 0.85μs +/- 150ns | high-time for sending a `0`
|
|
| T~1L~ | 0.45μs +/- 150 ns | low-time for sending a `0`
|
|
| RESET | Above 50μs | low-time for sending a RESET command
|
|
|=======================
|
|
|
|
|
|
**Timing Configuration**
|
|
|
|
The basic carrier frequency (800kHz for the WS2812 LEDs) is configured via a 3-bit main clock prescaler (_NEOLED_CTRL_PRSCx_, see table below)
|
|
that scales the main processor clock f~main~ and a 5-bit cycle multiplier _NEOLED_CTRL_T_TOT_x_.
|
|
|
|
.NEOLED prescaler configuration
|
|
[cols="<4,^1,^1,^1,^1,^1,^1,^1,^1"]
|
|
[options="header",grid="rows"]
|
|
|=======================
|
|
| **`NEOLED_CTRL_PRSCx`** | `0b000` | `0b001` | `0b010` | `0b011` | `0b100` | `0b101` | `0b110` | `0b111`
|
|
| Resulting `clock_prescaler` | 2 | 4 | 8 | 64 | 128 | 1024 | 2048 | 4096
|
|
|=======================
|
|
|
|
The duty-cycles (or more precisely: the high- and low-times for sending either a '1' bit or a '0' bit) are
|
|
defined via the 5-bit _NEOLED_CTRL_T_ONE_H_x_ and _NEOLED_CTRL_T_ZERO_H_x_ values, respectively. These programmable
|
|
timing constants allow to adapt the interface for a wide variety of smart LED protocol (for example WS2812 vs.
|
|
WS2811).
|
|
|
|
|
|
**Timing Configuration - Example (WS2812)**
|
|
|
|
Generate the base clock f~TX~ for the NEOLED TX engine:
|
|
|
|
* processor clock f~main~ = 100 MHz
|
|
* _NEOLED_CTRL_PRSCx_ = `0b001` = f~main~ / 4
|
|
|
|
_**f~TX~**_ = _f~main~[Hz]_ / `clock_prescaler` = 100MHz / 4 = 25MHz
|
|
|
|
_**T~TX~**_ = 1 / _**f~TX~**_ = 40ns
|
|
|
|
Generate carrier period (T~carrier~) and *high-times* (duty cycle) for sending `0` (T~0H~) and `1` (T~1H~) bits:
|
|
|
|
* _NEOLED_CTRL_T_TOT_ = `0b11110` (= decimal 30)
|
|
* _NEOLED_CTRL_T_ZERO_H_ = `0b01010` (= decimal 10)
|
|
* _NEOLED_CTRL_T_ONE_H_ = `0b10100` (= decimal 20)
|
|
|
|
_**T~carrier~**_ = _**T~TX~**_ * _NEOLED_CTRL_T_TOT_ = 40ns * 30 = 1.4µs
|
|
|
|
_**T~0H~**_ = _**T~TX~**_ * _NEOLED_CTRL_T_ZERO_H_ = 40ns * 10 = 0.4µs
|
|
|
|
_**T~1H~**_ = _**T~TX~**_ * _NEOLED_CTRL_T_ONE_H_ = 40ns * 20 = 0.8µs
|
|
|
|
[TIP]
|
|
The NEOLED SW driver library (`neorv32_neoled.h`) provides a simplified configuration
|
|
function that configures all timing parameters for driving WS2812 LEDs based on the processor
|
|
clock frequency.
|
|
|
|
|
|
**TX Data FIFO**
|
|
|
|
The interface features a TX data buffer (a FIFO) to allow more CPU-independent operation. The buffer depth
|
|
is configured via the _IO_NEOLED_TX_FIFO_ top generic (default = 1 entry).
|
|
The FIFO size configuration can be read via the _NEOLED_CTRL_BUFS_x_
|
|
control register bits, which result log2(_IO_NEOLED_TX_FIFO_).
|
|
|
|
When writing data to the `DATA` register the data is automatically written to the TX buffer. Whenever
|
|
data is available in the buffer the serial transmission engine will take it and transmit it to the LEDs.
|
|
The data transfer size (_NEOLED_MODE_EN_) can be modified at every time since this control register bit is also buffered
|
|
in the FIFO. This allows to arbitrarily mixing RGB and RGBW LEDs in the chain.
|
|
|
|
Software can check the FIFO fill level via the control register's _NEOLED_CTRL_TX_EMPTY_, _NEOLED_CTRL_TX_HALF_
|
|
and _NEOLED_CTRL_TX_FULL_ flags. The _NEOLED_CTRL_TX_BUSY_ flags provides additional information if the the TX unit is
|
|
still busy sending data.
|
|
|
|
[WARNING]
|
|
Please note that the timing configurations (_NEOLED_CTRL_PRSCx_, _NEOLED_CTRL_T_TOT_x_,
|
|
_NEOLED_CTRL_T_ONE_H_x_ and _NEOLED_CTRL_T_ZERO_H_x_) are **NOT** stored to the buffer. Changing
|
|
these value while the buffer is not empty or the TX engine is still busy will cause data corruption.
|
|
|
|
|
|
**Strobe Command ("RESET")**
|
|
|
|
According to the WS2812 specs the data written to the LED's shift registers is strobed to the actual PWM driver
|
|
registers when the data line is low for 50μs ("RESET" command, see table above). This can be implemented
|
|
using busy-wait for at least 50μs. Obviously, this concept wastes a lot of processing power.
|
|
|
|
To circumvent this, the NEOLED module provides an option to automatically issue an idle time for creating the RESET
|
|
command. If the _NEOLED_CTRL_STROBE_ control register bit is set, _all_ data written to the data FIFO (via `DATA`,
|
|
the actually written data is irrelevant) will trigger an idle phase (`neoled_o` = zero) of 127 periods (= _**T~carrier~**_).
|
|
This idle time will cause the LEDs to strobe the color data into the PWM driver registers.
|
|
|
|
Since the _NEOLED_CTRL_STROBE_ flag is also buffered in the TX buffer, the RESET command is treated just as another
|
|
data word being written to the TX buffer making busy wait concepts obsolete and allowing maximum refresh rates.
|
|
|
|
|
|
**NEOLED Interrupt**
|
|
|
|
The NEOLED modules features a single interrupt that becomes pending based on the current TX buffer fill level.
|
|
The interrupt can only become pending if the NEOLED module is enabled. The specific interrupt condition
|
|
is configured via the _NEOLED_CTRL_IRQ_CONF_ bit in the unit's control register.
|
|
|
|
If _NEOLED_CTRL_IRQ_CONF_ is cleared, an interrupt is generated whenever the TX FIFO _becomes_ less than half-full.
|
|
In this case software can write up to _IO_NEOLED_TX_FIFO_/2 new data words to `DATA` without checking the FIFO
|
|
status flags. If _NEOLED_CTRL_IRQ_CONF_ is set, an interrupt is generated whenever the TX FIFO _becomes_ empty.
|
|
|
|
One the NEOLED interrupt has been triggered and became pending, it has to explicitly cleared again by
|
|
writing zero to according <<_mip>> CSR bit.
|
|
|
|
[NOTE]
|
|
The _NEOLED_CTRL_IRQ_CONF_ is hardwired to one if _IO_NEOLED_TX_FIFO_ = 1 (-> IRQ if FIFO is empty).
|
|
If the FIFO is configured to contain only a single entry (_IO_NEOLED_TX_FIFO_ = 1) the interrupt
|
|
will become pending if the FIFO (which is just a single register providing simple _double-buffering_) is empty.
|
|
|
|
|
|
**Register Map**
|
|
|
|
<<<
|
|
.NEOLED register map (`struct NEORV32_NEOLED`)
|
|
[cols="<4,<5,<9,^2,<9"]
|
|
[options="header",grid="all"]
|
|
|=======================
|
|
| Address | Name [C] | Bit(s), Name [C] | R/W | Function
|
|
.30+<| `0xffffffd8` .30+<| `NEORV32_NEOLED.CTRL` <|`0` _NEOLED_CTRL_EN_ ^| r/w <| NEOLED enable
|
|
<|`1` _NEOLED_CTRL_MODE_ ^| r/w <| data transfer size; `0`=24-bit; `1`=32-bit
|
|
<|`2` _NEOLED_CTRL_STROBE_ ^| r/w <| `0`=send normal color data; `1`=send RESET command on data write access
|
|
<|`3` _NEOLED_CTRL_PRSC0_ ^| r/w <| 3-bit clock prescaler, bit 0
|
|
<|`4` _NEOLED_CTRL_PRSC1_ ^| r/w <| 3-bit clock prescaler, bit 1
|
|
<|`5` _NEOLED_CTRL_PRSC2_ ^| r/w <| 3-bit clock prescaler, bit 2
|
|
<|`6` _NEOLED_CTRL_BUFS0_ ^| r/- .4+<| 4-bit log2(_IO_NEOLED_TX_FIFO_)
|
|
<|`7` _NEOLED_CTRL_BUFS1_ ^| r/-
|
|
<|`8` _NEOLED_CTRL_BUFS2_ ^| r/-
|
|
<|`9` _NEOLED_CTRL_BUFS3_ ^| r/-
|
|
<|`10` _NEOLED_CTRL_T_TOT_0_ ^| r/w .5+<| 5-bit pulse clock ticks per total single-bit period (T~total~)
|
|
<|`11` _NEOLED_CTRL_T_TOT_1_ ^| r/w
|
|
<|`12` _NEOLED_CTRL_T_TOT_2_ ^| r/w
|
|
<|`13` _NEOLED_CTRL_T_TOT_3_ ^| r/w
|
|
<|`14` _NEOLED_CTRL_T_TOT_4_ ^| r/w
|
|
<|`15` _NEOLED_CTRL_T_ZERO_H_0_ ^| r/w .5+<| 5-bit pulse clock ticks per high-time for sending a zero-bit (T~0H~)
|
|
<|`16` _NEOLED_CTRL_T_ZERO_H_1_ ^| r/w
|
|
<|`17` _NEOLED_CTRL_T_ZERO_H_2_ ^| r/w
|
|
<|`18` _NEOLED_CTRL_T_ZERO_H_3_ ^| r/w
|
|
<|`19` _NEOLED_CTRL_T_ZERO_H_4_ ^| r/w
|
|
<|`20` _NEOLED_CTRL_T_ONE_H_0_ ^| r/w .5+<| 5-bit pulse clock ticks per high-time for sending a one-bit (T~1H~)
|
|
<|`21` _NEOLED_CTRL_T_ONE_H_1_ ^| r/w
|
|
<|`22` _NEOLED_CTRL_T_ONE_H_2_ ^| r/w
|
|
<|`23` _NEOLED_CTRL_T_ONE_H_3_ ^| r/w
|
|
<|`24` _NEOLED_CTRL_T_ONE_H_4_ ^| r/w
|
|
<|`27` _NEOLED_CTRL_IRQ_CONF_ ^| r/w <| TX FIFO interrupt configuration: `0`=IRQ if FIFO is less than half-full, `1`=IRQ if FIFO is empty
|
|
<|`28` _NEOLED_CTRL_TX_EMPTY_ ^| r/- <| TX FIFO is empty
|
|
<|`29` _NEOLED_CTRL_TX_HALF_ ^| r/- <| TX FIFO is _at least_ half full
|
|
<|`30` _NEOLED_CTRL_TX_FULL_ ^| r/- <| TX FIFO is full
|
|
<|`31` _NEOLED_CTRL_TX_BUSY_ ^| r/- <| TX serial engine is busy when set
|
|
| `0xffffffdc` | `NEORV32_NEOLED.DATA` <|`31:0` / `23:0` ^| -/w <| TX data (32-/24-bit)
|
|
|=======================
|