Skip to content

Commit 5322862

Browse files
GadgetoidGadgetoid
committed
Tidying up for 3.1.0
1 parent 37656b7 commit 5322862

File tree

4 files changed

+155
-91
lines changed

4 files changed

+155
-91
lines changed

‎library/MANIFEST.in

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ include setup.py
66
include rpi_ws281x_wrap.c
77
include neopixel/*.py
88
include rpi_ws281x/*.py
9-
include README.md
9+
include README.rst
10+
include CHANGELOG.txt
1011
include LICENSE
1112
include Makefile

‎library/README.md

Lines changed: 0 additions & 88 deletions
This file was deleted.

‎library/README.rst

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
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.
21+
22+
Bit 1 - 1 1 0
23+
Bit 0 - 1 0 0
24+
25+
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.
32+
33+
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
37+
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+
```
41+
42+
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+
```
47+
48+
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+
```
54+
55+
56+
### Power and voltage requirements
57+
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.
62+
63+
It is also possible to run the LEDs from a 3.3V - 3.6V power source, and
64+
connect the GPIO directly at a cost of brightness, but this isn't
65+
recommended.
66+
67+
The test program is designed to drive a 8x8 grid of LEDs e.g.from
68+
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.
71+
72+
Know what you're doing with the hardware and electricity. I take no
73+
reponsibility for damage, harm, or mistakes.
74+
75+
76+
### Important warning about DMA channels
77+
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.
79+
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.
81+
82+
The default DMA channel (10) should be safe for the Raspberry Pi 3 Model B, but this may change in future software releases.
83+
84+
### Limitations:
85+
86+
#### PWM
87+
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
92+
93+
blacklist snd_bcm2835
94+
95+
If the audio device is still loading after blacklisting, you may also
96+
need to comment it out in the /etc/modules file.
97+
98+
On headless systems you may also need to force audio through hdmi
99+
Edit config.txt and add:
100+
101+
hdmi_force_hotplug=1
102+
hdmi_force_edid_audio=1
103+
104+
A reboot is required for this change to take effect
105+
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.
108+
109+
#### PCM
110+
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.
113+
114+
#### SPI
115+
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.
118+
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+
```
130+
131+
SPI requires you to be in the `gpio` group if you wish to control your LEDs
132+
without root.
133+
134+
### Comparison PWM/PCM/SPI
135+
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.
145+
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%
150+

‎library/setup.py

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,11 @@ def run(self):
1919
setup(name = 'rpi_ws281x',
2020
version = '3.1.0',
2121
author = 'Jeremy Garff <[email protected]>, Phil Howard <[email protected]>',
22-
author_email = '[email protected]',
22+
author_email = '[email protected], [email protected]',
2323
description = 'Userspace Raspberry Pi PWM/PCM/SPI library for SK6812 and WS281X LEDs.',
24+
long_description = open('README.rst').read() + "\n" + open('CHANGELOG.txt').read(),
2425
license = 'MIT',
25-
url = 'https://github.com/pimoroni/rpi_ws281x-python/',
26+
url = 'https://github.com/rpi-ws281x/rpi-ws281x-python/',
2627
cmdclass = {'build_py':CustomInstallCommand},
2728
packages = ['neopixel', 'rpi_ws281x'],
2829
ext_modules = [Extension('_rpi_ws281x',

0 commit comments

Comments
 (0)