Composer to Cognio: Lua Extensions Changes

Overview

This guide summarizes what changed in the Lua API extensions when migrating Intelligent Module scripts from Composer to Cognio. Most APIs carry over without modification. A few have meaningful additions, and a small number of properties were removed. Review the relevant sections below before testing your migrated scripts.

Quick Reference

NamedControl

The NamedControl API received the most significant additions in Cognio. Six new functions were added, the list of available control types was updated, and one property was renamed.

New Functions

NamedControl.ModifyValue

NamedControl.ModifyValue(name, offset) modifies a named control's value by the specified offset amount. Use this for increment and decrement button logic instead of reading and rewriting the value manually.

NamedControl.ModifyValue("MyFader", 0.1)     -- Increase value by 0.1
NamedControl.ModifyValue("MyFader", -0.1)    -- Decrease value by 0.1

NamedControl.GetChanged

NamedControl.GetChanged(name) returns 1 if the named control has changed since you last called this function, or 0 if it has not. Reading this value clears the changed flag.

if NamedControl.GetChanged("MyFader") == 1 then
    -- Value changed since last check
end

NamedControl.SubscribeText

NamedControl.SubscribeText(name) subscribes to a named control so that NamedControl.EventHandler fires whenever that control changes. This enables event-driven scripts that do not require a polling timer.

NamedControl.SubscribeText("MyFader")

NamedControl.EventHandler

NamedControl.EventHandler is the callback function invoked when a subscribed control changes. The value argument is always passed as a string. Use tonumber() if you need to compare it numerically.

NamedControl.EventHandler = function(name, value)
    if name == "MyFader" then
        if tonumber(value) > 0.5 then
            NamedControl.SetValue("MyLED", 1)
        end
    end
end

NamedControl.GetProperty

NamedControl.GetProperty(name, propertyName) reads a layout property of the named control. The following property names are supported:

visible = NamedControl.GetProperty("MyButton", "visible")

NamedControl.SetProperty

NamedControl.SetProperty(name, propertyName, v1...vN) sets a layout property on the named control. Use the same property names as GetProperty.

NamedControl.SetProperty("MyButton", "visible", true)

Renamed Property

The Control Name property in the Intelligent Module editor has been renamed to Script Name in Cognio. Update any user documentation or instructions that reference the old name.

Updated Control Types

The available control types changed between Composer and Cognio. The table below shows the current Cognio list and highlights what changed.

The following Composer control types are no longer available in Cognio:

• Multistate LED
• Gauge
• Video Stream

If your Composer scripts depended on any of these control types, redesign those UI elements using the available Cognio types listed above.

Device

New Functions

Device.GetLastRecalledPreset

Device.GetLastRecalledPreset returns two strings: the remote name and the user name of the last preset recalled on the device. If no preset has been recalled, it returns nil for each value.

remoteName, userName = Device.GetLastRecalledPreset
print(remoteName)    -- "Starting Preset"

Device.RecallPreset

Device.RecallPreset(remoteName) recalls the preset with the specified remote name. Presets are recalled globally. The function returns a non-zero value if a preset with that remote name exists.

result = Device.RecallPreset("Starting Preset")
if result ~= 0 then
    print("Preset recalled")
end

Removed Properties

The following Device.LocalUnit properties are not available in Cognio. Remove any references to them from your scripts to avoid runtime errors.

Removed Device Type

The Server D100 (type code 157) no longer appears in the Device.LocalUnit.Type enumeration. The current list of supported device types ends at Radius NX 4x4 (113). Update any code that checks for or branches on this device type.

UdpSocket

New Multicast Support

Cognio adds full multicast support to the UdpSocket API through two new properties and one new method.

UdpSocketName.MulticastTtl (Integer) sets the number of network hops allowed when transmitting multicast packets. The default is 1. Set this before calling Open().

MyUdp.MulticastTtl = 5

UdpSocketName.MulticastLoop (Boolean) controls whether sent multicast packets loop back to the local socket. The default is true. Set this before calling Open().

MyUdp.MulticastLoop = false

UdpSocketName:JoinMulticast(multicastIp, interfaceIp) joins a multicast group so the socket can receive multicast traffic. Call this after Open(). The multicastIp must be in the range 224.0.0.0–239.255.255.255. The interfaceIp argument is optional and specifies which network interface to use.

MyUdp:Open(Device.LocalUnit.ControlIP, 48631)
MyUdp:JoinMulticast("224.1.1.1", Device.LocalUnit.ControlIP)

JoinMulticast() returns a boolean indicating whether the operation succeeded.

APIs With No Changes

The following APIs are functionally identical in Composer and Cognio. Your existing scripts using these APIs do not require modification:

• Controls — Input and output pin access is unchanged.
• HttpClient — All Download, Upload, CreateUrl, EncodeParams, EncodeString, and DecodeString functions are unchanged.
• JSON — The json.encode, json.decode, and json.null functions are unchanged.
• SSH — All connection, authentication, and event handling APIs are unchanged.
• System — All properties and functions are unchanged.
• TcpSocket — All connection, timeout, and event handling APIs are unchanged.
• Timer — Timer creation, start, stop, and EventHandler are unchanged.