Lua Hub API
Require a new fucntionality
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:
- core (API to an abstract model of gateways/devices/items)
- storage (API to a storage holding data between scripts launching)
- scenes (API to a scenes functionality)
- timer (API to a timers functionality)
- network (API to a network functionality (Berkeley sockets, REST requests))
Modules provided by corresponding addons:
- zwave (API to a ZWave functionality backed by a Zwave hardware)
- zigbee (API to a Zigbee functionality backed by a Zigbee hardware)
Events subscription
Plugin can be subscribed for events (zwave
, core
, network
, ...) using subsribe( scipt_name )
method. When some event happens, a subscribed script gets called with an appropriate
event (or, which is the same, plugin gets notified with this event).
Structure of a generic event:
{
"event": "string",
"data": {}
}
fields | type | description |
---|---|---|
event | string | type of an event |
data | table | data specific to the event |
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's 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