From 3dd7a8426e769c182b40501687299f70a96c5b57 Mon Sep 17 00:00:00 2001 From: Phil Howard Date: Tue, 17 Apr 2018 10:38:56 +0000 Subject: [PATCH] Fixed README --- library/README.rst | 213 +++++++++++++++++++++++++-------------------- 1 file changed, 117 insertions(+), 96 deletions(-) diff --git a/library/README.rst b/library/README.rst index ec78bc5..09a3218 100644 --- a/library/README.rst +++ b/library/README.rst @@ -1,64 +1,69 @@ -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. +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: +----------- -### 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. +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 -``` +:: + + 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. -``` + +:: + + 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. -``` +:: + + 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 +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. +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 @@ -66,85 +71,101 @@ 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. +(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 +Know what you're doing with the hardware and electricity. I take no reponsibility for damage, harm, or mistakes. +Important warning about DMA channels +------------------------------------ -### 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 `__ +by the operating system. -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 -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. +The default DMA channel (10) should be safe for the Raspberry Pi 3 Model +B, but this may change in future software releases. -The default DMA channel (10) should be safe for the Raspberry Pi 3 Model B, but this may change in future software releases. +Limitations: +------------ -### Limitations: +PWM +~~~ -#### 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 -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: +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. +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. -#### PCM +Many distributions have a maximum SPI transfer of 4096 bytes. This can +be changed in ``/boot/cmdline.txt`` by appending -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 + spidev.bufsiz=32768 -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. +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. -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 -``` +:: -SPI requires you to be in the `gpio` group if you wish to control your LEDs -without root. + core_freq=250 -### Comparison PWM/PCM/SPI +SPI requires you to be in the ``gpio`` group if you wish to control your +LEDs without root. -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. +Comparison PWM/PCM/SPI +---------------------- -When controlling a LED string of 240 LEDs the CPU load on the original Pi 2 (BCM2836) are: - PWM 5% - PCM 5% - SPI 1% +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%