TypeScript API¶

Клавиатурой можно управлять не только из окна, но и из своих скриптов на Node.js: транспорт и протокол вынесены в отдельные модули, которые не зависят от Electron.

Байты и тайминги совпадают с Python-версией, это проверяют тесты.

Соответствие Python¶

Python	TypeScript	Где
`Katana()`	`new Katana(await HidFeatureDevice.open(), log)`	`main/device/katana.ts`, `hid.ts`
`keyboard.close()`	`await device.close()`	`main/device/hid.ts`
`keyboard.lighting(payload, save)`	`await k.lighting(payload, save)`	`main/device/katana.ts`
`keyboard.write_key_table(colors, save)`	`await k.writeKeyTable(colors, save)`	`main/device/katana.ts`
`keyboard.write_bind_table(records, save)`	`await k.writeBindTable(records, save)`	`main/device/katana.ts`
`keyboard.write_macro_table(macros, save)`	`await k.writeMacroTable(macros, save)`	`main/device/katana.ts`
`keyboard.show_custom(brightness, save)`	`await k.showCustom(brightness, save)`	`main/device/katana.ts`
`keyboard.read_frame()`	`await k.readFrame()`	`main/device/katana.ts`
—	`await k.readLiveFrame()`	`main/device/katana.ts`
`keyboard.reset()`	`await usbReset()`	`main/device/reset.ts`
`resolve_key`, `parse_color`	`resolveKey`, `parseColor`	`shared/protocol/codec.ts`
`build_payload(mode, rgb, ...)`	`buildPayload(mode, rgb, flag, brightness, speed)`	`shared/protocol/codec.ts`
`KEYS_COUNT`	`KEYS_COUNT`	`shared/protocol/constants.ts`

Цвет в TypeScript — массив [r, g, b], методы асинхронные.

Чтение кадра без save¶

readLiveFrame() читает кадр без 04 f0 по схеме f5 → 9 GET → commit и отдаёт до 15 кадров в секунду. На этом методе построен живой предпросмотр «Подсветки».

В katana.py такого метода пока нет: там read_frame() читает кадр с save. По правилам проекта новые возможности протокола сначала появляются в Python-версии, поэтому перенос readLiveFrame() в katana.py — в планах.

Использование в приложении¶

Внутри окна обращайтесь к клавиатуре через KatanaService.run(), чтобы операции не пересекались с действиями из интерфейса.

const table = Array.from({ length: KEYS_COUNT }, (): Rgb => [0, 0, 0])
table[resolveKey('esc')!] = [255, 0, 0]
await service.run('esc красным', async (k) => {
  await k.writeKeyTable(table, false)
  await k.showCustom(15, false)
})

Очередь одна на всё приложение: пока идёт операция, кнопки записи в окне недоступны.

Ограничения¶

Скорость записи, скорость чтения и ресурс флеш-памяти одинаковы для обеих реализаций.

Операция	Время или частота
Запись таблицы раскраски	~0,6 с
Смена режима	~0,4 с
Чтение живого кадра	до 15 кадров/с
Пауза между запросами	40 мс

В приложении действует то же правило: предпросмотр раскраски всегда идёт без записи во флеш, а save включается только флажком «Записать в устройство».

Подробнее о скорости и флеше — в разделе Свои скрипты.