Перейти до основного вмісту

Розробка Lua Плагінів

Структура Плагіна​

Плагін розробляється як один lua файл, який повертає таблицю, що містить визначення плагіна. 1

Це включає наступні поля:

  • name <string> - назва плагіна, має бути унікальною серед усіх плагінів
  • version <table> - версія плагіна, має бути таблицею з 3 чисел (наприклад, {0,0,1})
  • provided_interfaces <table> - таблиця інтерфейсів, що надаються плагіном (див.: Визначення Інтерфейсу)
  • overriden_interfaces <table> - таблиця інтерфейсів, які плагін перевизначає (див.: Перевизначення Інтерфейсу)
  • devices <table> - прототипи пристроїв, доступні для реєстрації (див.: Визначення Типу Пристрою)

Також таблиця plugin повинна містити функції зворотного виклику для подій життєвого циклу плагіна 2:

  • init(reason) - ініціалізація плагіна, викликається один раз при завантаженні плагіна
    • reason <string> - причина ініціалізації плагіна
  • register(uuid) - плагін зареєстровано, викликається, коли плагін зареєстровано в головній програмі хаба
    • uuid <string> - UUID плагіна
  • unregister(topic, payload) - плагін скасовано реєстрацію, викликається, коли плагін скасовано реєстрацію з головної програми хаба
    • topic <string> - MQTT topic
    • payload <table> - MQTT payload
  • reconnect() - плагіну потрібно перереєструватися, викликається, коли головна програма перезавантажується
  • discover_devices(topic, payload) - виявити пристрої, викликається, коли плагін запитується для виявлення пристроїв
    • topic <string> - MQTT topic
    • payload <table> - MQTT payload
  • device_create(topic, payload) - викликається, коли запитується створення пристрою, потрібно надіслати запит на створення нового пристрою
    • topic <string> - MQTT topic
    • payload <table> - MQTT payload
  • device_created(topic, payload) - зворотний виклик створеного пристрою, цей зворотний виклик повинен завершити створення пристрою, додавши його до БД або щось інше
    • topic <string> - MQTT topic
    • payload <table> - MQTT payload
  • device_registered(id, name, params) - пристрій зареєстровано, викликається, коли пристрій зареєстровано в головній програмі хаба
    • id <string> - ID пристрою
    • name <string> - назва пристрою
    • params <table> - параметри пристрою
  • device_removed(topic, payload) - пристрій видалено, викликається, коли пристрій видалено з головної програми хаба
    • topic <string> - MQTT topic
    • payload <table> - MQTT payload

Визначення Інтерфейсу​

Інтерфейс - це набір дій і параметрів, які можуть бути реалізовані пристроєм, це дозволяє визначити можливості пристрою та надати додаткам загальний спосіб розуміння функціональності пристрою.

Інтерфейс визначається як таблиця з наступними полями

Визначення Дії​

Дія – це функція, яку може викликати програма для виконання певної дії на пристрої.

Кожне визначення дії містить поля name, description, arguments та handler.

  • name <string> - назва дії, має бути унікальною серед усіх дій, що надаються інтерфейсом
  • description <string> - опис дії
  • arguments <table> - таблиця аргументів, які приймає дія
    • name <string> - назва аргументу, має бути унікальною серед усіх аргументів, що надаються дією
    • description <string> - опис аргументу
    • type <string> - тип аргументу, може бути одним із: string, number, boolean, json
    • optional <boolean> - чи є аргумент необов'язковим
    • position <number> - номер аргументу для позиційного виклику дії (починаючи з 0)
  • handler <function> - функція обробника дії, повинна приймати 2 аргументи: self і args

Визначення Наданого Параметру​

Параметр – це значення, яке повідомляється в полі params пристрою.

Параметр представлений у полі parameters визначення інтерфейсу як таблиця, де ключ є назвою параметра, а значення є таблицею дескриптора параметра з наступними полями:

  • type <string> - тип параметра, може бути одним із: string, number, boolean, json
  • value <string> - значення параметра за замовчуванням (?)

Перевизначення Інтерфейсу​

інформація

Ще не реалізовано

Визначення Типу Пристрою​

Тип пристрою - це кращий спосіб полегшити створення пристрою, надаючи прототип пристрою, який можна використовувати для створення нового пристрою.

Визначення типу пристрою складається з полів, які необхідно переслати в хаб у запиті на створення пристрою. Також це надає спосіб відображення додаткових полів в інтерфейсі користувача налаштувань пристрою:

  • type <string> - тип пристрою (для доступних типів див.: Типи Пристроїв)
  • role <string> - роль пристрою (для доступних ролей див.: Ролі Пристрою)
  • icon <string> - іконка пристрою
  • interfaces <table> - список інтерфейсів, реалізованих пристроєм
  • parameters <table> - таблиця параметрів, що надаються пристроєм (див.: Визначення Параметру)

Типи Пристроїв​

Див. C-Home API documentation для доступних типів пристроїв та їх вимог.

Ролі Пристрою​

Див. C-Home API documentation для доступних ролей пристроїв та їх вимог.

Визначення Параметру​

Параметр визначається в полі parameters визначення типу пристрою як таблиця, де ключ є назвою параметра, а значення є таблицею дескриптора параметра з наступними полями:

  • type <string> - тип параметра, може бути одним із: string, number, boolean, json
  • value <string> - значення параметра за замовчуванням
  • role <string> - роль параметра для UI (show або edit), якщо поле відсутнє, параметр не відображається в UI
  • locale <table> - відображуване ім'я для параметра в UI, є картою імен локалей до значень локалей (актуально лише якщо role присутній)

Приклад Плагіна​

Ось приклад плагіна, який дозволяє додати комп'ютер як пристрій до Butler Smart Home, він надає спосіб надсилати WOL пакети на комп'ютер.

TODO

Додати фактичний код плагіна

Footnotes​

  1. Таблиця визначення плагіна повинна бути повернута як останній оператор у файлі плагіна ↩

  2. Див. приклад плагіна для більш детальної інформації про реалізацію зворотних викликів ↩