Add files via upload

2025-10-09 14:45:23 +02:00 · 2025-10-09 14:45:23 +02:00 · 0bd86793ac
commit 0bd86793ac
parent ffdd049589
18 changed files with 3628 additions and 1 deletions
--- a/qmk_flash_tools/MAPPING_LOGIC.md
+++ b/qmk_flash_tools/MAPPING_LOGIC.md
@ -0,0 +1,200 @@
+# Device Mapping Logic - Simple Explanation
+
+## The Three States
+
+```
+State 1: EMPTY      →  Learn both devices
+State 2: PARTIAL    →  Complete the mapping  
+State 3: COMPLETE   →  Only allow known devices
+```
+
+## State Transitions
+
+```
+┌─────────────┐
+│   EMPTY     │  No devices mapped
+│   (0/2)     │
+└──────┬──────┘
+       │ Flash first device
+       ▼
+┌─────────────┐
+│  PARTIAL    │  One device mapped
+│   (1/2)     │
+└──────┬──────┘
+       │ Flash second device
+       ▼
+┌─────────────┐
+│  COMPLETE   │  Both devices mapped
+│   (2/2)     │  ← Stays here forever
+└─────────────┘
+```
+
+## Behavior by State
+
+### State 1: EMPTY (0/2 devices)
+```
+Action: LEARN
+Rule:   Save devices as user specifies
+Result: Build initial mapping
+```
+
+### State 2: PARTIAL (1/2 devices)
+```
+Action: COMPLETE
+Rule:   Known device must match, unknown must be the missing side
+Result: Complete mapping OR error if ambiguous
+```
+
+### State 3: COMPLETE (2/2 devices)
+```
+Action: VERIFY
+Rule:   Only known devices allowed, must match expected side
+Result: Continue OR error immediately
+```
+
+## Decision Tree
+
+```
+Device Detected
+       │
+       ▼
+┌────────────────┐
+│ Mapping State? │
+└───┬────┬───┬───┘
+    │    │   │
+    ▼    ▼   ▼
+  Empty Part Comp
+    │    │    │
+    │    │    ▼
+    │    │  ┌──────────────┐
+    │    │  │ Device Known?│
+    │    │  └──┬───────┬───┘
+    │    │     │       │
+    │    │     NO      YES
+    │    │     │       │
+    │    │     ▼       ▼
+    │    │   REJECT  Match?
+    │    │            │
+    │    │      ┌─────┴─────┐
+    │    │      YES          NO
+    │    │      │            │
+    │    │      ▼            ▼
+    │    │    CONTINUE    MISMATCH
+    │    │                 OPTIONS
+    │    │
+    │    ▼
+    │  ┌──────────────┐
+    │  │ Device Known?│
+    │  └──┬───────┬───┘
+    │     │       │
+    │     NO      YES
+    │     │       │
+    │     ▼       ▼
+    │  Expected  Match?
+    │  unmapped    │
+    │   side?  ┌───┴────┐
+    │     │    YES      NO
+    │     ▼    │        │
+    │  ┌───┐  ▼        ▼
+    │  │YES│CONTINUE  ERROR
+    │  └─┬─┘
+    │    │NO
+    │    ▼
+    │  ERROR
+    │
+    ▼
+  SAVE AS
+  EXPECTED
+```
+
+## Examples
+
+### Example 1: First Time (Empty → Partial → Complete)
+```
+$ ./autoflash_modular.sh
+
+State: EMPTY (0/2)
+You: "left"
+Device: ABC123
+Action: Save ABC123 → left
+New State: PARTIAL (1/2)
+
+You: "Flash right? yes"
+Device: XYZ789
+Action: Save XYZ789 → right
+New State: COMPLETE (2/2)
+
+Mapping: {"ABC123": "left", "XYZ789": "right"}
+```
+
+### Example 2: Normal Use (Complete)
+```
+$ ./autoflash_modular.sh
+
+State: COMPLETE (2/2)
+You: "left"
+Device: ABC123
+Check: ABC123 is mapped to "left" ✅
+Action: Continue
+
+You: "right"
+Device: XYZ789
+Check: XYZ789 is mapped to "right" ✅
+Action: Continue
+```
+
+### Example 3: Unknown Device (Complete → Rejected)
+```
+$ ./autoflash_modular.sh
+
+State: COMPLETE (2/2)
+You: "left"
+Device: UNKNOWN
+Check: Not in mapping ❌
+Action: REJECT and EXIT
+
+Error: "Unknown device! Expected ABC123 or XYZ789"
+```
+
+### Example 4: Partial Mapping - Good
+```
+State: PARTIAL (1/2) - Only "left" mapped
+
+Scenario A: Known device
+You: "left"
+Device: ABC123 (known as left)
+Action: Continue ✅
+
+Scenario B: Unknown device for unmapped side
+You: "right" (unmapped)
+Device: UNKNOWN
+Action: Save as right ✅
+New State: COMPLETE
+```
+
+### Example 5: Partial Mapping - Bad
+```
+State: PARTIAL (1/2) - Only "left" mapped
+
+You: "left" (already mapped)
+Device: UNKNOWN
+Question: Is this a replacement for left? Or the unmapped right?
+Action: ERROR - ambiguous ❌
+Message: "Cannot determine! Clear mappings."
+```
+
+## Key Principle
+
+**Once both sides are mapped (COMPLETE state), the script becomes protective:**
+- ✅ Only the two known devices can be flashed
+- ❌ Any unknown device is rejected immediately
+- 🛡️ This prevents accidentally flashing the wrong keyboard
+
+**To reset:** `cd qmk_flash_tools && rm device_mappings.json`
+
+## Why This Works
+
+1. **Learning Phase** (Empty/Partial) - Flexible, builds mapping
+2. **Protection Phase** (Complete) - Strict, prevents mistakes
+3. **Clear Errors** - Always know why something failed
+4. **Easy Recovery** - Delete mapping file to restart