229 lines
16 KiB
Markdown
229 lines
16 KiB
Markdown
# Расширение функционала: свои скрипты и анимации
|
||
|
||
Встроенных команд `katana.py` хватает для настройки подсветки, но настоящий интерес начинается, когда вы пишете собственные скрипты.
|
||
Модуль спроектирован как библиотека: класс `Katana` и вспомогательные функции импортируются в любой ваш скрипт одной строкой.
|
||
|
||
Документ описывает программный интерфейс, его ограничения и готовые приёмы.
|
||
Справка по CLI-командам — в [cli/README.md](cli/README.md), низкоуровневые детали протокола — в [protocol.md](protocol.md).
|
||
|
||
## Что даёт per-key API
|
||
|
||
Прошивка хранит таблицу из 143 слотов `[индекс, R, G, B]` и умеет показывать её как отдельный режим `0x80`.
|
||
Ключевое свойство, проверенное на железе: **таблица обновляется живьём**.
|
||
Если подсветка уже в режиме `0x80`, каждая новая запись таблицы сразу меняет свечение клавиш — переключать режим повторно не нужно.
|
||
Именно это делает возможными анимации: цикл «изменил таблицу → записал → пауза» превращается в эффект.
|
||
|
||
Второе свойство — чтение живого кадра (`04 f5`): скрипт видит, что сейчас светится, с учётом яркости и активных анимаций.
|
||
На этом строятся скрипты, которые дорисовывают поверх текущей картинки, не затирая её.
|
||
|
||
## Подключение библиотеки
|
||
|
||
Все примеры предполагают, что скрипт лежит рядом с `katana.py` (или путь добавлен в `sys.path`).
|
||
|
||
```python
|
||
from light import Katana, KEYS_COUNT, resolve_key, build_payload
|
||
|
||
keyboard = Katana() # находит /dev/hidrawN и открывает его
|
||
try:
|
||
... # работа с клавиатурой
|
||
finally:
|
||
keyboard.close() # обязательно закрывать дескриптор
|
||
```
|
||
|
||
Импортируется именно `light`, а не дублируется транспорт: все проверки ACK, контрольных сумм и таймингов уже внутри.
|
||
|
||
## Справочник API
|
||
|
||
| Объект | Сигнатура | Что делает |
|
||
| ------------------------------------------------ | --------------------------------- | --------------------------------------------------------------------------------------------- |
|
||
| `Katana()` | конструктор | Находит hidraw-узел интерфейса 0 и открывает его. |
|
||
| `keyboard.close()` | — | Закрывает дескриптор. Вызывайте в `finally`. |
|
||
| `keyboard.lighting(payload, save=True)` | payload — 64 байта | Полная транзакция: begin → data-begin → payload → commit → save. Переключает режим подсветки. |
|
||
| `keyboard.write_key_table(colors, save=True)` | colors — 143 кортежей `(r, g, b)` | Записывает per-key таблицу (9 пакетов). При активном режиме `0x80` свечение меняется сразу. |
|
||
| `keyboard.show_custom(brightness=15, save=True)` | brightness 1–15 | Переключает подсветку в режим `0x80` (показ таблицы). |
|
||
| `keyboard.read_frame()` | — | Читает живой кадр, возвращает список из 143 кортежей `(r, g, b)`. |
|
||
| `keyboard.reset()` | — | USB port reset: снимает клин прошивки без переподключения. |
|
||
| `resolve_key(name)` | `'tab'`, `'tilde'`, `'0x25'` | Имя или символ клавиши → LED-индекс (`None`, если не найдено). |
|
||
| `build_payload(mode, rgb, ...)` | см. докстринг | Собирает 64-байтный payload для `lighting()`. |
|
||
| `KEYS_COUNT` | константа | Размер таблицы: 143 слота (`0x00`–`0x8e`). |
|
||
|
||
Имена слотов: индекс — это позиция в таблице, а не номер клавиши.
|
||
Карта «индекс → физическая клавиша» — в `keymap.py` (`KEYMAP`, `BLIND`), человекочитаемо: `python3 keymap.py`.
|
||
|
||
## Ограничения, которые надо знать заранее
|
||
|
||
### Скорость: ~1 кадр в секунду
|
||
|
||
Между любыми двумя USB-запросами выдерживается пауза `DELAY = 0.04` с (вендорский тайминг, ускорять не стоит — прошивка теряет пакеты).
|
||
Один кадр записи таблицы — это 17 запросов, что даёт измеренные на железе цифры:
|
||
|
||
| Операция | Время |
|
||
| ----------------------------- | ------ |
|
||
| `write_key_table(save=False)` | ~0,6 с |
|
||
| `write_key_table(save=True)` | ~0,7 с |
|
||
| `read_frame()` | ~0,6 с |
|
||
| `lighting()` (смена режима) | ~0,4 с |
|
||
|
||
Практический потолок плавной анимации — **1–1,5 кадра в секунду**.
|
||
Эффекты с быстрым движением (бегущая строка) будут дёргаными; хорошо смотрятся медленные волны, дыхание, плавные переливы.
|
||
|
||
### Флеш-память: не пишите в неё каждый кадр
|
||
|
||
`save=True` после каждой записи коммитит настройки во флеш-память, у которой ограниченный ресурс перезаписи.
|
||
Для анимаций это недопустимо расточительно, поэтому:
|
||
|
||
- в цикле анимации всегда используйте `save=False`;
|
||
- настройка, сохранённая последним `save`, остаётся во флеше и восстанавливается при включении клавиатуры;
|
||
- правило проекта: вызовы `./katana.py paint` из шелла — только с `--no-save` (см. AGENTS.md).
|
||
|
||
Несохранённая сессия не вредит: следующая команда откроет её заново (`begin` ответит `ff` = «сессия уже открыта», это штатно).
|
||
Но не оставляйте сессию открытой на часы — при зависании прошивки помогает `katana.py reset`.
|
||
|
||
### Слепые слоты
|
||
|
||
39 слотов из 143 ни к какому LED не подключены (список `BLIND` в `keymap.py`).
|
||
Прошивка молча принимает в них любой цвет, но светиться ничего не будет — не ищите баг у себя.
|
||
|
||
## Приём 1. Разовая раскраска скриптом
|
||
|
||
Скрипт-«пресет»: заливка по вашему алгоритму вместо перечисления `--key` в шелле.
|
||
|
||
```python
|
||
#!/usr/bin/env python3
|
||
"""Двухцветная раскраска: буквенный блок — один цвет, остальное — другой."""
|
||
import time
|
||
|
||
from light import Katana, KEYS_COUNT, resolve_key
|
||
from keymap import KEYMAP
|
||
|
||
LETTERS = {resolve_key(l) for l in "qwertyuiopasdfghjklzxcvbnm"}
|
||
|
||
def make_table(base, accent):
|
||
"""143 кортежей (r, g, b): буквам — accent, остальным — base."""
|
||
return [accent if i in LETTERS else base for i in range(KEYS_COUNT)]
|
||
|
||
keyboard = Katana()
|
||
try:
|
||
keyboard.write_key_table(make_table((30, 0, 40), (255, 120, 0)), save=False)
|
||
keyboard.show_custom(brightness=15, save=True) # режим 0x80 + один save
|
||
finally:
|
||
keyboard.close()
|
||
```
|
||
|
||
Обратите внимание: `save` выполняется один раз — в `show_custom`.
|
||
Таблица при этом остаётся несохранённой во флеше, но горит до выключения клавиатуры.
|
||
|
||
## Приём 2. Анимация: бегущая волна
|
||
|
||
Каркас любой анимации: подготовить режим `0x80` один раз, затем в цикле менять таблицу.
|
||
|
||
```python
|
||
#!/usr/bin/env python3
|
||
"""Синяя волна пробегает по цифровому ряду слева направо."""
|
||
import math
|
||
import time
|
||
|
||
from light import Katana, KEYS_COUNT, resolve_key
|
||
|
||
ROW = [resolve_key(k) for k in "`1234567890-="] # индексы 0x13..0x1f
|
||
FRAME_PAUSE = 0.2 # пауза между кадрами
|
||
|
||
keyboard = Katana()
|
||
try:
|
||
# один раз включаем режим 0x80 и гасим таблицу
|
||
keyboard.write_key_table([(0, 0, 0)] * KEYS_COUNT, save=False)
|
||
keyboard.show_custom(brightness=15, save=True)
|
||
|
||
phase = 0
|
||
while True:
|
||
table = [(0, 0, 0)] * KEYS_COUNT
|
||
for pos, idx in enumerate(ROW):
|
||
# волна: яркость синего канала зависит от расстояния до фронта
|
||
wave = max(0.0, math.cos((pos - phase) * math.pi / 6))
|
||
table[idx] = (0, 0, int(255 * wave))
|
||
keyboard.write_key_table(table, save=False)
|
||
phase = (phase + 1) % (len(ROW) + 6)
|
||
time.sleep(FRAME_PAUSE)
|
||
finally:
|
||
keyboard.close()
|
||
```
|
||
|
||
Цикл бесконечный — останавливайте `Ctrl+C`, блок `finally` закроет дескриптор.
|
||
Полный кадр занимает ~0,8 с (запись + пауза), волна движется заметно плавно, потому что форма синусоиды «размазана» по 13 клавишам.
|
||
|
||
Советы по анимациям:
|
||
|
||
- меняйте за кадр всю таблицу целиком — частичные обновления всё равно требуют полной транзакции;
|
||
- не пишите `save` внутри цикла никогда;
|
||
- гасите таблицу в начале (`[(0, 0, 0)] * KEYS_COUNT`), иначе волна наложится на старую раскраску;
|
||
- для «дыхания» масштабируйте цвет всех клавиш одним коэффициентом — это дёшево и выглядит хорошо при 1 FPS.
|
||
|
||
## Приём 3. Дорисовка поверх живого кадра
|
||
|
||
`read_frame()` возвращает текущую картинку, поэтому скрипт может добавлять акценты, не затирая остальное.
|
||
Это тот же механизм, что у команды `paint --keep`.
|
||
|
||
```python
|
||
frame = keyboard.read_frame() # что светится сейчас
|
||
table = list(frame) # копия, чтобы не портить оригинал
|
||
table[resolve_key("esc")] = (255, 0, 0)
|
||
keyboard.write_key_table(table, save=False)
|
||
```
|
||
|
||
Так работают индикаторы: капс-лок красным, заряд беспроводного режима зелёным, напоминание о перерыве — подсветить ряд цифр после часа работы.
|
||
Данные для условия скрипт берёт откуда угодно: файл, сокет, D-Bus, `os.stat`.
|
||
|
||
Ограничение: в режиме `0x80` кадр — это сама таблица, поэтому «дорисовка поверх анимации прошивки» (например, поверх `spectrum`) даст статичную замену, а не наложение.
|
||
Смешивать своё и встроенные эффекты в одном кадре прошивка не умеет — это ограничение железа, а не API.
|
||
|
||
## Приём 4. Переключение сценариев из шелла
|
||
|
||
Скриптам не нужен свой CLI, если хочется вызывать их как команды `katana.py`.
|
||
Оформите каждый сценарий функцией и выбирайте аргументом:
|
||
|
||
```python
|
||
#!/usr/bin/env python3
|
||
"""./my_fx.py wave|breath|off — выбор сценария первым аргументом."""
|
||
import sys
|
||
|
||
def wave(kb): ...
|
||
def breath(kb): ...
|
||
|
||
SCENARIOS = {"wave": wave, "breath": breath}
|
||
|
||
if __name__ == "__main__":
|
||
from light import Katana
|
||
name = sys.argv[1] if len(sys.argv) > 1 else "wave"
|
||
kb = Katana()
|
||
try:
|
||
SCENARIOS[name](kb)
|
||
finally:
|
||
kb.close()
|
||
```
|
||
|
||
Привычные цвета принимайте через `parse_color` из `light` — так ваши скрипты поймут и `ff8800`, и `darkorange`.
|
||
|
||
## Грабли
|
||
|
||
- **`pyusb` с `detach_kernel_driver` ломает печать.**
|
||
Транспорт — только hidraw-ioctl, как в `katana.py`.
|
||
- **Сессию всегда доводите до `save` или закрывайте программой.**
|
||
Долгая висящая сессия клинит прошивку; лечение — `katana.py reset`.
|
||
- **Не укорачивайте `DELAY`.**
|
||
Пауза 0,04 с снята с вендорских захватов; при ускорении прошивка начинает терять пакеты и ACK-и.
|
||
- **`read_frame()` возвращает масштабированные яркостью цвета.**
|
||
При яркости 15/15 максимум `ee`, а не `ff` — не сравнивайте кадр с записанным цветом «в лоб».
|
||
- **Слот `0x6d` всегда читается как `000000`.**
|
||
Это null-слот прошивки, даже у вендорской утилиты.
|
||
|
||
## Идеи для скриптов
|
||
|
||
- индикатор загрузки CPU или памяти — градиент по функциональному ряду;
|
||
- подсветка уведомлений: вспышка волной при новом сообщении;
|
||
- «помидор»: 25 минут работы — спокойный цвет, перерыв — зелёная заливка;
|
||
- плавный рассвет: медленное нарастание яркости и цвета по утрам;
|
||
- визуализация музыки через любой FFT-вход: спектр по рядам клавиатуры;
|
||
- световой «миникарт»: подсветка зоны WASD в играх, где это уместно.
|
||
|
||
Список открытых направлений самого протокола (переназначение клавиш, байты направлений) — в [protocol.md](protocol.md) → «Следующие шаги».
|