# ak820-upload

Upload an image, GIF or video to the 128x128 TFT screen of the AJAZZ AK820 Pro
keyboard from Linux, without the official Windows software or a browser.

Any input ffmpeg can read works. It is center-cropped to a square, scaled to
128x128, resampled to the chosen frame rate and capped at 255 frames, then
written to the keyboard's stored animation (the "GIF" page, Fn + knob press
to switch pages).

## Requirements

- Rust (build only, no crates)
- ffmpeg at runtime
- the keyboard on the USB-C cable in wired mode (VID:PID `0c45:8009`)
- read/write access to its `/dev/hidraw*` nodes (desktop sessions usually
  grant this through `uaccess`; otherwise add a udev rule for `0c45:8009`)

## Build and usage

```sh
cargo build --release
./target/release/ak820-upload [--gif out.gif] <image|gif|video> [fps]
```

`--gif out.gif` writes exactly what would be uploaded (same crop, scale,
frame rate and frame cap) as a GIF for previewing or sharing, and does not
touch the keyboard.

`fps` defaults to 15 and must be between 2 and 50: the keyboard stores each
frame's delay in 2 ms units in one byte, so no frame can last longer than
about 510 ms. At 15 fps the 255-frame limit gives about 17 seconds.

## Protocol

Taken from a USB capture of the official software (v1.0.0.5):

1. On interface 3, feature reports with report ID 0 and 64 bytes of data:
   `04 18` (start), then `04 72 02 .. .. .. .. .. <chunks lo> <chunks hi>`.
   Every SET_REPORT is followed by a 64-byte GET_REPORT, without which the
   keyboard ignores the upload.
2. On interface 2 (interrupt OUT endpoint 0x03), the payload in 4096-byte
   chunks. The keyboard acks each chunk with `01 5a 02` on endpoint 0x84, and
   the next chunk is only sent after the ack.
3. `04 02` (save) on interface 3.

Payload: a 256-byte header (frame count, one delay byte per frame in 2 ms
units, 0xFF padding), then every frame as 128x128 RGB565 little-endian, padded
with 0xFF to a whole number of chunks.

## License

GPL-2.0-only. See [LICENSE](LICENSE).

## Development Approach

This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.

All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.

The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.