rootiest/qmk_firmware
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Merged
rootiest merged 1 commits from chore/claude-docs into main 2026-04-13 17:02:12 +00:00
Conversation 0 Commits 1 Files Changed 1
+40 -6
rootiest commented 2026-04-13 16:58:00 +00:00
Owner
Copy Link
Copy Source

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
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
bug
Something is not working
 documentation
Scope affects only documentation
 duplicate
This issue or pull request already exists
 enhancement
New feature
 help wanted
Need some help
 invalid
Something is wrong
 question
More information is needed
 wontfix
This won't be fixed
No labels documentation
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
rootiest (Rootiest)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: rootiest/qmk_firmware#19