Python matrix options (hzeller#268)

* Python - Added support for creating RGBMatrix with options.
* RGBMatrix class initializer can accept either previous parameters (rows, chains, parallel; now optional) or RGBMatrixOptions
* Modified samplebase.py to initialize RGBMatrix with RGBMatrixOptions built from command line arguments
* Removed GPIO structure. This is now created internally.
* Python - Renamed command line arguments names for samples to be consistent with the C++ arguments.

Author: danielvy

python/README.md

@@ -5,8 +5,8 @@ Building
 --------
 
 If you have a different than the standard wiring (for instance if you have an
-Adafruit HAT), edit the [../lib/Makefile](../lib/Makefile#L26) first to choose
-the hardware in question.
+Adafruit HAT), you can edit the [../lib/Makefile](../lib/Makefile#L26) first to choose
+the hardware in question (see below for setting it via command line argument).
 
 Then, in the root directory for the matrix library simply type:
 
@@ -93,6 +93,12 @@ cd samples
 sudo ./runtext.py --chain=4
 ```
 
+To use different wiring without recompiling the library to change the default,
+you can use `--hardware_mapping` (or `-m`). For example, to use Adafruit HAT:
+```bash
+sudo ./runtext.py --hardware_mapping=adafruit-hat
+```
+
 Here a complete example how to write an image viewer:
 ```python
 #!/usr/bin/env python

python/rgbmatrix/__init__.py

@@ -4,4 +4,4 @@
 __version__ = "0.0.1"
 __author__ = "Christoph Friedrich <christoph.friedrich@vonaffenfels.de>"
 
-from .core import RGBMatrix, FrameCanvas
+from .core import RGBMatrix, FrameCanvas, RGBMatrixOptions

python/rgbmatrix/core.cpp

@@ -8,7 +8,14 @@ cdef class FrameCanvas(Canvas):
 
 cdef class RGBMatrix(Canvas):
     cdef cppinc.RGBMatrix *__matrix
-    cdef cppinc.GPIO *__gpio
+
+cdef class RGBMatrixOptions:
+    cdef cppinc.Options __options
+    cdef cppinc.RuntimeOptions __runtime_options
+    # Must keep a reference to the encoded bytes for hardware_mapping string
+    # otherwise, when the Options struct is used, it will be garbage collected
+    cdef bytes __py_encoded_hardware_mapping
+
 
 # Local Variables:
 # mode: python

python/rgbmatrix/core.pxd

@@ -83,23 +83,99 @@ cdef class FrameCanvas(Canvas):
         def __get__(self): return (<cppinc.FrameCanvas*>self.__getCanvas()).pwmbits()
         def __set__(self, pwmBits): (<cppinc.FrameCanvas*>self.__getCanvas()).SetPWMBits(pwmBits)
 
+cdef class RGBMatrixOptions:
+    def __cinit__(self):
+        self.__options = cppinc.Options()
+        self.__runtime_options = cppinc.RuntimeOptions()
+
+    # RGBMatrix::Options properties
+    property hardware_mapping:
+        def __get__(self): return self.__options.hardware_mapping
+        def __set__(self, value):
+            self.__py_encoded_hardware_mapping = value.encode('utf-8')
+            self.__options.hardware_mapping = self.__py_encoded_hardware_mapping
+
+    property rows:
+        def __get__(self): return self.__options.rows
+        def __set__(self, uint8_t value): self.__options.rows = value
+
+    property chain_length:
+        def __get__(self): return self.__options.chain_length
+        def __set__(self, uint8_t value): self.__options.chain_length = value
+
+    property parallel:
+        def __get__(self): return self.__options.parallel
+        def __set__(self, uint8_t value): self.__options.parallel = value
+
+    property pwm_bits:
+        def __get__(self): return self.__options.pwm_bits
+        def __set__(self, uint8_t value): self.__options.pwm_bits = value
+
+    property pwm_lsb_nanoseconds:
+        def __get__(self): return self.__options.pwm_lsb_nanoseconds
+        def __set__(self, uint32_t value): self.__options.pwm_lsb_nanoseconds = value
+
+    property brightness:
+        def __get__(self): return self.__options.brightness
+        def __set__(self, uint8_t value): self.__options.brightness = value
+
+    property scan_mode:
+        def __get__(self): return self.__options.scan_mode
+        def __set__(self, uint8_t value): self.__options.scan_mode = value
+
+    property disable_hardware_pulsing:
+        def __get__(self): return self.__options.disable_hardware_pulsing
+        def __set__(self, value): self.__options.disable_hardware_pulsing = value
+
+    property show_refresh_rate:
+        def __get__(self): return self.__options.show_refresh_rate
+        def __set__(self, value): self.__options.show_refresh_rate = value
+
+    property swap_green_blue:
+        def __get__(self): return self.__options.swap_green_blue
+        def __set__(self, value): self.__options.swap_green_blue = value
+
+    property inverse_colors:
+        def __get__(self): return self.__options.inverse_colors
+        def __set__(self, value): self.__options.inverse_colors = value
+
+    # RuntimeOptions properties
+
+    property gpio_slowdown:
+        def __get__(self): return self.__runtime_options.gpio_slowdown
+        def __set__(self, uint8_t value): self.__runtime_options.gpio_slowdown = value
+
+    property daemon:
+        def __get__(self): return self.__runtime_options.daemon
+        def __set__(self, uint8_t value): self.__runtime_options.daemon = value
+
+    property drop_privileges:
+        def __get__(self): return self.__runtime_options.drop_privileges
+        def __set__(self, uint8_t value): self.__runtime_options.drop_privileges = value
+
 
 cdef class RGBMatrix(Canvas):
-    def __cinit__(self, int rows, int chains = 1, int parallel = 1):
-        # TODO(Saij): this should initialize an RGBMatrix::Options and
-        # RuntimeOptions, then call CreateMatrixFromOptions() instead of the
-        # cppinc.RGBMatrix() constructor directly. No __gpio needed anymore.
-        # The options allow to set more things, so they should probably be
-        # available as named parameters in Python ?
-        self.__gpio = new cppinc.GPIO()
-        if not self.__gpio.Init():
-            raise Exception("Error initializing GPIOs")  # will segfault?!
-        self.__matrix = new cppinc.RGBMatrix(self.__gpio, rows, chains, parallel)
+    def __cinit__(self, int rows = 0, int chains = 0, int parallel = 0,
+        RGBMatrixOptions options = None):
+
+        # If RGBMatrixOptions not provided, create defaults and set any optional
+        # parameters supplied
+        if options == None:
+            options = RGBMatrixOptions()
+
+        if rows > 0:
+            options.rows = rows
+        if chains > 0:
+            options.chain_length = chains
+        if parallel > 0:
+            options.parallel = parallel
+
+        self.__matrix = cppinc.CreateMatrixFromOptions(options.__options,
+            options.__runtime_options)
 
     def __dealloc__(self):
         self.__matrix.Clear()
         del self.__matrix
-        del self.__gpio
 
     cdef cppinc.Canvas* __getCanvas(self) except *:
         if <void*>self.__matrix != NULL:

python/rgbmatrix/core.pyx

@@ -13,20 +13,8 @@ cdef extern from "canvas.h" namespace "rgb_matrix":
         void Clear() nogil
         void Fill(uint8_t, uint8_t, uint8_t) nogil
 
-cdef extern from "gpio.h" namespace "rgb_matrix":
-    cdef cppclass GPIO:
-        GPIO() except +
-        bool Init()
-        uint32_t InitOutputs(uint32_t)
-        void SetBits(uint32_t)
-        void ClearBits(uint32_t)
-        void WriteMaskedBits(uint32_t, uint32_t)
-        void Write(uint32_t)
-
 cdef extern from "led-matrix.h" namespace "rgb_matrix":
     cdef cppclass RGBMatrix(Canvas):
-        RGBMatrix(GPIO*, int, int, int) except +
-        void SetGPIO(GPIO*)
         bool SetPWMBits(uint8_t)
         uint8_t pwmbits()
         void set_luminance_correct(bool)
@@ -40,6 +28,37 @@ cdef extern from "led-matrix.h" namespace "rgb_matrix":
         bool SetPWMBits(uint8_t)
         uint8_t pwmbits()
 
+    struct RuntimeOptions:
+      RuntimeOptions() except +
+      int gpio_slowdown
+      int daemon
+      int drop_privileges
+
+
+    RGBMatrix *CreateMatrixFromOptions(Options &options, RuntimeOptions runtime_options)
+
+
+
+cdef extern from "led-matrix.h" namespace "rgb_matrix::RGBMatrix":
+    cdef struct Options:
+        Options() except +
+
+        const char *hardware_mapping
+
+        int rows
+        int chain_length
+        int parallel
+        int pwm_bits
+        int pwm_lsb_nanoseconds
+        int brightness
+        int scan_mode
+
+        bool disable_hardware_pulsing
+        bool show_refresh_rate
+        bool swap_green_blue
+        bool inverse_colors
+
+
 cdef extern from "graphics.h" namespace "rgb_matrix":
     cdef struct Color:
         Color(uint8_t, uint8_t, uint8_t) except +