# AGENTS.md

Guidance for AI coding agents working in this repository.

## What this is

`ak820-upload`: single-file Rust CLI (`src/main.rs`, std only, no crates)
that writes an animation to the AJAZZ AK820 Pro screen over Linux hidraw.
ffmpeg (subprocess) decodes any input to raw RGB565LE frames; the program
builds the payload and drives the upload. `--gif out.gif` runs the same
ffmpeg crop/scale/fps chain to a GIF file instead (preview/share, no device).
`README.md` documents the protocol.

On the maintainer's machine the release binary is linked into PATH, so a
`cargo build --release` is live immediately:

    ~/bin/ak820-upload -> target/release/ak820-upload

## Protocol facts (verified on hardware, do not "simplify" away)

The protocol comes from a USB capture of the official Windows app. Earlier
attempts based on community projects (gohv, ajazz-ak820-config) failed in
instructive ways:

- The 64-byte GET_REPORT after every SET_REPORT is required. Without it the
  keyboard accepts the bytes and does nothing. A zero-length GET is rejected
  by the kernel with EINVAL and never reaches the device.
- Control reports go out as report ID 0 with `04` as the first data byte
  (`wValue 0x0300`), not report ID 4.
- IMAGE sub-command is `0x02`. Chunks are plain 4096 bytes, no filler or
  short packet (gohv's 4123-byte chunks misalign every other chunk).
- Chunk acks arrive on endpoint 0x84, which belongs to interface 2 (the data
  interface), not interface 3. Wait for each ack before the next chunk.
- Frame delay byte is in 2 ms units (app value 50 -> 0x19, 250 -> 0x7d).
- A still image is just a 1-frame animation; there is no separate path.

Interfaces by `HID_PHYS` suffix: `/input2` = data (EP 0x03 OUT, 0x84 IN),
`/input3` = control.

## Testing

`cargo test` checks the packet and payload layout against the captured
bytes. `cargo clippy --release` must stay clean. A real check needs the
keyboard: upload a few distinct, numbered frames and watch them cycle on the
GIF page. If an upload is interrupted the keyboard shows "loading NN%";
replug it before retrying.

## Repo facts

- License: GPL-2.0-only (`LICENSE`, SPDX header in `src/main.rs`).