K380 Function Key Switcher for MacOSX
        =====================================

About
======

This app is a Mac version of https://github.com/chres/bin/tree/master/k810, adapted for the
Logitech K380 keyboard (vendor 0x046d, product 0xb342). Linux's hidraw is replaced by the
[signal11/hidapi](https://github.com/signal11/hidapi) library.

It talks to the keyboard directly over HID++ to toggle Fn-lock, so it works independently of
Logitech Options / Options+.

Requires root privileges to run, so it either needs to be launched with sudo or have its
setuid bit set beforehand.


Build
======

    make

This produces a `k380` binary, built from k380.cpp and the bundled hidapi backend (hid.c).

    make clean

Removes build artifacts.


Install
========

    ./install.sh

Builds the binary and installs it to /usr/local/bin/k380 with the setuid bit set
(prompts for sudo). Set PREFIX to install elsewhere, e.g. `PREFIX=$HOME/bin ./install.sh`.

It also installs and loads a LaunchAgent (~/Library/LaunchAgents/com.k380fkeysmac.watch.plist)
that runs `k380 watch` at login, so F-keys are switched on automatically every time the K380
connects (including right after install, and after every sleep/wake or Bluetooth reconnect).
Set SKIP_WATCH=1 to skip installing it: `SKIP_WATCH=1 ./install.sh`.

To remove the LaunchAgent later:

    launchctl bootout gui/$(id -u)/com.k380fkeysmac.watch
    rm ~/Library/LaunchAgents/com.k380fkeysmac.watch.plist


Usage
======

    sudo ./k380 on     # F-keys send plain function keys (F1-F12) by default
    sudo ./k380 off    # F-keys send media/system functions (F1 = brightness, etc.)
    sudo ./k380 watch  # watch for K380 connect events and turn F-keys on each time

Running with no argument is equivalent to `on`.

`watch` blocks forever (meant to run under the LaunchAgent installed by install.sh, or in
your own terminal/tmux session), and fires once immediately for a K380 that's already
connected, then again on every reconnect.

After running install.sh, no sudo is needed:

    k380 on
    k380 off

Or, to avoid installing, set the setuid bit on the local build once:

    sudo chown root k380
    sudo chmod u+s k380

Your K380 must be paired and connected over Bluetooth before running the tool.


Diagnostics
============

    ./k380 devices       # list the K380's HID sub-devices (vid/pid, usage page/usage)
    sudo ./k380 probe    # read-only dump of the device's HID++ 2.0 feature table

Both are read-only (no writes to the device), safe to run any time. `devices` only enumerates
and doesn't need sudo; `probe` opens and briefly seizes the device (same as on/off/watch) so
it does. `probe` is how we identified that fkeys on/off writes to feature 0x40a2
(NEW_FN_INVERSION) at index 0x0b.


Known limitation: Easy-Switch to an unavailable device
=========================================================

If you switch channels with Fn+F2/F3 (Easy-Switch) to a device that isn't actually available
to connect to (not paired, powered off, out of range), then switch back with F1/Fn+F1, the
K380 can come back with scrambled key codes (or, if you'd just run `k380 off`, refuse to
reconnect at all) until it's power-cycled with its physical switch.

This isn't something this tool can fix: `k380 watch` already re-applies the fkeys setting
immediately on every detected reconnect, and that works correctly for normal Easy-Switch use
(switching to a device that's actually there and back). The failure only happens on a *failed*
handoff attempt, which points at the keyboard's own Bluetooth link-layer state getting
confused below anything an HID++ feature write can reach -- re-sending the fkeys command
doesn't clear it, only a physical power-cycle does. Avoid Easy-Switching to a channel that
isn't actually connectable, and if it happens anyway, use the keyboard's power switch to
recover.


Feel free to work with it and use as needed.