Community modules

[tzarc]

Description

Add support for community modules. Community modules are intended to be an area which provides common functionality to be easily imported into a keymap.

Additionally, community modules support placement inside userspace; module developers can thus create modules in separate repositories, and users can subsequently add them as userspace-local submodules to make them available for use in user keymaps.

• keyboard.json, info.json, and keymap.json now accept a top-level array of strings called "modules"
• Keyboard-imported modules precede keymap-imported modules.
• Module implementations are able to hook an initial set of key APIs within QMK, now allowing for the sequence _modules => _kb => _user.
• Each module has an equivalent hook API generated and invoked inside _modules, in the module order provided.
  • For a single API example, the hello_world module has the following overridable functions defined:
    • process_record_hello_world_user -- a no-op but allows user keymaps to hook the module
    • process_record_hello_world_kb -- invokes _user by default, follows the same callback ordering as the rest of QMK
    • process_record_hello_world -- the actual module implementation of process_record_xxxx, executed before process_record_kb or process_record_user.
• The full list of hookable APIs will be present in the documentation when written.
• An introspection.c file present in the module's directory will automatically be injected into the keymap.c during compilation, using the same mechanism as the rest of core's keymap_introspection.c. Same for introspection.h.

A couple of community modules I've used for testing can be found here.

Types of Changes

• Core
• Bugfix
• New feature
• Enhancement/optimization
• Keyboard (addition or update)
• Keymap/layout (addition or update)
• Documentation

Checklist

• My code follows the code style of this project: C, Python
• I have read the PR Checklist document and have made the appropriate changes.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• I have tested the changes and verified that they work and don't break anything (as well as I can manage).

[getreuer]

Very cool! I'm excited to see ASSERT_COMMUNITY_MODULES_MIN_API_VERSION. With my userspace libs, I do a hacky preprocessor check to detect very old QMK versions:

#if !defined(IS_QK_MOD_TAP)
// Attempt to detect out-of-date QMK installation, which would fail with
// implicit-function-declaration errors in the code below.
#error "achordion: QMK version is too old to build. Please update QMK."
#else
// Achordion implementation...

ASSERT_COMMUNITY_MODULES_MIN_API_VERSION is way better =)

[tzarc]

Made a simple conversion of @getreuer's socd_cleaner including use of introspection to validate things are on the right track:

https://github.com/tzarc/qmk_modules/tree/main/socd_cleaner

https://github.com/tzarc/qmk_userspace/blob/4250acc53f5ee015e4674bea54b668a1d65480bc/keyboards/tzarc/djinn/keymaps/tzarc/keymap.c#L79-L86

https://github.com/tzarc/qmk_userspace/blob/4250acc53f5ee015e4674bea54b668a1d65480bc/keyboards/tzarc/djinn/keymaps/tzarc/keymap.json

[thomasbaart]

This is a super cool development, and it's looking good!

A suggestion I'd like to make would be to have a community module be able to define their own part of the switch matrix, as a way to support hardware modules.

We added support for our splitkb.com Halcyon modules (which currently are a display, rotary encoder and cirque trackpad) through a QMK userspace, but I feel like the implementation of modules in this pull request could be far cleaner and easier to adapt and adopt for users.

A challenge we faced is that hardware modules (such as the encoder) can introduce additional inputs to the keyboard matrix, while the keyboard has no dedicated spots in its matrix for them. I think it would be nice if a module could introduce its own part of the matrix, so that keys can be mapped to it in software like VIA or Vial. VIA or Vial would be able to display an additional tab called "Modules" for example, in which each module could expose its matrix for easy remapping.

It's a long shot for sure! I hope this idea might provide inspiration for future development if it comes to that. Thank you very much!

[tzarc]

There's definitely future improvements to be made, including stuff like dealing with data storage and persistence.
I'm sure there will be future discussions covering information like what you've proposed -- we'll see how we go.