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+
Raw data
{
"_id": null,
"home_page": "https://github.com/rpi-ws281x/rpi-ws281x-python/",
"name": "rpi-ws281x",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Jeremy Garff <jer@jers.net>, Phil Howard <phil@pimoroni.com>",
"author_email": "jer@jers.net, phil@pimoroni.com",
"download_url": "https://files.pythonhosted.org/packages/c0/1e/642208a685c5e96d38323f42c75d9b24f95e2d1b8390dd104e04a712f29e/rpi_ws281x-5.0.0.tar.gz",
"platform": null,
"description": "rpi\\_ws281x\n===========\n\nUserspace Raspberry Pi library for controlling WS281X LEDs. This\nincludes WS2812 and SK6812RGB RGB LEDs Preliminary support is now\nincluded for SK6812RGBW LEDs (yes, RGB + W) The LEDs can be controlled\nby either the PWM (2 independent channels) or PCM controller (1 channel)\nor the SPI interface (1 channel).\n\nBackground:\n-----------\n\nThe BCM2835 in the Raspberry Pi has both a PWM and a PCM module that are\nwell suited to driving individually controllable WS281X LEDs. Using the\nDMA, PWM or PCM FIFO, and serial mode in the PWM, it's possible to\ncontrol almost any number of WS281X LEDs in a chain connected to the\nappropriate output pin. For SPI the Raspbian spidev driver is used\n(``/dev/spidev0.0``). This library and test program set the clock rate\nto 3X the desired output frequency and creates a bit pattern in RAM from\nan array of colors where each bit is represented by 3 bits as follows.\n\n::\n\n Bit 1 - 1 1 0\n Bit 0 - 1 0 0\n\nGPIO Usage:\n-----------\n\nThe GPIOs that can be used are limited by the hardware of the Pi and\nwill vary based on the method used to drive them (PWM, PCM or SPI).\nBeware that the GPIO numbers are not the same as the physical pin\nnumbers on the header.\n\nPWM:\n\n::\n\n PWM0, which can be set to use GPIOs 12, 18, 40, and 52.\n Only 12 (pin 32) and 18 (pin 12) are available on the B+/2B/3B\n\n PWM1 which can be set to use GPIOs 13, 19, 41, 45 and 53.\n Only 13 is available on the B+/2B/PiZero/3B, on pin 33\n\nPCM:\n\n::\n\n PCM_DOUT, which can be set to use GPIOs 21 and 31.\n Only 21 is available on the B+/2B/PiZero/3B, on pin 40.\n\nSPI:\n\n::\n\n SPI0-MOSI is available on GPIOs 10 and 38.\n Only GPIO 10 is available on all models.\n See also note for RPi 3 below.\n\nPower and voltage requirements\n------------------------------\n\nWS281X LEDs are generally driven at 5V. Depending on your actual LED\nmodel and data line length you might be able to successfully drive the\ndata input with 3.3V. However in the general case you probably want to\nuse a level shifter to convert from the Raspberry Pi GPIO/PWM to 5V.\n\nIt is also possible to run the LEDs from a 3.3V - 3.6V power source, and\nconnect the GPIO directly at a cost of brightness, but this isn't\nrecommended.\n\nThe test program is designed to drive a 8x8 grid of LEDs e.g.from\nAdafruit (http://www.adafruit.com/products/1487) or Pimoroni\n(https://shop.pimoroni.com/products/unicorn-hat). Please see the\nAdafruit and Pimoroni websites for more information.\n\nKnow what you're doing with the hardware and electricity. I take no\nreponsibility for damage, harm, or mistakes.\n\nImportant warning about DMA channels\n------------------------------------\n\nYou must make sure that the DMA channel you choose to use for the LEDs\nis not `already in\nuse <https://www.raspberrypi.org/forums/viewtopic.php?p=609380#p609380>`__\nby the operating system.\n\nFor example, **using DMA channel 5 will cause filesystem corruption** \non the Raspberry Pi 3 Model B. \nSee: https://github.com/jgarff/rpi_ws281x/issues/224\n\nThe default DMA channel (10) should be safe for the Raspberry Pi 3 Model\nB, but this may change in future software releases.\n\nLimitations:\n------------\n\nPWM\n~~~\n\nSince this library and the onboard Raspberry Pi audio both use the PWM,\nthey cannot be used together. You will need to blacklist the Broadcom\naudio kernel module by creating a file\n``/etc/modprobe.d/snd-blacklist.conf`` with\n\n::\n\n blacklist snd_bcm2835\n\nIf the audio device is still loading after blacklisting, you may also\nneed to comment it out in the /etc/modules file.\n\nOn headless systems you may also need to force audio through hdmi Edit\nconfig.txt and add:\n\n::\n\n hdmi_force_hotplug=1\n hdmi_force_edid_audio=1\n\nA reboot is required for this change to take effect\n\nSome distributions use audio by default, even if nothing is being\nplayed. If audio is needed, you can use a USB audio device instead.\n\nPCM\n~~~\n\nWhen using PCM you cannot use digital audio devices which use I2S since\nI2S uses the PCM hardware, but you can use analog audio.\n\nSPI\n~~~\n\nWhen using SPI the ledstring is the only device which can be connected\nto the SPI bus. Both digital (I2S/PCM) and analog (PWM) audio can be\nused.\n\nMany distributions have a maximum SPI transfer of 4096 bytes. This can\nbe changed in ``/boot/cmdline.txt`` by appending\n\n::\n\n spidev.bufsiz=32768\n\nOn a RPi 3 you have to change the GPU core frequency to 250 MHz,\notherwise the SPI clock has the wrong frequency. Do this by adding the\nfollowing line to /boot/config.txt and reboot.\n\n::\n\n core_freq=250\n\nOn a RPi 4 its dynamic frequency clocking has to be disabled, since it will\ndesync the SPI clock. Do this by adding this line to\n``/boot/config.txt``. (``core_freq`` does not have to be changed, since\nthe default value of 500MHz is SPI compatible)\n\n::\n\n core_freq_min=500\n\nSPI requires you to be in the ``gpio`` group if you wish to control your\nLEDs without root.\n\nComparison PWM/PCM/SPI\n----------------------\n\nBoth PWM and PCM use DMA transfer to output the control signal for the\nLEDs. The max size of a DMA transfer is 65536 bytes. Since each LED\nneeds 12 bytes (4 colors, 8 symbols per color, 3 bits per symbol) this\nmeans you can control approximately 5400 LEDs for a single strand in PCM\nand 2700 LEDs per string for PWM (Only PWM can control 2 independent\nstrings simultaneously) SPI uses the SPI device driver in the kernel.\nFor transfers larger than 96 bytes the kernel driver also uses DMA. Of\ncourse there are practical limits on power and signal quality. These\nwill be more constraining in practice than the theoretical limits above.\n\nWhen controlling a LED string of 240 LEDs the CPU load on the original\nPi 2 (BCM2836) are: PWM 5% PCM 5% SPI 1%\n\n\n5.0.0\n-----\n\n* Bumped to rpi_ws281x v1.0.0 (15330cb)\n* Full rpi_ws281x changes: https://github.com/jgarff/rpi_ws281x/compare/9be313f...15330cb\n* New: Added support for Revisions 0xa03141, 0xb03141, 0xc04141, 0xd03141 (CM4)\n* New: Added support for Revision 0xa32082 (Pi 3 B)\n* New: Added support for slices on PixelStrip\n* New: Regenerated SWIG bindings with v4.0.2\n* New: RGBW class for interfacing with pixel values\n\n4.3.4\n-----\n\n* New: Added support for Revision 0xa03115 (Pi 4, 1GB v1.5)\n\n4.3.3\n-----\n\n* New: Added support for Revision 0xc03115 (Pi 4, 4GB v1.5)\n* New: Added support for Revision 0xd03115 (Pi 4, 8GB v1.5)\n\n4.3.2\n-----\n\n* New: Added support for Revision 0xc03131 (Pi 400, 4GB v1.1)\n* New: Added support for Revision 0xb03115 (Pi 4, 2GB v1.5)\n\n4.3.1\n-----\n\n* New: Added support for Revision 0x902120 (Pi Zero 2 W v1.0)\n\n4.3.0\n-----\n\n* Switched to upstream jgarff/rpi_ws281x library\n* New: Added support for Revision 0xd03140 (CM4 v1.0 WiFi)\n\n4.2.6\n-----\n\n* New: Added support for Revision 0xc03114 (Pi 4, 4GB v1.4)\n* New: Added support for Revision 0xa03140 (CM4 v1.0 eMMC)\n* New: Added support for Revision 0xb03140 (CM4 v1.0 Lite)\n* New: Added support for Revision 0xc03140 (CM4 v1.0 WiFi)\n\n4.2.5\n-----\n\n* New: Added support for Revision 0xc03130 (Pi 400, 4GB)\n* New: Added support for Revision 0xb03114 (Pi 4, 2GB v1.4)\n\n4.2.4\n-----\n\n* Fix: Fixed rpi_hw_detect for aarch64\n* New: Added support for Revision 0xD03114 (Raspberry Pi Model B - 8GB)\n\n4.2.3\n-----\n\n* Fix: Added support for Pi 4 Rev 1.2 - 0xa03112, 0xb03112, 0xc03112\n\n4.2.2\n-----\n\n* Fix: Fixed Slice support when setting pixels\n* New: Added support for Revision 0xa02083\n* New: Added support for Revision 0xa22083\n\n4.2.1\n-----\n\n* Fix: Added white colour channel to Color()\n\n4.2.0\n-----\n\n* New: Added support for Raspberry Pi 4\n\n4.1.0\n-----\n\n* New: Added support for the Pi 3A+\n* Fix: Bugfix for ARM64 support\n\n4.0.0\n-----\n\n* Warning: Removed \"neopixel\" module from this library, use \"rpi_ws281x\" instead, see #8\n\n3.1.0\n-----\n\n* New: Exposed all contents of ws for easy access to strip_type constants\n* Fix: Matched functionality of upstream legacy library by supporting strip_type\n* Note: Default strip type is WS2811_STRIP_GRB\n\n3.0.7\n-----\n\n* New: Added support for Pi 3B+",
"bugtrack_url": null,
"license": "MIT",
"summary": "Userspace Raspberry Pi PWM/PCM/SPI library for SK6812 and WS281X LEDs.",
"version": "5.0.0",
"project_urls": {
"Homepage": "https://github.com/rpi-ws281x/rpi-ws281x-python/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c01e642208a685c5e96d38323f42c75d9b24f95e2d1b8390dd104e04a712f29e",
"md5": "9c87b5bedba0a48bb97e9953378dfb78",
"sha256": "00ce6db771436b778d0930245cf8ea2aae11008cc5fd67d57789c5422af3ee55"
},
"downloads": -1,
"filename": "rpi_ws281x-5.0.0.tar.gz",
"has_sig": false,
"md5_digest": "9c87b5bedba0a48bb97e9953378dfb78",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 64519,
"upload_time": "2023-05-16T12:04:22",
"upload_time_iso_8601": "2023-05-16T12:04:22.463535Z",
"url": "https://files.pythonhosted.org/packages/c0/1e/642208a685c5e96d38323f42c75d9b24f95e2d1b8390dd104e04a712f29e/rpi_ws281x-5.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-16 12:04:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rpi-ws281x",
"github_project": "rpi-ws281x-python",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "rpi-ws281x"
}
JSON
