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:

  1. Empty result
result = {}
  1. Text result
Field Type Description
text string Custom text result

Example:

result = {
    text = "Hi there!"
}

Supported error formats:

  1. No error
error = nil
  1. 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 )