keydous-bridge 0.1.0

# 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

| Model | USB ID | Connection | Status |
| --- | --- | --- | --- |
| NJ98-CP V4 | `3151:5030` | USB | Confirmed |

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

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.

The display clock is synchronized when the website connects. Run the bridge
again after the keyboard has been without power if its clock has reset.

## 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. The same release can be installed from crates.io with
`cargo install keydous-bridge`.