Refine readme

README.md

@@ -1,15 +1,15 @@
 # apa102-pi
 
 ## Introduction
-Apa102-pi is a pure Python library to drive APA102 type LED strands. It is supposed to work on a Raspberry Pi,
-and is not tested on any other platform.
+Apa102-pi is a pure Python library to drive APA102 and SK9822 type LED strands. It is supposed to work on a Raspberry
+Pi, and is not tested on any other platform.
 
 APA102 LEDs are typically 5050 type LEDs with an additional driver chip per LED.
 The driver chip takes care of receiving the desired colour via its input lines, and then holding
-this colour until a new command is received.
+this colour until a new command arrives.
 
-Depending on where these LEDs are bought, they might be called "APA102", "Superled", or "DotStar".
-They should not be confused with the three-wire WS2812 LEDs, also known as "NeoPixel".
+Depending on the LEDs vendor, they might be called "APA102", "SK9822", "Superled", or "DotStar".
+They must not be confused with the three-wire WS2812 LEDs, also known as "NeoPixel".
 
 The really nice part about the driver chip is this: Once it has received its own colour command,
 it forwards any further colour commands from its input to its output lines.
@@ -20,33 +20,37 @@ an entire 5 Meter, 60 LEDs per Meter strip.
 Some APA102 pictures are available [here](https://tinue.github.io/apa102-pi/)
 
 ## Purpose
-The library is designed to take care of the details about sending colour commands.
+The library takes care of the details on sending colour commands.
 It is supposed to be educational, and is therefore written in Python.
 The library is fast enough to produce nice colour effects on a 300 LED strand, even though it is running
 via the Python interpreter. However, if you need something really fast, e.g. to drive a
 small "display" based on APA102 LEDs with 15 frames per second, then you have to look elsewhere.
 
 ## Prerequisites
-* A Raspberry Pi, running an up-to-date version of Raspberry Pi OS (the library is tested with the 2020-05-27
-version of Raspberry Pi OS (32-bit) Lite).
+* A Raspberry Pi, running an up-to-date version of Raspbian / Raspberry Pi OS. To date, Raspberry Pi OS 2020-05-27
+is out, and the library works fine with this release. It should run on all Raspberry Pi models, from Zero
+to 4.
 * If hardware SPI is used: SPI enabled and active (`raspi-config`, Interfacing Options, SPI, \<Yes\>);
 The SPI must be free and unused.
 * For software SPI (bit bang mode): Two free GPIO pins
-* The Adafruit_Blinka library (https://github.com/adafruit/Adafruit_Blinka).
-The library will be installed automatically if you follow the instructions below.
-* For Bitbang SPI: The Adafruit Circuitpython Bitbangio library (https://github.com/adafruit/Adafruit_CircuitPython_BitbangIO). This library will also be installed automatically.
+* Three libraries from Adafruit: [Adafruit-Blinka](https://github.com/adafruit/Adafruit_Blinka), 
+[adafruit-circuitpython-bitbangio](https://github.com/adafruit/Adafruit_CircuitPython_BitbangIO),
+and [adafruit-circuitpython-busdevice](https://github.com/adafruit/Adafruit_CircuitPython_BusDevice).
+These libraries will be installed automatically if you follow the steps in
+[Use the APA102 project as a library](#use-the-apa102-project-as-a-library).
 
 For a permanent installation, a 10$ Raspberry Pi Zero W can be dedicated to the task of driving the LEDs.
 The connector to the LED stripe would be soldered directly to the correct ports on the board.
 For development purposes, a Raspberry Pi 4 Model B is a better choice due to its greater speed.
-Even the 1GB model is more than enough.
+Even the 1GB model is more than enough for this purpose.
 
 ## Wiring
 The Raspberry Pi is a 3.3 volt device, and the APA102 LEDs are 5 volt devices. 
-Therefore, it's possible that the 3.3 volt SPI signal is not properly recognized by the LED driver chips.
+Therefore, it is possible that the first LED driver chip does not properly detect the 3.3 volt SPI signal from
+the Raspberry Pi.  
+The first chip will amplify the signal to 5 volts before passing it on, so it is really only the first chip
+that must detect the 3.3 volt signal.  
 To avoid this risk, use a 74AHCT125 or 74AHC125 level shifter for both the clock and the MOSI signal.
-You will not damage the Raspberry Pi without a level shifter, because the Raspberry Pi determines
-the voltage of MOSI and SCLK.  
 In my limited testing with four different stripes from various Chinese sources I had no issues without
 a level shifter, but your experience might be different.
 
@@ -63,10 +67,10 @@ Select. You might be wondering where the Chip Select input line is on an LED str
 therefore can't disable the Strip from reading data on SCLK/MOSI, at least not without additional hardware. For
 example, you can wire the chip select GPIO of the Raspberry Pi to the level shifter "output-enable" pin.
 
-The Adafruit library does not use or support the hardware chip select pins on the Rapsberry Pi. Instead, any
-free GPIO pin can be used. Because this is multiplexed in software, it is very slow. The feature is intended
-for e.g. sensors that do not send or receive a lot of data over the bus, but in exchange there are more than two
-sensors attached.
+The Adafruit library does not use or support the hardware chip select pins of the Raspberry Pi. Instead, any
+free GPIO pin can be used. Because this is multiplexed in software, it is very slow. The feature supports
+e.g. sensors, where you have a lot of them (more than two), and each sensor only sends or
+receives a limited amount of data.  
 The apa102-pi library attempts to use this software multiplexing if a CE value is passed on driver initialization.
 The strip will update a lot slower if this is used. It is still a bit faster than bitbang, though.
 Please note that I have not tested this feature, because I never assembled the hardware required for this.
@@ -95,12 +99,12 @@ a bunch of APA 102 LEDs; They show the "Rainbow" color scheme:
 ![Raspberry Pi Zero W with Phat Beat](PhatBeat.jpg)
 
 Plugged into the USB port is a WLAN stick (nowadays I use a Raspberry Pi Zero W, of course).
-This way I can reprogram the light show from my desk, even if the strips are installed outside 
+This way I can reprogram the light show from my desk, even if the strips sit outside 
 as a Christmas light. Compare this to an Arduino/WS2812 based installation: To reprogram one has
 to take the Arduino inside, or a laptop outside.
 
 ## Quick Raspberry Pi setup
-Because the Raspberry Pi Zero runs headless, the Raspberry Pi OS Lite image was used.
+Because the Raspberry Pi Zero runs headless, I recommend using the Raspberry Pi OS *Lite* image.
 This image only contains the bare minimum of packages, and some packages have be added manually.
 
 The current Raspberry Pi OS Lite images can easily be set-up to run headless from the start.
@@ -128,16 +132,16 @@ Next, install additional packages and enable SPI:
 - Update your installation (`sudo apt update && sudo apt -y upgrade`).
 - Install packages: `sudo apt install -y python3-pip python3-rpi.gpio`
 - Activate SPI: `sudo raspi-config`; Go to "Interfacing Options"; Go to "SPI"; Enable SPI;
-While you are at it: Do change the default password! Exit exit the tool and reboot  
+While you are at it: Do change the default password! Exit the tool and reboot.  
 
 ## Use the APA102 project as a library
 The library was originally built as an educational piece of software. It shows how the protocol
 for APA102 LEDs works. Most of this is explained in the form of comments in the source code.
-If you are interested in this, then follow up with the next chapter.
+If you are interested in this, then follow up with the chapter after this one.
 If all you need is the library itself for your own projects, then this chapter is enough to get you started.
 
 Install the library like this: `sudo pip3 install apa102-pi`. 
-This will install the library and it's dependencies for all users. 
+This will install the library, and its dependencies for all users. 
 
 To verify the installation, download the test script from Github:
 `curl https://raw.githubusercontent.com/tinue/apa102-pi/master/runcolorcycle.py -o runcolorcycle.py`.
@@ -155,13 +159,13 @@ To retrieve the full library including source code, this is what you need to do
 
 ## Troubleshooting
 ### Flicker
-Some users reported flicker towards the end of large stripes. It seems that there is a correlation amongst
-three variables:
+Sometimes the end of large stripes flickers. It seems that there is a correlation amongst three variables:
 * SPI bus speed
 * Overall brightness of the strip
 * Length of the strip
 
-It turns out that you can only have two out of three: On a long, bright strip you will have to lower the bus speed significantly.
+It turns out that you can only have two out of three: On a long, bright strip you will have to lower the bus speed 
+significantly.  
 Check the apa102.py driver: Default is 8MHz (`BUS_SPEED_HZ = 8000000`). You may have to go as low as 1.5MHz, 
 i.e. `BUS_SPEED_HZ = 1500000`. This means that all light programs with lots of updates and zero wait
 (e.g. rainbow) will run much slower.
@@ -186,4 +190,5 @@ i.e. `BUS_SPEED_HZ = 1500000`. This means that all light programs with lots of u
 - 2.2.1 (2019-09-20): Nothing new, just a re-test of the library with Raspbian Buster
 - 2.3.0 (2019-11-24): Untested fix for SK9822 type LEDs; Fix name space; Update readme. Note: The namespace fix
                       breaks compatibility with the previous version, hence the minor upgrade in the version number.
-- 2.4.0 (2020-05-28): SPI: Switch from deprecated Adafruit_GPIO to Adafruit_Blinka library; Re-test with Raspberry Pi OS 2020-05-27
+- 2.4.0 (2020-05-28): SPI: Switch from the deprecated Adafruit_GPIO to the Adafruit CircuitPython libraries;
+                      Re-test with Raspberry Pi OS 2020-05-27.