Описание Prismatik API

Документ описывает "низкоуровневый" API (документация актуальна для версии API 1.4), который позволяет управлять устройством из внешних программ и плагинов через механизм сокетов.

Содержание:

help
exit
Авторизация подключения
apikey
GET-команды
getstatus
getstatusapi
getprofiles
getprofile
getcountleds
getmode
getfps
getleds
getcolors
- SET-команды
lock
unlock
setcolor
setgamma
setsmooth
setbrightness
setprofile
setstatus
setleds
setmode
newprofile
deleteprofile

Фактически, из любой ОС, вы можете подключиться через терминал и посылать устройству команды в режиме реального времени.

>> telnet 127.0.0.1 3636
<< Lightpack API v1.4 (type "help" for more info)

На практике для написания плагинов это не очень удобно из-за того, что постоянно приходится контролировать посылки в порт и ответы сервера. Поэтому мы создали специальный класс-обёртку для языка Python, которая называется pyLightpack. С его помощью вы изолируете себя от работы с сокетами и сможете сосредоточиться непосредственно на плагинах. Писать управляющие Лайтпаком скрипты с её помощью проще, чем настраивать конфиг для Quake.)

Однако, для точного понимания того, как именно функционирует API мы приводим здесь полный список команд с которыми он взаимодействует. Технически это взаимодействие реализуется через сервер, который при старте усправляющего софта Лайтпака открывает и "слушает" порт 3636 (по умолчанию).

help

<< help

Команда выводит самую актуальную справку по текущей версии API и доступна постоянно.

exit

>> exit
<< Goodbye!

Команда закрывает подключение к серверу и доступна постоянно.

Авторизация подключения

Начиная с версии 1.1 API поддерживает авторизацию внешних подключений. Это простейший путь защиты от несанкционированных подключений к устройству извне. Он предполагает посылку ключа авторизации, который известен лишь серверу. Вы всегда можете сгенерировать новый ключ авторизации, или вовсе отключить её в настройках программы захвата Лайтпака. Если авторизация включена, то единственный способ пройти её и получить доступ к остальным командам это команда

apikey

Возвращаемые значения: ok или fail

Отправляет серверу строку ключа авторизации. Если строка совпадает с заданной в программе, сервер авторизует подключение и у пользователя появляется доступ ко всем командам API.

>> apikey:{209e6248-b0d4-4757-a355-9593ee34f700}
<< fail
>> apikey:IDDQD
<< ok

GET-команды

Работают при любых настройках подключения, даже в том случае когда управление устройством не передано API

getstatus

Возвращаемые значения: on, off, device error или unknown

Возвращает состояние устройства, которое, будучи подключенным к ПК может быть выключено (светодиоды не горят), или включено в настройках программы захвата. Команда возвращает device error в случае ошибки доступа к устройству (иконка в трее меняется на запрещающую). Unknown -- маловероятное событие, которое происходит при истечении таймаута запроса к GUI (~1 с.)

>> getstatus
<< status:on

getstatusapi

Возвращаемые зачения: idle или busy

Возвращает текущее состояние API устройства. API занят в том случае, если управление устройством осуществляется извне (вами, вашим скриптом, кем-то по сети и пр.) и свободен если устройством управляет программа захвата. До тех пор пока не будет выполнена команда lock (см. ниже) API не может быть занят.

>> getstatusapi
<< statusapi:idle

getprofiles

Возвращает полный список профилей настроек управляющей программы через ; . Профили хранятся в папке Profiles.

>> getprofiles
<< profiles:Lightpack;test07;New profile 1;

getprofile

Возвращает имя текущего активного профиля.

>> getprofile
<< profile:test07

getcountleds

Начиная с версии 5.8 управляющей программы у пользователя появилась возможность управлять с её помощью разными устройствами. Для некоторых из них пользователь может самостоятельно выбирать количество зон захвата от 1 до 50 по количеству используемых светодиодов.

Команда возвращает общее количество всех зон захвата (активных и отключенных) в текущем профиле.

>> getcountleds
<< countleds:10

getmode

Возвращаемые значения: ambilight, moodlamp

Команда возвращает текущий режим работы подсветки. ambilight -- режим захвата картинки, moodlamp -- режим простой подсветки.

>> getmode
<< mode:moodlamp

getfps

Возвращает значение счётчика FPS (Frames Per Second) для режима захвата картинки.

>> getfps
<< fps:33.0

getleds

Возвращает настройки зон захвата в формате N-X,Y,W,H; Где N -- номер области захвата. X,Y -- координаты левого верхнего угла области. W,H -- ширина и высота области в пикселях.

>> getleds
<< leds:0-1157,972,637,117;1-1827,568,93,469;2-977,0,430,95;3-1818,93,102,462;4-1413,0,496,92;5-523,0,461,100;6-0,0,530,94;7-0,95,94,449;8-0,557,89,484;9-143,977,671,103;

getcolors

Возвращает цвет, выводимый на светодиоды в настоящий момент времени в формате N-R,G,B; Где N -- номер светодиода/области захвата. R,G,B -- соответствующие цветовые компоненты.

>> getcolors
<< colors:0-102,96,82;1-75,47,18;2-67,55,46;3-104,77,34;4-80,67,40;5-113,90,52;6-110,91,51;7-130,110,67;8-81,71,45;9-100,100,87;

SET-команды

Могут быть выполнены в том случае, когда контроль над устройством передан API посредством команды lock

lock

Возвращаемые значения: success или busy

Передаёт контроль над устройством от программы захвата вашему внешнему скрипту. До тех пор пока не выполнена эта команда, через API могут выполняться лишь GET-команды.

>> lock
<< lock:success

unlock

Возвращаемые значения: success или not locked

По аналогии с предыдущей командой передаёт управление от вашего скрипта обратно программе Лайтпака. Все настройки берутся из текущего профиля. Именно благодаря этому простейшему механизму передачи приоритета становится возможным полноценно использовать все фичи основной программы захвата в ваших скриптах.

>> unlock
<< unlock:not locked