How to make the NumLock LED work on OSX
tl;dr: This is what you’re looking for https://github.com/rajiteh/setledsmac
If you are reading this article, the chances are that you just got yourself a shiny new TKL/Gaming/Mechanical keyboard and found out that the NumLock key is not working when using it with a Mac.
Turns out that Apple keyboards never had a NumLock key and therefore the OS just never supported it.
There are few workarounds suggested on the internet on how to rectify the issue, most of them focus on toggling the number input vs alt-input at software or glueing together bunch of third party apps to get the job done. See here, here, or here.
Unfortunately, little to no focus is given to the fact that some keyboards use the NumLock LED to toggle the input mode physically on certain key sets. I ran in to this exact problem with my CoolerMaster MasterKeys Pro M where it required the NumLock LED to toggling number input vs Arrow keys the shared number pad.
Enter SetLedsMac
SetLedsMac is an excellent tool written to counter this exact issue. It taps in to the IOHIDDevice class in the Kernel and triggers NumLock, ScrollLock, and CapsLock LEDs on demand.
While this tool worked as described it was not ideal for everyday use. I did not want to run a command every single time I wanted to toggle NumLock. There were solutions on StackOverflow and elsewhere suggesting to use AppleScript or another input listener software to run the command automatically on keypress events. Some of these workarounds even required using licensed software, but none of them were elegant and easy-to-use.
I already paid for my Mac and my keyboard. I shouldn’t have to pay to use the damn NumLock LED!
What If We Run SetLedsMac as a Daemon?
So one afternoon, I decided to sit down and hack the excellent SetLedsMac project to add support for a daemon mode. I wanted to simply run this process in the background, make it listen to any NumLock input and then trigger the LEDs automatically without any extra work.
So after few hours of reading ObjectiveC documentation and mucking around with `launchctl`, I produced this:
Hello SetLedsMac + Monitor Mode!
Unlike many other solutions, this does not require you to install any third party utilities to manipulate or capture keystrokes. The utility built from this project runs standalone as a LaunchDaemon at login time and handles numlock, scrlck, and capslock LEDs.
Key Benefits:
- No third party software.
- Minimal system footprint.
- Automatically runs once you log in. (please let me know if anyone knows how to run a LaunchDaemon at login screen)
- GNU Licensed. You can build it yourself!
How to Listen to Key Events on OSX
Quartz Event Services
Provides features for managing event taps — filters for observing and altering the stream of low-level user input events in macOS.
CGEventTapCreate is an API from Quartz Event Service from the Apple Core Graphics Framework. It allows your program to capture and listen to any input event produced to the system. This is a very dangerous API and that is exactly why Apple requires any software that uses this API to be explicitly whitelisted in the Accessibility section in Security & Privacy Preferences.
Since this API listens to key events at a lower-level in the system, we can correctly capture unsupported key events like NumLock and other non-standard function keys your keyboard may have.
Running a Program at Startup
Sounds easy enough right? Wrong!
Similar other *nixes, OSX uses an init system to manage, resolve startup dependencies, and runlevels of services. Apple uses launchd (which apparently inspired the now famous systemd) to manage startup services. This system is not very well documented. The service specification is required to be defined in an XML file using Apple’s plist schema and then loaded to runtime configuration using a utility called launchctl.
You can see the crafted plist file for setledsmac here.
I recommend using this tool if you ever need to mess with launchd as it makes one’s life so much easier. http://launched.zerowidth.com/
Thats it folks!
Thanks for reading and hope you learned something (I sure did!). Enjoy your new keyboard!
