Lua Hub API

Require a new functionality

The Hub provides Lua API to access functionality it implements. This functionality is splitted in groups, namespaces or modules, like zwave, extensions, core, etc. Such modules (as such provided functionality) can be used withing Lua scripts by using a standart mean - require.

call: require "module_name"

Returns a lua module (table) which provides module_name functionality or nill in a case of an error. Note: require "module_name" also registers global variable "module_name" which refers to the lua module.

Note: each Lua script can be launched in a separate environment (does it use separate environment or not depends on hardware and platform). If you need to save some state use the storage module.

Global variables:

Variables type description
_PLATFORM string current operating system (freertos, linux)
_HARDWARE_REVISION int hardware revision, minimal is 1

List of lua modules:

Modules provided by firmware:

Modules provided by corresponding addons:

All resources allocated by a module on behalf of a plugin get released as the plugin gets restarted or updated/removed.

Events subscription

Plugin can be subscribed for module events (zwave, core, network, ...) using a subscriber_id = subscribe( script_name[, events_filter] ) method. When some module event happens, a subscribed script gets called with an appropriate event (or, which is the same, a plugin gets notified by this event) if this event passes specified events filter, if events filter omitted, a plugin will be notified about ALL module events. To block all events specify no filter rules: (events_filter = { rules = {} } or events_filter = { exclude = false, rules = {} })

A subscribe method returns an id (subscriber_id) which identifies a subscription created by the method call. This id can be used with set_set_subscription_filters() and unsubscribe() methods.

At this moment a subscriber_id equals to a name of an event handling script passed to a subscribe method, so it's possible to use a script name as a subscriber_id argument for methods requiring it.

Change subscription events filter rules

It's possible to change (add, modify, remove) subscription's events filter rules using a set_subscription_filters( subscriber_id, filter_rules ) method. To specify a filter rule to modify/remove a rule id is used (it should be specified during filter rule creation within a subscribe() method). filter_rules is an array of filter rules.

To add a rule, specify its id(if this rule is going to be changed) and a rule body.

To modify a rule, specify its id and a new rule body.

To remove a rule, specify its id and set an event field to "" or {}.

Examples:

This example removes a filter rule with an id == "1", modifies a rule with an id == "100500" and adds a new rule.

[
  { 
    "id": "1",
    "event": ""
  },
  { 
    "id": "100500",
    "event": "the best event",
    "accepts": [
      {
        "id": 42
      }
    ]
  },
  { 
    "event": "event_1"
  },
]

Format of an events_filter:

{
  "exclude": "bool",
  "rules": [
    {
      "id": "event_id",
      "event": "event_name",
      "accepts": [
        {
          "some_id": 42,
          "some_name": {}
        },
        {
          "some_stuff": "the best stuff"
        }
      ]
    },
    {
      "event": "event_name_2",
    },
    ...
  ]
}
fields type required description
exclude bool - event filter rules policy
rules table(array) + table specifying event filter rules
rules[i].id string - rule id (to change it in the future)
rules[i].event string + event name to match
rules[i].accepts table(array) - event parameters to match

An event filter rules policy specifies how to treat event filter rules:

Event matches a rule if:

accepts[i].pair_1 == event.pair_1 if accepts[i].key_1 == event.key_1 && accepts[i].value_1 == event.value_1 || accepts[i].key_1 == event.key_1 && accepts[i].value_1 == any( event.value_1 )

Examples of event filter rules:

Pass only node_added and event_1 events:

{
  "exclude": false,
  "rules": [
    {
      "event": "node_added",
    },
    {
      "event": "event_1",
    },
  ]
}

Pass only event_1 events if they have (id == 42 and name == "the best name ever") or ( age == 100500 and city == any value ) event data, events which have some date alongside with mention early, will pass too.

{
  "rules": [
    {
      "event": "event_1",
      "accepts": [
        {
          "id": 42,
          "name": "the best name ever"
        },
        {
          "age": 100500,
          "city": {}
        }
      ]
    }
  ]
}

Block only events event_1 and events_2:

{
  "exclude": true,
  "rules": [
    {
      "event": "event_1",
    },
    {
      "event": "event_2",
    },
  ]
}

Block all events:

{
  "exclude": false,
  "rules": []
}
  or
{
  "rules": []
}

Format of a generic event:

{
  "event": "string",
  ...
}
fields type description
event string type of an event
... data specific to the event

Example of a generic event:

{
  "event": "the best event",
  "id": 42,
  "some_key": "some_value",
  "info": {
    "key_1": 100500,
    "key_2": "value_2"
  }
}

Error handling

In a case of errors methods throw exceptions, if otherwise not stated. An uncaught exception causes a script to be aborted, if this is not what you want, caught it by using pcall.

example:

require "network"

--network.connect( {} )  would cause the script to be aborted
op_res, result = pcall( network.connect, {} )

if not op_res then
  print( "fail to connect by some local reason: " .. result )
else
  print( "wait till a remote side accepts our request for connection, conn_hndl: " .. result )
end