Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

- Set main/backlight, side-light, and decorative RGB effects.
- Read, remap, back up, and restore keymaps, including declarative TOML configuration.
- Read and set automatic sleep, both sleep timers, and the knob/button accessory switch.
- List HID devices and send raw reports for reverse engineering.

## Installation
Expand All @@ -30,6 +31,7 @@ nuphyctl list
nuphyctl rgb set --hex ff8800 --brightness 35
nuphyctl keymap info
nuphyctl keymap dump --changed
nuphyctl settings get --accessory
```

Use `nuphyctl --help` or `nuphyctl <command> --help` to explore the CLI.
Expand Down
28 changes: 28 additions & 0 deletions docs/reverse-engineering.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,34 @@ Keycodes are QMK-style:

`nuphyctl keymap keycodes` prints the full catalogue.

## Keyboard settings protocol (implemented)

Recovered from NuPhy IO's `main.ba072d08.js` and settings chunk
`829.01203ccb.chunk.js` at <https://drive.nuphy.io/> on 2026-11-10.
These are data commands using the same session-key framing as keymap operations,
not the legacy lighting subcommand format. This path is for mechanical firmware;
HE models use a different configuration block.

| cmd | name | address | length | data |
| --- | --- | --- | --- | --- |
| `0xf3` | GetSleepInfo | 0 | 4 | enable, Level 1 minutes, Level 2 minutes, reserved |
| `0xf5` | SetSleepCfg | 0 | 1 or 4 | same fields |
| `0xfb` | GetAppDefine | 168 | 1 | accessory: knob=0, button/key=1 |
| `0xfc` | SetAppDefine | 168 | 1 | accessory: knob=0, button/key=1 |

The web app writes one byte for the sleep toggle. For timer changes it reads four
bytes, updates byte 1 or 2, and writes all four back. The CLI reads and preserves the
four-byte block when updating any sleep setting. No extra apply command is used.
The settings UI limits both timers to 5–127 minutes. The accessory offset applies
to boards exposing the swappable control, including the Air75 V3.

Live read on the connected Air75 V3 returned sleep bytes `01 06 18 00` and accessory
`00`: auto-sleep on, Level 1 6 minutes, Level 2 24 minutes, knob. Changed-value writes
still need hardware validation; read-back verification is implemented for writes.

The Keyboard Layout selector calls the web app's local preference setter and reloads
the page. It sends no HID command and is not a firmware setting.

## 1) Capture packets in Chrome

Open <https://drive.nuphy.io/> in Chrome, then open DevTools Console and paste:
Expand Down
40 changes: 40 additions & 0 deletions docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,46 @@ Show help for a subcommand:
cargo run -- rgb set --help
```

## Keyboard settings

Read sleep settings, optionally including the accessory switch:

```bash
cargo run -- settings get
cargo run -- settings get --accessory --json
```

Update one or more settings:

```bash
cargo run -- settings set --auto-sleep on --level1-minutes 6 --level2-minutes 24
cargo run -- settings set --auto-sleep off
cargo run -- settings set --accessory knob
cargo run -- settings set --accessory button
cargo run -- settings set --level1-minutes 10 --dry-run
```

Both timers accept **5–127 minutes**, matching NuPhy IO. Level 1 turns off lighting;
Level 2 disables lighting and communication and requires Level 1 sleep first.
Disabling auto-sleep preserves both timers. Changing a timer preserves the sleep
toggle, the other timer, and the reserved configuration byte.

Writes are read back and verified; unchanged values are skipped. `--dry-run`
reads the keyboard and prints the proposed values without writing. `--json` is
available for both commands. All device selectors (such as `--path`) work here too.
If an update to several settings fails partway through, earlier writes may have
succeeded; use `settings get` to inspect the device before retrying.

These commands use the NuPhy IO **mechanical keyboard protocol**, read successfully
on an Air75 V3. HE models use a different configuration format and are not supported
by these commands. Use accessory options only for boards with a swappable knob/button;
`settings get` reads that model-dependent setting only when `--accessory` is passed.
Hardware writes have not yet been validated with changed values.

The web app's **Keyboard Layout** selector (for example US-ANSI-WIN) changes its
virtual keyboard labels only. It does not change firmware or the operating system's
layout, so there is no corresponding device setting in this CLI.

## Lighting examples

Set a static backlight color (`#RRGGBB` or `RRGGBB`):
Expand Down
8 changes: 7 additions & 1 deletion src/app.rs
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
use crate::cli::{
Cli, Command, DeviceSelector, KeymapSubcommand, RawSubcommand, RgbColorMode,
RgbDecorativeSetArgs, RgbDirection, RgbEffect, RgbSetArgs, RgbSideEffect, RgbSideSetArgs,
RgbSubcommand,
RgbSubcommand, SettingsSubcommand,
};
use crate::color::{RgbColor, parse_hex_bytes};
use crate::hid_transport::{
Expand Down Expand Up @@ -75,6 +75,10 @@ pub fn run(cli: Cli, api: &HidApi) -> Result<()> {
Command::Raw(raw) => match raw.action {
RawSubcommand::Send(args) => run_raw_send(api, &args.device, args.report_id, &args.hex),
},
Command::Settings(settings) => match settings.action {
SettingsSubcommand::Get(args) => crate::settings_cmd::run_get(api, &args),
SettingsSubcommand::Set(args) => crate::settings_cmd::run_set(api, &args),
},
}
}

Expand Down Expand Up @@ -375,6 +379,8 @@ fn parse_effect_color(
fn print_commands() {
const COMMANDS: &[&str] = &[
"list",
"settings get",
"settings set",
"rgb set",
"rgb side",
"rgb decorative",
Expand Down
75 changes: 75 additions & 0 deletions src/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ pub enum Command {
Rgb(RgbCommand),
/// Keymap commands (read, remap, back up and restore keys)
Keymap(KeymapCommand),
/// Keyboard sleep and accessory settings (NuPhy IO mechanical protocol)
Settings(SettingsCommand),
/// Send a raw HID output report
Raw(RawCommand),
}
Expand All @@ -44,6 +46,79 @@ pub struct DeviceSelector {
pub usage: Option<u16>,
}

#[derive(Args, Debug)]
pub struct SettingsCommand {
#[command(subcommand)]
pub action: SettingsSubcommand,
}

#[derive(Subcommand, Debug)]
pub enum SettingsSubcommand {
/// Read sleep settings; optionally include the model-dependent accessory switch
Get(SettingsGetArgs),
/// Update only the specified settings, then read back and verify
Set(SettingsSetArgs),
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, ValueEnum)]
pub enum Accessory {
Knob,
#[value(alias = "key")]
Button,
}

impl Accessory {
pub const fn protocol_value(self) -> u8 {
match self {
Self::Knob => 0,
Self::Button => 1,
}
}
}

#[derive(Args, Debug)]
pub struct SettingsGetArgs {
/// Also read the accessory switch (for boards with a swappable knob/button)
#[arg(long)]
pub accessory: bool,
#[arg(long)]
pub json: bool,
#[command(flatten)]
pub device: DeviceSelector,
}

#[derive(Args, Debug)]
#[group(required = true, multiple = true, args = ["auto_sleep", "level1_minutes", "level2_minutes", "accessory"])]
pub struct SettingsSetArgs {
/// Enable or disable automatic keyboard sleep (on/off)
#[arg(long, value_parser = parse_on_off)]
pub auto_sleep: Option<bool>,
/// Idle time for Level 1 sleep (lights off), in minutes
#[arg(long, value_parser = clap::value_parser!(u8).range(5..=127))]
pub level1_minutes: Option<u8>,
/// Level 2 sleep timer (lights and communication off), in minutes
#[arg(long, value_parser = clap::value_parser!(u8).range(5..=127))]
pub level2_minutes: Option<u8>,
/// Installed accessory on boards with a swappable knob/button
#[arg(long, value_enum)]
pub accessory: Option<Accessory>,
/// Show proposed settings without writing
#[arg(long)]
pub dry_run: bool,
#[arg(long)]
pub json: bool,
#[command(flatten)]
pub device: DeviceSelector,
}

fn parse_on_off(input: &str) -> Result<bool, String> {
match input {
"on" | "true" => Ok(true),
"off" | "false" => Ok(false),
_ => Err("expected on or off".into()),
}
}

#[derive(Subcommand, Debug)]
pub enum RgbSubcommand {
/// Set backlight effect and color using #RRGGBB or RRGGBB
Expand Down
1 change: 1 addition & 0 deletions src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ mod keycodes;
mod keymap;
mod keymap_cmd;
mod nuphy_protocol;
mod settings_cmd;

use anyhow::{Context, Result};
use clap::Parser;
Expand Down
59 changes: 59 additions & 0 deletions src/nuphy_protocol.rs
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,11 @@ const CMD_GET_DEFAULT_KEYS: u8 = 0xb1;
const CMD_GET_USE_KEYS: u8 = 0xb2;
const CMD_SET_USE_KEYS: u8 = 0xb3;
const CMD_RESTORE_USE_LAYERS: u8 = 0xb4;
const CMD_GET_SLEEP_INFO: u8 = 0xf3;
const CMD_SET_SLEEP_CFG: u8 = 0xf5;
const CMD_GET_APP_DEFINE: u8 = 0xfb;
const CMD_SET_APP_DEFINE: u8 = 0xfc;
const ACCESSORY_OFFSET: u16 = 168;

const DATA_INFO_LEN: u8 = 8;
const DATA_COMMAND_ATTEMPTS: usize = 3;
Expand Down Expand Up @@ -86,6 +91,38 @@ impl<'a> KeyboardProtocol<'a> {
self.session_key
}

/// NuPhy IO mechanical firmware: enable, shallow minutes, deep minutes,
/// and a reserved byte. Preserve the reserved byte when updating timers.
pub fn read_sleep_settings(&self) -> Result<[u8; 4]> {
let data = self
.data_command(CMD_GET_SLEEP_INFO, 0, 4, &[])
.context("GetSleepInfo failed; this firmware may not support sleep settings")?;
Ok(data
.try_into()
.expect("data_command returns requested length"))
}

pub fn write_sleep_settings(&self, data: &[u8; 4]) -> Result<()> {
self.data_command(CMD_SET_SLEEP_CFG, 0, 4, data)
.context("SetSleepCfg failed")?;
Ok(())
}

pub fn read_accessory(&self) -> Result<u8> {
let data = self
.data_command(CMD_GET_APP_DEFINE, ACCESSORY_OFFSET, 1, &[])
.context(
"cannot read accessory switch; use only on boards with a swappable knob/button",
)?;
Ok(data[0])
}

pub fn write_accessory(&self, value: u8) -> Result<()> {
self.data_command(CMD_SET_APP_DEFINE, ACCESSORY_OFFSET, 1, &[value])
.context("failed to write accessory switch")?;
Ok(())
}

pub fn set_main_light(&self, settings: MainLightSettings) -> Result<()> {
let effect_id = settings.effect.protocol_id();
let light_payload = build_main_light_payload(
Expand Down Expand Up @@ -599,6 +636,28 @@ mod tests {
);
}

#[test]
fn settings_packets_match_nuphy_io_data_commands() {
let key = SessionKey(0x5a);
for (cmd, addr, len, payload) in [
(CMD_GET_SLEEP_INFO, 0, 4, vec![]),
(CMD_SET_SLEEP_CFG, 0, 4, vec![1, 6, 24, 0xa5]),
(CMD_GET_APP_DEFINE, ACCESSORY_OFFSET, 1, vec![]),
(CMD_SET_APP_DEFINE, ACCESSORY_OFFSET, 1, vec![1]),
] {
let packet = build_data_packet(cmd, addr, len, &payload, key).unwrap();
assert_eq!(packet[1], cmd);
assert_eq!(decode_data_header(&packet, key), (len, addr));
assert_eq!(packet[7] ^ key.value(), 0);
assert_eq!(packet[3], calc_checksum(&packet));
for (i, byte) in payload.iter().enumerate() {
assert_eq!(packet[8 + i] ^ key.value(), *byte);
}
let response = reply(cmd, len, addr, &payload, key.value());
assert!(parse_data_response(&response, cmd, addr, len, key).is_ok());
}
}

fn reply(cmd: u8, len: u8, addr: u16, data: &[u8], key: u8) -> Report {
let mut r = [0u8; REPORT_LEN];
r[0] = 0xaa;
Expand Down
Loading