o Next step in avoiding the need to re-compile: make hardware GPIO

  mapping choosable at run-time (and hence: via command line flag).
  Now, Adafruit HAT users don't have to recompile.

Author: hzeller

README.md

@@ -84,8 +84,8 @@ This documentation is split into parts that help you through the process
   * <a href="wiring.md"><img src="img/wire-up-icon.png"></a>
     [Wire up the matrix to your Pi](./wiring.md). This document describes what
     goes where. You might also be interested in [breakout boards](./adapter)
-    for that. If you have an [Adafruit HAT], necessary steps are
-    [described below](#if-you-have-an-adafruit-hat)
+    for that. If you have an [Adafruit HAT], you can choose that with
+    a command line option [described below](#if-you-have-an-adafruit-hat)
   * Run a demo. You find that in the
      [examples-api-use/](./examples-api-use#running-some-demos) directory:
 ```
@@ -133,8 +133,22 @@ Some might need to be changed for your particular kind of panel.
 Here is a little run-down of what these command-line flags do and when you'd
 like to change them.
 
+First things first: if you have a different wiring than described in
+[wiring](./wiring.md), for instance if you have an Adafruit HAT, you can
+choose these here:
+
+```
+--led-gpio-mapping=<gpio-mapping>: Name of GPIO mapping used. Default "regular"
+```
+
+This can have values such as
+  - `--led-gpio-mapping=regular` The standard mapping of this library, described in the [wiring](./wiring.md) page.
+  - `--led-gpio-mapping=adafruit-hat` standard Adafruit HAT or
+  - `--led-gpio-mapping=adafruit-hat-pwm` Adafruit HAT with the anti-flicker hardware mod [described below](#improving-flicker).
+
+The next most important flags describe the type and number of displays connected
+
 ```
-# These are the most important
 --led-rows=<rows>         : Panel rows. 8, 16, 32 or 64. (Default: 32).
 --led-chain=<chained>     : Number of daisy-chained panels. (Default: 1).
 --led-parallel=<parallel> : For A/B+ models or RPi2,3b: parallel chains. range=1..3 (Default: 1).
@@ -365,16 +379,19 @@ ready-made vs. single-chain tradeoff is worthwhile, then you might go for that
 The Adafruit HAT uses this library but a modified pinout to support other
 features on the HAT. So they forked this library and modified the pinout there.
 However, that fork is _ancient_, so I strongly suggest to use this original
-library instead - which in the meantime also has a way to switch to their pinout.
+library instead. You can choose the Adafruit pinout with a command line flag.
 
-In this library here, you can choose the Adafruit HAT pinout by editing
-`lib/Makefile` and change `HARDWARE_DESC?=regular` to `HARDWARE_DESC=adafruit-hat`.
+Just pass the option `--led-gpio-mapping=adafruit-hat`.
 
-Alternatively, you can prefix the compilation call with this variable like so:
+If you want to have this the default whenever you start (or if you are using
+the Python library that does not support to set this at runtime yet), add the
+following setting in front of your compilation:
 ```
 HARDWARE_DESC=adafruit-hat make
 ```
-Then re-compile and a display connected to the HAT should work.
+(alternatively, you can modify the `lib/Makefile` and change it there directly)
+Then re-compile and the new flag default is now `adafruit-hat`, so
+no need to set it on the command line.
 
 ### Improving flicker
 
@@ -384,14 +401,17 @@ following picture (click to enlarge):
 
 <a href="img/adafruit-mod.jpg"><img src="img/adafruit-mod.jpg" height="80px"></a>
 
-Then, uncomment the following line in the Makefile and recompile.
+Then, start your programs with `--led-gpio-mapping=adafruit-hat-pwm`.
 
+If you want to make this the default setting your program starts with, you can
+also manually choose this with
 ```
-#DEFINES+=-DADAFRUIT_RGBMATRIX_HAT_PWM
+HARDWARE_DESC=adafruit-hat-pwm make
 ```
+to get this as default setting.
 
-Reboot the Pi and you now should have less visible flicker. This essentially
-gives you the hardware pulses feature.
+Now you should have less visible flicker. This essentially
+switches on the hardware pulses feature for the Adafruit HAT.
 
 ### 64x64 with E-line on Adafruit HAT
 There are LED panels that have 64x64 LEDs packed, but they need 5 address lines,

examples-api-use/README.md

@@ -17,6 +17,7 @@ Options:
                                     in the middle in an U-arrangement to get more vertical space.
         -R <rotation>             : Sets the rotation of matrix. Allowed: 0, 90, 180, 270. Default: 0.
         -t <seconds>              : Run for these number of seconds, then exit.
+        --led-gpio-mapping=<name> : Name of GPIO mapping used. Default "regular"
         --led-rows=<rows>         : Panel rows. 8, 16, 32 or 64. (Default: 32).
         --led-chain=<chained>     : Number of daisy-chained panels. (Default: 1).
         --led-parallel=<parallel> : For A/B+ models or RPi2,3b: parallel chains. range=1..3 (Default: 1).
@@ -86,6 +87,7 @@ using rgb_matrix::RGBMatrix;
 int main(int argc, char **argv) {
   // Set some defaults
   RGBMatrix::Options my_defaults;
+  my_defaults.hardware_mapping = "regular";  // or e.g. "adafruit-hat" or "adafruit-hat-pwm"
   my_defaults.chain_length = 3;
   my_defaults.show_refresh_rate = true;
   rgb_matrix::RuntimeOptions runtime_defaults;

examples-api-use/c-example.c

@@ -5,6 +5,7 @@
  */
 #include "led-matrix-c.h"
 
+#include <stdio.h>
 #include <string.h>
 #include <unistd.h>
 
@@ -31,6 +32,10 @@ int main(int argc, char **argv) {
   offscreen_canvas = led_matrix_create_offscreen_canvas(matrix);
 
   led_canvas_get_size(offscreen_canvas, &width, &height);
+
+  fprintf(stderr, "Size: %dx%d. Hardware gpio mapping: %s\n",
+          width, height, options.hardware_mapping);
+
   for (i = 0; i < 1000; ++i) {
     for (y = 0; y < height; ++y) {
       for (x = 0; x < width; ++x) {

examples-api-use/demo-main.cc

@@ -1160,7 +1160,8 @@ int main(int argc, char *argv[]) {
     matrix->ApplyStaticTransformer(RotateTransformer(rotation));
   }
 
-  printf("Size: %dx%d\n", matrix->width(), matrix->height());
+  printf("Size: %dx%d. Hardware gpio mapping: %s\n",
+         matrix->width(), matrix->height(), matrix_options.hardware_mapping);
 
   Canvas *canvas = matrix;
 

examples-api-use/minimal-example.cc

@@ -45,6 +45,7 @@ static void DrawOnCanvas(Canvas *canvas) {
 
 int main(int argc, char *argv[]) {
   RGBMatrix::Options defaults;
+  defaults.hardware_mapping = "regular";  // or e.g. "adafruit-hat"
   defaults.rows = 32;
   defaults.chain_length = 1;
   defaults.parallel = 1;

include/led-matrix-c.h

@@ -43,6 +43,12 @@ struct LedCanvas;
  * should zero out this struct before setting anything.
  */
 struct RGBLedMatrixOptions {
+  /*
+   * Name of the hardware mapping used. If passed NULL here, the default
+   * is used.
+   */
+  const char *hardware_mapping;
+
   /* The "rows" are the number of rows supported by the display, so 32 or 16.
    * Default: 32.
    * Corresponding flag: --led-rows

include/led-matrix.h

@@ -61,6 +61,9 @@ class RGBMatrix : public Canvas {
     // Returns 'true' if all options look good.
     bool Validate(std::string *err) const;
 
+    // Name of the hardware mapping. Something like "regular" or "adafruit-hat"
+    const char *hardware_mapping;
+
     // The "rows" are the number
     // of rows supported by the display, so 32 or 16. Default: 32.
     // Flag: --led-rows

lib/Makefile

@@ -4,29 +4,32 @@
 #   -lrgbmatrix
 ##
 OBJECTS=gpio.o led-matrix.o options-initialize.o framebuffer.o \
-        thread.o bdf-font.o graphics.o transformer.o led-matrix-c.o
+        thread.o bdf-font.o graphics.o transformer.o led-matrix-c.o \
+	hardware-mapping.o
 TARGET=librgbmatrix
 
 # There are several different pinouts for various breakout boards that uses
 # this library. If you are using the described pinout in the toplevel README.md
 # or the standard active-3 breakout board, then 'regular' is the one you'd like
-# to use (there is also a 'classic' one for an early form).
+# to use.
 #
 # Adafruit also made a breakout board, if you want to use that, choose
 # 'adafruit-hat'
 #
 # These are the choices
 #   regular            # Following this project wiring and using these PCBs
 #   adafruit-hat       # If you have a RGB matrix HAT from Adafruit
-#   classic            # Not really used anymore
+#   adafruit-hat-pwm   # If you have an Adafruit HAT with PWM hardware mod.
+#   classic            # (deprecated) Classic Pi1/2/. Not used anymore.
+#   classic-pi1        # (deprecated) Classic pinout on Rasperry Pi 1
 HARDWARE_DESC?=regular
 
 ###
 # After you change any of the following DEFINES, make sure to 'make' again.
 #
-# Note, all of these options that don't directly influence the hardware mapping
-# can now can be set programmatically and via command line flags as well.
-# So be prepared for these to be removed in this Makefile.
+# Note, all of these options can now can be set programmatically and
+# via command line flags as well. No real need to change them in the Makefile.
+# (So be prepared for these to be removed at some point)
 ###
 
 # If you see that your display is inverse, you might have a matrix variant
@@ -105,12 +108,9 @@ HARDWARE_DESC?=regular
 # connect GPIO 4 (old OE) with 18 (the new OE); there are
 # convenient solder holes labeled 4 and 18 on the Adafruit HAT, pretty
 # close together.
-# Then uncomment the following define and recompile.
-#DEFINES+=-DADAFRUIT_RGBMATRIX_HAT_PWM
-
-# If you use HARDWARE_DESC=classic and a Raspberry Pi 1, Revision A,
-# this might be useful (untested).
-#DEFINES+=-DPI_REV1_RGB_PINOUT
+# Then you can set the flag --led-gpio-mapping=adafruit-hat-pwm
+# .. or uncomment the following line.
+#HARDWARE_DESC=adafruit-hat-pwm
 
 # Typically, a Hub75 panel is split in two half displays, so that a 1:16
 # multiplexing actually multiplexes over two half displays and gives 32 lines.
@@ -125,8 +125,10 @@ HARDWARE_DESC?=regular
 # make USER_DEFINES="-DSHOW_REFRESH_RATE"
 DEFINES+=$(USER_DEFINES)
 
+DEFINES+=-DDEFAULT_HARDWARE='"$(HARDWARE_DESC)"'
 INCDIR=../include
-CXXFLAGS=-Wall -O3 -g -fPIC $(DEFINES) -Ihardware/$(HARDWARE_DESC)
+CFLAGS=-Wall -O3 -g -fPIC $(DEFINES)
+CXXFLAGS=$(CFLAGS)
 
 all : $(TARGET).a $(TARGET).so.1
 
@@ -144,11 +146,13 @@ graphics.o: graphics.cc utf8-internal.h
 %.o : %.cc compiler-flags
 	$(CXX) -I$(INCDIR) $(CXXFLAGS) -c -o $@ $<
 
+%.o : %.c compiler-flags
+	$(CC)  -I$(INCDIR) $(CXXFLAGS) -c -o $@ $<
+
 clean:
 	rm -f $(OBJECTS) $(TARGET).a $(TARGET).so.1
 
 compiler-flags: FORCE
-	@if [ ! -d hardware/$(HARDWARE_DESC) ] ; then echo "HARDWARE_DESC='$(HARDWARE_DESC)' is an unsupported hardware description. Typo ?"; exit 1; fi
 	@echo '$(CXX) $(CXXFLAGS)' | cmp -s - $@ || echo '$(CXX) $(CXXFLAGS)' > $@
 
 .PHONY: FORCE

lib/framebuffer-internal.h

@@ -17,6 +17,8 @@
 
 #include <stdint.h>
 
+#include "hardware-mapping.h"
+
 namespace rgb_matrix {
 class GPIO;
 class PinPulser;
@@ -64,6 +66,7 @@ class Framebuffer {
   ~Framebuffer();
 
   // Initialize GPIO bits for output. Only call once.
+  static void InitHardwareMapping(const char *named_hardware);
   static void InitGPIO(GPIO *io, int rows, int parallel,
                        bool allow_hardware_pulsing,
                        int pwm_lsb_nanoseconds);
@@ -96,9 +99,7 @@ class Framebuffer {
   void Fill(uint8_t red, uint8_t green, uint8_t blue);
 
 private:
-  // Define the type to do the pin-mapping. These are include fils
-  // found in include directory hardware/$(name-of-mapping)
-#include "led-panel-pin-mapping.h"  // see HARDWARE_DESC in lib/Makefile
+  static const struct HardwareMapping *hardware_mapping_;
 
   void InitDefaultDesignator(int x, int y, PixelDesignator *designator);
   inline void  MapColors(uint8_t r, uint8_t g, uint8_t b,
@@ -125,11 +126,8 @@ class Framebuffer {
   // Each bitplane-column is pre-filled IoBits, of which the colors are set.
   // Of course, that means that we store unrelated bits in the frame-buffer,
   // but it allows easy access in the critical section.
-  IoBits *bitplane_buffer_;
-  inline IoBits *ValueAt(int double_row, int column, int bit);
-  inline IoBits &color_bits(uint32_t *val) {
-    return *reinterpret_cast<IoBits*>(val);
-  }
+  gpio_bits_t *bitplane_buffer_;
+  inline gpio_bits_t *ValueAt(int double_row, int column, int bit);
 
   PixelMapper **shared_mapper_;  // Storage in RGBMatrix.
 };