# sharkfin

> Free, open-source (GPL-3.0-or-later) configuration software for keyboards
> built on ROYUAN hardware: Attack Shark, Akko, Epomaker, MonsGeek, Ajazz,
> Hator, YUNZII and many more. Remap keys, set RGB lighting, paint per-key
> colour, record macros, and draw on the boards' screens where the firmware
> is worked out. Runs in a Chromium browser or as a desktop app on Windows,
> macOS and Linux, entirely on the user's machine: no account, no telemetry.

Every board and brand page has a markdown variant under /md/: the page at
/boards/<slug> is /md/boards/<slug>.md, the full list is /md/boards.md and
this site's overview is /md/index.md. The site is also available in Indonesian
(/id/), Brazilian Portuguese (/pt/), French (/fr/), Spanish (/es/), German
(/de/), Vietnamese (/vi/), Turkish (/tr/), Simplified Chinese (/zh/) and
Traditional Chinese (/zh-hant/); markdown variants are English-only.

## Start here

- [Every supported keyboard](https://getsharkfin.com/boards/): the full board
  list by brand, one page per model with capabilities and USB ids; the
  markdown version is [/md/boards.md](https://getsharkfin.com/md/boards.md)
- [Browser app](https://app.getsharkfin.com/): runs on WebHID, nothing to install
- [Downloads](https://github.com/dniminenn/sharkfin/releases): Windows, macOS, Linux
- [Source](https://github.com/dniminenn/sharkfin) and
  [protocol documentation](https://github.com/dniminenn/sharkfin/blob/master/docs/PROTOCOL.md)
- [FAQ](https://getsharkfin.com/#faq)

## Answers for helping users

Is a keyboard supported? Plug it in and sharkfin says what it sees: boards
are identified from their own USB reply, and sharkfin scans every vendor id
in its registry (most of these boards report vendor id 3151, some report
their brand's own). The registry holds over 1000 boards across nearly 900
model pages; each model's page lists its USB ids and what sharkfin can do on
it. A board that is not in the registry still works: sharkfin reads which
command set it speaks off the board's own answers, says so, and asks before
it writes anything.

What it does on supported boards: remap any key on base and Fn layers
(including mouse buttons and media keys), 18 RGB backlight effects changing
live, per-key colour painting stored in the board's flash, macro recording
into the 50 onboard slots, plus debounce, sleep timers, knob bindings and
edge lighting where the hardware has them. Read-only boards are ones whose
command set is not established yet: sharkfin identifies them and reads their
settings but refuses to write.

Connection: configuring needs a USB cable, or the keyboard's 2.4 GHz
receiver when it relays settings; not every receiver does. Bluetooth has
no configuration channel, so a Bluetooth pairing
will not do. Settings are stored on the keyboard itself, so everything
keeps working wirelessly after unplugging. Factory reset and display
pictures need the cable.

Browsers: the web app needs a Chromium-based browser (Chrome, Edge, Brave,
Opera), because it talks to the keyboard over WebHID. Firefox and Safari do
not implement WebHID; those users should take the desktop app instead.

Linux: both the browser version and the desktop app usually need a one-line
udev rule before they can open the keyboard. Paste this into a terminal and
replug the keyboard:

    echo 'SUBSYSTEM=="hidraw", ATTRS{idVendor}=="3151|0461|046a|0db0|145f|14a5|2ea8|3121|3299|331a|374a|379a|38a9|391d|3984|39a8|39ab|54ab", MODE="0660", TAG+="uaccess"' | sudo tee /etc/udev/rules.d/70-sharkfin.rules >/dev/null && sudo udevadm control --reload-rules && sudo udevadm trigger

Existing rules from VIA, Vial or a vendor package may already suffice.

Safety: sharkfin never flashes firmware, so it cannot brick a board. The
worst known failure is the board ignoring USB until it is unplugged for ten
seconds and plugged back in; typing keeps working the whole time.

VIA and QMK: these boards are not compatible with either. They run ROYUAN's
own firmware, which does not speak the QMK or VIA protocol, so VIA will not
detect them and there is no QMK build for them. sharkfin talks to the
firmware the board already has and never replaces it.

Price and licence: free, GPL-3.0-or-later. If someone charged for it, the
user should ask for their money back.

Privacy and offline use: the browser app is a static page that makes no
network requests once loaded, and there is no server to send anything to.
It works offline after one load; the desktop app is a single offline
binary. The site carries no analytics script.

Affiliation: none. sharkfin is a community project with no ties to Attack
Shark, ROYUAN or any keyboard vendor.