Core module
Core module description
Core module provides an access to a coreD functionality.
CoreD implements and support the abstract model of gateways/devices/items to provide a universal way to control smart devices.
Gateway represents a communication domain or communication technology, like ZWave, Zigbee, Bluetooth, TCP/IP, SPI, RS232, etc.
Device represents a smart device to be controlled/monitored, like smart outlet, smart lock, smart switch, etc.
Item represents a virtual control point [vcp], like turn on/off, set some value, get current value, etc. Such virtual control point [pcp] gets mapped to a physical control point like electrical relay, shift register, AC/DC meter, etc.
example:
gateway: zwave
device: smart_lock_1
items: lock/unlock, set_password, get_password???
Core module API ( require "core"
)
Getters
get_product_name()
Get hub's product name.
call: core.get_product_name()
params: none.
return: a hub's product name (string) or nil in a case of an error.
example:
require "core"
local name = core.get_product_name()
if name == nil then
print("fail to get a hub's product name")
end
get_gateways()
Get all gateways registred within the hub.
call: core.get_gateways()
params: none.
return: an array of gateways (table) or nil in a case of an error.
example:
require "core"
local gateways = core.get_gateways()
if gateways then
for _, gate in ipairs( gateways ) do
print( "gateway name:" .. gate.name )
end
end
get_gateway()
Get a gateway registred for a plugin the current script belongs to.
call: core.get_gateway()
params: none.
return: a gateway (table) or nil in a case of an error.
example:
require "core"
local gateway = core.get_gateway()
if gateway == nil then
print("fail to get a gateway")
end
get_device()
Get device registered within the hub by specified id.
call: core.get_device()
params: device id (string).
return: device (table) or nil in a case of an error.
example:
require "core"
local device = core.get_device( "device_id" )
if device then
print( "device name:" .. device.name )
end
get_devices()
Get all devices registred within the hub.
call: core.get_devices()
params: none.
return: an array of devices (table) or nil in a case of an error.
example:
require "core"
local devices = core.get_devices()
if devices then
for _, dev in ipairs( devices ) do
print( "device name:" .. dev.name )
end
end
get_item()
Get item registered within the hub by specified id.
call: core.get_item()
params: item id (string).
return: item (table) or nil in a case of an error.
example:
require "core"
local item = core.get_item( item_id )
if item then
print( "item name:" .. item.name )
end
get_items()
Get all items registered within the hub.
call: core.get_items()
params: none.
return: an array of items (table) or nil in a case of an error.
example:
require "core"
local items = core.get_items()
if items then
for _, item in ipairs( items ) do
print( "item name:" .. item.name )
end
end
get_items_by_device_id()
Get all items registered within the hub related by specified device id.
call: core.get_items_by_device_id()
params: device id (string).
return: an array of items (table) or nil in a case of an error.
example:
require "core"
local items = core.get_items_by_device_id( device_id )
if items then
for _, item in ipairs( items ) do
print( "item name:" .. item.name )
end
end
get_setting()
Get device setting by its id
call: core.get_setting()
params: setting_id (string).
return: setting (table) or nil in a case of an error.
example:
require "core"
local setting = core.get_setting( setting_id )
if setting ~= nil then
print( "setting type:" .. setting.valueType )
end
get_setting_ids_by_device_id()
Get all device setting's ids by device id
call: core.get_setting_ids_by_device_id()
params: device_id (string).
return: array of setting's ids or nil in a case of an error.
example:
require "core"
local setting_ids = core.get_setting_ids_by_device_id( device_id )
if setting_ids ~= nil then
for _, setting_id in pairs(setting_ids) do
print( "setting id:" .. setting_id )
end
end
Adders
add_device()
Register a device for a specific gateway.
call: core.add_device()
params: device (table). Note, don't pass id into table, it's autogenerated.
return: device id (string) or nil if failed to add a device.
example:
require "core"
local gateway = core.get_gateway()
local device = core.add_device( { gateway_id = gateway._id, ... } )
add_item()
Register an item for a specific device.
call: core.add_item()
params: item (table). Note, don't pass field "id" into the table.
return: item id (string) or nil if failed to add an item.
example:
require "core"
local device = core.add_device( {...} )
local item = core.add_item( { device_id = device._id, ... } )
add_setting()
Register a setting for a specific device.
call: core.add_setting()
params: setting (table). Note, don't pass field "id" into table. It's autogenerated.
return: setting id (string) or nil if failed to add a setting
example:
require "core"
local device_id = core.add_device( {...} )
local setting = core.add_setting( { device_id = device_id, ... } )
Removers
remove_device()
Remove a device specified by a device id and all items registered for this device.
call: core.remove_device()
params: device id (string).
return: none.
example:
require "core"
core.remove_device( device_id )
remove_device_sync()
Remove a device specified by a device id and all items registered for this device. Execution of this method will be finished after device deletion.
call: core.remove_device_sync()
params: device id (string).
return: none.
example:
require "core"
core.remove_device_sync( device_id )
remove_item()
Remove an item specified by an item id.
call: core.remove_item()
params: item id (string).
return: none.
example:
require "core"
core.remove_item( item_id )
remove_gateway_devices()
Remove all devices registered for a gateway specified by a gateway id
call: core.remove_gateway_devices()
params: gateway id (string).
return: none.
example:
require "core"
core.remove_gateway_devices( gateway_id )
remove_item_dictionary_value()
Remove value with specific key from specific dictionary item
call: core.remove_item_dictionary_value()
params: item_id (string), item_dictionary_id (string)
return: none.
example:
require "core"
item_id = "1234abcd"
item_dictionary_id = "4"
core.remove_item_dictionary_value( item_id, item_dictionary_id )
remove_setting()
Remove a setting from the database
call: core.remove_setting()
params: setting_id (string).
return: nothing
example:
require "core"
core.remove_setting(setting_id)
Updaters
update_item_value()
Update a specific value for a specified item (item is specified by id).
call: core.update_item_value()
params: item_id (string), value (it depends on a value type of a item).
return: none.
example:
require "core"
value = true
core.update_item_value( item_id, value )
update_item_value_with_min_max()
Update a specific value in specific range for a specified item (item is specified by id).
call: core.update_item_value_with_min_max()
params: item_id (string), value (it depends on a value type of a item), value_min, value_max.
return: none.
example:
require "core"
item_id = "1234abcd"
value = {
value = 12,
scale = "celsius"
}
value_min = {
value = 0,
scale = "fahrenheit"
}
value_max = {
value = 34,
scale = "celsius"
}
core.update_item_value_with_min_max( item_id, value, value_min, value_max )
update_item_dictionary_value()
Update value with specific key of specific dictionary item
call: core.update_item_dictionary_value()
params: item_id (string), item_dictionary_id (string), value (it depends of item dictionary subtype)
return: none.
example:
require "core"
item_id = "1234abcd"
item_dictionary_id = "4"
value = {
userCode = "3141",
userName = "Ivan"
}
core.update_item_dictionary_value( item_id, item_dictionary_id, value )
update_reachable_state()
Update reachable state for a specified device and all items registered for this device (device is specified by id).
call: core.update_reachable_state()
params: device id (string), reachable (bool).
return: none.
example:
require "core"
reachable = true
core.update_reachable_state( dev_id, reachable )
update_ready_state()
Update ready state for a specified device (device is specified by id).
call: core.update_ready_state()
params: device id (string), ready (bool).
return: none.
example:
require "core"
ready = true
core.update_ready_state( dev_id, ready )
update_device_status()
Update device status for a specified device (device is specified by id).
call: core.update_device_status()
params: device id (string), status (string).
return: none.
example:
require "core"
local status = "broken"
core.update_device_status( "dev_id", ready )
modify_device()
Modify existing device fields. (only for migration)
call: core.modify_device()
params: device_id, device (table).
fields | type | description |
---|---|---|
gateway_id | string | [deprecated] an id of a gateway the device is being registering for |
name | string | a name displayed by the UI |
category | string | a device category |
subcategory | string | a device subcategory |
type | string | |
device_type_id | string | |
room_id | string | [opt] an id of a room this device belongs to |
parent_device_id | string | [opt] id of parent device |
info | [opt] some additional information for this device | |
battery_powered | bool | whether the device is battery powered |
reachable | bool | [opt] whether the device is reachable |
persistent | bool | [opt] whether the device is persistent. False by default. |
security | string | [opt] Security level how the device is connected. Possible options: no , low , middle , high . no by default. |
ready | bool | [opt] Ready status of device. true value means device is ready to any changes. false value means device is busy. |
status | string | [opt] Possible options: idle , broken . idle - device is in normal mode, broken - device has invalid data. |
return: none.
Fields that will be modified |
---|
category |
subcategory |
type |
security |
name |
parent_device_id |
info |
Possible info value | Required | Description |
---|---|---|
manufacturer | + | Name of device manufacturer |
model | + | Name of device model |
firmware | Firmware version | |
hardware | Harware version |
example:
require "core"
local gateway = core.get_gateway()
local device = core.modify_device( device_id, { gateway_id = gateway._id, ... } )
modify_item()
Modify existing item fields. (only for migration)
call: core.modify_item()
params: item_id, item (table).
fields | type | description |
---|---|---|
device_id | string | an id of a device the item is being registering for |
name | string | a type of the item |
value_type | string [int : bool : float : string : rgb : scalable : userCode : buttonState : token : dictionary.#subtype : array.#subtype] | a type of an item's value |
has_getter | bool | whether the item provides an ability to get a value |
has_setter | bool | whether the item provides an ability to set a value |
show | bool | whether the item should be shown on UI |
enum | table | [opt] set of values for value type 'token' |
value | int : bool : float : string : rgb : scalable : userCode : buttonState : token : dictionary.#subtype : array.#subtype | an item's value |
value_min | int : float : scalable | [opt] lower limit of item's value |
value_max | int : float : scalable | [opt] upper limit of item's value |
elementsMaxNumber | int | max allowed elements of a dictionary or an array value |
stringRestriction | string | Regexp restriction for a value in item of value type string |
userCodeRestriction | string | Regexp restriction for a field code in any value of userCode value type. E.g. it's used in item user_codes . |
userCodeModes | array of strings | List of available pin code modes. It's used in user_codes item. |
elementsMaxNumberPerArray | int | max allowed elements of each array ( if array is subtype of dictionary or another array ) |
oneWeekDayCost | int | cost of one week day in item weekly_user_code_intervals |
oneShiftedWeekDayCost | int | cost of one shifted (startTime > stopTime) week day in item weekly_user_code_intervals |
return: none.
All item fields can be modified using this method.
example:
require "core"
local item = core.modify_item( item_id, { device_id = device_id, ... } )
set_setting_value()
Update value of a setting
call: core.set_setting_value()
params: setting_id (string), value (int : bool : string : rgb : scalable), status(string)
return: nothing
example:
require "core"
core.set_setting_value(setting_id, true, "synced")
set_setting_status()
Update synchronization status of a setting
call: core.set_setting_status()
params: setting_id (string), status (string)
return: nothing
example:
require "core"
core.set_setting_status(setting_id, "pending")
set_setting_dictionary_value()
Add/Update/Remove value of a setting dictionary value. Generic ZWave configuration parameters are to be added as elements of the single grouping setting of type dictionary.zwave_device_configuration
call: core.set_setting_dictionary_value()
params: setting_id (string), key (string), value(table)
return: nothing
example:
require "core"
core.set_setting_dictionary_value(setting_id, "abc", { ... }) -- New key - add
core.set_setting_dictionary_value(setting_id, "abc", { ... }) -- Existing key - update
core.set_setting_dictionary_value(setting_id, "abc", {}) -- Empty value - remove
set_setting_dictionary_status()
Update synchronization status of a generic zwave configuration parameter
call: core.set_setting_dictionary_status()
params: setting_id (string), key (string), status (string)
return: nothing
example:
require "core"
core.set_setting_dictionary_value(setting_id, "1", "pending")
Others
generate_item_dictionary_number_id()
Generates free number key for specific dictionary item in specific range
call: core.generate_item_dictionary_number_id()
params: item_id (string), min_id (int), max_id (int)
return: item_dictionary_id (int) or nil if no free ids in the range.
example:
require "core"
item_id = "1234abcd"
item_dictionary_id = core.generate_item_dictionary_number_id(item_id, 1, 10)
print(item_dictionary_id) -- output: 1
core.update_item_dictionary_value( item_id, tostring(item_dictionary_id), "value1" )
item_dictionary_id = core.generate_item_dictionary_number_id(item_id, 1, 10)
print(item_dictionary_id) -- output: 2
send_ui_broadcast
Send broadcast with custom data to ui.
call: core.send_ui_broadcast()
params: broadcast_data (table)
return: none.
broadcasts:
Broadcast | Description |
---|---|
hub.extensions.plugin.ui_broadcast | Informs about some changes in plugins |
example:
require "core"
core.send_ui_broadcast( { data = "data" } )
send_response
Send response on setItemValueCommand request if gatway has custom setItemValueResponsePolicy.
call: core.send_response()
params: operation_id (string), result (table), error (table)
return: none.
example:
local core = require("core")
-- item value set logic
local result = {
text = "Hi there!"
}
local error = nil
core.send_response(params.operation_id, result, error)
Supported result formats:
- Empty result
result = {}
- Text result
Field | Type | Description |
---|---|---|
text | string | Custom text result |
Example:
result = {
text = "Hi there!"
}
Supported error formats:
- No error
error = nil
- Custom error
error = {
code = <code_number>,
data = "<data_string>",
message = "<message_string>"
}
Supported errors:
Cpde | Data | Message |
---|---|---|
3740 | "custom_error" | "custom error text" |
subscribe()
Subscribe a script for Core events. After subscribing the script will be launched for events happen on a Core and information about this event will be passed as a parameter.
call: core.subscribe()
params:
fields | type | description |
---|---|---|
script | string | The path to handle script. Example: HUB:scripts/handle_broadcasts . The broadcast information comes to this script as argument. |
return: none
example:
local core = require "core"
core.subscribe( "HUB:scripts/handle_broadcasts" )
unsubscribe()
Unsubscribe a script from Core events.
call: core.unsubscribe()
params:
fields | type | description |
---|---|---|
script | string | The path to handle script. Example: HUB:scripts/handle_broadcasts . |
return: none
example:
local core = require "core"
core.unsubscribe( "HUB:scripts/events_handling" )
Methods for using in external gateways
This methods could be used for both internal and external gateways
get_local_time()
Get hub local time in format is set by argument.
call: core.get_local_time()
params:
fields | type | description |
---|---|---|
format | string | [opt] time format |
return: local time (string) or empty string in a case of an error. Example: 2004-05-23T14:25:10+0200
example:
local core = require "core"
local local_time = core.get_local_time()
print( local_time )
local format = "%I:%M%p"
local_time = core.get_local_time( format )
print( local_time )
get_location()
Get hub location.
call: core.get_local_time()
params: none
return:
fields | type | description |
---|---|---|
latitude | string | the geo position latitude |
longitude | string | the geo position longitude |
example:
local core = require "core"
local location = core.get_location()
print( location )
get_timezone()
Get hub timezone.
call: core.get_timezone()
params: none
return: timezone (string) or empty string in a case of an error. Example: Europe/Kiev
example:
local core = require "core"
local timezone = core.get_timezone()
print( timezone )
get_hub_info()
Get hub information.
call: core.get_hub_info()
params: none
return:
field | type | description |
---|---|---|
model | string | Production name |
architecture | string | SOC architecture |
firmware | string | Firmware version |
kernel | string | Kernel version (for atom32 ESP-SDK version used) |
hardware | string | Hardware version |
serial | string | Serial number |
location | JsonObj | Location information |
location.latitude | float32 | Latitude value |
location.longitude | float32 | Longitude value |
location.timezone | string | Time zone name. Can be empty on internal error. Check logs on the hub for the error message (/var/log/firmware/ha-uid.log for H2) |
location.state | string | Can contain one of possible values: default , customAll , customTimezone , customCoordinates |
build | JsonObj | Build info |
build.time | string | Time and date when the build was made (ISO 8601: YYYY-MM-DDThh:mm:ss±hhmm) |
build.builder | string | Where the firmware was builded (user@host) |
build.branch | string | Branch name |
build.commit | string | Commit hash |
battery | object | If controller have no battery support whole section is not returned |
battery.status | enum | initializing , missing , charging , full , discharging |
battery.charge_state | int | Percent of available battery capacity |
battery.remaining_time | int | Remaining time in minutes to empty if discharging, or to full if charging |
battery.health | int | Percent of current full capacity relative to original full capacity |
uptime | string | Hub uptime |
localtime | string | Current time on hub (ISO 8601: YYYY-MM-DDThh:mm:ss±hhmm) |
example:
local core = require "core"
local info = core.get_hub_info()
print( info )
set_item_value()
Set a value for a specified item (item is specified by id).
call: core.set_item_value()
params:
fields | type | description |
---|---|---|
item_id | string | the id of item |
value | it depends on a value type of a item | the value of item |
return: none.
example:
local core = require "core"
local item_id = "588b7eb528b12d03be86f36f"
local value = true
core.set_item_value( item_id, value )
set_item_dictionary_value()
Set a element of item dictionary (item is specified by id).
call: core.set_item_dictionary_value()
params:
fields | type | description |
---|---|---|
item_id | string | the id of item |
item_dictionary_id | string | the id of dictionary |
value | it depends on a value type of a item | the value of dictionary |
return: none.
example:
local core = require "core"
local item_id = "588b7eb528b12d03be86f36f"
local item_dictionary_id = "1"
local value = true
core.set_item_dictionary_value( item_id, item_dictionary_id, value )
add_item_dictionary_value()
Add a element of item dictionary (item is specified by id).
call: core.add_item_dictionary_value()
params:
fields | type | description |
---|---|---|
item_id | string | the id of item |
value | it depends on a value type of a item | the value of dictionary |
return: none.
example:
local core = require "core"
local item_id = "588b7eb528b12d03be86f36f"
local value = true
core.add_item_dictionary_value( item_id, value )
delete_item_dictionary_value()
Delete a element of item dictionary (item is specified by id).
call: core.delete_item_dictionary_value()
params:
fields | type | description |
---|---|---|
item_id | string | the id of item |
value | it depends on a value type of a item | the value of dictionary |
return: none.
example:
local core = require "core"
local item_id = "588b7eb528b12d03be86f36f"
local value = true
core.delete_item_dictionary_value( item_id, value )