Skip to content

Add dynamic board names using custom VIA values - #430

Merged
Cipulot merged 1 commit into
mainfrom
dynamic-board-name
Jul 27, 2026
Merged

Add dynamic board names using custom VIA values#430
Cipulot merged 1 commit into
mainfrom
dynamic-board-name

Conversation

@Cipulot

@Cipulot Cipulot commented Jul 27, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds support for dynamically selecting the displayed board name using a value returned through the existing VIA custom-value channel.
This allows multiple hardware variants sharing the same VID/PID and definition to display different names without requiring changes to QMK core.

Definition format

Existing static names remain supported:

{
  "name": "Existing Board"
}

Definitions can now provide multiple names and a custom-value command:

{
  "name": {
    "options": [
      "Default Board",
      "Alternate Board",
      "Special Edition"
    ],
    "content": ["id_board_variant", 0, 200]
  }
}

The content tuple uses the existing custom-control format:

[token ID, custom channel ID, value ID]

The board returns a zero-based index corresponding to an entry in options.

Behavior

  • Uses the returned value to select the displayed board name.
  • Falls back to the first option when the response is missing, malformed,
    unhandled, or outside the available range.
  • Stores the selected option per connected device.
  • Preserves existing string-based board names without behavioral changes.
  • Uses the resolved name in the keyboard badge, device list, layout exports,
    debug views, and design views.

Diagnostics

Custom-menu commands now carry their semantic command names through the HID queue.

This distinguishes overlapping protocol command IDs correctly:

  • Custom-value failures display CUSTOM_MENU_GET_VALUE.
  • Actual legacy backlight failures display BACKLIGHT_CONFIG_GET_VALUE.
  • The same distinction is applied to custom set and save commands.

This changes diagnostic labels only; command bytes and response validation
remain unchanged.

Dependencies

  • Updates @the-via/reader to 1.14.2.
  • Forces the app and via-keyboards to share reader 1.14.2.
  • Updates bun.lock and package-lock.json.
  • Removes the local reader development link and related duplicate dependency.

Compatibility

  • Existing definitions require no changes.
  • Dynamic names are opt-in.
  • Uses the existing VIA custom-value protocol.
  • Does not require QMK-core changes.

Verification

  • bun install --frozen-lockfile
  • bun run build
  • git diff --check

@Cipulot
Cipulot merged commit 4c8d4f7 into main Jul 27, 2026
1 check passed
@Cipulot
Cipulot deleted the dynamic-board-name branch July 27, 2026 09:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant