Working version for Beta testers

GeekyTim · Aug 20, 2020 · b1b397e · b1b397e
1 parent 48a9598
commit b1b397e
Show file tree

Hide file tree

Showing 32 changed files with 873 additions and 587 deletions.
diff --git a/.gitignore b/.gitignore
@@ -91,7 +91,7 @@ ipython_config.py
 #   install all needed dependencies.
 #Pipfile.lock
 
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+# PEP 582; used by e.green. github.com/David-OConnor/pyflow
 __pypackages__/
 
 # Celery stuff

diff --git a/.idea/.gitignore b/.idea/.gitignore
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -2,18 +2,19 @@
 
 import sys
 
-# import site
 import mock
+import sphinx_rtd_theme
+from sphinx.ext import autodoc
 
-PACKAGE_NAME = u"PixelPi Library"
+PACKAGE_NAME = "PixelPi Library"
 PACKAGE_HANDLE = "PixelPi"
 PACKAGE_MODULE = "Strip"
+PACKAGE_COPYRIGHT = "2020, Hut 8 Designs"
+PACKAGE_AUTHOR = "Geeky Tim"
 
 # Prompte /usr/local/lib to the front of sys.path
 # sys.path.insert(0,site.getsitepackages()[0])
 
-import sphinx_rtd_theme
-
 sys.modules['RPi'] = mock.Mock()
 sys.modules['RPi.GPIO'] = mock.Mock()
 sys.modules['rpi_ws281x'] = mock.Mock()
@@ -22,8 +23,7 @@
 sys.modules['atexit'] = mock.Mock()
 
 sys.path.insert(0, '../../library')
-
-from sphinx.ext import autodoc
+from pixelpi import Strip
 
 
 class OutlineMethodDocumenter(autodoc.MethodDocumenter):
@@ -97,8 +97,8 @@ def setup(app):
 
 # General information about the project.
 project = PACKAGE_NAME
-copyright = u'2020, Hut 8 Designs'
-author = u'Geeky Tim'
+copyright = PACKAGE_COPYRIGHT
+author = PACKAGE_AUTHOR
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -136,13 +136,13 @@ def setup(app):
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #
-html_logo = '.\images\hut256.png'
+html_logo = 'images/hut256.png'
 
 # The name of an image file (relative to this directory) to use as a favicon of
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
+# shift large.
 #
-html_favicon = '.\images\hut256.png'
+html_favicon = 'images/hut256.png'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -179,7 +179,7 @@ def setup(app):
 #
 # html_use_opensearch = ''
 
-# This is the file name suffix for HTML files (e.g. ".xhtml").
+# This is the file name suffix for HTML files (e.green. ".xhtml").
 # html_file_suffix = None
 
 # Language to be used for generating the HTML full-text search index.

diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -0,0 +1,60 @@
+============
+Example Code
+============
+Example code has been supplied to illustrate the methods available.
+
+.. Note::
+  Remember to change the Strip definition to suit the LEDs connected. Each of the four terminals may use a
+  different LED type and shape.
+
+Run the code using::
+
+ sudo python3 example.py
+
+Rainbow
+-------
+
+Displays a moving rainbow on your LEDs.
+
+.. literalinclude:: ../../examples/rainbow.py
+   :language: python
+
+Shifting LEDs
+-------------
+The LED colours can be shifted by a number of LEDs and direction:
+
+Shifting LED Strings
+^^^^^^^^^^^^^^^^^^^^
+.. literalinclude:: ../../examples/string_shift.py
+   :language: python
+
+Shifting LED Matrices
+^^^^^^^^^^^^^^^^^^^^^
+.. literalinclude:: ../../examples/matrix_shift.py
+   :language: python
+
+Mirroring in an Axis
+--------------------
+Mirroring LED Strings
+^^^^^^^^^^^^^^^^^^^^^
+.. literalinclude:: ../../examples/string_mirror.py
+   :language: python
+
+Mirroring LED Matrices
+^^^^^^^^^^^^^^^^^^^^^^
+.. literalinclude:: ../../examples/matrix_mirror.py
+   :language: python
+
+Displaying an Image
+-------------------
+Displaying Images of LED Matrices
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. literalinclude:: ../../examples/matrix_image.py
+   :language: python
+
+.. :Note::
+  The image must be formatted in RGB format.  See
+        `Pillow image file formats <https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html>`_
+  You may manipulate the
+
+:Note: You can of course display an image on an LED string by supplying a 1 by x image.
diff --git a/docs/source/images/PixelPi.zip b/docs/source/images/PixelPi.zip
diff --git a/docs/source/images/hut256.png b/docs/source/images/hut256.png
diff --git a/docs/source/images/matrix.jpg b/docs/source/images/matrix.jpg
diff --git a/docs/source/images/string.jpg b/docs/source/images/string.jpg
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,15 +1,28 @@
+========================================================
+The PixelPi WS281x Controller Board for the Raspberry Pi
+========================================================
+The PixelPi Library is intended to be used with the PixelPi PCB from Hut 8 Designs.
+
+The PixelPi is a HAT-like add on board from Hut 8 Designs for the Raspberry Pi computer (40-pin versions) and enables you to control
+up to four (4) WS281x type RGB LED strips or matrices independently with one Raspberry Pi.
+
+.. image:: images/pixelpi.jpg
+  :width: 800
+  :alt: The PixelPi in action!
+
+*The PixelPi in action!*
+
+
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
     :numbered:
 
     building
     installation
     testing
+    examples
     library
 
-.. include:: intro.rst
-
-
 Indices and tables
 ==================
 

diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -35,6 +35,10 @@ Uncomment or add the following to in the optional hardware interfaces::
 
  dtparam=spi=on
 
+Add the following line to the end of the file to set memory frequency::
+
+ core_freq=250
+
 Disable Sound in the Kernel
 ===========================
 
@@ -54,7 +58,7 @@ boot commandline file::
 
  sudo nano /boot/cmdline.txt
 
-Add the following to the end of the only line to increase the SPI buffer size:
+Add the following to the end of the only line to increase the SPI buffer size::
 
  spidev.bufsiz=32768
 

diff --git a/docs/source/intro.rst b/docs/source/intro.rst
diff --git a/docs/source/library.rst b/docs/source/library.rst
@@ -7,29 +7,26 @@ If you have not already installed the library, see :ref:`Installing the Python L
 
 Creating a Strip Object
 -----------------------
+.. module:: pixelpi
 
 .. autoclass:: pixelpi.Strip
-   :members: getLength, getWidth, getHeight, getStripType, getStripNumber, getUpdateStatus, getStripPattern
+   :members: getLength, getWidth, getHeight, getStripType, getStripNumber, updateStatus
 
-Setting LED Colours
--------------------
-.. automethod:: pixelpi.Strip.showStrip
+Setting LED Colours and Brightness
+----------------------------------
+.. automethod:: pixelpi.Strip.setLEDs
 
-.. automethod:: pixelpi.Strip.setLED
+.. automethod:: pixelpi.Strip.getLEDs
 
-.. automethod:: pixelpi.Strip.clearStrip
+.. automethod:: pixelpi.Strip.clearLEDs
 
-.. automethod:: pixelpi.Strip.setBrightness
+Manipulating LED Colours
+------------------------
+.. automethod:: pixelpi.Strip.shift
 
-.. automethod:: pixelpi.Strip.setUpdateStatus
+.. automethod:: pixelpi.Strip.mirror
 
-.. automethod:: pixelpi.Strip.getLED
-
-.. automethod:: pixelpi.Strip.setImage
-
-.. automethod:: pixelpi.Strip.setStripPattern
-
-.. automethod:: pixelpi.Strip.rotateStrip
-
-.. automethod:: pixelpi.Strip.reflectStrip
+Updating LEDs
+-------------
+.. automethod:: pixelpi.Strip.showLEDs
 
diff --git a/docs/source/testing.rst b/docs/source/testing.rst
@@ -1,4 +1,71 @@
-================
-PixelPi Examples
-================
+=====================
+Identifying LED Types
+=====================
 
+When you attach your LEDs you may not know the exact LED type they, and if it is a matrix, you may not know the order of
+the LEDs. Sample code has been given to help you identify both LED type and matrix shape.
+
+Connecting the LEDs to the PixelPi board
+----------------------------------------
+WS281x LEDs have three wires which are usually red, green and white.  The red wire should be connected to + on a
+terminal, the white to - and the green to the centre.
+
+Strings and matrices that use the same LED type may be connected together to form longer strings or larger matrices
+but you should note that LED brightness will diminish the further away from the start they are.
+
+:Note: Only ever connect a 5v power supply to the PixelPi board. Higher voltage will destroy the board, the Raspberry
+  Pi, the LEDs or all three.
+
+
+Strings and Matrices
+--------------------
+An LED strip, or string, is a set of LEDs on a long, flexible PCB. They come in many different lengths and LED spacing.
+
+.. image:: images/string.jpg
+  :width: 800
+  :alt: An LED String
+
+LED matrices are a 2D array of LEDs:
+
+.. image:: images/matrix.jpg
+  :width: 800
+  :alt: An LED Matrix
+
+Finding LED Types
+-----------------
+Once connected to the board, use the following code (in /PixelPiLibrary/examples/string_test.py or
+/PixelPiLibrary/examples/matrix_test.py if you are using a matrix):
+
+.. literalinclude:: ../../examples/string_test.py
+   :language: python
+   :emphasize-lines: 34
+   :linenos:
+
+Edit line 34 to set:
+
+ - Which terminal your LEDs are connected to.
+ - The number of LEDs in the string (or matrix size, in (width, height) format))
+ - The LED type.
+ - If you are using a matrix, the ``shape`` must also be set to either ``matrix`` or ``zmatrix``.
+
+To run the code, use the following::
+
+ sudo python3 string_test.py
+
+or::
+
+ sudo python3 matrix_test.py
+
+:Note: ``sudo`` is currently required.
+
+If the LEDs do not display colours in the order RED, GREEN, BLUE followed by a white moving LED you should change the
+LED type to one of the following:
+
+  WS2812, SK6812, SK6812W, SK6812_RGBW, SK6812_RBGW, SK6812_GRBW, SK6812_GBRW, SK6812_BRGW, SK6812_BGRW, WS2811_RGB,
+  WS2811_RBG, WS2811_GRB, WS2811_GBR, WS2811_BRG, WS2811_BGR
+
+For example, your LEDs may display BLUE, GREEN then all go white. This will not damage them, but indicates you are using
+the incorrect type.  Change the type until the colors are displayed in the right order.
+
+For a matrix, the white LED should move in the same direction for each row. If it does not, swap the ``shape`` between
+``zmatrix`` and ``matrix``.
diff --git a/examples/clear.py b/examples/clear.py
@@ -1,33 +1,13 @@
 #!/usr/bin/env python3
 
-import colorsys
-import time
-from pixelpi import PixelPi
+from pixelpi import Strip
 
-"""
-Available strip types (note, setting the white element of LEDs is currently not supported):
+strip1 = Strip(1, 300, brightness=40)
+strip2 = Strip(2, 300, brightness=40)
+strip3 = Strip(3, 300, brightness=40)
+strip4 = Strip(4, 300, brightness=40)
 
-* `WS2812`
-* `SK6812`
-* `SK6812W`
-* `SK6812_RGBW`
-* `SK6812_RBGW`
-* `SK6812_GRBW`
-* `SK6812_GBRW`
-* `SK6812_BRGW`
-* `SK6812_BGRW`
-* `WS2811_RGB`
-* `WS2811_RBG`
-* `WS2811_GRB`
-* `WS2811_GBR`
-* `WS2811_BRG`
-* `WS2811_BGR`
-"""
-
-strip = PixelPi(1, 300, striptype='WS2811_GRB', brightness=40)
-strip = PixelPi(2, 300, striptype='WS2811_GRB', brightness=40)
-strip = PixelPi(3, 300, striptype='WS2811_GRB', brightness=40)
-strip = PixelPi(4, 300, striptype='WS2811_GRB', brightness=40)
-
-strip.clearStrip()
-strip.showStrip()
+for strip in [strip1, strip2, strip3, strip4]:
+    strip.clearLEDs()
+    strip.showLEDs()
+    del strip