Extract the hub75 driver as a library

[mkalkbrenner]

Hi,

first of all, thank you for improving the driver. I consider to switch to your code for the Pi Pico build of https://github.com/PPUC/ZeDMD

I already forked the repository and experimentally extracted the pure hub75 driver as library that can be added as dependency to other projects. But before creating a PR, I want to know if you're interested in that.

Another thing we noticed when switching from pimoroni version to this one is that we get some ghosting. So in sharp images, some pixels next to the illuminated ones are also illuminated using a very dark shade. Are you aware of this issue? I assume that you won't notice it with fotos or movies, but it is obvious with pixel art or typical pinball DMD content.

[JuPfu]

Hi Markus, sure, I am interested in your PR!

Please, can you give me some information about the led matrix device which showed the ghosting. Do you have a data-sheet at hand ? Can you refer to an alternative matrix driver which does not display ghosting for this matrix panel ? Do you have an example program which I can use for testing ? Do you have any further information which can help me to identify the problem ?

Best regards
Jürgen

[mkalkbrenner]

Hi, sorry for the delay.

Using the original pimoroni hub75 driver, the ghosting doesn't happen.

I already have a draft of the extracted library:
https://github.com/PPUC/hub75/tree/library

The ZeDMD builds using the pimoroni driver are OK:
https://github.com/PPUC/ZeDMD

This PR uses your lib instead:
PPUC/ZeDMD#117

The pico_128x32 builds will show a ZeDMD logo on two 64x32 panels.

[JuPfu]

Hi Markus,

thank you for the information supplied in your last comment!

I reviewed my code and made some modifications to setup a starting point on which to proceed.

I published a test branch with some modification. Is ghosting still a problem with this branch ? If so, can you please send me a foto or short film of the problem. On my matrix panel I cannot detect any ghosting.

Some notes to my changes:

• TEMPORAL_DITHERING is now undefined by default. This feature is still in development and might cause some problems / artefacts beeing displayed. You already disabled TEMPORAL_DITHERING in your port of the driver - very good 😊. Nevertheless, you can give it a try if you like.

• You already cared for the proper definition of the wiring pins in hub75.hpp - moved in this direction, too. ☑️ I added some comments to the gpio pin definitions.

• I fixed a problem in set_row_in_bit_plane. The left shift should always be 5 and therefore not be dependent on ROWSEL_N_PINS - perfect already in your code ☑️

• The default panel type is set to PANEL_GENERIC in hub75_driver.cpp.

• Not relevant for your port of the driver - I also updated the pimoroni libraries bitmap_fonts, hershey_fonts and pico_graphics to the latest version in the test branch

Can you give me a hint, where to find the creation of the hub75 driver in your code ? To increase performance the hub75 driver is running on core1.

/**
 * @brief Secondary core entry point - creates and starts driver for HUB75 rgb matrix.
 */
void core1_entry()
{
    create_hub75_driver(RGB_MATRIX_WIDTH, RGB_MATRIX_HEIGHT, PANEL_GENERIC, STB_INVERTED);
    start_hub75_driver();
}

Which update frequency do you use ? For high dynamic scenes I would advise to use 100.0f or even higher update frequency.

    // The Hub75 driver is constantly running on core 1 with a frequency much higher than 200Hz. CPU load on core 1 is low due to DMA and PIO usage.
    // The animated examples are updated at 60Hz.
    float hz = 60.0f;
    float ms = 1000.0f / hz;

Kind regards,
Jürgen

[JuPfu]

Hi Markus,

if your issue is still actively pursued by you - here some information which might help to narrow down your problem.

I updated the main branch. All configuration parameters are now bundled in hub75.hpp. I thereby followed your proposal.

If you have a 64x64 hub75 matrix panel at hand, can you, please, run the program as is on your pico microprocessor. No further devices should be attached to your pico (no spi devices etc.)! Is ghosting visible in one of the demo effects, for example the bouncing balls or rotating line ? Do not hesitate to contact me when something is unclear, undocumented or simply incomprehensible.

Can you supply me the name of the matrix panel you are using ?

If not yet done or finished, I gladly help to integrate the hub75 into your project!

Kind regards,
Jürgen

[JuPfu]

Hi Markus,

flickering or ghosting might be due to pushing the data to quickly to the matrix panel. This should be particularly relevant for matrix panels with less equal to 32 rows. Pimoroni's solution to this problem had been to reduce the state machine speed of the pio. I have adapted this solution.

The main branch contains the latest changes.

Here the code segment from file hub75.cpp :

#define SM_CLOCKDIV 1
#if SM_CLOCKDIV != 0
// To prevent flicker or ghosting it might be worth a try to reduce state machine speed.
// For panels with height less or equal to 16 rows try a factor of 8.0f
// For panels with height less or equal to 32 rows try a factor of 2.0f or 4.0f
// Adapt the SM_CLOCKDIV_FACTOR to your needs.
#define SM_CLOCKDIV_FACTOR 4.0f
#endif

If I had not been clear enough, do not hesitate to ask.

Best regards,
Jürgen

[mkalkbrenner]

Hi Jürgen,

Thanks for the updates. I sent you a mail to speak about some topics.

[mkalkbrenner]

/**
 * @brief Secondary core entry point - creates and starts driver for HUB75 rgb matrix.
 */
void core1_entry()
{
    create_hub75_driver(MATRIX_PANEL_WIDTH, MATRIX_PANEL_HEIGHT, PANEL_TYPE, INVERTED_STB);

    dma_channel_set_write_addr(oen_finished_chan, &oen_finished_data, true);
#if defined(HUB75_MULTIPLEX_2_ROWS)
    dma_channel_set_read_addr(pixel_chan, &frame_buffer[row_address * (width << 1)], true);
#elif defined(HUB75_P10_3535_16X32_4S) || defined(HUB75_P3_1415_16S_64X64_S31)
    dma_channel_set_read_addr(pixel_chan, &frame_buffer[row_address * (width << 2)], true);
#endif

    // KEEP CORE 1 ALIVE — without this, Core 1's NVIC is torn down and DMA_IRQ_1 stops firing
    while (true)
    {
        tight_loop_contents();
    }
}

/**
 * @brief Starts the DMA transfers for the HUB75 display driver.
 *
 * This function initializes the DMA transfers by setting up the write address
 * for the Output Enable finished DMA channel and the read address for pixel data.
 * It ensures that the display begins processing frames.
 */
void start_hub75_driver()
{
    multicore_reset_core1();             // Reset core 1
    multicore_launch_core1(core1_entry); // Launch core 1 entry function - the Hub75 driver is doing its job there
}

The recent changes break the usage as library. Other components might also leverage core1. The current code kills everything else that is running on core1 and then starts an endless loop on core1 that doesn't allow any other task to be executed on core1 except low level IRQ and DMA handling.

We should keep create_hub75_driver()and start_hub75_driver()logic as before. The calling code has to be in charge to balance the tasks between cores if required.

[JuPfu]

To recap - here the most important changes to make it easier to extract the hub75 driver as a library.

• the directory structure has been changed. The relevant source files for the bare driver are located in the src directory
• library.json file can be found in the root directory. This file contains some meta-information about the hub75 project.
• (nearly) all defines can now be set at compile time

# No need to modify preprocessor defines in hub75.cpp - instead set their values here.
#
# Example:
# Settings for a RP2350B microcontroller with GPIO pins spanning from 30 to 43.
# Beware to set `PICO_PLATFORM rp2350` and `PICO_BOARD none` prior to `include(pico_sdk_import.cmake)`
target_compile_definitions(hub75 PRIVATE
    PICO_RP2350A=0              # `PICO_RP2350A=0` means not a RP2350A but a RP2350B microcontroller - uncomment for RP235xB microcontroller only!
    USE_PICO_GRAPHICS=true      # set to false if you use hub75 as a library - any reference to pico_graphics is removed
    MATRIX_PANEL_WIDTH=64       # your matrix panel width
    MATRIX_PANEL_HEIGHT=64      # your matrix panel height
    DATA_BASE_PIN=30            # base GPIO pin (aka start index) of R0, G0, B0, R1, G1, B1 GPIO pins
    DATA_N_PINS=6               # number (count) of colour pins (usually 6)
    ROWSEL_BASE_PIN=36          # base GPIO address pin (aka start index) of A, B (, C, D. E) GPIO pins
    ROWSEL_N_PINS=5             # number (count) of address pins available on your matrix panel board (look at your panels connector)
    CLK_PIN=41                  # GPIO pin for CLK
    STROBE_PIN=42               # GPIO pin for STROBE (LATCH)
    OEN_PIN=43                  # GPIO for OE pin
    PANEL_TYPE=PANEL_GENERIC    # select PANEL_TYPE
    INVERTED_STB=false          # inverted pin signal for OE (untested)
    TEMPORAL_DITHERING=false    # experimental - switch on temporal dithering to improve colour depth (currently 2 additional bits)
    SM_CLOCKDIV_FACTOR=1.0f     # to prevent flicker or ghosting it might be worth a try to reduce state machine speed
    BIT_DEPTH=10                # numner (count) of bit-planes used for BCM (Binary Code Modulation) - valid values for BIT_DEPTH are 8 or 10
    HUB75_MULTICORE=true        # use core1 for the hub75 driver
)