zmk icon indicating copy to clipboard operation
zmk copied to clipboard

docs(feat): further generalize RGB information

Open lesshonor opened this issue 5 months ago • 1 comments

Using PIO SPI for the "Other Boards" example:

  1. Does a better job of demonstrating how the RGB config for hardware X can differ from hardware Y (the current examples are nearly-identical).
  2. Provides a reference configuration which an increasing number of hobbyist keyboard makers will inevitably end up looking for in the near term. (When/if ZMK moves to Zephyr 3.7, switching to worldsemi,ws2812-pio might be a good idea for further emphasis on point 1.)

Etc.

  • Since the primary motivation is to expand beyond a single hardware configuration, much of the rest of the page was edited with TMTOWTDI in mind.
  • That said, I don't know if any ZMKers have ever tested any of the other LED ICs in the list. Rather than affirmatively stating "ZMK supports X", it's probably better to gently guide users toward checking Zephyr.
  • The adjective "per-key" is more widely-used than "under-key".
  • ~~Reduce duplication. Instead of copying the CONFIG_* section, write it once for end-users then "yes, and" with an example of Kconfig.defconfig defaults for board/shield writers.~~
  • Explain with examples. Linking to two of Kyria's different board configurations shines more light on the board/shield paradigm. I'm a little less sold on the Corne LED counts but it's accurate at this moment in time.
  • Having an info box and a note box right next to each other deemphasises the "callout" aspect of both and looks a little unsightly, so I moved the low-frequency I/O pin disclaimer to a sentence near the beginning of that section.

What Could Definitely Use Improvement

Maybe the hardware-specific implementations could be a set of tabs for nRF52 WS2812 SPI and RP2040 WS2812 PIO SPI; that would make it easier to pull out the common led_strip definition vs replicating.

The "Other Boards" description is genuinely an awful cop-out, but I'm not sure how to more delicately express that if you can't find an explanation or example of something in ZMK, you should check Zephyr. It doesn't help that Zephyr doesn't appear to have an "led_strip" index; just the sample code, which I'm not sold on linking to. Maybe it'd be better to link to worldsemi, but consider the first bullet in the et cetera list...

lesshonor avatar Sep 17 '24 04:09 lesshonor