# GAMEKB-K17: reconstructing a macropad configuration protocol

> Implements the vendor HID configuration protocol for the GAMEKB-K17/HCY-K017 macropad. It writes key mappings, firmware macros and RGB settings, then reads them back; protocol notes separate tested commands from unconfirmed observations and other-device findings.

- Type: Case study
- Targets: Protocol
- Category: Independent reconstruction cases
- Relationship: Independent reconstruction project
- Sources reviewed: 2026-10-17
- Added to the catalog: 2026-10-17
- Original resource: <https://github.com/dvdarkin/gamekb-k17>
- Primary source: <https://github.com/dvdarkin/gamekb-k17/blob/e61f444793857c0e10a31692674335ee4ee9c89e/README.md>
- Catalog page: <https://awesomerea.org/resources/gamekb-k17-case/>
- Record JSON: <https://awesomerea.org/resources/gamekb-k17-case/record.json>
- Chinese version: [简体中文](https://awesomerea.org/zh/resources/gamekb-k17-case/index.md)

## Requirements & limits

- **Prerequisites:** Package 3.0.0 requires Python 3.11+ and hidapi; the optional editor uses tkinter. Hardware identity is USB 0816:0220.
- **Testing evidence:** Windows is project-tested; other hidapi platforms are untested. Linux configuration requires suitable device permissions.
- **Scope:** The documented scope includes 18 remappable controls and up to 16 firmware macros. The volume dial is fixed in firmware.
- **Testing evidence:** Read-back verification and interruption ordering are project claims backed by protocol documentation.
- **License:** MIT license. The reviewed primary files establish reverse engineering of the vendor WebHID configurator.

## Primary sources

1. <https://github.com/dvdarkin/gamekb-k17/blob/e61f444793857c0e10a31692674335ee4ee9c89e/README.md>
2. <https://github.com/dvdarkin/gamekb-k17/blob/e61f444793857c0e10a31692674335ee4ee9c89e/docs/PROTOCOL.md>
3. <https://github.com/dvdarkin/gamekb-k17/blob/e61f444793857c0e10a31692674335ee4ee9c89e/pyproject.toml>
4. <https://github.com/dvdarkin/gamekb-k17/blob/e61f444793857c0e10a31692674335ee4ee9c89e/LICENSE>

## More in Protocols

- [cooler-lcd: a Thermalright display protocol implementation](https://awesomerea.org/resources/cooler-lcd-case/index.md) · Case study
- [NJFE: a Soulear camera protocol bridge for desktop inspection](https://awesomerea.org/resources/njfe-ear-camera-bridge-case/index.md) · Case study
- [hw-harness: scanner USB protocol investigation](https://awesomerea.org/resources/hw-harness-reference-case/index.md) · Case study
- [Roborock Local Server: a self-hosted stand-in for Roborock’s vacuum cloud](https://awesomerea.org/resources/roborock-local-server-cloud-case/index.md) · Case study
- [pypush: a Python client for Apple’s push protocol](https://awesomerea.org/resources/pypush-apns-protocol-case/index.md) · Case study
- [PixMob IR reverse engineering: controlling event wristbands at home](https://awesomerea.org/resources/pixmob-ir-protocol-case/index.md) · Case study

## About this entry

The description was reviewed against primary sources.
Original editorial content: MIT. Linked projects, papers and assets retain their own rights and licenses.