Object functions

grp provides simplified access to the objects stored in the database and group address request helpers.

Most functions use alias parameter — object group address or unique object name. (e.g. '1/1/1' or 'My object')

grp.getvalue(alias)

Returns value for the given alias or Lua nil when object cannot be found.

grp.find(alias)

Returns single object with the for the given alias. Object value will be decoded automatically only if the data type has been specified in the 'Objects' module. Returns Lua nil when object cannot be found, otherwise it returns Lua table with the following items:

When object data type has been specified in the 'Objects' module the following fields are available:

grp.tag(tags, mode)

Returns Lua table containing objects with the given tag. Tags parameter can be either Lua table or a string. Mode parameter can be either 'all' (return objects that have all of the given tags) or 'any' (default — returns objects that have any of the given tags). You can use object functions on the returned table.

grp.alias(alias)

Converts group address to object name or name to address. Returns Lua nil when object cannot be found.

Object functions

Objects received by using grp.find(alias) or grp.tag(tags, mode) have the following functions attached to them:

Always check that the returned object was found otherwise calling these functions will result in an error. See the example below.

object:write(value, datatype)

Sends group write request to object's group address. Data type is taken from the database if not specified as second parameter. Returns Lua boolean as the result.

object:response(value, datatype)

Similar to object:write. Sends group response request to object's group address.

object:read()

Sends group read request to object's group address. Note: this function returns immediately and cannot be used to return the result of read request. Use event-based script instead.

object:update(value, datatype)

Similar to object:write, but does not send new value to the bus. Useful for objects that are used only in visualization.

Group communication functions

These functions should only be used if it is required to access objects by group address directly, it is recommended to use single or multiple object functions.

grp.write(alias, value, datatype)

Sends group write request to the given alias. Data type is taken from the database if not specified as third parameter. Returns Lua boolean as the result.

grp.response(alias, value, datatype)

Similar to grp.write. Sends group response request to the given alias.

grp.read(alias)

Sends group read request to the given alias. Note: this function returns immediately and cannot be used to return the result of read request. Use event-based script instead.

grp.update(alias, value, datatype)

Similar to grp.write, but does not send new value to the bus. Useful for objects that are used only in visualization.

Examples

Find object by name and write new value.

myobject = grp.find('My object') -- grp.find will return nil if object was not found if myobject then myobject:write(1) -- update object value with 1 end

Find object by address and write new value.

myobject = grp.find('1/1/15') -- verify that the requested object was found if myobject then myobject:write(52.12, dt.float16) -- explicitly set data type to dt.float16 (2-byte floating point) end

Switch all binary objects tagged 'lights' off.

lights = grp.tag('lights') lights:write(false)

Group write to the specified group address and data type.

grp.write('1/1/1', true, dt.bool) -- write 1-bit 'on' to 1/1/1 grp.write('1/1/2', 50, dt.scale) -- write 1-byte 50% to 1/1/2