Qmk_firmware: RGB Matrix support for Massdrop arm_atsam (CTRL & ALT)

[helluvamatt]

I have been doing some work getting the Massdrop CTRL to support the Quantum RGB Matrix component. I'm opening this issue to guage interest and invite commentary from the maintainers.

What I have working so far

• Full RGB matrix support with all effects including key press effects
• RAW HID support (I am also working on a live configurator WinForms application)

Implementation Notes

• Requires modifying the RGB matrix code in quantum/ to support more than 16 columns (CTRL has 17)

Issues

• No EEPROM support (the MCU can emulate EEPROM using a flash user page, but it is only 64 bytes, and has a limited number of erase/write cycles and the entire page must be erased and written each time)

[patrickmt]

Hi @helluvamatt, I know some people have been looking for this functionality, and in general is desired to be implemented to get the arm_atsam code more aligned with QMK. Do you have a public repo available of the current work for review?

I was thinking to get EEPROM support worked into the end of programmable flash but haven't been able to focus on its implementation.

[helluvamatt]

Hey @patrickmt, my code lives in the ctrl_matt branch at https://github.com/helluvamatt/qmk_firmware

I don't have everything checked in at the moment, as I'm still working out the row and col values for the keys for keypress effects. At this time, I believe I don't need to modify the RGB matrix code to support more than 16 columns as I now believe the matrix is wired in an 8x11 grid as evidenced by ctrl.h. Can you confirm this? I will be testing on live hardware myself.

[patrickmt]

I'm not seeing that branch on your repo currently.
Yes the grid is 8x11, also as indicated in config.h
#define MATRIX_ROWS 11
#define MATRIX_COLS 8
I can also help in testing if you run into any issues.

[helluvamatt]

Sorry about that, I have pushed now.

Here is the commit for RAW HID support:
https://github.com/helluvamatt/qmk_firmware/commit/bb6eeb93bffd11fe4bd0404b392bfbdfdfbffe03

[just-another-jxliu]

I have some changes in the works that will pull the LED instruction code out of arm_atsam/led_matrix.c and put it in keyboards/massdrop/ , so you won't have to wrangle with that. Looks like we went in similar directions regarding having a color map that led_matrix.c reads from.

I still need to fix a few things for my changes and get it reviewed by Patrick before submitting an official PR. I can post it when it's solidified.

[helluvamatt]

@patrickmt https://github.com/helluvamatt/qmk_firmware/commit/49decb8fc611c5ccd2aa912b3c693890e6fff0b2

Still needs ALT keymaps and CTRL mac keymap updated. Also need to remove my custom RAW handling code from ctrl.c. But this is the direction I'm going.

[drashna]

No EEPROM support (the MCU can emulate EEPROM using a flash user page, but it is only 64 bytes, and has a limited number of erase/write cycles and the entire page must be erased and written each time)

Actually, this is exactly what the STM32 code is doing right now. We use emulated EEPROM backed by the program storage.

As for the 64 byte limit, that should be okay for now, I think. I think we're using about 32 bytes, right now.

[helluvamatt]

@drashna I was perusing the datasheet for the CTRL (Honestly, I was trying to find out if we are BE or LE), and I noticed the MCU has a SDHC controller... Wouldn't that be interesting?

[helluvamatt]

My branch has a complete working implementation. All effects, including keypress effects, work perfectly, and I have a keymap that maps the RGB_* keycodes to their rough equivalents in the default CTRL firmware.

There is a random crash in my raw_receive (it only happens when I am running my configurator WinForms application which is constantly requesting information from the device about LED status, etc..) I am not sure how to determine what the crash is, but the symptoms are that the keyboard stops responding to keypresses and the RGB animation freezes. The keyboard must be unplugged to reset it. The Fn+B combination does not restart the device after a crash. I need to learn a bit more about debugging actual hardware (exception interrupts, etc..) to go further here.

Many animations run much faster, so I've had to rework them a bit to slow them down. I think I have a solid implementation, but it needs more testing with other keyboards with RGB matrices. (Clueboard, Planck, others?) There are only 4 speed steps in the RGB matrix code, and each one is twice as fast as the last for most animations. The digital rain animation has only one speed which can be configured in the rgb_matrix_digital_rain method.

@just-another-jxliu My code still uses arm_atsam/led_matrix.c to actually set the LEDs on the hardware. I stripped it down to just the implementations of the rgb_matrix_driver_t and supporting code:

https://github.com/helluvamatt/qmk_firmware/blob/ctrl_matt/tmk_core/protocol/arm_atsam/led_matrix.c

void led_set_one(int i, uint8_t r, uint8_t g, uint8_t b) {
  // ...
}

void led_set_all(uint8_t r, uint8_t g, uint8_t b) {
  // ...
}

void init(void) {
  // ...
}

void flush(void) {
  // ...
}

const rgb_matrix_driver_t rgb_matrix_driver = {
  .init = init,
  .flush = flush,
  .set_color = led_set_one,
  .set_color_all = led_set_all
};

[drashna]

Awesome!

[OneBadSanta]

Hi. I am quite the noob so I apologize if this is the wrong area to ask this. I'm just trying to find some direction. I am looking to set up my CTRL lighting on a per key basis and all I could find was the led_setup_s which is based on percentage. Is this RGB matrix support something I should look into for this functionality? Thanks

[helluvamatt]

@OneBadSanta You might see if the Massdrop Keyboard Configurator does what you want. The RGB matrix support I wrote is very experiemental, and I believe you can do per-key colors with the configurator.

[OneBadSanta]

Ya. I used that and it works pretty good. The only issue that the configurator superimposes on top of the other led layers and there is some multi-key combinations that are not possible :/ Plus, I was enjoying learning C :) Thanks anyways. much appreciated.

[helluvamatt]

@OneBadSanta Another thing you might look into is helping us start support for Aurora

QMK effort will be tracked under these issues:

https://github.com/antonpup/Aurora/issues/1344
https://github.com/qmk/qmk_firmware/issues/4644

[OneBadSanta]

I'm not a gamer and I do not use Windows, but that project looks support cool.

[tsndr]

Will it be added to this repo soon?

[NanoAi]

Is the RAW HID support still being worked on? I'd love to start messing around with it.

[helluvamatt]

@tsndr @NanoAi

I am not actively developing this at the moment. If you are interesting in coding some, you can pull my branch and taking a look at some of the code under tmk_core/protocol/arm_atsam or keyboards/massdrop/ctrl.

[daniel5151]

My ALT arrives in a couple days, and I was planning on writing a lighting mode that plays Snake. Right now, I have a version on my local branch that hooks into the ALT's built in lighting system, but having it automatically work on all keebs that support RGB Matrix would be absolutely wicked!

I'm definitely planning on building off your branch, adding support for the ALT's LEDs.

@helluvamatt, if you're not actively working on this right now, is it cool if I hammer on your changes a bit, and potentially open a PR? Maybe even two, depending on if I can get Raw HID working a bit better?

[helluvamatt]

@daniel5151 Yes of course. Look forward to seeing your code!

[daniel5151]

Cool!

Anyone interested can follow progress on my branch.

That first commit ballooned to encompass a bunch of stuff:

• helluvamatt's changes (Getting the CTRL switched over to RGB Matrix)
• Getting the ALT switched over to RGB Matrix
• Some RGB Matrix tweaks, namely
  
  
  
  • The ability to define additional rgb modes from keymaps (see massdrop/alt:prilik)
  
  
  • A flag to have RGB_TOG cycle through 2 additional lighting modes (just keys + just underglow), just like massdrop's L_T_MD
  
  
• My custom keymap (under massdrop/alt/keymaps/prilik)

It's already pretty good, but there are a couple of things I'd like to take a crack at before opening a PR.
Namely, AFAIK, the ISSI3733 used in the CTRL/ALT is actually just a IS31FL3733, which RGB Matrix should have out-of-the-box support for. If I can figure out how to hook things up, it _should_ be possible to rip out all nonstandard lighting code (i.e led_matrix.h/c)

That said, there does seem to be some weird code that has to do with juggling the LED output with the USB hub state, which might complicate things. If @patrickmt could shed some light on that, that would be wicked.

P.S: Haven't had a chance to look into raw hid support, but it is on my list!
P.S.S: Getting EEPROM working would be awesome, but I'm not sure where to start. I'd love to be able to save RGB Matrix settings (color + current mode).

[patrickmt]

Yes the LED driver used for the CTRL and ALT is the IS31FL3733. There are two drivers on each.

I'm not sure which code you are referring to with the USB hub state, other than disabling the drivers if the USB is in sleep state. Could you please reference the code?

There is a power manager adjusting brightness of the LEDs according to available power (to prevent USB port overloading). This relies on the driver's Global Current Control Register setting, so RGB values do not need to change with brightness and the response of changing brightness is quicker. Variables to inspect would be v_5v (5V bus reading), v_5v_avg (5V bus with averaging), gcr_desired (user's brightness setting fn+w fn+s), gcr_actual (what the power manager is allowing), and any others prefixed with gcr_. The function gcr_compute() handles most of this.

Since we are running a USB HUB and a potentially power hungry device may be plugged into it, the gcr will automatically roll back power on the LEDs to a safe level that will not overload and shut down the host's USB port. The LEDs may actually turn off completely in this case. If the system is overloaded even with the LEDs off, the USB will disable the 5V output to the device, and the LEDs would recover to where they were.

It may be best to have a macro to define using QMK's RGB code vs the current arm_atsam code, in the keyboard's rules.mk. The Massdrop configurator is designed using the arm_atsam code so just removing code would break that. @just-another-jxliu is the one to talk to in regards to this.

[daniel5151]

Thanks for the explanation about USB, that makes sense.

I looked at the changes on the Massdrop branch, and by the looks of it, all the Massdrop configurator does is populate the led_instruction_t led_instructions[]; array with LED overrides.

Instead of maintaining the entire old system, it should be possible to maintain compatibility with the existing configurator by tweaking the RGB Matrix code to look for this array, and performing the appropriate functionality.

Thoughts?

[patrickmt]

Yes it seems reasonable.

One other thing I thought to mention is the arm_atsam code processes LEDs in chunks to allow time for other functions like power management. If that is not configurable with the RGB Matrix code, it can be dealt with separately when ready for testing.

[drashna]

I'm closing this, because, well, it's been added!!