Skip to main content

Lua Plugins Development

Plugin Structure​

Plugin is developed as a single lua file that returns a table containing plugin definition. 1

This includes next fields:

  • name <string> - plugin name, should be unique among all plugins
  • version <table> - plugin version, should be a table of 3 numbers (i.e. {0,0,1})
  • provided_interfaces <table> - table of interfaces provided by plugin (see: Interface Definition)
  • overriden_interfaces <table> - table of interfaces that plugin overrides (see: Interface Override)
  • devices <table> - device prototypes available for registration (see: Device Type Definition)

Also plugin table should contain callback functions for plugin lifecycle events 2:

  • init(reason) - plugin initialization, called once on plugin load
    • reason <string> - reason for plugin initialization
  • register(uuid) - plugin registered, called when plugin is register in hub's main application
    • uuid <string> - plugin UUID
  • unregister(topic, payload) - plugin unregistered, called when plugin is unregistered from hub's main application
    • topic <string> - MQTT topic
    • payload <table> - MQTT payload
  • reconnect() - plugin need to re-register, called when main application is restarted
  • discover_devices(topic, payload) - discover devices, called when plugin is requested to discover devices
    • topic <string> - MQTT topic
    • payload <table> - MQTT payload
  • device_create(topic, payload) - called when device creation requested, needs to send request to create new device
    • topic <string> - MQTT topic
    • payload <table> - MQTT payload
  • device_created(topic, payload) - device created callback, this callback should finalize device creation by adding it to DB or whatever
    • topic <string> - MQTT topic
    • payload <table> - MQTT payload
  • device_registered(id, name, params) - device registered, called when device is registered in hub's main application
    • id <string> - device ID
    • name <string> - device name
    • params <table> - device parameters
  • device_removed(topic, payload) - device removed, called when device is removed from hub's main application
    • topic <string> - MQTT topic
    • payload <table> - MQTT payload

Interface Definition​

Interface is a set of actions and parameters that can be implemented by device, it allows to define device capabilities and provide applications to have a common way to understand device functionality.

Interface is defined as a table with next fields

Action Definition​

Action is a function that can be called by application to perform some action on device.

Every action definition contain name, description, arguments and handler fields.

  • name <string> - action name, should be unique among all actions provided by interface
  • description <string> - action description
  • arguments <table> - table of arguments that action accepts
    • name <string> - argument name, should be unique among all arguments provided by action
    • description <string> - argument description
    • type <string> - argument type, can be one of: string, number, boolean, json
    • optional <boolean> - is argument optional
    • position <number> - argument number for positional action calling (starting from 0)
  • handler <function> - action handler function, should accept 2 arguments: self and args

Provided Parameter Definition​

Parameter is a value that is reported in params field of device.

Parameter is represented in parameters field of interface definition as a table where key is parameter name and value is parameter descriptor table with next fields:

  • type <string> - parameter type, can be one of: string, number, boolean, json
  • value <string> - default parameter value (?)

Interface Override​

info

Not implemented yet

Device Type Definition​

Device type is a preferred way to make device creation easier by providing a prototype of device that can be used to create new device.

Device type definition consists of fields that are needed to be forwarded to hub in a device creation request. Also it provides a way to display additional fields in device setting UI:

  • type <string> - device type (for available types see: Device Types)
  • role <string> - device role (for available roles see: Device Roles)
  • icon <string> - device icon
  • interfaces <table> - list of interfaces implemented by device
  • parameters <table> - table of parameters provided by device (see: Parameter Definition)

Device Types​

See C-Home API documentation for available device types and their requirements.

Device Roles​

See C-Home API documentation for available device roles and their requirements.

Parameter Definition​

Parameter is defined in parameters field of device type definition as a table where key is parameter name and value is parameter descriptor table with next fields:

  • type <string> - parameter type, can be one of: string, number, boolean, json
  • value <string> - default parameter value
  • role <string> - parameter role for UI (show or edit), if field is not present, parameter is not shown in UI
  • locale <table> - display name for parameter in UI, is map of locale names to locale values (only relevant if role is present)

Example Plugin​

Here is an example plugin that allows to add computer as a device to Butler Smart Home, it provides a way to issue WOL packets to computer.

TODO

Add actual plugin code

Footnotes​

  1. Plugin definition table should be returned as a last statement in plugin file ↩

  2. See example plugin for more details on callbacks implementation ↩