| Line 6... |
Line 6... |
[frame="topbot",grid="none"]
|
[frame="topbot",grid="none"]
|
|=======================
|
|=======================
|
| Hardware source file(s): | neorv32_neoled.vhd |
|
| Hardware source file(s): | neorv32_neoled.vhd |
|
| Software driver file(s): | neorv32_neoled.c |
|
| Software driver file(s): | neorv32_neoled.c |
|
| | neorv32_neoled.h |
|
| | neorv32_neoled.h |
|
| Top entity port: | `neoled_o` | 1-bit serial data
|
| Top entity port: | `neoled_o` | 1-bit serial data output
|
| Configuration generics: | _IO_NEOLED_EN_ | implement NEOLED when _true_
|
| 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>>)
|
| CPU interrupts: | fast IRQ channel 9 | NEOLED interrupt (see <<_processor_interrupts>>)
|
|=======================
|
|=======================
|
|
|
**Theory of Operation**
|
**Theory of Operation**
|
|
|
| Line 23... |
Line 24... |
|
|
[NOTE]
|
[NOTE]
|
The NEOLED interface is compatible to the "Adafruit Industries NeoPixel" products, which feature
|
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).
|
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 LEDs. Since the
|
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)
|
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 also possible.
|
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 _NEOLED_CT_ and the
|
|
TX data register _NEOLED_DATA_. The NEOLED module is globally enabled via the control register's
|
|
_NEOLED_CT_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 _NEOLED_CT_ 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 _NEOLED_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 _NEOLED_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.
|
|
|
|
|
**Theory of Operation – Protocol**
|
**Theory of Operation – Protocol**
|
|
|
The interface of the WS2812 LEDs uses an 800kHz carrier signal. Data is transmitted in a serial manner
|
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 LED chip (= color code) is defined via an 8-bit
|
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
|
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 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"
|
.WS2812 bit-level protocol - taken from the "Adafruit NeoPixel Überguide"
|
image::neopixel.png[align=center]
|
image::neopixel.png[align=center]
|
| Line 49... |
Line 75... |
| T~1H~ | 0.85μs +/- 150ns | high-time for sending a `0`
|
| 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`
|
| T~1L~ | 0.45μs +/- 150 ns | low-time for sending a `0`
|
| RESET | Above 50μs | low-time for sending a RESET command
|
| RESET | Above 50μs | low-time for sending a RESET command
|
|=======================
|
|=======================
|
|
|
**Theory of Operation – NEOLED Module**
|
|
|
|
The NEOLED modules provides two accessible interface register: the control register _NEOLED_CT_ and the
|
|
TX data register _NEOLED_DATA_. The NEOLED module is globally enabled via the control register's
|
|
_NEOLED_CT_EN_ bit. Clearing this bit will terminate any current operation, 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 _NEOLED_CT_ register to provide maximum flexibility.
|
|
|
|
**Timing Configuration**
|
**Timing Configuration**
|
|
|
The basic carrier frequency (800kHz for the WS2812 LEDs) is configured via a 3-bit main clock prescaler (_NEOLED_CT_PRSCx_, see table below)
|
The basic carrier frequency (800kHz for the WS2812 LEDs) is configured via a 3-bit main clock prescaler (_NEOLED_CT_PRSCx_, see table below)
|
that scales the main processor clock f~main~ and a 5-bit cycle multiplier _NEOLED_CT_T_TOT_x_.
|
that scales the main processor clock f~main~ and a 5-bit cycle multiplier _NEOLED_CT_T_TOT_x_.
|
| Line 75... |
Line 94... |
The duty-cycles (or more precisely: the high- and low-times for sending either a '1' bit or a '0' bit) are
|
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_CT_T_ONE_H_x_ and _NEOLED_CT_T_ZERO_H_x_ values, respecively. These programmable
|
defined via the 5-bit _NEOLED_CT_T_ONE_H_x_ and _NEOLED_CT_T_ZERO_H_x_ values, respecively. These programmable
|
timing constants allow to adapt the interface for a wide variety of smart LED protocol (for example WS2812 vs.
|
timing constants allow to adapt the interface for a wide variety of smart LED protocol (for example WS2812 vs.
|
WS2811).
|
WS2811).
|
|
|
|
|
**Timing Configuration – Example (WS2812)**
|
**Timing Configuration – Example (WS2812)**
|
|
|
Generate the base clock f~TX~ for the NEOLED TX engine:
|
Generate the base clock f~TX~ for the NEOLED TX engine:
|
|
|
* processor clock f~main~ = 100 MHz
|
* processor clock f~main~ = 100 MHz
|
| Line 101... |
Line 121... |
_**T~1H~**_ = _**T~TX~**_ * _NEOLED_CT_T_ONE_H_ = 40ns * 20 = 0.8µs
|
_**T~1H~**_ = _**T~TX~**_ * _NEOLED_CT_T_ONE_H_ = 40ns * 20 = 0.8µs
|
|
|
[TIP]
|
[TIP]
|
The NEOLED SW driver library (`neorv32_neoled.h`) provides a simplified configuration
|
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
|
function that configures all timing parameters for driving WS2812 LEDs based on the processor
|
clock configuration.
|
clock frequency.
|
|
|
**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 _NEOLED_DATA_. 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 _NEOLED_DATA_.
|
|
|
|
**TX Data FIFO**
|
**TX Data FIFO**
|
|
|
The interface features a TX data buffer (a FIFO) to allow CPU-independent operation. The buffer depth
|
The interface features a TX data buffer (a FIFO) to allow more CPU-independent operation. The buffer depth
|
is configured via the `tx_buffer_entries_c` constant (default = 4 entries) in the module's VHDL source
|
is configured via the _IO_NEOLED_TX_FIFO_ top generic (default = 1 entry).
|
file `rtl/core/neorv32_neoled.vhd`. The current configuration can be read via the _NEOLED_CT_BUFS_x_
|
The FIFO size configuration can be read via the _NEOLED_CT_BUFS_x_
|
control register bits, which result log2(`tx_buffer_entries_c`).
|
control register bits, which result log2(_IO_NEOLED_TX_FIFO_).
|
|
|
When writing data to the _NEOLED_DATA_ register the data is automatically written to the TX buffer. Whenever
|
When writing data to the _NEOLED_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.
|
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
|
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.
|
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_CT_TX_EMPTY_, _NEOLED_CT_TX_HALF_
|
|
and _NEOLED_CT_TX_FULL_ flags. The _NEOLED_CT_TX_BUSY_ flags provides additional information if the the TX unit is
|
|
still busy sending data.
|
|
|
[WARNING]
|
[WARNING]
|
Please note that the timing configurations (_NEOLED_CT_PRSCx_, _NEOLED_CT_T_TOT_x_,
|
Please note that the timing configurations (_NEOLED_CT_PRSCx_, _NEOLED_CT_T_TOT_x_,
|
_NEOLED_CT_T_ONE_H_x_ and _NEOLED_CT_T_ZERO_H_x_) are NOT stored to the buffer. Changing
|
_NEOLED_CT_T_ONE_H_x_ and _NEOLED_CT_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 sending will cause data corruption.
|
these value while the buffer is not empty or the TX engine is still busy will cause data corruption.
|
|
|
**Status Configuration**
|
|
|
|
The NEOLED modules features two read-only status bits in the control register: _NEOLED_CT_BUSY_ and
|
** Strobe Command ("RESET") **
|
_NEOLED_CT_TX_STATUS_.
|
|
|
|
If the _NEOLED_CT_TX_STATUS_ is set the serial TX engine is still busy sending serial data to the LED stripes.
|
According to the WS2812 specs the data written to the LED's shift registers is strobed to the actual PWM driver
|
If the flag is cleared, the TX engine is idle and the serial data output `neoled_o` is set LOW.
|
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.
|
|
|
The _NEOLED_CT_BUSY_ flag provides a programmable option to check for the TX buffer state. The control
|
To circumvent this, the NEOLED module provides an option to automatically issue an idle time for creating the RESET
|
register's _NEOLED_CT_BSCON_ bit is used to configure the "meaning" of the _NEOLED_CT_BUSY_ flag. The
|
command. If the _NEOLED_CT_STROBE_ control register bit is set, _all_ data written to the data FIFO (via _NEOLED_DATA_,
|
condition for sending an interrupt request (IRQ) to the CPU is also configured via the _NEOLED_CT_BSCON_
|
the actually written data is irrelevant) will trigger an idle phase (`neoled_o` = zero) of 127 periods (= _**T~carrier~**_).
|
bit.
|
This idle time will cause the LEDs to strobe the color data into the PWM driver registers.
|
|
|
[cols="^5,^8,^8"]
|
Since the _NEOLED_CT_STROBE_ flag is also buffered in the TX buffer, the RESET command is treated as just another
|
[options="header",grid="all"]
|
data word being written to the TX buffer making busy wait concepts obsolete and allowing maximum refresh rates.
|
|=======================
|
|
| _NEOLED_CT_BSCON_ | _NEOLED_CT_BUSY_ | Sending an IRQ when ...
|
|
| 0 | the busy flag will clear if there **IS at least one free entry** in the TX buffer | the IRQ will fire if **at least one entry GETS free** in the TX buffer
|
**Interrupt**
|
| 1 | the busy flag will clear if the **whole TX buffer IS empty** | the IRQ will fire if the **whole TX buffer GETS empty**
|
|
|=======================
|
The NEOLED modules features a single interrupt that is triggered whenever the TX FIFO's fill level
|
|
falls below _half-full_ level. In this case software can write up to _IO_NEOLED_TX_FIFO_/2 new data
|
|
words to _NEOLED_DATA_ without checking the FIFO status flags.
|
|
|
|
This highly relaxes time constraints for sending a continuous data stream to the LEDs
|
|
(as an idle time beyond 50μs will trigger the LED's a RESET command).
|
|
|
When _NEOLED_CT_BSCON_ is set, the CPU can write up to `tx_buffer_entries_c` of new data words to
|
|
_NEOLED_DATA_ without checking the busy flag _NEOLED_CT_BUSY_. This highly relaxes time constraints for
|
|
sending a continuous data stream to the LEDs (as an idle time beyond 50μs will trigger the LED's a RESET
|
|
command).
|
|
|
|
|
|
.NEOLED register map
|
.NEOLED register map
|
[cols="<4,<5,<9,^2,<9"]
|
[cols="<4,<5,<9,^2,<9"]
|
[options="header",grid="all"]
|
[options="header",grid="all"]
|
|=======================
|
|=======================
|
| Address | Name [C] | Bit(s), Name [C] | R/W | Function
|
| Address | Name [C] | Bit(s), Name [C] | R/W | Function
|
.22+<| `0xffffffd8` .22+<| _NEOLED_CT_ <|`0` _NEOLED_CT_EN_ ^| r/w <| NEOLED enable
|
.25+<| `0xffffffd8` .25+<| _NEOLED_CT_ <|`0` _NEOLED_CT_EN_ ^| r/w <| NEOLED enable
|
<|`1` _NEOLED_CT_MODE_ ^| r/w <| data transfer size; `0`=24-bit; `1`=32-bit
|
<|`1` _NEOLED_CT_MODE_ ^| r/w <| data transfer size; `0`=24-bit; `1`=32-bit
|
<|`2` _NEOLED_CT_BSCON_ ^| r/w <| busy flag / IRQ trigger configuration (see table above)
|
<|`2` _NEOLED_CT_STROBE_ ^| r/w <| `0`=send normal color data; `1`=send RESET command on data write access
|
<|`3` _NEOLED_CT_PRSC0_ ^| r/w <| 3-bit clock prescaler, bit 0
|
<|`3` _NEOLED_CT_PRSC0_ ^| r/w <| 3-bit clock prescaler, bit 0
|
<|`4` _NEOLED_CT_PRSC1_ ^| r/w <| 3-bit clock prescaler, bit 1
|
<|`4` _NEOLED_CT_PRSC1_ ^| r/w <| 3-bit clock prescaler, bit 1
|
<|`5` _NEOLED_CT_PRSC2_ ^| r/w <| 3-bit clock prescaler, bit 2
|
<|`5` _NEOLED_CT_PRSC2_ ^| r/w <| 3-bit clock prescaler, bit 2
|
<|`6` _NEOLED_CT_BUFS0_ ^| r/- .4+<| 4-bit log2(`tx_buffer_entries_c`)
|
<|`6` _NEOLED_CT_BUFS0_ ^| r/- .4+<| 4-bit log2(_IO_NEOLED_TX_FIFO_)
|
<|`7` _NEOLED_CT_BUFS1_ ^| r/-
|
<|`7` _NEOLED_CT_BUFS1_ ^| r/-
|
<|`8` _NEOLED_CT_BUFS2_ ^| r/-
|
<|`8` _NEOLED_CT_BUFS2_ ^| r/-
|
<|`9` _NEOLED_CT_BUFS3_ ^| r/-
|
<|`9` _NEOLED_CT_BUFS3_ ^| r/-
|
<|`10` _NEOLED_CT_T_TOT_0_ ^| r/w .5+| 5-bit pulse clock ticks per total single-bit period (T~total~)
|
<|`10` _NEOLED_CT_T_TOT_0_ ^| r/w .5+<| 5-bit pulse clock ticks per total single-bit period (T~total~)
|
<|`11` _NEOLED_CT_T_TOT_1_ ^| r/w
|
<|`11` _NEOLED_CT_T_TOT_1_ ^| r/w
|
<|`12` _NEOLED_CT_T_TOT_2_ ^| r/w
|
<|`12` _NEOLED_CT_T_TOT_2_ ^| r/w
|
<|`13` _NEOLED_CT_T_TOT_3_ ^| r/w
|
<|`13` _NEOLED_CT_T_TOT_3_ ^| r/w
|
<|`14` _NEOLED_CT_T_TOT_4_ ^| r/w
|
<|`14` _NEOLED_CT_T_TOT_4_ ^| r/w
|
<|`20` _NEOLED_CT_ONE_H_0_ ^| r/w .5+<| 5-bit pulse clock ticks per high-time for sending a one-bit (T~H1~)
|
<|`20` _NEOLED_CT_ONE_H_0_ ^| r/w .5+<| 5-bit pulse clock ticks per high-time for sending a one-bit (T~H1~)
|
<|`21` _NEOLED_CT_ONE_H_1_ ^| r/w
|
<|`21` _NEOLED_CT_ONE_H_1_ ^| r/w
|
<|`22` _NEOLED_CT_ONE_H_2_ ^| r/w
|
<|`22` _NEOLED_CT_ONE_H_2_ ^| r/w
|
<|`23` _NEOLED_CT_ONE_H_3_ ^| r/w
|
<|`23` _NEOLED_CT_ONE_H_3_ ^| r/w
|
<|`24` _NEOLED_CT_ONE_H_4_ ^| r/w
|
<|`24` _NEOLED_CT_ONE_H_4_ ^| r/w
|
<|`30` _NEOLED_CT_TX_STATUS_ ^| r/- <| transmit engine busy when `1`
|
<|`30` _NEOLED_CT_TX_STATUS_ ^| r/- <| transmit engine busy when `1`
|
<|`31` _NEOLED_CT_BUSY_ ^| r/- <| busy / buffer status flag; configured via _NEOLED_CT_BSCON_ (see table above)
|
<|`31` _NEOLED_CT_TX_EMPTY_ ^| r/- <| TX FIFO is empty
|
|
<|`31` _NEOLED_CT_TX_HALF_ ^| r/- <| TX FIFO is _at least_ half full
|
|
<|`31` _NEOLED_CT_TX_FULL_ ^| r/- <| TX FIFO is full
|
|
<|`31` _NEOLED_CT_TX_BUSY_ ^| r/- <| TX serial engine is busy when set
|
| `0xffffffdc` | _NEOLED_DATA_ <|`31:0` / `23:0` ^| -/w <| TX data (32-/24-bit)
|
| `0xffffffdc` | _NEOLED_DATA_ <|`31:0` / `23:0` ^| -/w <| TX data (32-/24-bit)
|
|=======================
|
|=======================
|
