1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
|
# 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`).
|
