From 2a4d82726d4c83a364e0ae09ba7adebbcb97d2d7 Mon Sep 17 00:00:00 2001 From: Martin Erzberger Date: Sat, 16 Nov 2019 22:14:09 +0100 Subject: [PATCH 01/15] Attempt support of SK9822 --- driver/apa102.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/driver/apa102.py b/driver/apa102.py index 5f991a0..0a545ee 100644 --- a/driver/apa102.py +++ b/driver/apa102.py @@ -68,7 +68,7 @@ class APA102: down the line to the last LED. """ # Constants - MAX_BRIGHTNESS = 31 # Safeguard: Max. brightness that can be selected. + MAX_BRIGHTNESS = 120 # Safeguard: Max. brightness that can be selected. LED_START = 0b11100000 # Three "1" bits, followed by 5 brightness bits def __init__(self, num_led, global_brightness=MAX_BRIGHTNESS, @@ -129,6 +129,8 @@ def clock_end_frame(self): of the driver could omit the "clockStartFrame" method if enough zeroes have been sent as part of "clockEndFrame". """ + # Send reset frame necessary for SK9822 type LEDs + self.spi.write([0] * 4) # Round up num_led/2 bits (or num_led/16 bytes) for _ in range((self.num_led + 15) // 16): self.spi.write([0x00]) From 317627377e3bfb0a01a30e97d48119b091ab500b Mon Sep 17 00:00:00 2001 From: Martin Erzberger Date: Sun, 17 Nov 2019 12:52:23 +0100 Subject: [PATCH 02/15] Add comment for SK9822 type LEDs --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c98a421..b9384d0 100644 --- a/README.md +++ b/README.md @@ -107,4 +107,5 @@ To retrieve the full library including source code, this is what you need to do - 2.1.0 (2018-06-08): Make the library installable - 2.1.1 (2019-03-15): Enable Chip Select (thanks @grandinquisitor); Simplify installation (thanks @nielstron) - 2.2.0 (2019-03-16): First version that is available on PyPi (pip 3 install); Renamed package for compliancy with PEP 8. -- 2.2.1 (2019-09-20): Nothing new, just a re-test of the library with Raspbian Buster \ No newline at end of file +- 2.2.1 (2019-09-20): Nothing new, just a re-test of the library with Raspbian Buster +- 2.2.2 (2019-11-17): Possibly fix for SK9822 type LEDs \ No newline at end of file From 1d025dfd0aafc88ffb6f304fc51c9e41d20eef1d Mon Sep 17 00:00:00 2001 From: Martin Erzberger Date: Sun, 17 Nov 2019 15:49:04 +0100 Subject: [PATCH 03/15] Extend readme --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index b9384d0..8da9c9b 100644 --- a/README.md +++ b/README.md @@ -89,6 +89,7 @@ To retrieve the full library including source code, this is what you need to do - Get the APA102 Library and sample light programs: `git clone https://github.com/tinue/apa102-pi.git && cd apa102-pi` - You might want to set the number of LEDs to match your strip: `nano runcolorcycle.py`; Update the number, Ctrl-X and "Yes" to save. - Run the sample lightshow: `./runcolorcycle.py`. +- Optional: Remove the previously installed central version of the library (but keep the necessary dependencies): `sudo pip3 uninstall apa102-pi` ## Release history - 1.0.0 (2015-04-13): Initial version From 87824cc10bc61aff3ffadf7216ce78221f540f22 Mon Sep 17 00:00:00 2001 From: Martin Erzberger Date: Sat, 23 Nov 2019 12:09:04 +0100 Subject: [PATCH 04/15] Try first with pre-release and test PyPI --- .github/workflows/pythonpublish.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/pythonpublish.yml b/.github/workflows/pythonpublish.yml index 0d43e67..78ed55e 100644 --- a/.github/workflows/pythonpublish.yml +++ b/.github/workflows/pythonpublish.yml @@ -2,7 +2,7 @@ name: Upload Python Package on: release: - types: [published] + types: [prereleased] jobs: deploy: From bcf98eb07576ae1f2fc61634417e2fcccc45ef11 Mon Sep 17 00:00:00 2001 From: Martin Erzberger Date: Sat, 23 Nov 2019 12:10:03 +0100 Subject: [PATCH 05/15] Add top-level namespace --- __init__.py | 2 -- {colorschemes => apa102_pi/colorschemes}/__init__.py | 0 {colorschemes => apa102_pi/colorschemes}/colorschemes.py | 2 +- {driver => apa102_pi/driver}/__init__.py | 0 {driver => apa102_pi/driver}/apa102.py | 0 {driver => apa102_pi/driver}/colorcycletemplate.py | 2 +- runcolorcycle.py | 2 +- runcolorcycle_blinkt.py | 2 +- sample.py | 2 +- 9 files changed, 5 insertions(+), 7 deletions(-) delete mode 100644 __init__.py rename {colorschemes => apa102_pi/colorschemes}/__init__.py (100%) rename {colorschemes => apa102_pi/colorschemes}/colorschemes.py (98%) rename {driver => apa102_pi/driver}/__init__.py (100%) rename {driver => apa102_pi/driver}/apa102.py (100%) rename {driver => apa102_pi/driver}/colorcycletemplate.py (99%) diff --git a/__init__.py b/__init__.py deleted file mode 100644 index 677452e..0000000 --- a/__init__.py +++ /dev/null @@ -1,2 +0,0 @@ -name = "apa102-pi" -__all__ = ["driver", "colorschemes"] diff --git a/colorschemes/__init__.py b/apa102_pi/colorschemes/__init__.py similarity index 100% rename from colorschemes/__init__.py rename to apa102_pi/colorschemes/__init__.py diff --git a/colorschemes/colorschemes.py b/apa102_pi/colorschemes/colorschemes.py similarity index 98% rename from colorschemes/colorschemes.py rename to apa102_pi/colorschemes/colorschemes.py index d257bea..54a8b0a 100644 --- a/colorschemes/colorschemes.py +++ b/apa102_pi/colorschemes/colorschemes.py @@ -1,6 +1,6 @@ """This module contains a few concrete colour cycles to play with""" -from driver import colorcycletemplate +from apa102_pi.driver import colorcycletemplate class StrandTest(colorcycletemplate.ColorCycleTemplate): diff --git a/driver/__init__.py b/apa102_pi/driver/__init__.py similarity index 100% rename from driver/__init__.py rename to apa102_pi/driver/__init__.py diff --git a/driver/apa102.py b/apa102_pi/driver/apa102.py similarity index 100% rename from driver/apa102.py rename to apa102_pi/driver/apa102.py diff --git a/driver/colorcycletemplate.py b/apa102_pi/driver/colorcycletemplate.py similarity index 99% rename from driver/colorcycletemplate.py rename to apa102_pi/driver/colorcycletemplate.py index 68d76a4..389daea 100644 --- a/driver/colorcycletemplate.py +++ b/apa102_pi/driver/colorcycletemplate.py @@ -1,6 +1,6 @@ """The module contains templates for colour cycles""" import time -from driver import apa102 +from apa102_pi.driver import apa102 class ColorCycleTemplate: diff --git a/runcolorcycle.py b/runcolorcycle.py index 639e160..f664383 100755 --- a/runcolorcycle.py +++ b/runcolorcycle.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 """Sample script to run a few colour tests on the strip.""" -from colorschemes import colorschemes +from apa102_pi.colorschemes import colorschemes NUM_LED = 430 diff --git a/runcolorcycle_blinkt.py b/runcolorcycle_blinkt.py index 6f09acd..572fbd0 100755 --- a/runcolorcycle_blinkt.py +++ b/runcolorcycle_blinkt.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 """Sample script to run a few colour tests on a Pimoroni Blinkt!.""" -from colorschemes import colorschemes +from apa102_pi.colorschemes import colorschemes NUM_LED = 8 MOSI = 23 # Hardware SPI uses BCM 10 & 11. Change these values for bit bang mode diff --git a/sample.py b/sample.py index fec4fea..0141803 100755 --- a/sample.py +++ b/sample.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 """Ultra simple sample on how to use the library""" -from driver import apa102 +from apa102_pi.driver import apa102 import time # Initialize the library and the strip From ca2839699de9e4477cb5d9484f7924214d907f3f Mon Sep 17 00:00:00 2001 From: Martin Erzberger Date: Sat, 23 Nov 2019 13:44:41 +0100 Subject: [PATCH 06/15] Prepare pre-release --- .github/workflows/pythonpublish.yml | 8 ++++---- apa102_pi/__init__.py | 1 + setup.py | 5 +++-- 3 files changed, 8 insertions(+), 6 deletions(-) create mode 100644 apa102_pi/__init__.py diff --git a/.github/workflows/pythonpublish.yml b/.github/workflows/pythonpublish.yml index 78ed55e..5c0e063 100644 --- a/.github/workflows/pythonpublish.yml +++ b/.github/workflows/pythonpublish.yml @@ -5,7 +5,7 @@ on: types: [prereleased] jobs: - deploy: + deploy-test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v1 @@ -19,8 +19,8 @@ jobs: pip install setuptools wheel twine - name: Build and publish env: - TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }} - TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }} + TWINE_USERNAME: ${{ secrets.TEST_PYPI_USERNAME }} + TWINE_PASSWORD: ${{ secrets.TEST_PYPI_PASSWORD }} run: | python setup.py sdist bdist_wheel - twine upload dist/* + twine upload --repository-url https://test.pypi.org/legacy/ dist/* diff --git a/apa102_pi/__init__.py b/apa102_pi/__init__.py new file mode 100644 index 0000000..3d7ae94 --- /dev/null +++ b/apa102_pi/__init__.py @@ -0,0 +1 @@ +__all__ = ["colorschemes", "driver"] diff --git a/setup.py b/setup.py index 6b39cf8..9e5d756 100755 --- a/setup.py +++ b/setup.py @@ -5,7 +5,7 @@ setuptools.setup( name="apa102-pi", - version="2.2.0", + version="2.2.2", author="Martin Erzberger", author_email="martin@erzberger.ch", description="Driver for APA102 LEDs on a Raspberry Pi", @@ -14,6 +14,7 @@ url="https://github.com/tinue/apa102-pi", python_requires='>3', packages=setuptools.find_packages(), + license='GPLv2', classifiers=[ "Programming Language :: Python :: 3", "License :: OSI Approved :: GNU General Public License v2 (GPLv2)", @@ -24,5 +25,5 @@ "Topic :: Software Development :: Libraries :: Python Modules", ], install_requires=["Adafruit-GPIO"], - platforms=["Raspbian Stretch", "Raspberry Pi"] + platforms=["Raspbian Buster", "Raspberry Pi"] ) From a810cab4eaafefdd80e2f39ae3b1a3d1ff044885 Mon Sep 17 00:00:00 2001 From: Martin Erzberger Date: Sat, 23 Nov 2019 13:57:05 +0100 Subject: [PATCH 07/15] Switch to branch trigger --- .github/workflows/pythonpublish.yml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/.github/workflows/pythonpublish.yml b/.github/workflows/pythonpublish.yml index 5c0e063..d5fefa1 100644 --- a/.github/workflows/pythonpublish.yml +++ b/.github/workflows/pythonpublish.yml @@ -1,14 +1,17 @@ -name: Upload Python Package +name: Upload Python Package to Test PyPi on: - release: - types: [prereleased] + push: + branches: + - development jobs: deploy-test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v1 + with: + ref: development - name: Set up Python uses: actions/setup-python@v1 with: From 6580c78841e5eb5eca3b92bb79c6390d67bc5f91 Mon Sep 17 00:00:00 2001 From: Martin Erzberger Date: Sat, 23 Nov 2019 19:23:56 +0100 Subject: [PATCH 08/15] Back to release trigger --- .github/workflows/pythonpublish.yml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/workflows/pythonpublish.yml b/.github/workflows/pythonpublish.yml index d5fefa1..4618691 100644 --- a/.github/workflows/pythonpublish.yml +++ b/.github/workflows/pythonpublish.yml @@ -1,9 +1,8 @@ name: Upload Python Package to Test PyPi on: - push: - branches: - - development + release: + types: [prereleased] jobs: deploy-test: From e6b1d3747c855b446facb79fe1523ab08ce8ac08 Mon Sep 17 00:00:00 2001 From: Martin Erzberger Date: Sat, 23 Nov 2019 20:12:17 +0100 Subject: [PATCH 09/15] Move bus speed into a constant; Revert max brightness to safe value --- apa102_pi/driver/apa102.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/apa102_pi/driver/apa102.py b/apa102_pi/driver/apa102.py index 0a545ee..140ea9e 100644 --- a/apa102_pi/driver/apa102.py +++ b/apa102_pi/driver/apa102.py @@ -68,11 +68,12 @@ class APA102: down the line to the last LED. """ # Constants - MAX_BRIGHTNESS = 120 # Safeguard: Max. brightness that can be selected. + MAX_BRIGHTNESS = 31 # Safeguard: Max. brightness that can be selected. LED_START = 0b11100000 # Three "1" bits, followed by 5 brightness bits + BUS_SPEED_HZ = 8000000 # SPI bus speed; If the strip flickers, lower this value def __init__(self, num_led, global_brightness=MAX_BRIGHTNESS, - order='rgb', mosi=10, sclk=11, max_speed_hz=8000000, + order='rgb', mosi=10, sclk=11, bus_speed_hz=BUS_SPEED_HZ, ce=None): """Initializes the library. @@ -90,7 +91,7 @@ def __init__(self, num_led, global_brightness=MAX_BRIGHTNESS, # MOSI 10 and SCLK 11 is hardware SPI, which needs to be set-up differently if mosi == 10 and sclk == 11: - self.spi = SPI.SpiDev(0, 0 if ce is None else ce, max_speed_hz) # Bus 0 + self.spi = SPI.SpiDev(0, 0 if ce is None else ce, bus_speed_hz) # Bus 0 else: self.spi = SPI.BitBang(GPIO.get_platform_gpio(), sclk, mosi, ss=ce) From e785d84bddb7f140f45dcbc498db8992aee8e1d6 Mon Sep 17 00:00:00 2001 From: Martin Erzberger Date: Sat, 23 Nov 2019 20:12:31 +0100 Subject: [PATCH 10/15] Prepare release --- README.md | 123 +++++++++++++++++++++++++++++++++++++++++++----------- setup.py | 2 +- 2 files changed, 99 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 8da9c9b..3b236ec 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,61 @@ # apa102-pi +## Updating +If you are currently using this library, you will have to update your `import` statements and add the +previously missing package name. For example: +* Old: `from driver import apa102` +* New: `from apa102_pi.driver import apa102` + ## 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 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. +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. -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 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". -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. This allows to easily chain multiple LEDs together. Colour command #1 lights the first LED, command #2 the next LED, and so forth. Sending for example 300 colour commands does light an entire 5 Meter, 60 LEDs per Meter strip. +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. +This allows to easily chain multiple LEDs together. Colour command #1 lights the first LED, +command #2 the next LED, and so forth. Sending for example 300 colour commands does light +an entire 5 Meter, 60 LEDs per Meter strip. Some APA102 pictures are available [here](https://www.iot-projekte.ch/apa102-led-part-1-pictures) + ## Purpose -The library is designed to take care of the details about 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. +The library is designed to take care of the details about 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 Raspbian (the library is tested with the 2019-07-10 version of Raspbian Buster Lite). -* If hardware SPI is used: SPI enabled and active (`raspi-config`, Interfacing Options, SPI, \); The SPI must be free and unused. +* A Raspberry Pi, running an up-to-date version of Raspbian (the library is tested with the 2019-09-26 +version of Raspbian Buster Lite). +* If hardware SPI is used: SPI enabled and active (`raspi-config`, Interfacing Options, SPI, \); +The SPI must be free and unused. * For software SPI (bit bang mode): Two free GPIO pins -* The Adafruit_Python_GPIO library (https://github.com/adafruit/Adafruit_Python_GPIO). The library will be installed automatically if you follow the instructions below. -* Python 3: Some people tried with Python 2 and reported it working, but I can't vouch for this myself. I used Python 3 for all development and test. +* The Adafruit_Python_GPIO library (https://github.com/adafruit/Adafruit_Python_GPIO). +The library will be installed automatically if you follow the instructions below. +* Python 3: Some people tried with Python 2 and reported it working, but I can't vouch for this myself. +I used Python 3 for all development and test. -Ideally, a 10$ Raspberry Pi Zero W is dedicated to the task of driving the LEDs. The connector to the LED stripe can be soldered directly to the correct ports on the board. +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. ## 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. 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 if you don't use a level shifter, because the Raspberry Pi determines the voltage of MOSI and SCLK. +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. +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. Without a level shifter, the wiring is very simple: @@ -31,11 +63,20 @@ Without a level shifter, the wiring is very simple: - LED Data to Raspberry SPI MOSI - LED Clock to Raspberry SPI SCLK -Note that the "Chip Select" line (CE0 or CE1) is not used on an APA102 strip. The APA102 chip always accepts data, and cannot be switched off. For "Chip Select" to work, you need additional hardware. If you use a level shifter, you can wire CE0 or CE1 to its "output-enable" pin, for example. +Note that the "Chip Select" line (CE0 or CE1) is not used on an APA102 strip. +The APA102 chip always accepts data, and cannot be switched off. +For "Chip Select" to work, you need additional hardware. If you use a level shifter, +you can wire CE0 or CE1 to its "output-enable" pin, for example. -The LED strip uses a lot of power (roughly 20mA per LED, i.e. 60mA for one bright white dot). If you try to power the LEDs from the Raspberry Pi 5V output, you will most likely immediately kill the Raspberry! Therefore I recommend not to connect the power line of the LED with the Raspberry. To be on the safe side, use a separate USB power supply for the Raspberry, and a strong 5V supply for the LEDs. If you use a level shifter, power it from the 5V power supply as well. +The LED strip uses a lot of power (roughly 20mA per LED, i.e. 60mA for one bright white dot). +If you try to power the LEDs from the Raspberry Pi 5V output, you will most likely immediately +kill the Raspberry! Therefore I recommend not to connect the power line of the LED with the Raspberry. +To be on the safe side, use a separate USB power supply for the Raspberry, and a strong 5V supply +for the LEDs. If you use a level shifter, power it from the 5V power supply as well. -Having said this, you *can* power the Raspberry from the same power supply as the LED stripes (instead of using an extra USB power supply). If you decide to do this, make sure to never plug a USB power supply to the Raspberry Pi, or you risk that the LEDs try to take power through the Raspberry. +Having said this, you *can* power the Raspberry from the same power supply as the LED stripes +(instead of using an extra USB power supply). If you decide to do this, make sure to never plug +a USB power supply to the Raspberry Pi, or you risk that the LEDs try to take power through the Raspberry. All combined, this is my extremely low-tech wiring diagram: @@ -45,16 +86,25 @@ And here it is, the finished contraption running a "rainbow" program: ![Raspberry Pi Zero driving APA102 LEDs](Finished.jpg) -This is a Raspberry Pi Zero W with a Phat Beat amplifier on top. The amplifier's "VU meter" is simply a bunch of APA 102 LEDs; They show the "Rainbow" color scheme: +This is a Raspberry Pi Zero W with a Phat Beat amplifier on top. The amplifier's "VU meter" is simply +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 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 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. +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 +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 Raspbian Lite image was used. This image only contains the bare minimum of packages, therefore some packages have be added manually. +Because the Raspberry Pi Zero runs headless, the Raspbian Lite image was used. +This image only contains the bare minimum of packages, and some packages have be added manually. -The current Raspbian Lite images can easily be set-up to run headless from the start. After burning the card on a Mac or PC, it will be mounted as "boot". Go to this directory, and create an empty file named `ssh` to enable SSH. On a Mac you would do this: `touch /Volumes/boot/ssh`. To enable and configure WLAN, create a file named `wpa_supplicant.conf`. Its content should be: +The current Raspbian Lite images can easily be set-up to run headless from the start. +After burning the card on a Mac or PC, it will be mounted as "boot". Go to this directory, +and create an empty file named `ssh` to enable SSH. +On a Mac you would do this: `touch /Volumes/boot/ssh`. To enable and configure WLAN, create +a file named `wpa_supplicant.conf`. Its content should be: country=CH ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev @@ -66,23 +116,32 @@ The current Raspbian Lite images can easily be set-up to run headless from the s key_mgmt=WPA-PSK } -Of course, use the correct country and ssid/psk. After booting (be patient: The Pi will initially boot twice) you can SSH into the Raspberry Pi: `ssh pi@raspberrypi.local`. The initial password is `raspberry`: Make sure to change it right away! +Of course, use the correct country and ssid/psk. After booting (be patient: The Pi will initially boot twice) +you can SSH into the Raspberry Pi: `ssh pi@raspberrypi.local`. The initial password +is `raspberry`: Make sure to change it right away! 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` -- 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 +- 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 ## 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 all you need is the library itself for your own projects, then this chapter is enough to get you started. +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 all you need is the library itself for your own projects, then this chapter is enough to get you started. -All you need to to is: `sudo pip3 install apa102-pi`. This will install the library and it's dependencies for all users. +Install the library like this: `sudo pip3 install apa102-pi`. +This will install the library and it's 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`. To run, type `python3 ./runcolorcycle.py`. +To verify the installation, download the test script from Github: +`curl https://raw.githubusercontent.com/tinue/apa102-pi/master/runcolorcycle.py -o runcolorcycle.py`. +To run, type `python3 ./runcolorcycle.py`. ## Full installation -To retrieve the full library including source code, this is what you need to do in addition: +To retrieve the full library including source code, this is what you need to do *additionally*: - Install the git client: `sudo apt install -y git` - Prepare GIT: `git config --global user.name "John Doe" && git config --global user.email johndoe@example.com` - Create a development directory and change into it: `mkdir ~/Development && cd ~/Development` @@ -91,6 +150,19 @@ To retrieve the full library including source code, this is what you need to do - Run the sample lightshow: `./runcolorcycle.py`. - Optional: Remove the previously installed central version of the library (but keep the necessary dependencies): `sudo pip3 uninstall apa102-pi` +## Troubleshooting +### Flicker +Some users reported flicker towards the end of large stripes. 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. +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. + ## Release history - 1.0.0 (2015-04-13): Initial version - 1.1.0 (2015-12-04): Add documentation @@ -109,4 +181,5 @@ To retrieve the full library including source code, this is what you need to do - 2.1.1 (2019-03-15): Enable Chip Select (thanks @grandinquisitor); Simplify installation (thanks @nielstron) - 2.2.0 (2019-03-16): First version that is available on PyPi (pip 3 install); Renamed package for compliancy with PEP 8. - 2.2.1 (2019-09-20): Nothing new, just a re-test of the library with Raspbian Buster -- 2.2.2 (2019-11-17): Possibly fix for SK9822 type LEDs \ No newline at end of file +- 2.3.0 (2019-11-23): 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. \ No newline at end of file diff --git a/setup.py b/setup.py index 9e5d756..a468223 100755 --- a/setup.py +++ b/setup.py @@ -5,7 +5,7 @@ setuptools.setup( name="apa102-pi", - version="2.2.2", + version="2.3.0-RC1", author="Martin Erzberger", author_email="martin@erzberger.ch", description="Driver for APA102 LEDs on a Raspberry Pi", From 8b863a4e96e3d6fbf960b1d9856914b81d649c35 Mon Sep 17 00:00:00 2001 From: Martin Erzberger Date: Sat, 23 Nov 2019 20:40:34 +0100 Subject: [PATCH 11/15] Rename file --- .github/workflows/pythonpublishprerelease.yml | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 .github/workflows/pythonpublishprerelease.yml diff --git a/.github/workflows/pythonpublishprerelease.yml b/.github/workflows/pythonpublishprerelease.yml new file mode 100644 index 0000000..4618691 --- /dev/null +++ b/.github/workflows/pythonpublishprerelease.yml @@ -0,0 +1,28 @@ +name: Upload Python Package to Test PyPi + +on: + release: + types: [prereleased] + +jobs: + deploy-test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + with: + ref: development + - name: Set up Python + uses: actions/setup-python@v1 + with: + python-version: '3.x' + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install setuptools wheel twine + - name: Build and publish + env: + TWINE_USERNAME: ${{ secrets.TEST_PYPI_USERNAME }} + TWINE_PASSWORD: ${{ secrets.TEST_PYPI_PASSWORD }} + run: | + python setup.py sdist bdist_wheel + twine upload --repository-url https://test.pypi.org/legacy/ dist/* From 9a2226cf8e67f5af708998e94c35a75230bfe821 Mon Sep 17 00:00:00 2001 From: Martin Erzberger Date: Sat, 23 Nov 2019 20:42:28 +0100 Subject: [PATCH 12/15] Add action for releases --- .github/workflows/pythonpublish.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/pythonpublish.yml b/.github/workflows/pythonpublish.yml index 4618691..c16d5b8 100644 --- a/.github/workflows/pythonpublish.yml +++ b/.github/workflows/pythonpublish.yml @@ -2,7 +2,7 @@ name: Upload Python Package to Test PyPi on: release: - types: [prereleased] + types: [published] jobs: deploy-test: @@ -10,7 +10,7 @@ jobs: steps: - uses: actions/checkout@v1 with: - ref: development + ref: master - name: Set up Python uses: actions/setup-python@v1 with: @@ -21,8 +21,8 @@ jobs: pip install setuptools wheel twine - name: Build and publish env: - TWINE_USERNAME: ${{ secrets.TEST_PYPI_USERNAME }} - TWINE_PASSWORD: ${{ secrets.TEST_PYPI_PASSWORD }} + TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }} + TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }} run: | python setup.py sdist bdist_wheel - twine upload --repository-url https://test.pypi.org/legacy/ dist/* + twine upload dist/* From cd0a9e3a163df6bae6066e5725dd49b932bdf6f9 Mon Sep 17 00:00:00 2001 From: Martin Erzberger Date: Sat, 23 Nov 2019 20:45:30 +0100 Subject: [PATCH 13/15] Prepare release --- README.md | 2 +- setup.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3b236ec..e9ede04 100644 --- a/README.md +++ b/README.md @@ -182,4 +182,4 @@ i.e. `BUS_SPEED_HZ = 1500000`. This means that all light programs with lots of u - 2.2.0 (2019-03-16): First version that is available on PyPi (pip 3 install); Renamed package for compliancy with PEP 8. - 2.2.1 (2019-09-20): Nothing new, just a re-test of the library with Raspbian Buster - 2.3.0 (2019-11-23): 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. \ No newline at end of file + breaks compatibility with the previous version, hence the minor upgrade in the version number. \ No newline at end of file diff --git a/setup.py b/setup.py index a468223..cf040e0 100755 --- a/setup.py +++ b/setup.py @@ -5,7 +5,7 @@ setuptools.setup( name="apa102-pi", - version="2.3.0-RC1", + version="2.3.0-rc2", author="Martin Erzberger", author_email="martin@erzberger.ch", description="Driver for APA102 LEDs on a Raspberry Pi", From 30d6f45cf28b8666586c6573da4003d59875d2ea Mon Sep 17 00:00:00 2001 From: Martin Erzberger Date: Sat, 23 Nov 2019 20:46:38 +0100 Subject: [PATCH 14/15] Fix name --- .github/workflows/pythonpublish.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/pythonpublish.yml b/.github/workflows/pythonpublish.yml index c16d5b8..50769b1 100644 --- a/.github/workflows/pythonpublish.yml +++ b/.github/workflows/pythonpublish.yml @@ -1,4 +1,4 @@ -name: Upload Python Package to Test PyPi +name: Upload Python Package to PyPi on: release: From 5601e4d2ef41cee0ba076b6182ed542a1981fe3d Mon Sep 17 00:00:00 2001 From: Martin Erzberger Date: Sun, 24 Nov 2019 20:54:36 +0100 Subject: [PATCH 15/15] Prepare release --- README.md | 2 +- setup.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e9ede04..bc512fc 100644 --- a/README.md +++ b/README.md @@ -181,5 +181,5 @@ i.e. `BUS_SPEED_HZ = 1500000`. This means that all light programs with lots of u - 2.1.1 (2019-03-15): Enable Chip Select (thanks @grandinquisitor); Simplify installation (thanks @nielstron) - 2.2.0 (2019-03-16): First version that is available on PyPi (pip 3 install); Renamed package for compliancy with PEP 8. - 2.2.1 (2019-09-20): Nothing new, just a re-test of the library with Raspbian Buster -- 2.3.0 (2019-11-23): Untested fix for SK9822 type LEDs; Fix name space; Update readme. Note: The namespace fix +- 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. \ No newline at end of file diff --git a/setup.py b/setup.py index cf040e0..88606d7 100755 --- a/setup.py +++ b/setup.py @@ -5,7 +5,7 @@ setuptools.setup( name="apa102-pi", - version="2.3.0-rc2", + version="2.3.0", author="Martin Erzberger", author_email="martin@erzberger.ch", description="Driver for APA102 LEDs on a Raspberry Pi",