303 lines
8.5 KiB
Text
303 lines
8.5 KiB
Text
Metadata-Version: 2.1
|
|
Name: rpi_ws281x
|
|
Version: 5.0.0
|
|
Summary: Userspace Raspberry Pi PWM/PCM/SPI library for SK6812 and WS281X LEDs.
|
|
Home-page: https://github.com/rpi-ws281x/rpi-ws281x-python/
|
|
Author: Jeremy Garff <jer@jers.net>, Phil Howard <phil@pimoroni.com>
|
|
Author-email: jer@jers.net, phil@pimoroni.com
|
|
License: MIT
|
|
Classifier: Development Status :: 4 - Beta
|
|
Classifier: Operating System :: POSIX :: Linux
|
|
Classifier: License :: OSI Approved :: MIT License
|
|
Classifier: Intended Audience :: Developers
|
|
Classifier: Programming Language :: Python :: 3
|
|
Classifier: Topic :: Software Development
|
|
Classifier: Topic :: System :: Hardware
|
|
Requires-Python: >=3.6
|
|
License-File: LICENSE
|
|
|
|
rpi\_ws281x
|
|
===========
|
|
|
|
Userspace Raspberry Pi library for controlling WS281X LEDs. This
|
|
includes WS2812 and SK6812RGB RGB LEDs Preliminary support is now
|
|
included for SK6812RGBW LEDs (yes, RGB + W) The LEDs can be controlled
|
|
by either the PWM (2 independent channels) or PCM controller (1 channel)
|
|
or the SPI interface (1 channel).
|
|
|
|
Background:
|
|
-----------
|
|
|
|
The BCM2835 in the Raspberry Pi has both a PWM and a PCM module that are
|
|
well suited to driving individually controllable WS281X LEDs. Using the
|
|
DMA, PWM or PCM FIFO, and serial mode in the PWM, it's possible to
|
|
control almost any number of WS281X LEDs in a chain connected to the
|
|
appropriate output pin. For SPI the Raspbian spidev driver is used
|
|
(``/dev/spidev0.0``). This library and test program set the clock rate
|
|
to 3X the desired output frequency and creates a bit pattern in RAM from
|
|
an array of colors where each bit is represented by 3 bits as follows.
|
|
|
|
::
|
|
|
|
Bit 1 - 1 1 0
|
|
Bit 0 - 1 0 0
|
|
|
|
GPIO Usage:
|
|
-----------
|
|
|
|
The GPIOs that can be used are limited by the hardware of the Pi and
|
|
will vary based on the method used to drive them (PWM, PCM or SPI).
|
|
Beware that the GPIO numbers are not the same as the physical pin
|
|
numbers on the header.
|
|
|
|
PWM:
|
|
|
|
::
|
|
|
|
PWM0, which can be set to use GPIOs 12, 18, 40, and 52.
|
|
Only 12 (pin 32) and 18 (pin 12) are available on the B+/2B/3B
|
|
|
|
PWM1 which can be set to use GPIOs 13, 19, 41, 45 and 53.
|
|
Only 13 is available on the B+/2B/PiZero/3B, on pin 33
|
|
|
|
PCM:
|
|
|
|
::
|
|
|
|
PCM_DOUT, which can be set to use GPIOs 21 and 31.
|
|
Only 21 is available on the B+/2B/PiZero/3B, on pin 40.
|
|
|
|
SPI:
|
|
|
|
::
|
|
|
|
SPI0-MOSI is available on GPIOs 10 and 38.
|
|
Only GPIO 10 is available on all models.
|
|
See also note for RPi 3 below.
|
|
|
|
Power and voltage requirements
|
|
------------------------------
|
|
|
|
WS281X LEDs are generally driven at 5V. Depending on your actual LED
|
|
model and data line length you might be able to successfully drive the
|
|
data input with 3.3V. However in the general case you probably want to
|
|
use a level shifter to convert from the Raspberry Pi GPIO/PWM to 5V.
|
|
|
|
It is also possible to run the LEDs from a 3.3V - 3.6V power source, and
|
|
connect the GPIO directly at a cost of brightness, but this isn't
|
|
recommended.
|
|
|
|
The test program is designed to drive a 8x8 grid of LEDs e.g.from
|
|
Adafruit (http://www.adafruit.com/products/1487) or Pimoroni
|
|
(https://shop.pimoroni.com/products/unicorn-hat). Please see the
|
|
Adafruit and Pimoroni websites for more information.
|
|
|
|
Know what you're doing with the hardware and electricity. I take no
|
|
reponsibility for damage, harm, or mistakes.
|
|
|
|
Important warning about DMA channels
|
|
------------------------------------
|
|
|
|
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.
|
|
|
|
For example, **using DMA channel 5 will cause filesystem corruption**
|
|
on the Raspberry Pi 3 Model B.
|
|
See: https://github.com/jgarff/rpi_ws281x/issues/224
|
|
|
|
The default DMA channel (10) should be safe for the Raspberry Pi 3 Model
|
|
B, but this may change in future software releases.
|
|
|
|
Limitations:
|
|
------------
|
|
|
|
PWM
|
|
~~~
|
|
|
|
Since this library and the onboard Raspberry Pi audio both use the PWM,
|
|
they cannot be used together. You will need to blacklist the Broadcom
|
|
audio kernel module by creating a file
|
|
``/etc/modprobe.d/snd-blacklist.conf`` with
|
|
|
|
::
|
|
|
|
blacklist snd_bcm2835
|
|
|
|
If the audio device is still loading after blacklisting, you may also
|
|
need to comment it out in the /etc/modules file.
|
|
|
|
On headless systems you may also need to force audio through hdmi Edit
|
|
config.txt and add:
|
|
|
|
::
|
|
|
|
hdmi_force_hotplug=1
|
|
hdmi_force_edid_audio=1
|
|
|
|
A reboot is required for this change to take effect
|
|
|
|
Some distributions use audio by default, even if nothing is being
|
|
played. If audio is needed, you can use a USB audio device instead.
|
|
|
|
PCM
|
|
~~~
|
|
|
|
When using PCM you cannot use digital audio devices which use I2S since
|
|
I2S uses the PCM hardware, but you can use analog audio.
|
|
|
|
SPI
|
|
~~~
|
|
|
|
When using SPI the ledstring is the only device which can be connected
|
|
to the SPI bus. Both digital (I2S/PCM) and analog (PWM) audio can be
|
|
used.
|
|
|
|
Many distributions have a maximum SPI transfer of 4096 bytes. This can
|
|
be changed in ``/boot/cmdline.txt`` by appending
|
|
|
|
::
|
|
|
|
spidev.bufsiz=32768
|
|
|
|
On a RPi 3 you have to change the GPU core frequency to 250 MHz,
|
|
otherwise the SPI clock has the wrong frequency. Do this by adding the
|
|
following line to /boot/config.txt and reboot.
|
|
|
|
::
|
|
|
|
core_freq=250
|
|
|
|
On a RPi 4 its dynamic frequency clocking has to be disabled, since it will
|
|
desync the SPI clock. Do this by adding this line to
|
|
``/boot/config.txt``. (``core_freq`` does not have to be changed, since
|
|
the default value of 500MHz is SPI compatible)
|
|
|
|
::
|
|
|
|
core_freq_min=500
|
|
|
|
SPI requires you to be in the ``gpio`` group if you wish to control your
|
|
LEDs without root.
|
|
|
|
Comparison PWM/PCM/SPI
|
|
----------------------
|
|
|
|
Both PWM and PCM use DMA transfer to output the control signal for the
|
|
LEDs. The max size of a DMA transfer is 65536 bytes. Since each LED
|
|
needs 12 bytes (4 colors, 8 symbols per color, 3 bits per symbol) this
|
|
means you can control approximately 5400 LEDs for a single strand in PCM
|
|
and 2700 LEDs per string for PWM (Only PWM can control 2 independent
|
|
strings simultaneously) SPI uses the SPI device driver in the kernel.
|
|
For transfers larger than 96 bytes the kernel driver also uses DMA. Of
|
|
course there are practical limits on power and signal quality. These
|
|
will be more constraining in practice than the theoretical limits above.
|
|
|
|
When controlling a LED string of 240 LEDs the CPU load on the original
|
|
Pi 2 (BCM2836) are: PWM 5% PCM 5% SPI 1%
|
|
|
|
|
|
5.0.0
|
|
-----
|
|
|
|
* Bumped to rpi_ws281x v1.0.0 (15330cb)
|
|
* Full rpi_ws281x changes: https://github.com/jgarff/rpi_ws281x/compare/9be313f...15330cb
|
|
* New: Added support for Revisions 0xa03141, 0xb03141, 0xc04141, 0xd03141 (CM4)
|
|
* New: Added support for Revision 0xa32082 (Pi 3 B)
|
|
* New: Added support for slices on PixelStrip
|
|
* New: Regenerated SWIG bindings with v4.0.2
|
|
* New: RGBW class for interfacing with pixel values
|
|
|
|
4.3.4
|
|
-----
|
|
|
|
* New: Added support for Revision 0xa03115 (Pi 4, 1GB v1.5)
|
|
|
|
4.3.3
|
|
-----
|
|
|
|
* New: Added support for Revision 0xc03115 (Pi 4, 4GB v1.5)
|
|
* New: Added support for Revision 0xd03115 (Pi 4, 8GB v1.5)
|
|
|
|
4.3.2
|
|
-----
|
|
|
|
* New: Added support for Revision 0xc03131 (Pi 400, 4GB v1.1)
|
|
* New: Added support for Revision 0xb03115 (Pi 4, 2GB v1.5)
|
|
|
|
4.3.1
|
|
-----
|
|
|
|
* New: Added support for Revision 0x902120 (Pi Zero 2 W v1.0)
|
|
|
|
4.3.0
|
|
-----
|
|
|
|
* Switched to upstream jgarff/rpi_ws281x library
|
|
* New: Added support for Revision 0xd03140 (CM4 v1.0 WiFi)
|
|
|
|
4.2.6
|
|
-----
|
|
|
|
* New: Added support for Revision 0xc03114 (Pi 4, 4GB v1.4)
|
|
* New: Added support for Revision 0xa03140 (CM4 v1.0 eMMC)
|
|
* New: Added support for Revision 0xb03140 (CM4 v1.0 Lite)
|
|
* New: Added support for Revision 0xc03140 (CM4 v1.0 WiFi)
|
|
|
|
4.2.5
|
|
-----
|
|
|
|
* New: Added support for Revision 0xc03130 (Pi 400, 4GB)
|
|
* New: Added support for Revision 0xb03114 (Pi 4, 2GB v1.4)
|
|
|
|
4.2.4
|
|
-----
|
|
|
|
* Fix: Fixed rpi_hw_detect for aarch64
|
|
* New: Added support for Revision 0xD03114 (Raspberry Pi Model B - 8GB)
|
|
|
|
4.2.3
|
|
-----
|
|
|
|
* Fix: Added support for Pi 4 Rev 1.2 - 0xa03112, 0xb03112, 0xc03112
|
|
|
|
4.2.2
|
|
-----
|
|
|
|
* Fix: Fixed Slice support when setting pixels
|
|
* New: Added support for Revision 0xa02083
|
|
* New: Added support for Revision 0xa22083
|
|
|
|
4.2.1
|
|
-----
|
|
|
|
* Fix: Added white colour channel to Color()
|
|
|
|
4.2.0
|
|
-----
|
|
|
|
* New: Added support for Raspberry Pi 4
|
|
|
|
4.1.0
|
|
-----
|
|
|
|
* New: Added support for the Pi 3A+
|
|
* Fix: Bugfix for ARM64 support
|
|
|
|
4.0.0
|
|
-----
|
|
|
|
* Warning: Removed "neopixel" module from this library, use "rpi_ws281x" instead, see #8
|
|
|
|
3.1.0
|
|
-----
|
|
|
|
* New: Exposed all contents of ws for easy access to strip_type constants
|
|
* Fix: Matched functionality of upstream legacy library by supporting strip_type
|
|
* Note: Default strip type is WS2811_STRIP_GRB
|
|
|
|
3.0.7
|
|
-----
|
|
|
|
* New: Added support for Pi 3B+
|