Skip to content

Commit 3dd7a84

Browse files
GadgetoidGadgetoid
committed
Fixed README
1 parent 5322862 commit 3dd7a84

File tree

1 file changed

+117
-96
lines changed

1 file changed

+117
-96
lines changed

‎library/README.rst

Lines changed: 117 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -1,150 +1,171 @@
1-
rpi_ws281x
2-
==========
3-
4-
Userspace Raspberry Pi library for controlling WS281X LEDs.
5-
This includes WS2812 and SK6812RGB RGB LEDs
6-
Preliminary support is now included for SK6812RGBW LEDs (yes, RGB + W)
7-
The LEDs can be controlled by either the PWM (2 independent channels)
8-
or PCM controller (1 channel) or the SPI interface (1 channel).
9-
10-
### Background:
11-
12-
The BCM2835 in the Raspberry Pi has both a PWM and a PCM module that
13-
are well suited to driving individually controllable WS281X LEDs.
14-
Using the DMA, PWM or PCM FIFO, and serial mode in the PWM, it's
15-
possible to control almost any number of WS281X LEDs in a chain connected
16-
to the appropriate output pin.
17-
For SPI the Raspbian spidev driver is used (`/dev/spidev0.0`).
18-
This library and test program set the clock rate to 3X the desired output
19-
frequency and creates a bit pattern in RAM from an array of colors where
20-
each bit is represented by 3 bits as follows.
1+
rpi\_ws281x
2+
===========
3+
4+
Userspace Raspberry Pi library for controlling WS281X LEDs. This
5+
includes WS2812 and SK6812RGB RGB LEDs Preliminary support is now
6+
included for SK6812RGBW LEDs (yes, RGB + W) The LEDs can be controlled
7+
by either the PWM (2 independent channels) or PCM controller (1 channel)
8+
or the SPI interface (1 channel).
9+
10+
Background:
11+
-----------
12+
13+
The BCM2835 in the Raspberry Pi has both a PWM and a PCM module that are
14+
well suited to driving individually controllable WS281X LEDs. Using the
15+
DMA, PWM or PCM FIFO, and serial mode in the PWM, it's possible to
16+
control almost any number of WS281X LEDs in a chain connected to the
17+
appropriate output pin. For SPI the Raspbian spidev driver is used
18+
(``/dev/spidev0.0``). This library and test program set the clock rate
19+
to 3X the desired output frequency and creates a bit pattern in RAM from
20+
an array of colors where each bit is represented by 3 bits as follows.
21+
22+
::
2123

2224
Bit 1 - 1 1 0
2325
Bit 0 - 1 0 0
2426

27+
GPIO Usage:
28+
-----------
2529

26-
### GPIO Usage:
27-
28-
The GPIOs that can be used are limited by the hardware of the Pi and will
29-
vary based on the method used to drive them (PWM, PCM or SPI).
30-
Beware that the GPIO numbers are not the same as the physical pin numbers
31-
on the header.
30+
The GPIOs that can be used are limited by the hardware of the Pi and
31+
will vary based on the method used to drive them (PWM, PCM or SPI).
32+
Beware that the GPIO numbers are not the same as the physical pin
33+
numbers on the header.
3234

3335
PWM:
34-
```
35-
PWM0, which can be set to use GPIOs 12, 18, 40, and 52.
36-
Only 12 (pin 32) and 18 (pin 12) are available on the B+/2B/3B
3736

38-
PWM1 which can be set to use GPIOs 13, 19, 41, 45 and 53.
39-
Only 13 is available on the B+/2B/PiZero/3B, on pin 33
40-
```
37+
::
38+
39+
PWM0, which can be set to use GPIOs 12, 18, 40, and 52.
40+
Only 12 (pin 32) and 18 (pin 12) are available on the B+/2B/3B
41+
42+
PWM1 which can be set to use GPIOs 13, 19, 41, 45 and 53.
43+
Only 13 is available on the B+/2B/PiZero/3B, on pin 33
4144

4245
PCM:
43-
```
44-
PCM_DOUT, which can be set to use GPIOs 21 and 31.
45-
Only 21 is available on the B+/2B/PiZero/3B, on pin 40.
46-
```
46+
47+
::
48+
49+
PCM_DOUT, which can be set to use GPIOs 21 and 31.
50+
Only 21 is available on the B+/2B/PiZero/3B, on pin 40.
4751

4852
SPI:
49-
```
50-
SPI0-MOSI is available on GPIOs 10 and 38.
51-
Only GPIO 10 is available on all models.
52-
See also note for RPi 3 below.
53-
```
5453

54+
::
55+
56+
SPI0-MOSI is available on GPIOs 10 and 38.
57+
Only GPIO 10 is available on all models.
58+
See also note for RPi 3 below.
5559

56-
### Power and voltage requirements
60+
Power and voltage requirements
61+
------------------------------
5762

58-
WS281X LEDs are generally driven at 5V. Depending on your actual
59-
LED model and data line length you might be able to successfully drive
60-
the data input with 3.3V. However in the general case you probably
61-
want to use a level shifter to convert from the Raspberry Pi GPIO/PWM to 5V.
63+
WS281X LEDs are generally driven at 5V. Depending on your actual LED
64+
model and data line length you might be able to successfully drive the
65+
data input with 3.3V. However in the general case you probably want to
66+
use a level shifter to convert from the Raspberry Pi GPIO/PWM to 5V.
6267

6368
It is also possible to run the LEDs from a 3.3V - 3.6V power source, and
6469
connect the GPIO directly at a cost of brightness, but this isn't
6570
recommended.
6671

6772
The test program is designed to drive a 8x8 grid of LEDs e.g.from
6873
Adafruit (http://www.adafruit.com/products/1487) or Pimoroni
69-
(https://shop.pimoroni.com/products/unicorn-hat).
70-
Please see the Adafruit and Pimoroni websites for more information.
74+
(https://shop.pimoroni.com/products/unicorn-hat). Please see the
75+
Adafruit and Pimoroni websites for more information.
7176

72-
Know what you're doing with the hardware and electricity. I take no
77+
Know what you're doing with the hardware and electricity. I take no
7378
reponsibility for damage, harm, or mistakes.
7479

80+
Important warning about DMA channels
81+
------------------------------------
7582

76-
### Important warning about DMA channels
83+
You must make sure that the DMA channel you choose to use for the LEDs
84+
is not `already in
85+
use <https://www.raspberrypi.org/forums/viewtopic.php?p=609380#p609380>`__
86+
by the operating system.
7787

78-
You must make sure that the DMA channel you choose to use for the LEDs is not [already in use](https://www.raspberrypi.org/forums/viewtopic.php?p=609380#p609380) by the operating system.
88+
For example, **using DMA channel 5 will cause filesystem corruption**
89+
on the Raspberry Pi 3 Model B.
90+
See: https://github.com/jgarff/rpi_ws281x/issues/224
7991

80-
For example, **using DMA channel 5 [will cause](https://github.com/jgarff/rpi_ws281x/issues/224) filesystem corruption** on the Raspberry Pi 3 Model B.
92+
The default DMA channel (10) should be safe for the Raspberry Pi 3 Model
93+
B, but this may change in future software releases.
8194

82-
The default DMA channel (10) should be safe for the Raspberry Pi 3 Model B, but this may change in future software releases.
95+
Limitations:
96+
------------
8397

84-
### Limitations:
98+
PWM
99+
~~~
85100

86-
#### PWM
101+
Since this library and the onboard Raspberry Pi audio both use the PWM,
102+
they cannot be used together. You will need to blacklist the Broadcom
103+
audio kernel module by creating a file
104+
``/etc/modprobe.d/snd-blacklist.conf`` with
87105

88-
Since this library and the onboard Raspberry Pi audio
89-
both use the PWM, they cannot be used together. You will need to
90-
blacklist the Broadcom audio kernel module by creating a file
91-
`/etc/modprobe.d/snd-blacklist.conf` with
106+
::
92107

93108
blacklist snd_bcm2835
94109

95110
If the audio device is still loading after blacklisting, you may also
96111
need to comment it out in the /etc/modules file.
97112

98-
On headless systems you may also need to force audio through hdmi
99-
Edit config.txt and add:
113+
On headless systems you may also need to force audio through hdmi Edit
114+
config.txt and add:
115+
116+
::
100117

101118
hdmi_force_hotplug=1
102119
hdmi_force_edid_audio=1
103120

104121
A reboot is required for this change to take effect
105122

106-
Some distributions use audio by default, even if nothing is being played.
107-
If audio is needed, you can use a USB audio device instead.
123+
Some distributions use audio by default, even if nothing is being
124+
played. If audio is needed, you can use a USB audio device instead.
125+
126+
PCM
127+
~~~
128+
129+
When using PCM you cannot use digital audio devices which use I2S since
130+
I2S uses the PCM hardware, but you can use analog audio.
131+
132+
SPI
133+
~~
134+
135+
When using SPI the ledstring is the only device which can be connected
136+
to the SPI bus. Both digital (I2S/PCM) and analog (PWM) audio can be
137+
used.
108138

109-
#### PCM
139+
Many distributions have a maximum SPI transfer of 4096 bytes. This can
140+
be changed in ``/boot/cmdline.txt`` by appending
110141

111-
When using PCM you cannot use digital audio devices which use I2S since I2S
112-
uses the PCM hardware, but you can use analog audio.
142+
::
113143

114-
#### SPI
144+
spidev.bufsiz=32768
115145

116-
When using SPI the ledstring is the only device which can be connected to
117-
the SPI bus. Both digital (I2S/PCM) and analog (PWM) audio can be used.
146+
On a RPi 3 you have to change the GPU core frequency to 250 MHz,
147+
otherwise the SPI clock has the wrong frequency. Do this by adding the
148+
following line to /boot/config.txt and reboot.
118149

119-
Many distributions have a maximum SPI transfer of 4096 bytes. This can be
120-
changed in `/boot/cmdline.txt` by appending
121-
```
122-
spidev.bufsiz=32768
123-
```
124-
On a RPi 3 you have to change the GPU core frequency to 250 MHz, otherwise
125-
the SPI clock has the wrong frequency.
126-
Do this by adding the following line to /boot/config.txt and reboot.
127-
```
128-
core_freq=250
129-
```
150+
::
130151

131-
SPI requires you to be in the `gpio` group if you wish to control your LEDs
132-
without root.
152+
core_freq=250
133153

134-
### Comparison PWM/PCM/SPI
154+
SPI requires you to be in the ``gpio`` group if you wish to control your
155+
LEDs without root.
135156

136-
Both PWM and PCM use DMA transfer to output the control signal for the LEDs.
137-
The max size of a DMA transfer is 65536 bytes. Since each LED needs 12 bytes
138-
(4 colors, 8 symbols per color, 3 bits per symbol) this means you can
139-
control approximately 5400 LEDs for a single strand in PCM and 2700 LEDs per string
140-
for PWM (Only PWM can control 2 independent strings simultaneously)
141-
SPI uses the SPI device driver in the kernel. For transfers larger than
142-
96 bytes the kernel driver also uses DMA.
143-
Of course there are practical limits on power and signal quality. These will
144-
be more constraining in practice than the theoretical limits above.
157+
Comparison PWM/PCM/SPI
158+
----------------------
145159

146-
When controlling a LED string of 240 LEDs the CPU load on the original Pi 2 (BCM2836) are:
147-
PWM 5%
148-
PCM 5%
149-
SPI 1%
160+
Both PWM and PCM use DMA transfer to output the control signal for the
161+
LEDs. The max size of a DMA transfer is 65536 bytes. Since each LED
162+
needs 12 bytes (4 colors, 8 symbols per color, 3 bits per symbol) this
163+
means you can control approximately 5400 LEDs for a single strand in PCM
164+
and 2700 LEDs per string for PWM (Only PWM can control 2 independent
165+
strings simultaneously) SPI uses the SPI device driver in the kernel.
166+
For transfers larger than 96 bytes the kernel driver also uses DMA. Of
167+
course there are practical limits on power and signal quality. These
168+
will be more constraining in practice than the theoretical limits above.
150169

170+
When controlling a LED string of 240 LEDs the CPU load on the original
171+
Pi 2 (BCM2836) are: PWM 5% PCM 5% SPI 1%

0 commit comments

Comments
 (0)