keychron-hardware-design

# Keychron Hardware Design Skill > Skill by [ara.so](https://ara.so) — Design Skills collection. This skill enables working with Keychron's production-grade hardware design files for 135+ keyboard and mouse models. The repository contains CAD assets in STEP, DXF, DWG, and PDF formats for cases, plates, keycaps, stabilizers, and full assemblies across all major Keychron series (Q, K, V, C, L, P, M, G). ## What This Project Provides - **135+ device models** with industrial design files - **734+ design files** across multiple CAD formats - **Production-grade geometry** for cases, plates, stabilizers, encoders, and keycaps - **Source-available license** allowing personal use, education, and original compatible accessories - **Multiple keyboard series**: Q Series, Q Pro, Q HE, Q Max, Q Ultra 8K, K Pro, K Max, K HE, K QMK, V Max, V Ultra 8K, V 8K, C Pro 8K, L Series, P HE - **Mouse series**: M1-M7, G1-G2 with shell and full model files ## Repository Structure ``` Keychron-Keyboards-Hardware-Design/ ├── C-Pro-8K-Series/ │ ├── C1 Pro 8K/ │ ├── C2 Pro 8K/ │ └── C3 Pro 8K/ ├── Q-Series/ │ ├── Q0 Plus/ │ ├── Q1/ through Q12/ │ ├── Q60/ │ └── Q65/ ├── Q-Pro-Series/ │ └── Q1 Pro/ through Q14 Pro/ ├── Q-HE-Series/ │ └── Q0 HE/ through Q12 HE/ ├── Q-Max-Series/ │ └── Q0 Max/ through Q15 Max/ ├── K-Pro-Series/ │ └── K1 Pro/ through K17 Pro/ ├── K-Max-Series/ │ └── K0 Max/ through K17 Max/ ├── K-HE-Series/ │ └── K2 HE/, K4 HE/, K6 HE/, K8 HE/, K10 HE/ ├── K-QMK-Series/ │ └── K1 QMK/ through K10 QMK/ ├── V-Max-Series/ │ └── V1 Max/ through V10 Max/ ├── L-Series/ │ ├── L1/ │ └── L3/ ├── P-HE-Series/ │ ├── P1 HE/ │ ├── P2 HE/ │ └── P3 HE/ ├── Mice/ │ ├── M1/ through M7/ │ ├── G1/ │ └── G2/ ├── Keycap Profiles/ │ ├── Cherry Profile/ │ ├── KSA/ │ ├── LSA/ │ ├── MDA/ │ ├── OEM/ │ └── OSA/ └── docs/ ├── file-format-guide.md ├── getting-started.md ├── 3d-printing-guide.md ├── license-faq.md └── CONTRIBUTING.md ``` ## Installation Clone the repository to access design files: ```bash git clone https://github.com/Keychron/Keychron-Keyboards-Hardware-Design.git cd Keychron-Keyboards-Hardware-Design ``` For large repositories, use sparse checkout to download only specific models: ```bash git clone --filter=blob:none --sparse https://github.com/Keychron/Keychron-Keyboards-Hardware-Design.git cd Keychron-Keyboards-Hardware-Design git sparse-checkout set "Q-Series/Q1" ``` ## File Formats and CAD Software Compatibility ### STEP Files (.stp, .step) Universal 3D CAD format for full geometry **Compatible software:** - **FreeCAD** (free, open source) - **Fusion 360** (free for personal use) - **SolidWorks** (commercial) - **Onshape** (cloud-based, free tier) - **Rhino** (commercial) - **Blender** (free, with CAD add-ons) ### DXF/DWG Files 2D technical drawings for plates and cutouts **Compatible software:** - **QCAD** (free) - **LibreCAD** (free, open source) - **AutoCAD** (commercial) - **DraftSight** (commercial) ### PDF Files Technical documentation and dimension references ## Working with Design Files ### Opening STEP Files in FreeCAD ```python # freecad_open_keychron.py import FreeCAD import Part # Open a Keychron case STEP file doc = FreeCAD.open("/path/to/Keychron-Keyboards-Hardware-Design/Q-Series/Q1/Q1-Case.stp") # Access the imported shapes objects = doc.Objects print(f"Loaded {len(objects)} objects") # Get bounding box dimensions for obj in objects: if hasattr(obj, 'Shape'): bbox = obj.Shape.BoundBox print(f"Object: {obj.Label}") print(f" Dimensions: {bbox.XLength:.2f} x {bbox.YLength:.2f} x {bbox.ZLength:.2f} mm") ``` ### Extracting Plate Dimensions from DXF ```python # dxf_plate_analysis.py import ezdxf # Load a Keychron plate DXF file doc = ezdxf.readfile("K-Pro-Series/K8-Pro/K8-Pro-Plate.dxf") msp = doc.modelspace() # Extract all circles (switch holes and mounting holes) circles = msp.query('CIRCLE') print(f"Found {len(circles)} circular features") for circle in circles: center = circle.dxf.center radius = circle.dxf.radius diameter = radius * 2 print(f"Circle at ({center.x:.2f}, {center.y:.2f}), diameter: {diameter:.2f}mm") # Find switch plate outline polylines = msp.query('LWPOLYLINE') for polyline in polylines: points = list(polyline.get_points()) print(f"Polyline with {len(points)} vertices") ``` ### Modifying Case Geometry in Python ```python # modify_case_mounting.py from OCP import gp, BRepPrimitivAPI, BRepAlgoAPI, BRepBuilderAPI import cadquery as cq # Load original Keychron case original_case = cq.importers.importStep("Q-Series/Q3/Q3-Case.stp") # Add custom mounting posts post_height = 10.0 post_diameter = 5.0 post_positions = [(20, 20), (20, 100), (140, 20), (140, 100)] for x, y in post_positions: post = cq.Workplane("XY").circle(post_diameter / 2).extrude(post_height) post = post.translate((x, y, 0)) original_case = original_case.union(post) # Export modified case cq.exporters.export(original_case, "Q3-Case-Modified.step") print("Modified case exported successfully") ``` ### Creating Compatible Accessory Plate ```python # create_accessory_plate.py import cadquery as cq # Reference Q1 case dimensions from STEP file case = cq.importers.importStep("Q-Series/Q1/Q1-Case.stp") bbox = case.val().BoundingBox() # Create top plate accessory with matching outline plate_thickness = 1.5 margin = 2.0 accessory_plate = ( cq.Workplane("XY") .box(bbox.xlen - margin * 2, bbox.ylen - margin * 2, plate_thickness) .faces(">Z") .workplane() # Add mounting holes matching Keychron mount points .pushPoints([(0, 0), (60, 0), (-60, 0)]) .circle(2.5) .cutThruAll() ) # Export accessory cq.exporters.export(accessory_plate, "Q1-Top-Plate-Accessory.step") print(f"Accessory plate: {bbox.xlen:.1f} x {bbox.ylen:.1f} x {plate_thickness}mm") ``` ## 3D Printing Workflow ### Preparing Case for 3D Printing ```python # prepare_for_printing.py import cadquery as cq from cadquery import exporters # Load Keychron case case = cq.importers.importStep("K-Max-Series/K3-Max/K3-Max-Case.stp") # Rotate for optimal printing orientation (largest face down) case_oriented = case.rotate((0, 0, 0), (1, 0, 0), 180) # Export as STL for slicing exporters.export(case_oriented, "K3-Max-Case-Printable.stl") # Check dimensions bbox = case_oriented.val().BoundingBox() print(f"Print bed requirements: {bbox.xlen:.1f} x {bbox.ylen:.1f} mm") print(f"Print height: {bbox.zlen:.1f} mm") ``` ### Generating Mounting Bracket ```python # mounting_bracket.py import cadquery as cq # Design bracket to attach accessories to Keychron case bracket = ( cq.Workplane("XY") .box(30, 15, 3) .faces(">Z").workplane() .rect(20, 8).cutBlind(-1.5) # Add screw holes .faces(">Z").workplane() .pushPoints([(10, 0), (-10, 0)]) .circle(1.5) .cutThruAll() ) # Export STL cq.exporters.export(bracket, "keychron-mount-bracket.stl", tolerance=0.01) ``` ## Common Patterns ### Measuring Switch Plate Hole Spacing ```python # analyze_plate_spacing.py import ezdxf import math doc = ezdxf.readfile("Q-Series/Q6/Q6-Plate.dxf") msp = doc.modelspace() # Extract switch holes (typically 14mm diameter circles) switch_holes = [c for c in msp.query('CIRCLE') if 13 < c.dxf.radius * 2 < 15] # Calculate spacing between adjacent switches centers = [(c.dxf.center.x, c.dxf.center.y) for c in switch_holes] centers.sort(key=lambda p: (p[1], p[0])) # Sort by row, then column # Standard keyboard spacing is 19.05mm (0.75 inches) for i in range(len(centers) - 1): dx = centers[i+1][0] - centers[i][0] dy = centers[i+1][1] - centers[i][1] distance = math.sqrt(dx**2 + dy**2) if distance < 25: # Adjacent switches print(f"Switch spacing: {distance:.2f}mm") ``` ### Extracting Stabilizer Positions ```python # extract_stabilizer_positions.py import cadquery as cq import json # Load full keyboard model keyboard = cq.importers.importStep("Q-Pro-Series/Q5-Pro/Q5-Pro-Full-Model.stp") # Stabilizers are typically rectangular cutouts 6.5-7mm wide # This example shows the pattern for finding them programmatically def find_stabilizer_cutouts(assembly): """Extract stabilizer mounting positions from assembly""" positions = [] # Iterate through all solid bodies in assembly for solid in assembly.solids().vals(): bbox = solid.BoundingBox() # Stabilizer cutouts are typically: # - Rectangular holes ~6.5-7mm wide # - Located in the plate layer # - Paired on either side of large keys if 6 < bbox.xlen < 8 and bbox.zlen < 5: positions.append({ "x": round((bbox.xmin + bbox.xmax) / 2, 2), "y": round((bbox.ymin + bbox.ymax) / 2, 2), "width": round(bbox.xlen, 2) }) return positions stabilizers = find_stabilizer_cutouts(keyboard) print(json.dumps(stabilizers, indent=2)) ``` ### Creating Custom Keycap Profile ```python # custom_keycap_profile.py import cadquery as cq # Reference Cherry profile dimensions from repository cherry_ref = cq.importers.importStep("Keycap Profiles/Cherry Profile/Cherry-R1.stp") ref_bbox = cherry_ref.val().BoundingBox() # Create custom keycap based on Cherry dimensions def create_custom_keycap(top_width=12, top_depth=12, height=8, angle=7): """Generate custom keycap with specified parameters""" keycap = ( cq.Workplane("XY") # Base (standard 18x18mm) .box(18, 18, 1) .faces(">Z").workplane() # Tapered body .box(top_width, top_depth, height) .faces(">Z").workplane() # Angled top surface .transformed(rotate=(angle, 0, 0)) # Slight dish .circle(top_width / 2).cutBlind(-0.5) # Stem mount (Cherry MX compatible) .faces("<Z").workplane() .rect(4, 1.2).extrude(4) .rect(1.2, 4).cutThruAll() ) return keycap custom_cap = create_custom_keycap(top_width=13, top_depth=13, height=9) cq.exporters.export(custom_cap, "custom-keycap.step") ``` ### Batch Processing Multiple Models ```python # batch_export_cases.py import os import cadquery as cq from pathlib import Path # Process all Q-Series cases q_series_path = Path("Q-Series") output_dir = Path("exports/q-series-stl") output_dir.mkdir(parents=True, exist_ok=True) for model_dir in q_series_path.iterdir(): if not model_dir.is_dir(): continue # Look for case STEP files case_files = list(model_dir.glob("*Case*.stp")) + list(model_dir.glob("*Case*.step")) for case_file in case_files: try: print(f"Processing {case_file.name}...") case = cq.importers.importStep(str(case_file)) # Export as STL output_file = output_dir / f"{case_file.stem}.stl" cq.exporters.export(case, str(output_file)) print(f" → Exported to {output_file.name}") except Exception as e: print(f" ✗ Error processing {case_file.name}: {e}") ``` ## Configuration and Environment ### Setting Up CAD Toolchain ```bash # Install Python CAD libraries pip install cadquery ezdxf numpy pip install OCP # OpenCascade bindings # For FreeCAD Python API pip install freecad # or use system FreeCAD installation ``` ### Environment Variables ```python # config.py import os from pathlib import Path # Repository location KEYCHRON_REPO = Path(os.getenv("KEYCHRON_REPO_PATH", "./Keychron-Keyboards-Hardware-Design")) # CAD export settings