LumaLink

External Display Brightness Control for macOS

LumaLink is a native macOS menu bar app that gives you full control over external display brightness using DDC/CI protocol. Control your monitors with hardware keys (F1/F2), menu bar sliders, or keyboard shortcuts—just like the built-in MacBook display.

✨ Features

• 🖥️ Multi-Display Support — Control brightness on all external displays independently
• ⌨️ Hardware Key Integration — Use F1/F2 brightness keys (or Fn+F1/F2) on external displays
• 🎚️ Smooth Control — Per-display sliders with debounced writes for responsive adjustments
• 🔌 DDC/CI Protocol — Direct hardware control via I2C (no software overlays needed)
• 🌙 Software Dimming Fallback — Gamma-based dimming for displays that don't support DDC
• 🚀 Auto-Launch — Optional launch at login using SMAppService
• 💾 Persistent Settings — Remembers per-display preferences across reboots
• ⚡ Low CPU Usage — Event-driven architecture, no polling loops

📋 Requirements

• macOS 13.0 (Ventura) or later (macOS 14 Sonoma recommended)
• Apple Silicon (M1/M2/M3) or Intel Mac
• External display connected via:
  • USB-C / Thunderbolt
  • DisplayPort
  • HDMI
• Accessibility permission for keyboard monitoring

🚀 Quick Start

Pre-built App

1. Download the latest release from Releases
2. Drag LumaLink.app to /Applications
3. Launch the app
4. Grant Accessibility permission when prompted
5. Adjust brightness from the menu bar ☀️

Building from Source

See BUILD.md for detailed build instructions.

# Clone repository
git clone https://github.com/yourusername/LumaLink.git
cd LumaLink

# Open in Xcode
open LumaLink.xcodeproj

# Build and run
⌘ + R

📖 Usage

Menu Bar Controls

Click the ☀️ icon in the menu bar to access:

• Per-Display Sliders — Adjust brightness for each monitor independently
• Quick Actions — Set all displays to 25%, 50%, 75%, or 100%
• Display Menu — Enable software dimming or access advanced settings
• Preferences — Configure launch at login, brightness step, and permissions

Keyboard Shortcuts

• F1 (or Fn+F1) — Decrease brightness on selected external display
• F2 (or Fn+F2) — Increase brightness on selected external display

Default step: 6% (configurable in Preferences)

Software Dimming

If your display doesn't support DDC over certain connections (USB-C docks, some KVMs):

1. Click the gear icon next to the display name
2. Select "Enable Software Dimming"
3. Brightness will be controlled via gamma curves (visual dimming only)

Note: Software dimming doesn't change the backlight—it's a color profile overlay.

🔧 Troubleshooting

Display Not Detected

Symptoms: External display doesn't appear in LumaLink menu

Solutions:

1. Click "Refresh Displays" in the menu
2. Check cable connection (try a different USB-C port)
3. Some USB-C hubs/docks don't expose I2C — try direct connection
4. Restart LumaLink after connecting display

DDC Not Working

Symptoms: "DDC unavailable" warning or brightness changes have no effect

Common Causes:

• USB-C Docks/Hubs — Many cheaper docks don't pass through DDC/CI signals
  • Try: Direct USB-C to DisplayPort/HDMI cable
• KVM Switches — Most KVMs block DDC
  • Try: Direct connection or enable software dimming
• HDR Mode — Some displays disable DDC when HDR is active
  • Try: Disable HDR in System Settings → Displays
• Display Settings — DDC may be disabled in monitor OSD
  • Try: Check monitor settings for "DDC/CI" option

Workaround: Enable "Software Dimming" for affected displays

Brightness Keys Not Working

Symptoms: F1/F2 keys don't adjust external brightness

Solutions:

1. Grant Accessibility permission:
   • System Settings → Privacy & Security → Accessibility
   • Add and enable LumaLink
2. Check "Use F1, F2 as standard function keys" setting:
   • System Settings → Keyboard → Keyboard Shortcuts → Function Keys
   • LumaLink works with both configurations
3. Restart LumaLink after granting permissions

Known Limitations

Issue	Explanation	Workaround
USB-C dock brightness	Many docks don't pass I2C	Use direct cable or software dimming
KVM switches	Most KVMs block DDC signals	Switch KVM input or use software dimming
HDR displays	DDC often disabled in HDR mode	Disable HDR or use software dimming
Slow response	Some panels throttle DDC writes	Normal—app debounces to 100ms
Multiple controllers	Daisy-chained displays	Unchain or control individually

Advanced Debugging

Enable debug logging:

# View logs in Console.app
log stream --predicate 'subsystem == "com.lumalink.LumaLink"' --level debug

Common error codes:

• transportFailed — I2C communication blocked (dock/cable issue)
• timeout — Display not responding (try power cycle)
• invalidResponse — Corrupted DDC packet (retry)

🏗️ Architecture

Project Structure

LumaLink/
├── Sources/
│   ├── App/
│   │   └── LumaLinkApp.swift          # App entry point
│   ├── UI/
│   │   ├── Menu/MenuView.swift        # Menu bar interface
│   │   └── Preferences/               # Settings window
│   ├── Domain/
│   │   ├── Display.swift              # Display model & discovery
│   │   └── BrightnessService.swift    # Core brightness logic
│   ├── Infra/
│   │   ├── DDC/
│   │   │   ├── DDCClient.swift        # VCP packet encoding
│   │   │   └── IOKitI2CTransport.swift # Low-level I2C
│   │   ├── Hotkeys/KeyboardMonitor.swift
│   │   ├── Config/AppConfig.swift     # Persistence
│   │   └── Logging/Log.swift
│   └── Support/
│       └── EDIDParser.swift           # EDID hashing
└── Tests/                             # Unit tests

Key Technologies

• SwiftUI — Modern declarative UI with MenuBarExtra
• IOKit I2C — Direct framebuffer I2C access via IOI2CInterface
• DDC/CI — VESA standard for monitor control (VCP code 0x10)
• CGDisplay APIs — Display enumeration and identification
• NSEvent Monitors — Global keyboard event interception
• ServiceManagement — Login item registration

🧪 Testing

Run unit tests:

# In Xcode
⌘ + U

# Or via command line
xcodebuild test -scheme LumaLink -destination 'platform=macOS'

Test Coverage:

• DDC packet encoding/decoding: ✅ 95%
• EDID parsing & hashing: ✅ 90%
• Brightness service logic: ✅ 85%
• Debouncing & rate limiting: ✅ 80%

Integration tests use mock I2C transport to simulate hardware responses.

🔐 Security & Privacy

Permissions Required

1. Accessibility — To monitor F1/F2 key presses globally
   • Only intercepts brightness keys
   • Does not log or record keystrokes

Code Signing

LumaLink must be signed and notarized for distribution:

• Non-sandboxed (required for IOKit I2C access)
• Hardened runtime enabled
• No private frameworks used
• Developer ID signed

Privacy Guarantees

• ❌ No analytics or telemetry
• ❌ No network requests
• ❌ No data leaves your Mac
• ✅ Settings stored locally in ~/Library/Application Support

🛠️ Development

Prerequisites

• Xcode 15.0 or later
• Swift 5.9 or later
• macOS 13.0 SDK

Build Configuration

Setting	Value	Reason
App Sandbox	OFF	IOKit I2C requires root-level access
Hardened Runtime	ON	Required for notarization
Library Validation	ON	Security best practice
Code Signing	Developer ID	Distribution outside Mac App Store

Performance Targets

• Idle CPU: < 1%
• Memory: < 30 MB
• I2C timeout: 800ms
• Debounce interval: 100ms
• Max retry: 2 attempts with 200ms backoff

📚 References

DDC/CI Protocol

• VESA DDC/CI Standard
• VCP Code Table
• VCP 0x10: Brightness (0-100)
• VCP 0x12: Contrast (0-100)
• VCP 0xD6: Power Mode

Apple Documentation

• IOKit I2C
• CGDisplay APIs
• ServiceManagement

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests for new functionality
4. Ensure all tests pass (⌘ + U)
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Inspired by MonitorControl
• DDC implementation references from ddcctl
• EDID parsing based on VESA EDID Standard

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

---

Made with ☀️ for external display users