docs: expand CLAUDE.md with K17 Max, branch names, and EEPROM notes #19

2026-04-13T16:58:00Z

rootiest commented

2026-04-13 16:58:00 +00:00

Summary

Update dev branch names: q5_dev → dev/q5, add dev/k17 for K17 Max
Add K17 Max build/flash commands with the correct ansi_encoder/rgb subvariant path
Document EEPROM layout, Keychron RGB behaviour, and DIP switch overlay approach based on lessons learned from PR #18

Changes

Branch names

q5_dev renamed to dev/q5 throughout
dev/k17 added as the K17 Max development branch

K17 Max

Build/flash commands use keychron/k17_max/ansi_encoder/rgb (the RGB variant; a separate white LED variant exists at ansi_encoder)
Keymap path corrected to keyboards/keychron/k17_max/ansi_encoder/rgb/keymaps/via/

EEPROM Layout Notes (new section)

Documents EECONFIG_RGB_MATRIX address and bitfield packing
Explains VIA_EEPROM_MAGIC_ADDR 544 pinning rule and when to raise it
Notes the #undef EECONFIG_KB_DATA_SIZE requirement

Keychron RGB (new section)

When and where to call eeconfig_init_custom_rgb() vs eeconfig_reset_custom_rgb()
Why kc_rgb_save() must call eeconfig_update_rgb_matrix()
The retail_demo_enable 0xFF bug and the load-path clamp that recovers it
default_per_key_led[] / default_region[] must be defined in board-specific code

DIP Switch (new section)

Documents the frame overlay approach and why direct rgb_matrix_mode() calls corrupt EEPROM state

## Summary - Update dev branch names: `q5_dev` → `dev/q5`, add `dev/k17` for K17 Max - Add K17 Max build/flash commands with the correct `ansi_encoder/rgb` subvariant path - Document EEPROM layout, Keychron RGB behaviour, and DIP switch overlay approach based on lessons learned from PR #18 ## Changes **Branch names** - `q5_dev` renamed to `dev/q5` throughout - `dev/k17` added as the K17 Max development branch **K17 Max** - Build/flash commands use `keychron/k17_max/ansi_encoder/rgb` (the RGB variant; a separate white LED variant exists at `ansi_encoder`) - Keymap path corrected to `keyboards/keychron/k17_max/ansi_encoder/rgb/keymaps/via/` **EEPROM Layout Notes** (new section) - Documents `EECONFIG_RGB_MATRIX` address and bitfield packing - Explains `VIA_EEPROM_MAGIC_ADDR 544` pinning rule and when to raise it - Notes the `#undef EECONFIG_KB_DATA_SIZE` requirement **Keychron RGB** (new section) - When and where to call `eeconfig_init_custom_rgb()` vs `eeconfig_reset_custom_rgb()` - Why `kc_rgb_save()` must call `eeconfig_update_rgb_matrix()` - The `retail_demo_enable` 0xFF bug and the load-path clamp that recovers it - `default_per_key_led[]` / `default_region[]` must be defined in board-specific code **DIP Switch** (new section) - Documents the frame overlay approach and why direct `rgb_matrix_mode()` calls corrupt EEPROM state

rootiest added 1 commit 2026-04-13 16:58:01 +00:00

docs: expand CLAUDE.md with K17 Max, branch names, and EEPROM notes b4a76db6f3

- Rename dev branch references from q5_dev to dev/q5; add dev/k17 for
  K17 Max work
- Add K17 Max build/flash commands using the correct rgb subvariant path
  (keychron/k17_max/ansi_encoder/rgb) to distinguish from the white LED
  variant
- Add EEPROM Layout Notes section documenting the Q5 Max address map,
  VIA_EEPROM_MAGIC_ADDR pinning rules, and EECONFIG_KB_DATA_SIZE #undef
  requirement
- Add Keychron RGB section capturing lessons from the persistence work:
  when to call eeconfig_init_custom_rgb(), version stamp placement,
  kc_rgb_save() mode persistence, retail_demo_enable 0xFF bug, and
  extern array requirements
- Add DIP Switch section explaining the frame overlay approach and why
  direct rgb_matrix_mode() calls must be avoided

rootiest added the documentation label 2026-04-13 17:01:50 +00:00

rootiest merged commit ad41de2f54 into main

2026-04-13 17:02:12 +00:00

rootiest deleted branch chore/claude-docs

2026-04-13 17:02:12 +00:00

rootiest referenced this issue from a commit

2026-04-13 17:02:13 +00:00

Merge pull request 'docs: expand CLAUDE.md with K17 Max, branch names, and EEPROM notes' (#19) from chore/claude-docs into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: rootiest/qmk_firmware#19