# keydous-linux
Linux support for the Keydous NJ98-CP V4.
The project provides a small local bridge between the keyboard and the official
Keydous web driver. It replaces the Windows-only helper application, so the
keyboard can be configured from Chrome or Chromium on Linux.
## Supported features
- display clock synchronization
- static images and GIF animations on the display
- global and per-key RGB lighting
- Main and Fn key remapping
- onboard macros
- Hall-effect actuation and release points
- switch profiles and wireless sleep timers
- persistent web-driver data
- USB disconnect and reconnect
## Supported devices
| NJ98-CP V4 | `3151:5030` | USB | Confirmed |
| NJ98-CP V4 | `3151:5038` | 2.4 GHz | Confirmed interface |
Device detection and command validation are profile-based. Support for another
model requires its USB interface, Keydous web-profile ID, and command set to be
confirmed on real hardware before it is added.
## Installation
### Arch Linux (AUR)
Install the `keydous-linux` package with an AUR helper:
```bash
yay -S keydous-linux
```
```bash
paru -S keydous-linux
```
### crates.io
Install the bridge with Cargo:
```bash
cargo install keydous-bridge
```
The udev rule and systemd service are not included when installing from
crates.io. Install them from the source repository if needed.
### From source
Clone the repository and install the udev rule:
```bash
git clone https://github.com/Arrelin/keydous-linux.git
cd keydous-linux
sudo install -Dm644 packaging/udev/70-keydous-nj98-cp-v4.rules \
/etc/udev/rules.d/70-keydous-nj98-cp-v4.rules
sudo udevadm control --reload-rules
sudo udevadm trigger --subsystem-match=hidraw
```
Reconnect the keyboard after installing the rule.
Build the bridge:
```bash
cargo build --release -p keydous-bridge
```
The pinned Rust toolchain is installed automatically by rustup.
## Usage
Connect the keyboard by USB and start the bridge:
```bash
./target/release/keydous-bridge serve --allow-settings-write
```
Then open [the official Keydous web driver](https://keydousnj.rongyuan.tech)
in Chrome or Chromium. Keep the bridge running while using the website.
Settings are stored in the keyboard and remain active after the bridge exits.
To print read-only HID information for connected Keydous devices, including
models that are not supported yet, run:
```bash
keydous-bridge inspect
```
The display clock is synchronized automatically when the keyboard connects over
USB or 2.4 GHz.
Packages include a user systemd service. Enable it once to start the bridge
automatically when you log in:
```bash
systemctl --user enable --now keydous-bridge
```
The service waits by restarting when no supported keyboard is connected. Its
status and logs are available through:
```bash
systemctl --user status keydous-bridge
journalctl --user -u keydous-bridge
```
## Direct RGB control
RGB effects can also be changed without opening the web driver:
```bash
./target/release/keydous-bridge set-light static --color ff6600 --brightness 4
./target/release/keydous-bridge set-light breath --color 00aaff --brightness 3 --speed 2
./target/release/keydous-bridge set-light off
```
Available effects are `off`, `static`, `breath`, `neon`, `wave`, `dazzle`,
and `laser`.
## Data and safety
The bridge listens only on `127.0.0.1:3814` and accepts the official Keydous
website as its browser origin. Firmware, OTA, and bootloader commands are
deliberately blocked.
Web-driver metadata is stored at:
```text
$XDG_DATA_HOME/keydous-linux/web-driver.db
```
If `XDG_DATA_HOME` is unset, `~/.local/share/keydous-linux/web-driver.db` is
used.
## Development
```bash
cargo test
cargo clippy --all-targets --all-features
```
The crate uses semantic versioning from the workspace manifest. Releases use
matching Git tags such as `v0.1.0`; the AUR package template builds that exact
tag.