Skip to content

About

No description or website provided.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

5 Commits

Folders and files

Repository files navigation

💡 MacLightController

A native macOS application that automates your keyboard backlight based on time triggers, sunrise/sunset, and custom schedules. Built with SwiftUI and IOKit, this menu bar app runs quietly in the background and intelligently manages your MacBook's keyboard illumination. I built this side project for learning purposes and to solve a personal annoyance – manually adjusting keyboard backlight throughout the day.

📦 Technologies

  • Swift & SwiftUI
  • IOKit Framework
  • macOS AppKit
  • Combine Framework
  • Core Location (for sunrise/sunset)

🦄 Features

Here's what you can do with MacLightController:

Menu Bar Integration: Lives discreetly in your menu bar, accessible with a single click. No dock icon, no window clutter – just a simple status item that's always available when you need it.

Keyboard Backlight Control: Manually adjust brightness with a smooth slider or let automations handle it. Instant feedback shows the current brightness level as you adjust it.

Flexible Automation Triggers: Create schedules based on specific times, sunrise/sunset, or recurring intervals. Mix and match triggers to build the perfect lighting schedule for your workflow.

Sunrise & Sunset Awareness: Automatically adjusts based on actual sunrise and sunset times for your location. Optionally add offsets (e.g., "30 minutes before sunset") for even more control.

Smart Scheduling: Set different brightness levels for different times of day. Bright backlight during the day, dimmed for evening work, off at night – all handled automatically.

Location Services: Uses Core Location to determine accurate sunrise/sunset times. You can allow automatic location detection or manually set your coordinates for privacy.

Background Operation: Runs efficiently without draining battery or consuming significant resources. The app is optimized for Apple Silicon and uses minimal memory.

🎯 Keyboard Shortcuts

  • Click Menu Bar Icon: Open quick controls
  • Option+Click: Open full settings
  • Quick Slider: Adjust brightness instantly from menu

👩🏽‍🍳 The Process

I started this project out of personal frustration. I'd manually adjust my keyboard backlight multiple times a day – bright in the morning, dimmed in the afternoon, off at night. It felt like something a computer should handle automatically.

My first challenge was figuring out how to actually control the keyboard backlight programmatically. macOS doesn't expose this through standard APIs, so I had to dive into IOKit, Apple's low-level framework for hardware communication. Reading through obscure documentation and forum posts, I eventually found the IOKit services that manage keyboard illumination.

Building the automation engine was the next step. I needed a scheduler that could handle different types of triggers – specific times, sunrise/sunset calculations, and repeating intervals. I designed a plugin-based architecture where each trigger type is a separate module, making the system extensible for future automation types.

Integrating Core Location for sunrise/sunset was interesting. I had to handle user privacy concerns (some people don't want apps knowing their location), permission requests, and fallbacks for when location isn't available. I added manual coordinate entry as an alternative.

The UI evolved significantly. Initially, I built a full windowed app, but that felt heavyweight for something so simple. I pivoted to a menu bar-only interface, which felt much more macOS-native. Users can quickly adjust brightness or check automations without opening a separate window.

Apple Silicon optimization was important. I made sure the app ran natively on M-series chips, took advantage of power efficiency features, and minimized background activity. The goal was an app you could leave running 24/7 without noticing any performance impact.

Testing edge cases took time. What happens if the system wakes from sleep mid-automation? What if the user manually changes brightness – should automations override that? These scenarios required careful thought about user expectations and system behavior.

📚 What I Learned

During this project, I've picked up important skills and a deeper understanding of macOS development, system-level programming, and native app design.

🍎 macOS Native Development

SwiftUI for macOS: Building menu bar apps taught me about NSStatusItem, popover presentations, and macOS-specific UI patterns. SwiftUI on macOS differs from iOS in subtle but important ways.

IOKit Framework: Diving into hardware control through IOKit was eye-opening. I learned about service matching, property iteration, and how to safely communicate with hardware drivers without causing system instability.

App Sandbox Limitations: I discovered why App Sandbox had to be disabled for this app – direct hardware access isn't allowed in sandboxed environments. This taught me about macOS security models and trade-offs.

⏰ Scheduling & Automation

Time-Based Triggers: Implementing a reliable scheduler taught me about timezone handling, daylight saving time transitions, and how to calculate future execution times accurately.

Astronomical Calculations: Working with sunrise/sunset taught me about solar position algorithms, coordinate systems, and how to account for atmospheric refraction in civil twilight calculations.

Event-Driven Architecture: Building a plugin system for different trigger types taught me about abstract interfaces, dependency injection, and how to make code extensible without over-engineering.

🧠 System Programming

Hardware Abstraction: Learning to interact with hardware through abstraction layers taught me about driver architecture, service providers, and how operating systems manage hardware resources.

Background Operations: Keeping an app running efficiently in the background taught me about task scheduling, power management APIs, and how to be a "good citizen" in the macOS ecosystem.

🎨 macOS Design Patterns

Menu Bar Apps: I learned the conventions for menu bar applications – when to show badges, how to structure menus, and providing quick actions versus full settings.

Native Look & Feel: Matching system aesthetics taught me about design tokens, respecting user preferences (like reduced motion), and creating interfaces that feel like they belong to macOS.

📈 Overall Growth

This project taught me that solving your own problems leads to the best learning experiences. Because I used the app daily, I noticed every rough edge and iterated until it felt polished.

Working with low-level APIs like IOKit was intimidating initially, but it demystified system programming. Hardware isn't magic – it's just APIs and protocols, accessible once you understand the patterns.

Most importantly, I learned about restraint in feature design. I resisted adding display brightness, volume control, and other automations. By keeping the scope focused on keyboard backlight, I shipped a polished, reliable tool instead of a half-baked automation suite.

💭 How can it be improved?

  • Add support for display brightness automation
  • Implement dark mode toggle automation
  • Add system volume control schedules
  • Create Focus mode integrations
  • Add Shortcuts app integration for macOS
  • Implement smooth brightness transitions (fade in/out)
  • Add condition-based triggers (e.g., "when plugged in")
  • Create preset profiles for different workflows
  • Add notification preferences for automation events
  • Implement import/export for automation configurations

🚦 Running the Project

To run the project in your local environment, follow these steps:

  1. Clone the repository:

    git clone https://github.com/Shipwithsimo/MacLightController.git
    cd MacLightController
  2. Open the project in Xcode 15 or later:

    open MacLightController.xcodeproj
  3. Select the MacLightController scheme and your Mac as the destination

  4. Build and run (⌘R) the project

  5. Grant necessary permissions:

    • Accessibility: Required for keyboard backlight control
    • Location Services (optional): For sunrise/sunset features

System Requirements:

  • macOS 13.0 (Ventura) or later
  • Apple Silicon (M1/M2/M3/M4) Mac
  • MacBook with backlit keyboard

🎥 Preview

A minimal menu bar icon that shows the current backlight status. Clicking it reveals a clean popup with a brightness slider and a list of active automations. The settings panel lets you create new automations with intuitive date/time pickers and trigger options. The entire interface feels like a native macOS system preference.

About

No description or website provided.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages