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
51
52
53
54
55
56
57
|
# 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 <image|gif|video> [fps]
```
`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.
|
