a-funk / open-appleremote

# open-appleremote
**Use the first-generation Apple Siri Remote on Linux**: the touch remote of the 2015 and 2017 Apple TVs (A1513,
A1962), not the older infrared Apple Remote. Touch surface, buttons and tvOS-style gestures are decoded in plain
Python 3 with no dependencies; an optional virtual keyboard makes an old remote work in Kodi, a browser, an emulator
or any other app, and the remote's microphone records what you say while you hold Siri (decoding it needs libopus).
Paired with Linux, the remote does nothing: BlueZ exposes it only as a raw `/dev/hidrawN` node with a vendor-defined
report map, and it stays silent until it is unlocked. This package unlocks it, decodes its reports, and turns them
into events, gestures or key presses. docs/PROTOCOL.md documents everything it sends.
Status: 0.1.0, an early release, tested on an A1962 with Linux: finding, unlocking and reading the remote as a normal
user, and reconnecting after it sleeps. The virtual keyboard (`keys`) is not hardware-tested yet, and the voice
(`voice`, not released yet) hasn't run live: it is tested on synthetic captures, one of them built from another
project's recorded gen-1 frames. Reports are welcome (see CHANGELOG.md).
## Quick start
You need Linux with BlueZ (its `hog` plugin is on by default) and Python 3.8 or newer. There is nothing to install:
clone the repository and run the commands below from its top directory.
**1. Pair the remote** (once). Hold **Menu + Volume Up** for about 5 seconds next to the computer, then pair it in
`bluetoothctl`. After `scan on`, the remote shows up named after its serial number; use its address:
 [code] 
**2. Let your user read it** (once), instead of running everything as root:
 [code] 
Then press a button on the remote. The rules file explains the options for `/dev/uinput` and for headless machines.
**3. Watch it:**
 [code] 
The lab listens on 127.0.0.1 only. On a headless machine, forward it with `ssh -L 8791:127.0.0.1:8791 ` and
open the same address on your computer.
**4. Use it as a keyboard:**
 [code] 
This needs write access to `/dev/uinput` (root, or the optional line in the udev rules). The default key map:
| On the remote | Key |
|---|---|
| slide or flick up, down, left, right | arrow keys |
| click (press the touch surface) | Enter |
| Menu | Esc (back) |
| TV / Home | Home page (`KEY_HOMEPAGE`) |
| Play/Pause | Play/Pause |
| Volume + / − | Volume up / down |
| Siri | nothing |
Change it with a JSON file, `python3 -m appleremote keys --map keys.json`. Values are key names (`KEY_A` to `KEY_Z`,
digits, `KEY_F1` to `KEY_F12`, arrows, media keys: see `NAMES` in `appleremote/keys.py`), numbers from
`linux/input-event-codes.h`, or `null` to turn an input off:
 [code] 
To start it with your session, see systemd/appleremote-keys.service.
**No remote at hand?** `monitor`, `gestures`, `keys` and `lab` take `--replay FILE` to play a capture instead; all
but `keys` work on any OS. Try the lab with a real capture from the test data:
 [cod