Skip to content

Design a composable, geometry-aware lighting system - #1

Open
colonelpanic8 wants to merge 1 commit into
mainfrom
codex/lighting-system-design
Open

Design a composable, geometry-aware lighting system#1
colonelpanic8 wants to merge 1 commit into
mainfrom
codex/lighting-system-design

Conversation

@colonelpanic8

@colonelpanic8 colonelpanic8 commented Jul 20, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Summary

Adds a working design proposal for an RMK lighting system centered on:

  • deterministic composition of independent lighting sources;
  • first-class key mappings, physical geometry, and zones;
  • built-in layer-aware lighting;
  • allocation-free rendering and deadline-driven updates;
  • separation between topology, sources, compositor, processor, and driver; and
  • protocol-neutral integration with Rynk and Vial.

The document includes conceptual Rust interfaces and Mermaid diagrams for both
runtime ownership and board-configuration flow.

Purpose

This PR exists in the fork as an inline-review surface for the design. It does
not propose implementation code or commit RMK to the sketched API names and
generic parameters.

Upstream discussion: rmk-rs#979

Validation

  • prettier --check docs/docs/main/docs/development/lighting-design.md
  • git diff --check

@colonelpanic8 colonelpanic8 mentioned this pull request Jul 20, 2026
Open
@github-actions

github-actions Bot commented Jul 20, 2026

Copy link
Copy Markdown

Size Report

Example main PR Diff .text .data .bss
use_config/nrf52832_ble 389.8 KiB 389.8 KiB +0.00% 0 0 0
use_config/nrf52840_ble 435.3 KiB 435.3 KiB +0.00% ⬆️ +4 0 0
use_config/nrf52840_ble_split (central) 489.1 KiB 489.1 KiB +0.00% ⬇️ -4 0 0
use_config/nrf52840_ble_split (peripheral) 315.9 KiB 315.9 KiB +0.00% 0 0 0
use_config/pi_pico_w_ble 663.2 KiB 663.3 KiB +0.00% ⬆️ +4 0 0
use_config/rp2040 145.7 KiB 145.7 KiB +0.00% 0 0 0
use_config/rp2040_split (central) 159.2 KiB 159.2 KiB +0.00% 0 0 0
use_config/rp2040_split (peripheral) 27.8 KiB 27.8 KiB +0.00% 0 0 0
use_config/stm32f1 61.9 KiB 61.9 KiB +0.00% 0 0 0
use_config/stm32h7 99.0 KiB 99.0 KiB +0.00% 0 0 0
use_rust/nrf52832_ble 377.2 KiB 377.2 KiB +0.00% ⬆️ +4 0 0
use_rust/nrf52840_ble 432.8 KiB 432.8 KiB +0.00% 0 0 0
use_rust/nrf52840_ble_split (central) 497.5 KiB 497.5 KiB +0.00% 0 0 0
use_rust/nrf52840_ble_split (peripheral) 312.2 KiB 312.2 KiB +0.00% 0 0 0
use_rust/pi_pico_w_ble 663.7 KiB 663.7 KiB +0.00% ⬆️ +8 0 0
use_rust/rp2040 145.2 KiB 145.2 KiB +0.00% 0 0 0
use_rust/rp2040_split (central) 158.1 KiB 158.1 KiB +0.00% ⬇️ -4 0 0
use_rust/rp2040_split (peripheral) 28.2 KiB 28.2 KiB +0.00% 0 0 0
use_rust/stm32f1 61.2 KiB 61.2 KiB +0.00% 0 0 0
use_rust/stm32h7 119.7 KiB 119.7 KiB +0.00% ⬇️ -4 0 0
use_config/nrf52832_ble — 389.8 KiB → 389.8 KiB (+0.00%)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
 361076	   4588	  33520	 399184	  61750	rmk-nrf52832

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
 361076	   4588	  33520	 399184	  61750	rmk-nrf52832

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +2.1%      +1  [ = ]       0    [Unmapped]
  -0.0%     -30  [ = ]       0    .strtab
  -0.7%     -54  [ = ]       0    .debug_abbrev
  -0.1%    -229  [ = ]       0    .debug_line
  -0.0%    -245  [ = ]       0    .debug_str
  -0.0%    -351  [ = ]       0    .debug_info
  -0.0%    -908  [ = ]       0    TOTAL
use_config/nrf52840_ble — 435.3 KiB → 435.3 KiB (+0.00% ⬆️)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
 394064	   4596	  47080	 445740	  6cd2c	rmk-nrf52840

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
 394060	   4596	  47080	 445736	  6cd28	rmk-nrf52840

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +0.0%      +4  +0.0%      +4    .text
  +0.0%      +2  [ = ]       0    .debug_loc
  -8.3%      -4  [ = ]       0    [Unmapped]
  -0.0%     -30  [ = ]       0    .strtab
  -0.5%     -39  [ = ]       0    .debug_abbrev
  -0.0%     -82  [ = ]       0    .debug_line
  -0.0%    -110  [ = ]       0    .debug_str
  -0.0%    -137  [ = ]       0    .debug_info
  -0.0%    -396  +0.0%      +4    TOTAL
use_config/nrf52840_ble_split (central) — 489.1 KiB → 489.1 KiB (+0.00% ⬇️)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
 450544	   4652	  45600	 500796	  7a43c	central

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
 450548	   4652	  45600	 500800	  7a440	central

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +0.0%     +12  [ = ]       0    .strtab
   +20%      +9  [ = ]       0    [Unmapped]
  +0.0%      +2  [ = ]       0    .debug_loc
  -0.0%      -4  -0.0%      -4    .text
  -0.0%     -19  [ = ]       0    .debug_line
  -0.0%     -84  [ = ]       0    .debug_info
  -0.0%    -100  [ = ]       0    .debug_str
  -0.0%    -184  -0.0%      -4    TOTAL
use_config/nrf52840_ble_split (peripheral) — 315.9 KiB → 315.9 KiB (+0.00%)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
 291832	   4468	  27184	 323484	  4ef9c	peripheral

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
 291832	   4468	  27184	 323484	  4ef9c	peripheral

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +0.0%    +232  [ = ]       0    .debug_info
  +0.0%    +155  [ = ]       0    .debug_str
  +0.0%     +98  [ = ]       0    .debug_line
  +0.0%      +4  [ = ]       0    .strtab
  +0.0%      +2  [ = ]       0    .debug_loc
  -4.4%      -3  [ = ]       0    [Unmapped]
  +0.0%    +488  [ = ]       0    TOTAL
use_config/pi_pico_w_ble — 663.2 KiB → 663.3 KiB (+0.00% ⬆️)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
 625800	      0	  53372	 679172	  a5d04	rmk-pi-pico-w

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
 625796	      0	  53372	 679168	  a5d00	rmk-pi-pico-w

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +0.0%      +4  +0.0%      +4    .text
  -0.0%      -4  [ = ]       0    .strtab
 -15.2%      -7  [ = ]       0    [Unmapped]
  -0.0%     -10  [ = ]       0    .debug_loc
  -0.4%     -39  [ = ]       0    .debug_abbrev
  -0.0%     -97  [ = ]       0    .debug_line
  -0.0%    -136  [ = ]       0    .debug_str
  -0.0%    -251  [ = ]       0    .debug_info
  -0.0%    -540  +0.0%      +4    TOTAL
use_config/rp2040 — 145.7 KiB → 145.7 KiB (+0.00%)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
 134372	      0	  14788	 149160	  246a8	rmk-rp2040

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
 134372	      0	  14788	 149160	  246a8	rmk-rp2040

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +0.1% +2.11Ki  [ = ]       0    .debug_str
  +0.2%    +213  [ = ]       0    .strtab
  +0.1%    +124  [ = ]       0    .debug_line
  +0.0%     +37  [ = ]       0    .debug_info
  +0.0%     +10  [ = ]       0    .debug_loc
  -6.7%      -3  [ = ]       0    [Unmapped]
  +0.1% +2.48Ki  [ = ]       0    TOTAL
use_config/rp2040_split (central) — 159.2 KiB → 159.2 KiB (+0.00%)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
 147344	      0	  15652	 162996	  27cb4	central

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
 147344	      0	  15652	 162996	  27cb4	central

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +0.0%     +36  [ = ]       0    .debug_str
  +0.0%      +3  [ = ]       0    .strtab
  -0.0%      -9  [ = ]       0    .debug_info
  -0.0%     -30  [ = ]       0    .debug_line
  [ = ]       0  [ = ]       0    TOTAL
use_config/rp2040_split (peripheral) — 27.8 KiB → 27.8 KiB (+0.00%)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
  25616	     60	   2796	  28472	   6f38	peripheral

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
  25616	     60	   2796	  28472	   6f38	peripheral

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +0.0%      +2  [ = ]       0    .debug_str
  +0.0%      +1  [ = ]       0    .strtab
  +3.0%      +1  [ = ]       0    [Unmapped]
  +0.0%      +4  [ = ]       0    TOTAL
use_config/stm32f1 — 61.9 KiB → 61.9 KiB (+0.00%)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
  56504	     28	   6804	  63336	   f768	rmk-stm32f1

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
  56504	     28	   6804	  63336	   f768	rmk-stm32f1

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  [ = ]       0  [ = ]       0    TOTAL
use_config/stm32h7 — 99.0 KiB → 99.0 KiB (+0.00%)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
  92164	    264	   8992	 101420	  18c2c	rmk-stm32h7

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
  92164	    264	   8992	 101420	  18c2c	rmk-stm32h7

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +2.9%      +1  [ = ]       0    [Unmapped]
  -0.3%    -186  [ = ]       0    .strtab
  -0.1% -1.19Ki  [ = ]       0    .debug_str
  -0.0% -1.38Ki  [ = ]       0    TOTAL
use_rust/nrf52832_ble — 377.2 KiB → 377.2 KiB (+0.00% ⬆️)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
 349168	   4588	  32504	 386260	  5e4d4	rmk-nrf52832

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
 349164	   4588	  32504	 386256	  5e4d0	rmk-nrf52832

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +0.0%      +4  +0.0%      +4    .text
 -10.5%      -6  [ = ]       0    [Unmapped]
  -0.2%     -16  [ = ]       0    .debug_abbrev
  -0.0%     -30  [ = ]       0    .strtab
  -0.1%    -235  [ = ]       0    .debug_line
  -0.0%    -245  [ = ]       0    .debug_str
  -0.0%    -300  [ = ]       0    .debug_info
  -0.0%    -828  +0.0%      +4    TOTAL
use_rust/nrf52840_ble — 432.8 KiB → 432.8 KiB (+0.00%)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
 395280	   4588	  43368	 443236	  6c364	rmk-nrf52840

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
 395280	   4588	  43368	 443236	  6c364	rmk-nrf52840

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +0.1%    +236  [ = ]       0    .debug_line
  +0.0%    +208  [ = ]       0    .debug_info
  +0.0%    +110  [ = ]       0    .debug_str
  +0.5%     +39  [ = ]       0    .debug_abbrev
  +0.0%     +30  [ = ]       0    .strtab
  +1.9%      +1  [ = ]       0    [Unmapped]
  +0.0%    +624  [ = ]       0    TOTAL
use_rust/nrf52840_ble_split (central) — 497.5 KiB → 497.5 KiB (+0.00%)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
 454292	   4652	  50480	 509424	  7c5f0	central

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
 454292	   4652	  50480	 509424	  7c5f0	central

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +0.2%    +607  [ = ]       0    .debug_line
  +0.0%     +48  [ = ]       0    .debug_info
  +0.0%     +44  [ = ]       0    .debug_str
  +0.0%     +12  [ = ]       0    .strtab
  -5.7%      -3  [ = ]       0    [Unmapped]
  -0.0%     -12  [ = ]       0    .debug_loc
  +0.0%    +696  [ = ]       0    TOTAL
use_rust/nrf52840_ble_split (peripheral) — 312.2 KiB → 312.2 KiB (+0.00%)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
 289836	   4468	  25432	 319736	  4e0f8	peripheral

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
 289836	   4468	  25432	 319736	  4e0f8	peripheral

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +0.0%    +232  [ = ]       0    .debug_info
  +0.0%    +155  [ = ]       0    .debug_str
  +0.0%     +98  [ = ]       0    .debug_line
  +0.0%      +4  [ = ]       0    .strtab
  -9.8%      -5  [ = ]       0    [Unmapped]
  -0.0%     -12  [ = ]       0    .debug_loc
  +0.0%    +472  [ = ]       0    TOTAL
use_rust/pi_pico_w_ble — 663.7 KiB → 663.7 KiB (+0.00% ⬆️)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
 626104	      0	  53516	 679620	  a5ec4	rmk-pi-pico-w

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
 626096	      0	  53516	 679612	  a5ebc	rmk-pi-pico-w

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +0.0%      +8  +0.0%      +8    .text
 -11.9%      -8  [ = ]       0    [Unmapped]
  -0.0%     -26  [ = ]       0    .strtab
  -0.4%     -39  [ = ]       0    .debug_abbrev
  -0.0%    -105  [ = ]       0    .debug_line
  -0.0%    -180  [ = ]       0    .debug_str
  -0.0%    -246  [ = ]       0    .debug_info
  -0.0%    -596  +0.0%      +8    TOTAL
use_rust/rp2040 — 145.2 KiB → 145.2 KiB (+0.00%)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
 134056	      0	  14660	 148716	  244ec	rmk-rp2040

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
 134056	      0	  14660	 148716	  244ec	rmk-rp2040

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +0.0%    +101  [ = ]       0    .debug_str
  +0.1%     +92  [ = ]       0    .debug_line
  +0.0%     +37  [ = ]       0    .debug_info
  +7.5%      +3  [ = ]       0    [Unmapped]
  +0.0%      +1  [ = ]       0    .strtab
  -0.0%     -10  [ = ]       0    .debug_loc
  +0.0%    +224  [ = ]       0    TOTAL
use_rust/rp2040_split (central) — 158.1 KiB → 158.1 KiB (+0.00% ⬇️)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
 146468	      0	  15436	 161904	  27870	central

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
 146472	      0	  15436	 161908	  27874	central

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +7.1%      +3  [ = ]       0    [Unmapped]
  -0.0%      -1  [ = ]       0    .strtab
  -0.0%      -4  -0.0%      -4    .text
  -0.0%     -10  [ = ]       0    .debug_loc
  -0.0%     -12  -0.0%      -4    TOTAL
use_rust/rp2040_split (peripheral) — 28.2 KiB → 28.2 KiB (+0.00%)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
  25716	     60	   3060	  28836	   70a4	peripheral

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
  25716	     60	   3060	  28836	   70a4	peripheral

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +0.0%      +1  [ = ]       0    .debug_str
  -1.5%      -1  [ = ]       0    [Unmapped]
  [ = ]       0  [ = ]       0    TOTAL
use_rust/stm32f1 — 61.2 KiB → 61.2 KiB (+0.00%)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
  55916	     28	   6772	  62716	   f4fc	rmk-stm32f1

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
  55916	     28	   6772	  62716	   f4fc	rmk-stm32f1

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  -4.9%      -2  [ = ]       0    [Unmapped]
  -0.0%      -6  [ = ]       0    .debug_line
  -0.0%      -9  [ = ]       0    .strtab
  -0.0%     -63  [ = ]       0    .debug_str
  -0.0%     -80  [ = ]       0    TOTAL
use_rust/stm32h7 — 119.7 KiB → 119.7 KiB (+0.00% ⬇️)

cargo size (PR):

   text	   data	    bss	    dec	    hex	filename
 107296	    320	  14940	 122556	  1debc	rmk-stm32h7

cargo size (main):

   text	   data	    bss	    dec	    hex	filename
 107300	    320	  14940	 122560	  1dec0	rmk-stm32h7

Bloaty diff (PR vs main):

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +0.1%    +124  [ = ]       0    .debug_line
  +0.0%     +37  [ = ]       0    .debug_info
  +0.0%     +30  [ = ]       0    .strtab
   +17%      +7  [ = ]       0    [Unmapped]
  -0.0%      -2  [ = ]       0    .debug_loc
  -0.0%      -4  -0.0%      -4    .text
  -0.0%    -520  [ = ]       0    .debug_str
  -0.0%    -328  -0.0%      -4    TOTAL

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@colonelpanic8