wvke-sdk

wvke-sdk is a JavaScript and TypeScript SDK for gaming peripherals. It is built on WebHID and provides keyboard and mouse APIs for device discovery, initialization, configuration, lighting, and performance features.

Website and Docs

• Website: https://www.wvke.top/
• Documentation: https://www.wvke.top/docs/

Version

Current package version: 1.0.20260715

What's New in 1.0.20260715

• Added ServiceKeyboardMK — a standalone mechanical keyboard SDK service fully decoupled from the linear-axis ServiceKeyboard; exported from the main entry with complete TypeScript declarations.
• Fixed missing common methods on the mechanical keyboard service: getDevices, init, getConfig/setConfig, polling-rate, lighting sleep, and key-group methods.
• Fixed setAdvancedKeySOCD() runtime error caused by missing MAC_MODIFIER_PHYSICAL_HID_BY_NAME and BOOT_MODIFIER_BIT_HIDS constants.
• Synchronized mechanical keyboard API categories across the debugger, website documentation (13 Global / 7 Key / 9 Lighting / 6 Advanced), and TypeScript declarations.

What's New in 1.0.20260714

• Fixed setKeyCustomAxis() axis-range encoding to match the device firmware format: axisRangeMax is converted with axisRangeMax * 1000 / 50 and written to the correct protocol byte.
• Improved the SDK debug tool with gamepad testing support, XBOX/Classic gamepad icon assets, and shared HID device-filter configuration.
• Aligned website documentation with the debugger's actual API categories, including interface counts in sidebar labels; merged key-travel rendering APIs into Global Features and removed duplicate standalone pages.
• Synchronized TypeScript declarations, multilingual documentation, and the publishable package output.

What's New in 1.0.20260708

• SDK version bump: sync website i18n, debug page, and documentation version references.

• SDK image asset APIs (getShortcutFunctionList, getFineTuneAxisList, getKeyCustomLayer) now default to returning URLs without proactively fetching image assets.

• Added { includeImages: false } option to skip image URL generation and return empty image fields.

• Added { verifyImages: true } option for explicit accessibility verification of SDK image assets.

What's New in 1.0.20260704

• Added classic/XBOX gamepad test mode: auto-detects SDK getGamepadMode() values (0=keyboard/1=XBOX/2=classic), polls Gamepad API for axes, buttons, and POV data in real-time.
• Classic mode dynamic axis listing: auto-generates progress bars for all browser-exposed axes with semantic labels (Z axis/X rot/Y rot/Z rot/Throttle), throttle uses 0→1 unidirectional mapping.
• Gamepad test buttons now display raw indices matching the system test UI; POV hat supports both button-based and single-axis hat encoding.
• Unified HID device filters into src/lib/config/hid-filters.js shared module; debug page and SDK defaults now share the same 24-entry list, added 0x1CAA:0xFFF8 and 0x1CAA:0xFFF6.
• Merged setKeyConfig keyboard matrix and function picker: removed view toggle tabs, keyboard grid now shown directly above function category list.
• Increased floating tester max height to 960px; shortened gamepad mode badge labels; swapped XBOX Z-axis rendering direction (LT - RT).

What's New in 1.0.20260701

• Added getWinKeyStatus() / setWinKeyLock(): WIN key lock status read & set (protocol 0x20)
• Added ServiceFirmwareUpgrade.connectBootDevice(): WebHID device picker for BOOT mode device
• Enhanced upgrade(): supports { binFilePath, binData, onProgress } params object & local BIN file
• Fixed setAdvancedKeySOCD(): bypass _prepareAdvancedModeMutation to avoid interference
• Fixed _normalizeOutputReportData(): truncate oversized HID reports to 64 bytes (fixes MT command)
• Fixed setAdvancedKeyDKS() / setAdvancedKeyMPT() param defaults & task format
• Fixed param default initialization: selectMethod now populates param.default
• Fixed firmware enterBoot() call: auto-inject keyboard.currentDevice
• SDK test: 31 passed, 0 failed

What's New in 1.0.20260626

• Fixed keyboardKeyTravelRenderChange event: now emitted directly from getKeyTravelRender() and setKeyTravelRender() after command completion, and correctly detected via GLOBAL_FUNC_CODE (0x80) active-report path.
• Reordered global report listener interfaces: startGlobalReportListener and stopGlobalReportListener now appear at positions 2–3 in both the website API docs and the debug SDK category list.
• Increased setPerformance / setPerformanceBatch command throughput: default packet delay reduced from 50 ms to 20 ms.

What's New in 1.0.20260625

• Extended getKeyCustomLayer(): base layer (0x00) now returns the fn_code field for all custom function mappings, consistent with FN1/FN2/FN3 layers.
• Added keyboardKeyTravelRenderChange event to startGlobalReportListener: monitors the key travel real-time render switch status, including value and enabled fields.
• Added "Trip Status" shortcut icon (system_trip.svg) under the System function category.
• Enhanced setKeyConfig debug panel: function items now show a green checkmark badge (✓) when selected, with compact keyboard layout (tighter spacing, smaller key heights).
• Updated all documentation (README, npm-package README, 9 locale website docs) with new event tables, report examples, and API chapters.

What's New in 1.0.20260624

• Added key function recovery API recoverKeyConfig(keyName, layer): restores the factory function for a specific key on the specified layer. Protocol command KB2_CMD_Recover (0x21), supports recovery target parameter (3=specified key all layers, 4=specified key specified layer).
• Added key function recovery API recoverAllKeyConfig(layer): restores factory functions for all keys on the specified layer. Supports recovery target parameter (1=all keys all layers, 2=all keys specified layer).
• Protocol command SET_DEVICE_FUNCTION_RECOVER_CMD follows 0x5C 0x04 0x21 CRC recoverTarget param1(HID) param2(Layer) format, padded with 2 bytes of 0xFF at the end.
• Debug SDK added recoverKeyConfig and recoverAllKeyConfig method panels with keyName text input and layer dropdown selection, categorized under "Key Function".
• Updated Chinese and English API documentation with Recover Key Config and Recover All Key Config sections, including parameter tables, return types, and usage examples.
• Synced TypeScript type declarations.

What's New in 1.0.20260620

• Expanded setKeyConfig debug page: added keyboard matrix + function tabs panel (System/Mouse/Media/Firmware/Hotkey/Gamepad), loaded from getShortcutFunctionList.
• Fixed getKeyCustomLayer function type classification: all types (KEY/MEDIA/HOTKEY/MOUSE/SYS/MACRO/GAMEPAD/FUNC) now return consistent category identifiers.
• Added full icon coverage for all shortcut function categories: Media, System, Firmware, Hotkey, and Gamepad.
• Fixed setKeyConfig hotkey encoding: code generation now correctly combines hotkey base (0x60) with modifier bits.
• Product page pricing: non-Chinese locales now display USD (CNY→USD conversion at 7.2 rate).

What's New in 1.0.20260619

• Extended getKeyCustomLayer() return type: added "GAMEPAD" type for gamepad function mappings in the custom layer list (XBox A/B/X/Y, Classic gamepad, etc.), resolved from the GAMEPAD category in fn.map.json.

What's New in 1.0.20260618

• Expanded SOCD advanced key modes: added mode 2 (Absolute Priority: keyName2), mode 3 (Neutral/Cancel), and mode 4 (Depth Priority). Original mode 2 (Neutral) moved to mode 3. String aliases supported: socdAbsolutePriority2, socdNeutral/socdCancel, socdDepthPriority.
• Added global function getKeyTravelRender() / setKeyTravelRender(): protocol code 0xC0, controls the key travel real-time render switch (0=off, 1=on).
• Added RT key group APIs getRtKeyGroup() / setRtKeyGroup(): protocol code 0xFE, format HID + group number (e.g. 04,00). Default global group 0. Supports single-key and batch modes.
• Extended setPerformance() / setPerformanceBatch() RT switch modes: added 0x30 (RT active even when global RT switch is OFF) and 0x40 (RT active only when global RT switch is ON). rtSwitch parameter now supports values 0/1/2/3.
• Updated debug SDK: SOCD mode options, RT key group keyboard matrix panel, RT switch 4-mode options.
• Synced TypeScript declarations, HID device layer layout support (0xFE), command protocol config, and full multilingual i18n.

What's New in 1.0.20260614

• Rebranded SDK from "AVKE SDK" to "wvke-sdk" — updated package name, exports, and documentation.
• Added ServiceFirmwareUpgrade for custom firmware upgrades: enterBoot() to enter BOOT mode, upgrade() for firmware writing from URL/File/Blob sources, CRC verification, progress callbacks, and APP jump after completion.
• Added ClientDataService for pure frontend data computation: keyboard layout rendering, function map resolution, axis catalog queries, shortcut icon mapping, device model info, and SDK asset canonical URLs — no HID communication required.
• Added CloudService with generateSn() for batch SN number generation in a given range.
• Added a FIFO HID command queue (hid-command-queue.js): commands to the same HID device are serialized strictly in call order, preventing concurrent write conflicts.
• Added keyboard gamepad global protocol support: getGamepadMode() / setGamepadMode() (0xB9), getGamepadMappingSettings() / setGamepadMappingSettings() (0xBA), getGamepadCurveOptions() / setGamepadCurveOptions() (0xBB), getGamepadLinearCurve() / setGamepadLinearCurve() (0xBC).
• Extended function map (fn.map.json): added GAMEPAD category with 25 XBox and 23 Classic gamepad shortcut entries.
• Extended keyboard map (keyboard.map.json): added AP key (0xFA), RT key (0xFB), LIGHT key (0xFC), and PLAY key (0xD6).
• Fixed protocol templates: SOCD command length alignment, global journey read expansion, sign reboot command simplification, serial number command correction, RS command padding, and added system notification command (0xBF).
• Added axis catalog (axis.json) with full coverage of kailh, hexgears, wallhack, and other switch brands.
• Synced TypeScript declarations (new HidDeviceFilter, DeviceInfo, KeyboardPerformanceValues interfaces), debug tool entries, and website multilingual support (8 new languages).
• Added device selection matching tests, command queue ordering tests, and global report listener protocol tests.

What's New in 1.0.20260611

• Added valid VID/PID 0x3879:0x0806 to the default device filter lists in both the debug SDK and the SDK configs.
• Added global report support for command code 0xBE (offline settings notification). The SDK now emits a keyboardOfflineSettingsChange event when the firmware reports offline settings status, with statusLabel: "start" (value 0) or "complete" (value 1).
• Updated debug SDK: the startGlobalReportListener panel now renders offline settings cards with human-readable status labels and full i18n coverage across all 10 languages.
• Added GLOBAL_OFFLINE_SETTINGS_CODE (0xBE) to the protocol configuration.
• Synced type declarations, debug entries, protocol config, and i18n translations.

What's New in 1.0.20260608

• Fixed setGlobalJourney(): corrected data position from command bytes 5–6 to bytes 7–8 in SET_GLOBAL_JOURNEY_CMD, matching the official protocol reference implementation.
• Fixed getGlobalJourney(): corrected setGlobalJourneyData response parser to read from the correct byte positions (rows[7:8]), resolving the zero-return issue.
• Added wallhack brand to the axis catalog with three models: KS-Medium (ID 43), KS-Light (ID 44), and KS-Heavy (ID 45), each with RT: 0.01, maxHigth: 3.1.
• Resized wallhack axis image assets to match the hexgears standard dimensions (icon 100×100, z_b 600×626, z_y 373×501).
• Synced SDK type declarations and debug entries for global journey and wallhack axis support.

What's New in 1.0.20260604

• Added ServiceKeyboard.requestDevices(configs?) to open the browser WebHID authorization picker explicitly and return valid authorized keyboard devices.
• Changed ServiceKeyboard.getDevices() to only read devices already authorized by the browser, with keyboard usagePage filtering and device-ID deduplication.
• Improved debug SDK initialization: requestDevices is first in the Device Initialization group, shows the default allowed VID/PID array in hexadecimal JS-object form, and lets users select a device to fill init(deviceId).
• Added keyboard RT full-travel switch APIs: getRtAllJourneySwitch() and setRtAllJourneySwitch(value).
• Improved init(deviceId) matching so the selected deviceId or vendorId:productId is initialized precisely when multiple authorized devices are present.
• Updated TypeScript declarations, debug tools, initialization docs, README content, and regression tests. Release validation: 30 passed, 0 failed.

What's New in 1.0.20260602

• Fixed macOS keyboard configuration writes by padding every keyboard WebHID output report to 64 bytes with zero-filled tail bytes before sendReport().
• Tightened 5C 39 23 ED working-mode command construction so unused primary/secondary key slots are explicitly cleared instead of carrying template defaults.
• Improved macOS Command / Option / Meta modifier alias handling so boot modifier bits such as 0x08 and 0x04 are not used as physical target HIDs for performance writes.
• Aligned the legacy HIDDeviceObj.sendQueuedReport() path with ServiceKeyboard so older call sites also send fixed-length zero-padded reports.
• Fixed direct protocol-template mutation in setKeyConfig(), setConfig(), and setRateOfReturn() to prevent command state from leaking across consecutive writes.
• Added keyboard RT full-travel switch APIs: getRtAllJourneySwitch() and setRtAllJourneySwitch().
• Added regression coverage for HID output report padding and working-mode unused-slot clearing. Release validation: 25 passed, 0 failed.

What's New in 1.0.20260601

• Improved setPerformance() transfer stability with a dedicated packet interval, progress callbacks, and debug-page loading/packet timing feedback for larger performance payloads.
• Changed the default setPerformance() / setPerformanceBatch() packet interval to 50ms to reduce multi-packet transfer time. It can still be overridden with setPerformancePacketDelayMs or the compatibility option setPerformanceCommandDelayMs.
• Added setPerformanceBatch() for batch performance updates. It reads the current layout once, then sends working mode, trigger travel, RT configuration, and safe-zone layers in small complete key batches. batchKeyLimit / setPerformanceBatchKeyLimit can tune the batch size.
• Fixed MAC device-mode Win/Alt performance writes to use physical modifier HIDs by default: LWIN=E3, LALT=E2, RWIN=E7, and RALT=E6, avoiding boot modifier-bit or swapped-slot writes for physical axis performance data.
• Fixed journey, RT, and safe-zone command builders so each key clones the command template before filling protocol bytes, preventing state leakage across consecutive writes.
• Improved the debug SDK setPerformance tools with exact HID targeting, stale hidden-HID cleanup, SDK-backed batch writes, RT ON standalone display, and transfer metrics beside the loading state.
• Added keyboard gamepad/joystick global APIs and protocol coverage for getGamepadMode() / setGamepadMode(), gamepad mapping settings, curve options, linear curve read/write, and the Gamepad shortcut function catalog.
• Improved global active-report parsing and listener control for configuration, keyboard lighting, logo lighting, and battery-change events.
• Expanded TypeScript declarations and API documentation for lighting, custom lighting, advanced keys, axis fine-tuning, calibration status, and performance APIs.
• Synced SDK protocol configuration, key/function maps, tests, Chinese and English docs, website release notes, and npm-package preparation output for publishing.

What's New in 1.0.20260522

• Fixed startGlobalReportListener() and stopGlobalReportListener() global active-report control commands to use the KB2_CMD layout: 5C 04 00 94 BD 01/00.
• Added protocol coverage that verifies the exact HID commands sent by the global report listener start and stop APIs.
• Added LAN HTTPS development support and a Windows certificate helper so WebHID remains available when testing through LAN IP addresses or internal domains.
• Synced SDK build output, npm-package preparation output, and development documentation.

What's New in 1.0.20260521

What's New in 1.0.20260617

• Fixed setKeyCustomAxis() so it actually sends the axis HID command to the device. Added _buildAxisCommand to build SET_DEVICE_BUTTON_AXIS_CMD, and reads Layout 19 first to sync current device axis state before writing.
• Fixed getAxisDetails() to read Layout 19 from the device before returning results, ensuring real device axis configuration is returned. Unknown axis IDs now fall back to axis 0 as default.
• Added restoreProfile(profileIndex) global API to restore a specific configuration profile (profileIndex 0-3).
• Added key function APIs getKeyGroup() and setKeyGroup() for reading and writing key groups (Layout 0xFF). All keys default to group 0; supports single-key and batch modes.
• Added setKeyGroup interactive panel in the debug tool with keyboard matrix key picker, color-coded group list, auto-increment group creation, and auto-select of all keys in a group when switching.
• getKeyGroup result now renders group-colored keys on the keyboard matrix and shows Key / HID / Group columns in the table view.

What's New in 1.0.20260614

• Fixed SDK protocol template length and CRC alignment for SOCD, global travel reads, and DKS advanced-key commands so declared lengths match the effective payloads.
• Added stopLightingRealtimeReport() for custom lighting. It immediately notifies the device to stop keyboard-backlight or logo-lighting real-time reports and falls back to both stop protocols when the active target cannot be determined.
• Improved debug SDK live-listener cleanup. Switching to another API now stops active normal listeners, stopping lighting live preview also notifies the device, and stopping calibrationStart live preview automatically calls calibrationStop().
• Synced TypeScript declarations, debug-tool entries, Chinese and English API docs, README content, tests, and website build output.

What's New in 1.0.20260518

• Added a shared FIFO queue for WebHID communication. Commands sent to the same HID device are now serialized strictly in API call order, so later SDK calls cannot jump ahead of an earlier unfinished command.
• Routed the keyboard command helper, custom lighting read/write helpers, realtime matrix reads, advanced-key delete reports, legacy HID helper reports, and firmware-upgrade command/packet writes through the same per-device queue.
• Added queue-order coverage to the SDK test runner, including strict same-device ordering and continued queue execution after a rejected task.

What's New in 1.0.20260514

• Added the ServiceFirmwareUpgrade export for general custom firmware upgrades, including enterBoot() and upgrade() with BOOT reconnect flow, progress callbacks, firmware loading from URL/File/Blob sources, CRC verification, and App jump after a successful write.
• Added axis detail APIs for keyboard switch tuning: getAxisDetails() returns full-keyboard axis details and layout, and setKeyCustomAxis() switches a single key to a target axis with optional range and coefficient values.
• Improved SDK asset publishing by bundling key-layer icons, advanced-key custom icons, axis images, and tool images as regular static image assets.
• Synced TypeScript declarations, npm package preparation, and API documentation for the new firmware-upgrade and axis-related SDK surfaces.

What's New in 1.0.20260513

• Improved getDefaultKeyLayout() special-key descriptions for default keyboard layouts: 0xFA is now AP key, 0xFB is RT key, 0xD6 is Play key, and 0xFC is Lighting key.
• Synced the SDK and debug-tool builds so layout rendering and returned layout data can resolve these special keys.

What's New in 1.0.20260511

• Added keyboard global gamepad APIs: getGamepadMode, setGamepadMode, getGamepadMappingSettings, setGamepadMappingSettings, getGamepadCurveOptions, setGamepadCurveOptions, getGamepadLinearCurve, and setGamepadLinearCurve.
• Synced debug tool and website documentation for the new gamepad global settings.
• Standardized the returned switch values for gamepad mapping and curve options to numeric 0 and 1.
• Added getCalibrationStatus() for full-keyboard calibration status snapshots. It reads only the key-status layer, returns details and layout for keyboard rendering, and keeps the layout aligned with getADCSample().
• Updated calibrationStart() debug behavior so live calibration preview polls getCalibrationStatus() without reading ADC or travel layers. Legacy firmware that reports low-4-bit value 2 with high 4 bits 0 is treated as calibration success.

What's New in 1.0.20260506

• Added custom hotkey CODE helper support for single and multi-modifier shortcuts.
• Fixed custom keyboard backlight and logo lighting read/write helpers used by the SDK.
• Synced custom lighting command handling for the latest WebHID SDK build.

What's New in 1.0.20260422

• Fixed the npm package README publishing flow so the published README now uses src/lib/README.md as the single source of truth.
• Cleaned up the package README structure for npm publishing and aligned package preparation with the npm-package directory workflow.

What's New in 1.0.6

• Synced the DKS advanced-key API so the task parameter now uses the final 4-segment format only.
• Renamed DKS debug-tool fields from bits to trps and documented the 7-bit trigger order.
• Updated Chinese and English higherKey documentation with the trps bit mapping and refreshed website release content.

Install

npm install wvke-sdk

Runtime Requirements

• A modern browser with WebHID support.
• A user gesture before requesting device access.
• HTTPS or localhost during development and testing.

Main Exports

import ServiceKeyboard, {
  ServiceKeyboard,
  ServiceMouse,
  ServiceFirmwareUpgrade,
  versionManager,
  logger,
  performanceMonitor
} from 'wvke-sdk'

• ServiceKeyboard: keyboard SDK service.
• ServiceMouse: mouse SDK service.
• ServiceFirmwareUpgrade: general custom upgrade service.
• versionManager: SDK version and compatibility helper.
• logger: runtime logger.
• performanceMonitor: operation and connection metrics helper.

SDK Image Asset Options

Client data APIs that return icon URLs, such as getShortcutFunctionList(), getFineTuneAxisList(), and getKeyCustomLayer(), do not proactively fetch SDK image assets by default. They only return canonical image URLs for the host application to render when needed.

If your application does not use SDK-provided images, pass { includeImages: false } to skip image URL generation and return empty image fields:

const shortcuts = await ClientDataService.getShortcutFunctionList('media', {
  includeImages: false
})

const axisList = await ClientDataService.getFineTuneAxisList({
  includeImages: false
})

If you need the SDK to verify that image assets are reachable before returning URLs, pass { verifyImages: true }. This is the only mode that actively requests image assets.

const shortcuts = await ClientDataService.getShortcutFunctionList('media', {
  verifyImages: true
})

Keyboard Quick Start

import { ServiceKeyboard } from 'wvke-sdk'

const keyboard = new ServiceKeyboard()
const { code, devices } = await keyboard.requestDevices([
  { vendorId: 0x1CAA, productId: 0x0806, usagePage: 0xFFA0, usage: 0x01 }
])

if (code !== 0 || devices.length === 0) {
  throw new Error('No keyboard devices found')
}

await keyboard.init(devices[0].id)

const info = await keyboard.getDevicesInfo()
console.log(info)

Mouse Quick Start

import { ServiceMouse } from 'wvke-sdk'

const mouse = new ServiceMouse()
const devices = await mouse.getDevices()

if (devices.length === 0) {
  throw new Error('No mouse devices found')
}

await mouse.init(devices[0].id)

const dpi = await mouse.getDPI()
console.log(dpi)

General Custom Upgrade Quick Start

import { ServiceFirmwareUpgrade } from 'wvke-sdk'

const filters = [{ vendorId: 0x1caa, productId: 0x0806, usagePage: 0xffa0, usage: 0x01 }]

const [device] = await navigator.hid.requestDevice({ filters })
if (!device.opened) {
  await device.open()
}

const firmwareUpgrade = new ServiceFirmwareUpgrade()

await firmwareUpgrade.enterBoot(device)

// The device reboots into BOOT mode. Select the BOOT device again before upgrading.
// RF chip upgrades do not require enterBoot; pass the opened device directly to upgrade().
const [bootDevice] = await navigator.hid.requestDevice({ filters })
if (!bootDevice.opened) {
  await bootDevice.open()
}

await firmwareUpgrade.upgrade(bootDevice, '/firmware/example.bin', {
  onProgress: ({ phase, progress }) => {
    console.log(phase, progress)
  }
})

// Browser apps can also pass a File selected from an <input type="file">.
await firmwareUpgrade.upgrade(bootDevice, firmwareFile)

// Remote firmware files must use HTTPS.
await firmwareUpgrade.upgrade(bootDevice, 'https://example.com/firmware/example.bin')

The service exposes enterBoot(device, options?) for rebooting the app device into BOOT mode, and upgrade(bootDevice, binFilePath, options?) for the formal upgrade after the BOOT device is selected again. RF chip upgrades are an exception: the device does not need to enter BOOT mode first, and the opened device can be passed directly to upgrade(). It handles device SN reading, bootloader signing, erase, packet writing, CRC verification, and app jump internally. In Node.js it can read local filesystem paths and file:// URLs; in browsers, local paths must be URLs that the current site can fetch, or a File/Blob selected by the user.

Examples

Read current keyboard config and polling rate

import { ServiceKeyboard } from 'wvke-sdk'

const keyboard = new ServiceKeyboard()
const { code, devices } = await keyboard.getDevices()

if (code !== 0 || devices.length === 0) {
  throw new Error('No keyboard devices found')
}

const initResult = await keyboard.init(devices[0].id)

if (initResult.code !== 0) {
  throw new Error(initResult.info || 'Keyboard initialization failed')
}

const currentConfig = await keyboard.getConfig()
const pollingRate = await keyboard.getRateOfReturn()

console.log(currentConfig)
console.log(pollingRate)

Set keyboard backlight base config

await keyboard.setLightingBase({
  data: {
    mode: 2,
    childMode: 1,
    luminance: 3,
    speed: 4
  }
})

Read custom keyboard backlight with live reports

const handleReport = (payload) => {
  console.log('keyboardBacklightCustomReport', payload)
}

keyboard.on('keyboardBacklightCustomReport', handleReport)

const snapshot = await keyboard.getKeyboardBacklightCustom()
console.log(snapshot)

const heartbeatId = setInterval(() => {
  keyboard.getKeyboardBacklightCustom().catch(console.error)
}, 5000)

keyboard.off('keyboardBacklightCustomReport', handleReport)
clearInterval(heartbeatId)
await keyboard.stopLightingRealtimeReport()

Stop custom lighting real-time reports

stopLightingRealtimeReport() sends the custom-lighting stop operation (0x03) immediately. By default it automatically chooses the active keyboard-backlight or logo-lighting listener; if no local listener is active, it sends both stop notifications.

await keyboard.stopLightingRealtimeReport()

Listen for keyboard global active reports

startGlobalReportListener() sends firmware protocol 0xBD = 1, starts the device-level listener, and keeps the session alive with a 60-second heartbeat. Real-time data is delivered through events.

Available events:

| Event | Payload | Description | |---|---|---| | keyboardGlobalReport | { reportId, commandCode, errorCode, type, source, rows } | Raw global report | | keyboardConfigChange | { type, source, functionCode, configIndex, configName } | Profile/configuration switch | | keyboardLightingChange | { type, source, mode, modeLabel, childMode, childModeLabel, luminance, speed, sleep } | Keyboard backlight change | | keyboardLogoLightingChange | { type, source, mode, modeLabel, luminance, speed, sleep } | Logo lighting change | | keyboardBatteryChange | { type, source, battery, isCharging } | Battery level & charging status | | keyboardOfflineSettingsChange | { type, source, value, statusLabel } | Offline settings notification (start/complete) | | keyboardKeyTravelRenderChange | { type, source, value, enabled } | Key travel real-time render switch change |

const handleGlobalReport = (payload) => {
  console.log('keyboardGlobalReport', payload)
}

keyboard.on('keyboardGlobalReport', handleGlobalReport)
keyboard.on('keyboardConfigChange', (payload) => {
  console.log('profile changed', payload.configIndex)
})
keyboard.on('keyboardLightingChange', (payload) => {
  console.log('lighting changed', payload.mode, payload.luminance, payload.speed)
})
keyboard.on('keyboardBatteryChange', (payload) => {
  console.log('battery changed', payload.battery, payload.isCharging)
})
keyboard.on('keyboardKeyTravelRenderChange', (payload) => {
  console.log('key travel render changed', payload.enabled)
})

await keyboard.startGlobalReportListener()

await keyboard.stopGlobalReportListener()
keyboard.off('keyboardGlobalReport', handleGlobalReport)

Read and update keyboard RT full-travel switch

const rtAllJourneySwitch = await keyboard.getRtAllJourneySwitch()
console.log('RT full-travel switch', rtAllJourneySwitch.value, rtAllJourneySwitch.enabled)

await keyboard.setRtAllJourneySwitch(1)
await keyboard.setRtAllJourneySwitch(false)

Read and update keyboard key travel render switch

Controls the real-time rendering of key travel status (0 = off, 1 = on). When enabled, the device reports back the current travel state for each key press.

const travelRender = await keyboard.getKeyTravelRender()
console.log('key travel render', travelRender.value, travelRender.enabled)

await keyboard.setKeyTravelRender(1)
await keyboard.setKeyTravelRender(false)

Read and update keyboard gamepad global settings

const gamepadMode = await keyboard.getGamepadMode()
console.log('gamepad mode', gamepadMode.key, gamepadMode.value)

const mappingSettings = await keyboard.getGamepadMappingSettings()
console.log('mapping settings', mappingSettings)

await keyboard.setGamepadCurveOptions({
  enableAngleAdjustment: 0,
  angleAdjustmentValue: 45,
  enableSquareStickOutput: 1,
  enableExtremePriority: 0
})

await keyboard.setGamepadLinearCurve({
  pointA: 0.1,
  pointAValue: 20,
  pointB: 0.2,
  pointBValue: 60,
  pointC: 3.0,
  pointCValue: 200,
  pointD: 3.3,
  pointDValue: 255
})

Read and update mouse DPI

import { ServiceMouse } from 'wvke-sdk'

const mouse = new ServiceMouse()
const devices = await mouse.getDevices()

if (devices.length === 0) {
  throw new Error('No mouse devices found')
}

await mouse.init(devices[0].id)

const currentDpi = await mouse.getDPI()
await mouse.setDPI(1600)

console.log(currentDpi)

TypeScript

Type declarations are bundled with the package.

Notes

• ServiceKeyboard.requestDevices(configs?) opens the browser WebHID authorization picker and returns { code, devices }; pass configs to override the allowed VID/PID filters for that request.
• ServiceKeyboard.getDevices() returns { code, devices } for devices already authorized by the browser.
• ServiceMouse.getDevices() returns a device array directly.
• Keyboard custom backlight and logo custom lighting support real-time report events and heartbeat-based refresh.
• The package README published to npm is generated from this file via npm run package:prepare.