• Введение
• Структура Python-скрипта
• Базовые методы
• lightpack.lightpack()
• connect()
• lock()
• unlock()
• disconnect()
• GET-методы
• getProfile()
• getProfiles()
• getStatus()
• getAPIStatus()
• getCountLeds()
• SET-методы
• turnOn()
• turnOff()
• setProfile()
• setColor()
• setColorToAll()
• setGamma()
• setSmooth()
• setBrightness()
• Пример использования

Введение

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

import lightpack, time # Подключаем необходимые внешние модули

lpack = lightpack.lightpack('127.0.0.1', 3636, [2,3,6,7,8,9,10,4,5,1], 'IDDQD') #Создаём объект и настраиваем его
lpack.connect() # Подключаемся к серверу API
lpack.lock() # Передаём управление от софта в скрипт
lpack.setSmooth(100) # Устанавливаем необходимую степень плавности смены цветов

while True :
  lpack.setColorToAll(0,255,0) # Яркость зелёного канала всех светодидов на максимум
  time.sleep(1) # Ждём секунду
  lpack.setColorToAll(0,0,0) # Выключаем все каналы всех светодиодов
  time.sleep(1)

"Живьём" этот и некоторые другие выполненные на скорую руку эффекты выглядят так:

Этот документ содержит описание методов и некоторые примеры работы с ними. Для начала работы, неплохо было бы кратко ознакомиться с возможностями API, установить Python 2.7, положить файл lightpack.py в одну папку с вашим будущим скриптом-плагином. Если Python для вас в новинку, то есть смысл держать под рукой один из справочников-туториалов. Этот язык крайне гибок, но некоторые синтаксические конструкции могут казаться на первый взгляд неочевидными.

Если читать справку лень, а запустить скрипт хочется, то для совсем быстрого старта помимо вышеописанных рекомендаций нужно проделать следующее:

1. После установки Питона проследить за тем, чтобы файлы .py были ассоциированы с интерпретатором (происходит по умолчанию)
2. Запустить управляющий софт Лайтпака свежих версий, которые поддерживают API
3. Для Win выполнить run-->cmd запустив тем самым консоль
4. Посредством команд /cd (или любых удобных вам) перебраться в рабочую папку скрипта в которой обязательно должен находиться lightpack.py, как написано выше
5. Выполнить /moi_script.py

Не забывайте, что прервать выполнение Python-программы в любой момент из консоли можно посредством сочетания клавиш Ctrl+C. В примерах часто используются бесконечные циклы, так что это сочетание вам может пригодиться.

Структура Python-скрипта

Из примера выше можно понять, что базовая структура скрипта выглядит следующим образом:

< Подключение внешних модулей >
< Создание объекта lightpack.lightpack() и его настройка >
< connect() >
< lock() >
...
< Основное тело скрипта >
...
< unlock() или disconnect() >

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

Если по каким-то причинам Python вас не устраивает, вы можете работать напрямую с "низкоуровневым" API, или даже написать собственную обёртку (wrapper) под любимый язык. Если так, то не забудьте поделиться ей с нами.)

Базовые методы

Описание основных методов необходимых для подключения к API и управления приоритетами.

lightpack.lightpack()

Аргументы: host, port, ledMap, APIkey

Конструктор, который создаёт объект. В качестве аргументов передаются настройки. host -- адрес машины на которой запущен управляющий софт Лайтпака. В случае если машина та же, на которой вы запускаете скрипт, то нужно указать 127.0.0.1 или localhost. port -- адрес TCP-порта который слушает сервер (по умолчанию 3636). ledMap -- массив для ремаппинга вашей светодиодной конфигурации.

Не секрет, что при установке Лайтпака все пользователи используют разную конфигурацию светодиодов. Кто-то подсвечивает только боковые грани монитора, кто-то весь периметр. Кто-то использует 8 светодиодов, кто-то 10, а некоторые и вовсе светодиодные ленты. При этом светодиоды располагаются в произвольном порядке. Поэтому после настройки управляющего софта виджеты захвата в нём стоят не по порядку. И для установки цвета на конкретный светодиод из API вам нужно знать его номер (открыть настройки и посмотреть на номер виджета соответствующего нужному светодиоду). Именно для устранения этого неудобства мы ввели массив ремаппинга.

Для того чтобы правильно заполнить этот массив, нужно сделать следующее:

1. Открыть настройки программы захвата
2. Выбрать начальный (стартовый) светодиод (например, левый нижний угол)
3. Проставить все номера виджетов в массив по порядку начиная со стартового и дальше по часовой стрелке

Теперь, когда вы будете устанавливать цвета через API вам нужно будет просто помнить положение стартового светодиода, к которому вы сможете обращаться как к первому, следующий за ним по часовой стрелке будет вторым и т.д.

APIkey -- ключ авторизации для API-сервера. Его можно сгенерировать или отредактировать в соответствующем разделе программы захвата. Ключ нужен для простейшей защиты от несанкционированного использования API через сеть. Тем не менее, в программе есть возможность отключить авторизацию внешних скриптов и плагинов. В этом случае аргумент в конструкторе можно просто опустить.

 lpack = lightpack.lightpack('127.0.0.1', 3636, [2,3,6,7,8,9,10,4,5,1], 'mySecureAPIkey') 

connect()

Аргументы: нет

Через механизм сокетов при помощи этого метода осуществляется подключение к заданному в конструкторе порту по заданному в конструкторе адресу. Так же производится посылка серверу ключа авторизации, если он задан. Если попытка не удаётся (например, управляющий софт Лайтпака не запущен), то в консоли вы увидите предупреждение Lightpack API server is missing.

lpack = lightpack.lightpack('127.0.0.1', 3636, [2,3,6,7,8,9,10,4,5,1], 'mySecureAPIkey')
lpack.connect()

lock()

Аргументы: нет

Метод передаёт контроль над устройством от программы захвата вашему внешнему скрипту. До тех пор пока не выполнена эта команда, через API могут выполняться лишь GET-команды. Именно благодаря этому простейшему механизму передачи приоритета становится возможным полноценно использовать все фичи основной программы захвата в ваших скриптах. Например, из скрипта вы можете вклиниваться (выполняя lock()) в основной режим работы программы (захват или подсветку), отрабатывать набор действий и затем передавать приоритет обратно управляющей программе.

lpack = lightpack.lightpack('127.0.0.1', 3636, [2,3,6,7,8,9,10,4,5,1], 'mySecureAPIkey')
lpack.connect()
lpack.lock()

unlock()

Аргументы: нет

По аналогии с предыдущим методом возвращает приоритет обратно управляющей программе. За одну сессию установленную при помощи связки connect() / disconnect() можно сколько угодно раз использовать конструкцию lock() / unlock()

lpack = lightpack.lightpack('127.0.0.1', 3636, [2,3,6,7,8,9,10,4,5,1], 'mySecureAPIkey')
lpack.connect()
lpack.lock()
...  # Основная часть вашего скрипта
lpack.unlock()

disconnect()

Аргументы: нет

Отключает внешний скрипт от порта, который слушает API и закрывает все соединения с ним. Тем самым завершает сеанс связи с API. Никакие команды для управления Лайтпаком после disconnect() послать не получится. pyLightpack одновременно с закрытием соединения производит ещё и unlock() на тот случай, если пользователь забыл сделать это самостоятельно.

lpack = lightpack.lightpack('127.0.0.1', 3636, [2,3,6,7,8,9,10,4,5,1], 'mySecureAPIkey')
lpack.connect()
lpack.lock()
...  # Основная часть вашего скрипта
lpack.unlock()
lpack.disconnect()

GET-методы

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

getProfile()

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

Возвращает имя текущего активного профиля управляющего софта. Пример ниже выводит название профиля в консоль.

lpack = lightpack.lightpack('127.0.0.1', 3636, [2,3,6,7,8,9,10,4,5,1], 'mySecureAPIkey')
lpack.connect()
print (lpack.getProfile)
lpack.disconnect()

getProfiles()

Возвращаемые значения: список имён всех профилей

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

getStatus()

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

Возвращает флаг (строку) состояния Лайтпака, как оно отражено в настройках программы. Флаг соответствует кнопке "вкл/выкл Лайтпак". В зависимости от того выключено или включено сейчас устройство в настройках управляющего софта (а не физически!), метод возвращает off и on, соответственно.

...
if lpack.getStatus() == 'off' :
  print ('Lightpack is turned off now')  
  lpack.disconnect()
...

getAPIStatus()

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

Возвращает флаг (строку) готовности API к внешнему подключению, которое регулируется парой команд lock() / unlock(). В том случае, если API свободен и готов перейти под управление вашего скрипта/плагина возвращает idle.

...
if lpack.getAPIStatus() == 'idle' :
  lpack.lock()
...

getCountLeds()

Возвращаемые значения: кол-во зон захвата

Возвращает общее количество всех зон захвата (активных и отключенных) в текущем профиле. Актуально для устройств типа Adalight для которых программа позволяет устанавливать произвольное количество зон захвата.

SET-методы

Методы предназначены для того, чтобы передавать команды в порт, с последующим исполнением их на устройстве.

turnOn()

Аргументы: нет

Метод включает Лайтпак в том случае, если он был выключен в настройках управляющего софта. После его выполнения метод getStatus() будет возвращать on.

turnOff()

Аргументы: нет

По аналогии с предыдущим, метод выключает Лайтпак в том случае, если он был включен в настройках управляющего софта. После его выполнения метод getStatus() будет возвращать off.

setProfile()

Аргументы: имя профиля

Метод включает заданный профиль из списка доступных (см. getProfiles()).

...
prof = getProfiles()
if prof.index('test07') >= 0 :  # Если в списке вернувшихся профилей есть test07
  lpack.lock()
  lpack.setProfile('test07')  # то включаем его
  lpack.unlock()
...

setColor()

Аргументы: n, r, g, b

Метод устанавливает заданный цвет для заданного светодиода. При смене цвета учитываются текущие настройки профиля управляющего софта (степень плавности, гамма-коррекция и пр.) n -- номер светодиода в массиве ремаппинга (см. конструктор lightpack.lightpack()). r, g, b -- значения яркости каждого из каналов светодиода в промежутке от 0 до 255. Пример зажигает чётные светодиоды синим цветом, а нечётные красным:

...
for i in range (1, 11) :  # Повторяем от 1 до 10
  if i % 2 == 0 :  # Если i чётное, то
    lpack.setColor(i, 255, 0, 0)  # Устанавливаем на i-ый светодиод красный цвет
  else :
    lpack.setColor(i, 0, 0, 255) # А если не чётное, то синий
...

setColorToAll()

Аргументы: r, g, b

По аналогии с предыдущим методом устанавливает цвет на все светодиоды из массива ремаппинга. Аргумент, указывающий на номер светодиода отсутствует.

setGamma()

Аргументы: значение гамма-коррекции от 0.01 до 10.00

Устанавливает значение гамма-коррекции. Аналог соответствующей настройки в управляющем софте. Значение гамма-коррекции -- число в диапазоне от 0.01 до 10.00. Если отправленное значение будет находиться за границами этого диапазона от сервера в консоль придёт строка error. Значение гамма-коррекции устанавливается для всех светодиодов одновременно.

setSmooth()

Аргументы: значение степени плавности от 0 до 255

Устанавливает степень плавности смены цветов устройством. Аналог соответствующей настройки в управляющем софте. Значение степени плавности -- число в диапазоне от 0 до 255. Чем больше, тем плавнее изменяется цвет между двумя заданными. Если вы передадите значение выше или ниже допустимых границ диапазона, то API выставит максимально или минимально возможное, соответственно. Значение плавности устанавливается для всех светодиодов одновременно.

setBrightness()

Аргументы: значение общей яркости в диапазоне от 0 до 100

Устанавливает степень яркости для всех светодиодов устройства одновременно в диапазоне от 0 (подсветка выключена) до 100. Аналог соответствующей настройки в управляющем софте.

Пример использования

Для полноты понимания есть смысл рассмотреть настоящий скрипт. Приведённый скрипт один раз в 30 секунд подключается к вашему почтовому ящику на сервере gmail.com через протокол IMAP используя внешний модуль imaplib. Получив общее количество писем в ящике и количество непрочитанных скрипт запускает "змейку" по Лайтпаку в том случае, если есть хотя бы одно непрочитанное сообщение. Прокрутив змейку 8 кругов, скрипт передаёт приоритет действий управляющему софту и ждёт 30 секунд перед следующей проверкой почты.

Пример анимации реализован без обратной связи и во многом избыточен. Зато он позволит вам оценить скорость посылки данных через API.

import lightpack, time, imaplib, re, getpass

def gmail_checker(username,password):  # Определяем метод для парсинга данных        
        i=imaplib.IMAP4_SSL('imap.gmail.com')
        try:
                i.login(username,password)
                x,y=i.status('INBOX','(MESSAGES UNSEEN)')
                messages=int(re.search('MESSAGES\s+(\d+)',y[0]).group(1))
                unseen=int(re.search('UNSEEN\s+(\d+)',y[0]).group(1))
                return (messages,unseen)
        except:
                return False,0

lpack = lightpack.lightpack('127.0.0.1', 3636, [2,3,6,7,8,9,10,4,5,1], 'mySecureAPIkey')  # Создаём объект
lpack.connect()  # Соединяемся с API
mail = raw_input('Gmail: ')  # Запрашиваем e-mail
passwd = getpass.getpass('password: ')  # И пароль (маскируется)
while True :
        messages,unseen = gmail_checker(mail,passwd)  # Проверяем почту
        print "%i messages, %i unseen" % (messages,unseen)      + ' @ ' + time.ctime()
        if unseen > 0 :         # Если есть непрочитанные, то
                lpack.lock()    # Передаём управление скрипту
                lpack.setColorToAll(0,0,0)  # Выключаем все светодиоды
                time.sleep(2)  # Ждём пару секунд (вдруг плавность максимальная)
                lpack.setSmooth(8)  # Снижаем плавность
                i = 1
                while i < 80 :  # Повторяем 8 полных кругов
                        i = i+1
                        for k  in range (0, 10) :       
                                idx = (i+k) % 10  # Остаток от деления суммы счётчиков на 10
                                if k < 3 :  # Длина змейки -- 4 светодиода
                                        lpack.setColor(idx,255,0,0)                                     
                                else :
                                        lpack.setColor(idx,0,0,125)   
                        time.sleep(0.05)                                                
                lpack.unlock()                          
        time.sleep(30);