Please factor out matrix definition in all example code in external matrix_defines.h file (or equivalent)

[marcmerlin]

Virtually all the hardware libs I've worked with, including this one, duplicate panel config in every code example, and they're usually not in sync.
It's also annoying because once you modify them you can't git pull updates unless you git stash your local panel changes.
It's also a bit unnecessary to have everyone duplicate the effort of figuring it pin definitions for standard boards.

My own lib that includes all the other ones, uses a pretty big neomatrix_config.h that you set once, and everything uses it. You only change one file and everything else follows and just works.
It's a bit "big" because of how many hardware config it supports, but for example:
https://github.com/marcmerlin/FastLED_NeoMatrix_SmartMatrix_LEDMatrix_GFX_Demos/blob/master/neomatrix_config.h

In the case of this lib, I propose you simply factor out something like this and then make all demo code include this new file. This will make everyone's lives (including yours :) ) simpler. My new personal config now also supports setting up ifdefs when using make(1) builds so you can define all your configs in that common .h, and activate the one you're trying to use at build time without having to change the definition file. You don't need to actually do this, but by factoring out the config, the end user can do those ifdefs in that new file, getting to as complex a level as they need.

// Step 1) Provide the size of each individual physical panel LED Matrix panel that is chained (or not) together
#define PANEL_RES_X 64 // Number of pixels wide of each INDIVIDUAL panel module. 
#define PANEL_RES_Y 64 // Number of pixels tall of each INDIVIDUAL panel module.

// Step 2) Provide details of the physical panel chaining that is in place.
#define NUM_ROWS 1 // Number of rows of chained INDIVIDUAL PANELS
#define NUM_COLS 1 // Number of INDIVIDUAL PANELS per ROW
#define PANEL_CHAIN NUM_ROWS*NUM_COLS    // total number of panels chained one to another

// Step 3) How are the panels chained together?
#define PANEL_CHAIN_TYPE CHAIN_TOP_RIGHT_DOWN

// Refer to: https://github.com/mrcodetastic/ESP32-HUB75-MatrixPanel-DMA/tree/master/examples/VirtualMatrixPanel
//      and: https://github.com/mrcodetastic/ESP32-HUB75-MatrixPanel-DMA/blob/master/doc/VirtualMatrixPanel.pdf

// Virtual Panel dimensions - our combined panel would be a square 4x4 modules with a combined resolution of 128x128 pixels
#define VPANEL_W PANEL_RES_X*NUM_COLS 
#define VPANEL_H PANEL_RES_Y*NUM_ROWS
#define MATRIX_WIDTH VPANEL_W
#define MATRIX_HEIGHT VPANEL_H

#ifdef mapping1
    // custom pin mapping (this one is Adafruit Matrixportal ESP32S3)
    #define R1 42
    #define G1 41
    #define B1 40
    #define R2 38
    #define G2 39
    #define B2 37
    #define CH_A 45
    #define CH_B 36
    #define CH_C 48
    #define CH_D 35
    #define CH_E 21
    #define CLK 2
    #define LAT 47
    #define OE  14
#elif defined(mapping2)
(...)
#endif

My own config also factors out the matrix building in setup in that same file since it's always the same code, but that one I'll leave up to you whether it makes sense to you, or not.

[board707]

Mark, I think this is a very interesting idea. But could you clarify where this file should be located? If it's in the example directory, then each sketch will need a copy of this file. If it's in the library directory, then that means the user will have to edit the library's source code, which is not customary for the Arduino ecosystem.

[marcmerlin]

@board707 good question. when I did that for my own project, I did like this:
https://github.com/marcmerlin/FastLED_NeoMatrix_SmartMatrix_LEDMatrix_GFX_Demos
then subdirectories look like this
https://github.com/marcmerlin/FastLED_NeoMatrix_SmartMatrix_LEDMatrix_GFX_Demos/blob/master/GFX/neomatrix_config.h
and let's take Aurora which I don't remember if @mrcodetastic took my port of, or if he re-ported it separately:
https://github.com/marcmerlin/FastLED_NeoMatrix_SmartMatrix_LEDMatrix_GFX_Demos/tree/master/GFX/Aurora
it has its own symlink of netomatrix_config.h to .., and in .. it's lnked to .., top level version.

So in the end, the file is only there once.
I'm in the middle of writing a new backend compat layer for my framebuffer lib, and I will add support for this lib. This in turn will allow all the demos in that repo to work all at once
But I understand neomatrix_config.h, because it now supports so many backends from TFT to native display on my linux laptop (write arduino code on linux, compile on linux, display on linux, and gdb + ASAN on linux, totally rocks), and TFT displays, FastLED Arrays, SmartMatrix, soon this lib and of course rpi-rgb-panel that you are familiar with, the file has become a bit big. But the beauty is I can take any of the demo code, or my own 2D code, go on any platform and display, add one ifdef to say which backend to use + matrix definition/resolution, and everything else builds and runs.

The only small gotcha is that symlinks might not work on some older versions of windows (you need to set git core.symlinks to true and enable developer mode for windows). worst case windows people need to copy the file from .. to from ../.. to their current example directory.
Or they can (and should) install wsl in windows, write their ardiuino code in there and thanks to my lib, they can use ArduinoOnPC and compile and test their demo code directly in linux before pushing it to their ESP32 or whatnot.
I helped Mark Estes convert to this recently (he's the author of the best set of 2D demos I've ever seen), and he's a happy camper now, he can write and test on windows before he ever has to push to teensy/smartmatrix or rPi/rp-rgb-panels depending on the display size

[marcmerlin]

@board707 I just found out that you don't really need symlinks.
As long as the library has a file we can call esp32_hub75_matrix_config.h (it should not conflict with other filenames in other libs), #include will find it as long as the lib is in arduino/libraries

[board707]

#include will find it as long as the lib is in arduino/libraries

Hello, Marc.
As far as I understand, only one file will be needed, which is good. However, the user will have to open and edit the library source every time they want to change panel settings. Therefore, the convenience of one approach or another depends on the typical usage scenario. If you have a one panel (one type) and want to run multiple examples on it, your approach is fine. But if you want to run examples on different panels, it's more convenient to store the settings in the sketch itself.

Is it possible to combine the advantages of both approaches and make the settings in the sketch take precedence over the configuration in your file?

[marcmerlin]

@board707 there are 2 solutions to this.
First, there is a benefit to having all the base definitions (like the pin numbers for known boards like adafruit S3 portal) in one common file that can be included.
The common file is filled with ifdef blocks for each kind of config and then you can either have a local file that defines which ifdef block you want to activate, or you can in your sketch say #define adafruit_s3_portal before #include "hub75_matrix_config.h" and it will select the correct block.
But in my experience of doing this for 5+ years in my own list of examples
in https://github.com/marcmerlin/FastLED_NeoMatrix_SmartMatrix_LEDMatrix_GFX_Demos
the sketches get reused on lots of different matrices, so it's better to have the choice of which array config to be used, in an external file

For https://github.com/marcmerlin/FastLED_ESP32-HUB75-MatrixPanel_FrameBuffer_GFX which I just released and announced, I added this
https://github.com/marcmerlin/FastLED_ESP32-HUB75-MatrixPanel_FrameBuffer_GFX/blob/ca2179ae541377d4225edfa02b10d00b54de9313/neomatrix_config.h#L66

#if __has_include("neomatrix_config_whichdefine.h")
    #include "neomatrix_config_whichdefine.h"
#endif  

This lets you say anywhere convenient to you, which block define to activate