anthony/ardor-katana-linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
anthony
2026-09-06 01:06:40 +08:00
commit 57c4e80f0d
69 changed files with 20940 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cli/README.md
+23
View File
@@ -0,0 +1,23 @@
# Команды утилиты katana.py
Справочник команд и аргументов.
Все команды идут через транзакцию `begin → data → commit → save` и безопасны: печать не прерывается, прошивка остаётся живой.
Исключение — `macro set`/`macro clear`: вендор после записи макросов save не делает (подробности в [PROTOCOL.md](../PROTOCOL.md)).
Низкоуровневое описание транзакций — в [PROTOCOL.md](../PROTOCOL.md).
Режимы подсветки и их аргументы вынесены в отдельный документ: [COLOR-MODES.md](../COLOR-MODES.md).
## Состав справочника
| Документ | Тема |
| ------------------------------------- | ----------------------------------------------------------------------------- |
| [colors.md](colors.md) | Именованные цвета CSS вместо `RRGGBB`. |
| [keys.md](keys.md) | Имена клавиш: канонические, символы, синонимы, hex-индексы. |
| [paint.md](paint.md) | `paint` — per-key раскраска и shorthand-алиасы (`--wasd`, `--row1`…`--row6`). |
| [scan.md](scan.md) | `scan` — визуальный перебор режимов. |
| [raw.md](raw.md) | `raw` — произвольный payload для экспериментов. |
| [remap.md](remap.md) | `remap` — переназначение клавиш на мышь, шорткаты редактора, мультимедиа, горячие клавиши и макросы. |
| [macro.md](macro.md) | `macro` — запись макросов, работа с вендорским XML. |
| [apply.md](apply.md) | `apply` — применение YAML-конфига целиком (профиль настроек). |
| [commands.md](commands.md) | Команды без аргументов: `keys`, `reset`, `off`, `default`. |
| [troubleshooting.md](troubleshooting.md) | Что делать, если команда отклоняется или прошивка залипла. |
docs/cli/apply.md
+101
View File
@@ -0,0 +1,101 @@
# apply — применение YAML-конфига
Применяет конфиг из YAML-файла: вместо длинных команд — один файл со всеми настройками.
Файл можно хранить в любом месте (например `~/.config/katana.yaml`), в репозитории лежит пример [katana.yaml.example](../../katana.yaml.example).
```
./katana.py apply ~/my-katana.yaml # применить конфиг
./katana.py apply katana.yaml.example # применить пример из репозитория
```
Зависимость: PyYAML (`pip install pyyaml`, см. [INSTALL.md](../INSTALL.md)).
## Порядок применения и сохранение
Секции применяются всегда в одном порядке, независимо от их порядка в файле:
1. `remap` — таблица переназначений (04 11), save;
2. `paint` — per-key раскраска, включает режим 0x80, save;
3. `lighting` — финальный режим подсветки (mode/off/default), перекрывает 0x80 от paint, save;
4. `raw` — произвольный payload (для экспериментов);
5. `macros` — ВСЕ слоты одним блобом (04 19), save;
6. `remap` и `lighting` — **повторно** (если секции были в конфиге), со save.
**Модель сохранения** (проверена на железе): каждая область прошивки (bind-таблица, paint-таблица, режим, макросы) сохраняется во флеш **только своим собственным save** (04 f0) — чужой save чужую область ни сохраняет, ни затирает. Поэтому в apply каждая секция несёт свой save.
**Почему remap и lighting повторяются после макросов:** запись макросов (04 19) сбивает bind-таблицу и режим подсветки **в RAM** (во флеше они остаются). Повторная отправка восстанавливает их в RAM и заодно фиксирует save'ом.
**Почему все макросы одним блобом:** каждый вызов `macro set` обнуляет прочие слоты — несколько макросов нужно писать за одну транзакцию (apply так и делает).
Ключ `save` в секциях конфига **не поддерживается** — apply управляет save'ами сам (написанный по ошибке `save: false` отклоняется как неизвестный ключ).
Каждая секция прогоняется через соответствующую команду CLI — валидация значений та же самая.
Перед каждым шагом печатается `apply [...] ...`, после — итоговый список применённого.
Команды `keys`, `scan`, `reset` в конфиге не нужны: это диагностика, а не состояние.
## Секции
### `macros` — содержимое макросов (см. [macro.md](macro.md))
Все слоты пишутся **одним блобом** (пропуски между номерами — пустые слоты).
Ключ — номер слота 0..99, значение — `tokens` (список) или `xml` (файл).
```yaml
macros:
0:
tokens: ["+lctrl", "a@50", "-lctrl"] # Ctrl+A
1:
xml: raw-data/katana-v1/test.xml
```
### `remap` — переназначение клавиш (см. [remap.md](remap.md))
```yaml
remap:
keys:
caps: macro0 # КЛЮЧ: ДЕЙСТВИЕ — те же, что у remap --key
menu: meta+e
# clear: true # вместо keys: сбросить ВСЕ переназначения
```
### `paint` — раскраска клавиш (см. [paint.md](paint.md))
```yaml
paint:
all: black # база (или black: true / keep: true)
keys:
esc: "ff0000" # КЛЮЧ: ЦВЕТ
wasd: dodgerblue # shorthand-алиасы CLI: wasd, numpad, alpha, punct, digits, arrows
rows:
1: "202020" # ряды 1..6
brightness: 15
```
### `lighting` — режим подсветки (см. [COLOR-MODES.md](../COLOR-MODES.md))
`mode` — имя или номер 1..19, а также `off` и `default` (применяются как команды `off`/`default`).
```yaml
lighting:
mode: static
color: red
brightness: 15 # 1..15
# speed: 5 # 2..15
# rainbow: true # статика: спектр вместо color
# direction: north-south
```
### `raw` — сырой payload (см. [raw.md](raw.md))
```yaml
raw: "80 00 ... aa 55" # hex-строка или список строк
```
## Валидация
- Неизвестные секции и неизвестные ключи внутри секций отклоняются с указанием опечатки.
- `macros`: слот должен иметь либо `tokens`, либо `xml` (не оба и не ни одного).
- Значения проверяются тем же парсером, что и CLI-команды (`parse_color`, `parse_mode`, диапазоны).
Офлайн-тесты — `tests/test_apply.py` (пример конфига разбирается и превращается в валидные argv).
docs/cli/colors.md
+28
View File
@@ -0,0 +1,28 @@
# Именованные цвета
Вместо `RRGGBB` можно передавать имя из палитры CSS Color Module Level 4 — все 147 стандартных имён (`aliceblue`, `antiquewhite`, `aqua`, ..., `whitesmoke`, `yellow`, `yellowgreen`), включая оба варианта написания серых (`gray`/`grey`, `darkgray`/`darkgrey`, `slategray`/`slategrey`, `dimgray`/`dimgrey`, `lightslategray`/`lightslategrey`, `darkslategray`/`darkslategrey`) и `rebeccapurple`.
Полный список — `COLOR_ALIASES` в [katana.py](../../katana.py).
Наиболее употребимые:
| Имя | Hex | Имя | Hex |
| ---------------- | -------- | ------------------- | -------- |
| `red` | `ff0000` | `orange` | `ffa500` |
| `green` | `008000` | `purple` | `800080` |
| `blue` | `0000ff` | `violet` | `ee82ee` |
| `yellow` | `ffff00` | `magenta`/`fuchsia` | `ff00ff` |
| `cyan`/`aqua` | `00ffff` | `pink` | `ffc0cb` |
| `white` | `ffffff` | `lime` | `00ff00` |
| `black` | `000000` | `teal` | `008080` |
| `gold` | `ffd700` | `silver` | `c0c0c0` |
| `crimson` | `dc143c` | `indigo` | `4b0082` |
| `hotpink` | `ff69b4` | `navy` | `000080` |
| `maroon` | `800000` | `olive` | `808000` |
| `chartreuse` | `7fff00` | `turquoise` | `40e0d0` |
| `coral` | `ff7f50` | `salmon` | `fa8072` |
| `khaki` | `f0e68c` | `orchid` | `da70d6` |
| `gray`/`grey` | `808080` | `whitesmoke` | `f5f5f5` |
Примеры: `--color rebeccapurple`, `--key esc=hotpink`, `paint --black --wasd dodgerblue`.
Имена клавиш, которые принимают команды, описаны в [keys.md](keys.md).
docs/cli/commands.md
+28
View File
@@ -0,0 +1,28 @@
# Команды без аргументов
```
./katana.py keys # живой кадр
./katana.py reset # разблокировка прошивки
./katana.py off # выключение подсветки
./katana.py default # вендорский payload
```
## Команды
### `off`
Выключить подсветку (all-zero payload).
### `default`
Вендорский дефолтный payload (режим `0x80`, пустая таблица).
### `keys`
Прочитать живой кадр: текущие цвета всех 143 слотов с учётом яркости и анимаций.
Печатается сеткой 16 слотов на строку, `......` = чёрный.
### `reset`
USB port reset без переподключения: снимает залипание прошивки.
Перечисление ~2 с, клавиатура не отваливается от системы.
docs/cli/keys.md
+61
View File
@@ -0,0 +1,61 @@
# Имена клавиш
В `paint --key КЛЮЧ=ЦВЕТ` (и во всех shorthand-алиасах) клавиша задаётся любым из способов:
**Канонические имена** (US-раскладка, из `keymap.py`): `esc`, `f1`–`f12`, `` ` ``–`0` (цифры и тильда), `-`, `=`, `tab`, `q`–`p`, `[`, `]`, `caps`, `a`–`l`, `;`, `'`, `\`, `enter`, `z`–`m`, `,`, `.`, `/`, `lshift`, `lctrl`, `lwin`, `lalt`, `space`, `ralt`, `fn`, `menu`, `rctrl`, `arrowleft`, `arrowdown`, `arrowup`, `arrowright`, `backspace`, `prtsc`, `scrlk`, `pause`, `insert`, `home`, `pgup`, `delete`, `end`, `pgdown`, а также нумпад: `numlock`, `num/`, `num*`, `num-`, `num7`–`num0`, `num.`, `num+`, `numenter`.
Буквы — строчные или заглавные (`a` = `A`).
**Символы клавиш** пишутся как есть: `` ` ``, `1`–`0`, `-`, `=`, `[`, `]`, `;`, `'`, `\`, `,`, `.`, `/`, `~`.
**Синонимы** (полная таблица — `KEY_SYMBOL_ALIASES` в `keymap.py`; просмотр: `python3 keymap.py`), по клавишам:
| Клавиша | Синонимы |
| ---------------- | --------------------------------------------------------------------- |
| `` ` `` (тильда) | `tilde`, `grave`, `backquote`, `backtick` |
| `-` | `minus`, `dash`, `hyphen` |
| `=` | `equal`, `equals` |
| `[` | `lbracket`, `leftbracket`, `openbracket` |
| `]` | `rbracket`, `rightbracket`, `closebracket` |
| `;` | `semicolon`, `colon` |
| `'` | `quote`, `apostrophe`, `singlequote` |
| `\` | `backslash`, `bslash` |
| `,` | `comma`, `lessthan` |
| `.` | `period`, `dot`, `greaterthan` |
| `/` | `slash`, `question` |
| `space` | `spacebar` |
| `esc` | `escape` |
| `tab` | `tab` |
| `caps` | `capslock` |
| `enter` | `return`, `cr` |
| `backspace` | `bksp` |
| `lshift` | `shift`, `leftshift` |
| `rshift` | `rightshift` |
| `lctrl` | `ctrl`, `leftctrl` |
| `rctrl` | `rightctrl` |
| `lalt` | `alt`, `leftalt` |
| `ralt` | `altgr`, `rightalt` |
| `lwin` | `windows`, `super`, `meta` |
| `menu` | `context`, `apps` |
| `insert` | `ins` |
| `delete` | `del` |
| `pgup` | `pageup` |
| `pgdown` | `pgdn`, `pagedown` |
| `prtsc` | `printscreen`, `prntscr`, `pscr` |
| `scrlk` | `scrolllock`, `slck` |
| `pause` | `break` |
| `arrowleft` | `left`, `leftarrow` |
| `arrowright` | `right`, `rightarrow` |
| `arrowup` | `up`, `uparrow` |
| `arrowdown` | `down`, `downarrow` |
| `numlock` | `numlock` |
| `num/` | `numslash`, `numdivide` |
| `num*` | `numasterisk`, `numtimes` |
| `num-` | `numminus` |
| `num+` | `numplus` |
| `num.` | `numdot`, `numpoint`, `numdecimal`, `numdel`, `numcomma`, `numperiod` |
| `num0`–`num9` | `num0`, `num1`, … `num9` |
| `numenter` | `numenter` |
**Hex-индексы**: `0x00`–`0x8e` — прямой адрес LED-слота (голые цифры без `0x` — имена клавиш цифрового ряда, не индексы).
Цвета для `КЛЮЧ=ЦВЕТ` задаются hex-кодом или именем — см. [colors.md](colors.md).
docs/cli/macro.md
+69
View File
@@ -0,0 +1,69 @@
# macro — макросы
Записывает содержимое макросов в прошивку (канал 04 19) и работает с вендорским XML.
Формат протокола — в [PROTOCOL.md](../PROTOCOL.md).
Макрос нужно привязать к клавише через `remap --key КЛЮЧ=macro<N>` (индексация 0-based: «Макрос 1» вендорской утилиты = 0).
```
./katana.py macro set 0 -- a@126 s@101 -a@41 f # макрос 0 из токенов
./katana.py macro set 0 --xml test.xml # макрос 0 из вендорского XML
./katana.py remap --key caps=macro0 # привязать к Caps
./katana.py macro clear # стереть все макросы
./katana.py macro show test.xml # показать события из XML (офлайн)
./katana.py macro export my.xml -- +lctrl a@50 -lctrl # сгенерировать XML (офлайн)
```
## Токены событий
Токен: `[+-]имя[@задержка_мс]`.
`+` — нажать, `-` — отпустить, без знака — нажать и отпустить (задержка ставится на отпускание).
Задержка — пауза в мс после события.
Перед токенами, начинающимися с `-`, ставьте разделитель `--`, иначе argparse примет их за опции.
Разбор примера `a@126 s@101 -a@41`:
| Токен | Что делает |
| ------- | ------------------------------------------------------------- |
| `a@126` | нажать и отпустить `A`, после отпускания пауза 126 мс |
| `s@101` | нажать и отпустить `S`, пауза 101 мс |
| `+a` | только нажать `A` (отпустить позже через `-a`) |
| `-a@41` | только отпустить `A` (зажатую раньше через `+a`), пауза 41 мс |
Пример сочетания с модификатором: `+lctrl a@50 -lctrl` — зажать Ctrl, нажать-отпустить A, отпустить Ctrl (Ctrl+A).
Имена клавиш — строчные: буквы `a`–`z`, цифры `1`–`0`, `f1`–`f12`, модификаторы (`lctrl`, `lshift`, `lalt`, `lwin`, `rctrl`, ...), `esc`, `tab`, `enter`, `backspace`, `caps`, `space`, стрелки (`left`, `up`, `right`, `down` — собственные коды прошивки, Up/Down не проверены), громкость (`volup`, `voldown`).
Кнопки мыши — те же имена, что в `remap`: `lmb`, `rmb`, `mmb`, `back`, `forward`.
## Аргументы `macro set`
### `index`
Слот макроса (0-based), `0`–`99`.
### `tokens`
События макроса (см. «Токены событий» выше).
Указывается либо `tokens`, либо `--xml`.
### `--xml ФАЙЛ`
Взять события из вендорского XML.
### `--save`
Отправить `04 f0` после коммита.
По умолчанию выключено: вендор после записи макросов save НЕ делает.
**Важно:** запись перезаписывает ВСЕ слоты макросов — макросы в других слотах стираются.
Несколько макросов записывайте за один вызов (apply так и делает) — см. [apply.md](apply.md).
Ёмкость по дампу — 896 байт блоба: до ~60 событий в один слот.
Чтение содержимого из прошивки не реализовано (канал чтения неизвестен).
Save (`--save`) по умолчанию выключен (как у вендора), но макросы переживают переподключение **только со своим save** — у каждой области прошивки свой save (см. [apply.md](apply.md) → «Порядок применения и сохранение»).
После записи макросов bind-таблица и режим подсветки сбиваются в RAM — перепошлите их (remap + mode).
## `macro show` и `macro export`
Обе команды работают офлайн, без обращения к клавиатуре.
`show файл.xml` печатает события в форме токенов.
`export файл.xml [токены] [--name ИМЯ]` создаёт вендорский XML — такие файлы понимает фирменная утилита.
docs/cli/paint.md
+100
View File
@@ -0,0 +1,100 @@
# paint — per-key раскраска
```
./katana.py paint --all orange # вся клавиатура оранжевым
./katana.py paint --black --key Tab=green # только Tab зелёным
./katana.py paint --black --key a=red --key s=green --key d=blue
./katana.py paint --black --key 0x25=ff0000 # hex-индекс тоже работает
./katana.py paint --keep --key tilde=red --key semicolon=lime # синонимы клавиш
./katana.py paint --keep --key ~=red --key ;=lime # символы тоже работают
./katana.py paint --black --row1 red --row6 magenta # ряды: F-строка и низ
```
## Аргументы `paint`
### `--all ЦВЕТ`
Залить все 143 слота этим цветом.
Без `--black` незатронутые `--key` слоты получат этот же цвет.
### `--key КЛЮЧ=ЦВЕТ`
Покрасить одну клавишу.
Повторяется сколько нужно (`--key a=red --key s=green`).
КЛЮЧ — имя из `keymap.py` (`Tab`, `a`, `num7`, `esc`, `f12`), символ клавиши (`` ` ``, `1`, `-`, `[`, `;`, `'`, `\`, `,`, `.`, `/`, `~`), синоним (`tilde`, `minus`, `equal`, `lbracket`, `semicolon`, `quote`, `backslash`, `comma`, `period`, `dot`, `slash`, `question`, `shift`, `ctrl`, `alt`, `enter`, `return`, `del`, `ins`, `pgup`, `pgdn`, `left`/`right`/`up`/`down`, `num0`–`num9`, `numplus`, `numminus`, `numdot`, ...) или hex-индекс `0x00`–`0x8e` (голые цифры — имена клавиш цифрового ряда).
ЦВЕТ — hex или имя.
Подробности об именах клавиш — [keys.md](keys.md), о цветах — [colors.md](colors.md).
### `--wasd ЦВЕТ`
Shorthand для четырёх `--key`: покрасить W, A, S, D одним цветом.
Пример: `paint --black --wasd red`.
### `--numpad ЦВЕТ`
Shorthand для `--key`: покрасить весь нумпад одним цветом (NumLock, `/`, `*`, `-`, `7`–`0`, `.`, `+`, Enter).
Пример: `paint --black --numpad blue`.
### `--alpha ЦВЕТ`
Shorthand для `--key`: покрасить все 26 буквенных клавиш (A–Z) одним цветом.
Пример: `paint --black --alpha gold`.
### `--punct ЦВЕТ`
Shorthand для `--key`: покрасить знаковые клавиши основного блока `[`, `]`, `;`, `'`, `\`, `,`, `.`, `/` и пробел одним цветом.
Пример: `paint --black --punct orange`.
### `--digits ЦВЕТ`
Shorthand для `--key`: покрасить цифровой ряд `` ` ``, `1`–`0`, `-`, `=` одним цветом.
Пример: `paint --black --digits cyan`.
### `--arrows ЦВЕТ`
Shorthand для `--key`: покрасить четыре стрелки одним цветом.
Пример: `paint --black --arrows magenta`.
### `--row1`…`--row6 ЦВЕТ`
Shorthand для `--key`: покрасить горизонтальный ряд полной клавиатуры одним цветом (включая нумпад).
Ряд 1 (16 клавиш): `esc`, F1–F12, `prtsc`, `scrlk`, `pause`.
Ряд 2 (21): `` ` ``–`0`, `-`, `=`, `backspace`, `insert`, `home`, `pgup`, `numlock`, `num/`, `num*`, `num-`.
Ряд 3 (21): `tab`, Q–P, `[`, `]`, `\`, `delete`, `end`, `pgdown`, `num7`–`num9`, `num+`.
Ряд 4 (16): `caps`, A–L, `;`, `'`, `enter`, `num4`–`num6`.
Ряд 5 (17): `lshift`, Z–M, `,`, `.`, `/`, `rshift`, `arrowup`, `num1`–`num3`, `numenter`.
Ряд 6 (13): `lctrl`, `lwin`, `lalt`, `space`, `ralt`, `fn`, `menu`, `rctrl`, стрелки, `num0`, `num.`.
Высокие клавиши нумпада (`num+`, `numenter`) отнесены к ряду, где они начинаются физически.
Пример: `paint --black --row1 red --row6 magenta`.
### `--black`
Начать с полностью чёрной таблицы: покрашены будут только перечисленные клавиши.
### `--keep`
Начать с текущего живого кадра (чтение 04 f5): все прочие клавиши сохраняют свои цвета.
Используется только вместе с `--key`.
Цвета читаются в отмасштабированном по яркости виде (максимум `ee`).
### `--brightness 1–15`
Яркость режима `0x80`.
По умолчанию `15`.
### `--no-save`
Не писать во флеш (см. `mode --no-save` в [COLOR-MODES.md](../COLOR-MODES.md)).
По умолчанию save выполняется.
Без `--all` и `--key` команда завершается ошибкой.
Команда пишет таблицу и сразу переключает подсветку в режим `0x80` (custom-таблица).
Имена клавиш и цвета описаны в [keys.md](keys.md) и [colors.md](colors.md).
docs/cli/raw.md
+23
View File
@@ -0,0 +1,23 @@
# raw — произвольный payload
## Аргументы `raw`
### `hexstr`
Payload до 64 байт (пробелы допустимы).
Короче 64 — дополняется нулями, длиннее — обрезается.
Первые байты: `[0]` режим, `[1..3]` RGB, `[8]` flag, `[9]` яркость, `[10]` скорость, `[11]` подрежим, `[14..15]` = `aa 55`.
### `--no-save`
Не писать во флеш (см. `mode --no-save` в [COLOR-MODES.md](../COLOR-MODES.md)).
По умолчанию save выполняется.
```
./katana.py raw <64 байта hex> [--no-save]
```
Payload отправляется внутри штатной транзакции `begin → data → commit → save`.
Для экспериментов с неописанными байтами.
Формат payload'ов и назначение байтов — в [PROTOCOL.md](../PROTOCOL.md).
docs/cli/remap.md
+130
View File
@@ -0,0 +1,130 @@
# remap — переназначение клавиш
Переназначает клавиши на кнопки мыши, функции текстового редактора, мультимедиа/веб-действия, эмуляцию горячих клавиш и макросы (канал 04 11, формат — в [PROTOCOL.md](../PROTOCOL.md)).
```
./katana.py remap --key caps=lmb # Caps → левая кнопка мыши
./katana.py remap --key caps=lmb --key esc=back # несколько за раз
./katana.py remap --key caps=default # вернуть стандартное действие
./katana.py remap --key fn=macro0 # Fn → макрос 0 (однократно)
./katana.py remap --key fn=macro0:5 # Fn → макрос 0 пять раз
./katana.py remap --key fn=macro0-toggle # Fn → макрос 0 до повторного нажатия
./katana.py remap --key caps=copy # Caps → копировать (Ctrl+C)
./katana.py remap --key menu=paste --key rctrl=undo # функции редактора
./katana.py remap --key fn=volup # Fn → громкость +
./katana.py remap --key esc=play --key lwin=calc # мультимедиа и калькулятор
./katana.py remap --key caps=ctrl+c # Caps → горячая клавиша Ctrl+C
./katana.py remap --key menu=meta+e # Menu → горячая клавиша Win+E
./katana.py remap --key rctrl=shift+b --key lalt=f1 # Shift+B и F1
./katana.py remap --clear # сбросить ВСЕ переназначения
```
## Аргументы `remap`
### `--key КЛЮЧ=ДЕЙСТВИЕ`
Переназначить одну клавишу.
Повторяется сколько нужно.
КЛЮЧ — те же имена, что в `paint --key` (имена из `keymap.py`, символы, синонимы, hex-индексы).
Действия перечислены ниже.
### Действия `--key`
**Мышь:**
| Имена | Кнопка |
| ------------------------- | ------------------ |
| `lmb`, `mouse1` | левая |
| `rmb`, `mouse2` | правая |
| `mmb`, `mouse3` | средняя |
| `back`, `mouseback` | назад (боковая) |
| `forward`, `mouseforward` | вперёд (боковая) |
**Шорткаты редактора:**
| Имя | Функция | Шорткат |
| ----------- | ------------ | ------- |
| `open` | Открыть | Ctrl+O |
| `new` | Создать | Ctrl+N |
| `undo` | Отмена | Ctrl+Z |
| `save` | Сохранить | Ctrl+S |
| `copy` | Копировать | Ctrl+C |
| `cut` | Вырезать | Ctrl+X |
| `paste` | Вставить | Ctrl+V |
| `find` | Найти | Ctrl+F |
| `selectall` | Выбрать всё | Ctrl+A |
**Мультимедиа и веб:**
| Имя | Функция |
| ------------------------------ | ------------------------ |
| `player` | Плеер |
| `play`, `playpause` | Воспроизведение/пауза |
| `stop` | Стоп |
| `prev`, `prevsong` | Предыдущая песня |
| `next`, `nextsong` | Следующая песня |
| `volup` | Громкость + |
| `voldown` | Громкость − |
| `mute` | Без звука |
| `home`, `homepage` | Домашняя страница |
| `refresh`, `webrefresh` | Веб: обновить |
| `webstop` | Веб: остановить |
| `webback` | Веб: назад |
| `webforward` | Веб: вперед |
| `favorites`, `webfavorites` | Веб: избранное |
| `websearch`, `search` | Веб: поиск |
| `mycomputer`, `computer` | Мой компьютер |
| `calculator`, `calc` | Калькулятор |
| `email` | Электронная почта |
**Горячие клавиши:** `MOD+КЛАВИША` — эмуляция шортката с модификаторами, модификаторы можно комбинировать через `+` (например `ctrl+shift+x`).
Без модификатора тоже работает: `a` — просто клавиша A.
Формат снят по дампу keybind-hotkeys; одиночные модификаторы и комбинации (`ctrl+shift+c`) проверены на железе.
| Модификатор (`MOD`) | Смысл |
| ----------------------- | ----------- |
| `ctrl` | Ctrl |
| `shift` | Shift |
| `alt` | Alt |
| `meta`, `win`, `super` | Meta (Win) |
| Клавиша | Смысл |
| ---------------------- | ---------------------------------- |
| `a`..`z` | буквы |
| `0`..`9` | цифры верхнего ряда |
| `f1`..`f12` | F-клавиши |
| `esc` | Esc |
| `tab` | Tab |
| `enter` | Enter |
| `space` | пробел |
| `caps` | Caps Lock |
| `backspace` | Backspace |
| `num0`..`num9` | цифры нумпада |
| `fn` | Fn (собственный код прошивки) |
Примеры: `ctrl+c` (копировать), `shift+b`, `alt+d`, `meta+e` (Win+E), `esc`, `f1`, `num1`, `fn`.
**Макросы:**
| Формат | Поведение |
| ------------------- | ------------------------------ |
| `macro<N>` | макрос N однократно |
| `macro<N>:K` | макрос N повторить K раз |
| `macro<N>-toggle` | макрос N до повторного нажатия |
**Стандартное действие:** `default`/`none`/`off`.
### `--clear`
Сбросить все переназначения: записывается таблица из одних default-записей.
Нельзя сочетать с `--key`.
### `--no-save`
Не писать во флеш (см. `mode --no-save` в [COLOR-MODES.md](../COLOR-MODES.md)).
**Важно:** каждый вызов перезаписывает ВСЮ таблицу переназначений (как вендорская утилита).
Переназначения, не указанные в текущем вызове `--key`, сбрасываются в default.
Команда чтения текущих переназначений неизвестна — учитывайте это при комбинировании.
Макросы, на которые можно ссылаться через `macro<N>`, записываются командой `macro` — см. [macro.md](macro.md).
docs/cli/scan.md
+22
View File
@@ -0,0 +1,22 @@
# scan — визуальный перебор режимов
## Аргументы `scan`
| Аргумент | Значения | По умолчанию | Описание |
| -------------- | --------------- | ------------ | ---------------------- |
| `--from` | `1`–`19` | `1` | Первый режим перебора. |
| `--to` | `1`–`19` | `19` | Последний режим. |
| `--color` | hex или имя | `ff0000` | Цвет для всех режимов. |
| `--brightness` | `1`–`15` | `15` | Яркость. |
| `--speed` | `2`–`15` | `10` | Скорость. |
| `--delay` | секунды (float) | `2.0` | Пауза между режимами. |
```
katana.py scan --from 1 --to 19 --delay 2
```
Каждый режим отправляется с записью во флеш.
В конце печатается список принятых и отклонённых прошивкой режимов.
Полезно при реверсе: смотреть на клавиатуру и записывать, какой номер какой эффект показывает.
Сами режимы и их названия — в [COLOR-MODES.md](../COLOR-MODES.md).
docs/cli/troubleshooting.md
+6
View File
@@ -0,0 +1,6 @@
# Если что-то пошло не так
- Команда отклоняется со статусом `00`/`ff` — сессия залипла.
Сначала повторить команду, затем `katana.py reset` (переподключение порта ~2–12 с, клавиатура не отваливается от системы).
- `reset` не помог — выключить/включить клавиатуру физически.
- Подробности и все известные грабли — в [PROTOCOL.md](../PROTOCOL.md) (раздел «Важные грабли»).