Device

Overview

The Device API is a global variable table that gives the script information about the device it runs on and, for a Managed Device, the device it controls. Cognio DesignOps supplies these values while the Control Panel Group is not synced, and the Smart Device supplies them once it is synced.

This is especially helpful for TCP/UDP communications, so that a Managed Device's script can find the third-party device it controls.

Device.

	Type	Comment
`Device.Offline`	Bool	True if running in Cognio DesignOps (not synced)
`Device.GetLastRecalledPreset()`	Function	Returns the remote name and the user name for the last recalled preset
`Device.RecallPreset(remoteName)`	Function	Recalls the specified Preset

Device.Offline

Returns true if the script is running in Cognio DesignOps because its Control Panel Group is not synced. Returns false if the script is running on a Smart Device.

print(Device.Offline)               >> false

This is very commonly used to do different things in Cognio DesignOps and on the Smart Device.

if Device.Offline then
    --Running in Cognio DesignOps (not synced)
else
    --Running on the Smart Device (synced)
end

Device.GetLastRecalledPreset()

Returns two strings, the remote name and the user name for the last recalled preset. If none exists, returns nil for each.

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

Device.RecallPreset(remoteName)

Recalls the Preset specified using the remote name assigned to a preset which has been enabled for remote control. It returns a non-zero value if a preset of the specified remote name existed. Presets are recalled globally.

Device.RecallPreset("Starting Preset")      >> 1

Device.LocalUnit

The Device.LocalUnit API returns information about the device on which the script is executing.

	Type	Comment
`Device.LocalUnit.ControlIP`	String	Dotted IP address of network adapter used for control.
`Device.LocalUnit.AudioIP`	String	Dotted IP address of network adapter used for network audio.
`Device.LocalUnit.Name`	String	Network Name of the device running the script.
`Device.LocalUnit.Type`	Integer	Hardware type enumeration of the device running the script.
`Device.LocalUnit.TypeName`	String	Hardware type name of the device running the script.

Device.LocalUnit.ControlIP

Returns the dotted IP address of the network adapter used for control. When the Control Panel Group is synced, this is the Control IP address of the Smart Device running the script.

print(Device.LocalUnit.ControlIP)         >> 192.168.0.10

This is 0.0.0.0 on the Smart Device until its IP address has resolved. The script can (and should) check for 0.0.0.0 as a sign that the device has not finished starting up; even with no network connection, it eventually gets a link-local address.

While the Control Panel Group is not synced, it returns the IP address of the computer's network selected for Control in the Select Network(s) dialog.

Device.LocalUnit.AudioIP

Returns the dotted IP address of the network adapter used for network audio. When the Control Panel Group is synced, this is the Dante (audio network) IP address of the Smart Device running the script.

print(Device.LocalUnit.AudioIP)           >> 169.254.1.21

This is 0.0.0.0 on the Smart Device until its IP address has resolved. The script can (and should) check for 0.0.0.0 as a sign that the device has not finished starting up.

While the Control Panel Group is not synced, it may return 0.0.0.0.

Device.LocalUnit.Name

Returns the network name of the device running the script. When the Control Panel Group is synced, this is the Smart Device's control network name.

print(Device.LocalUnit.Name)              >> Lobby-C20-1A2B3C

On a Smart Device, the network name is made from the device's name followed by the last six digits of its control MAC address, so it is unique for all devices in your Site.

Device.LocalUnit.Type

Returns a number that identifies the type of device the script is running on. When the Control Panel Group is synced, this is the Smart Device running the script. While it is not synced, it is the device in your design that the Control Panel Group belongs to; for a Managed Device, that is the Managed Device itself.

print(Device.LocalUnit.Type)              >> 185

The codes returned on Cognio Smart Devices are:

C20 Processor = 185
C10 Processor = 198
T10C Processor = 199

While the Control Panel Group is not synced, you may also see Unspecified Cognio Device = 197 (before hardware is assigned), Unspecified Managed Device = 94, or the code of an xIO-family Managed Device.

Device.LocalUnit.TypeName

Returns the name of the device type, as listed above. Like Device.LocalUnit.Type, it can differ between synced and not synced. This will be the same for all devices of the same type. Names come from the firmware and can differ from the names shown in Cognio DesignOps; for example, an Unspecified Managed Device reports Unspecified Dante Device.

print(Device.LocalUnit.TypeName)                >> C20 Processor

Device.RemoteUnit

The Device.RemoteUnit API returns information about the third-party device a Managed Device controls, so use it only in a Managed Device's script. In a standalone Control Panel Group's script, Device.RemoteUnit is nil, so any of these calls cause an error. See 3rd Party Lua Control Drivers.

	Type	Comment
`Device.RemoteUnit.IP`	String	Dotted IP address of Dante unit's control interface, if known.
`Device.RemoteUnit.Name`	String	Name of the Dante unit being controlled.
`Device.RemoteUnit.Type`	Integer	Hardware type enumeration of Dante unit being controlled.
`Device.RemoteUnit.TypeName`	String	Hardware type name of Dante unit being controlled.
`Device.RemoteUnit.DanteIP`	String	Dotted IP address of Dante unit's audio interface.
`Device.RemoteUnit.DanteMAC`	String	MAC address of Dante unit in the form of XX:XX:XX:XX:XX.
`Device.RemoteUnit.DanteName`	String	Dante name of Dante unit being controlled.
`Device.RemoteUnit.DanteModel`	String	Model name of Dante unit being controlled.
`Device.RemoteUnit.DanteMfg`	String	Manufacturer name of Dante unit being controlled.

Device.RemoteUnit.IP

Returns the dotted IP address of the network adapter used for control of the associated Dante Device if known. When the Control Panel Group is synced, this is the Control IP address of the associated Dante Device.

print(Device.RemoteUnit.IP)         >> 192.168.0.10

Note this is not known for most remote devices and the control IP needs to be determined through other means and entered manually by the user for use by the script. In this case the API will return "0.0.0.0".

Device.RemoteUnit.Name

Returns the Network Name of the associated Dante Device. This is the same whether or not the Control Panel Group is synced. This will be unique for all devices in your Site.

print(Device.RemoteUnit.Name)             >> My Cool Dante Mic

This is the Network Name shown in the Network Info section of the Managed Device Properties.

Device.RemoteUnit.Type

Returns an enumeration for the type of the associated Dante Devices. This is the same whether or not the Control Panel Group is synced.

print(Device.RemoteUnit.Type)             >> 94

Unspecified Managed Devices use code 94.

Device.RemoteUnit.TypeName

Returns the name of the type of the associated Dante Device. This is the same whether or not the Control Panel Group is synced. This will be the same for all devices of the same type.

print(Device.RemoteUnit.TypeName)         >> Audio-Technica-ATND971

Device.RemoteUnit.DanteIP

Returns the dotted IP address of the network adapter used for the Dante network of the associated Dante Device. This is the same whether or not the Control Panel Group is synced.

print(Device.RemoteUnit.DanteIP)          >> 169.254.1.21

Device.RemoteUnit.DanteMAC

Returns the MAC address of the network adapter used for the Dante network of the associated Dante Device. This is the same whether or not the Control Panel Group is synced.

print(Device.RemoteUnit.DanteMAC)         >> 12:34:56:78:90:11

Device.RemoteUnit.DanteName

Returns the Dante Name of the associated Dante Device. This is the same whether or not the Control Panel Group is synced. This will be unique for all devices in your Site.

print(Device.RemoteUnit.DanteName)        >> My Cool Dante Mic

This is the name assigned in Dante Controller.

Device.RemoteUnit.DanteModel

Returns the Dante Model Name of the associated Dante Device. This is the same whether or not the Control Panel Group is synced. This will be the same for all products of the same model.

print(Device.RemoteUnit.DanteModel)       >> ATND971

This is the Model Name found on the Status tab in Dante Controller.

Device.RemoteUnit.DanteMfg

Returns the Dante Manufacturer Name of the associated Dante Device. This is the same whether or not the Control Panel Group is synced. This will be the same for all products with the same manufacturer.

print(Device.RemoteUnit.DanteMfg)         >> Audio-Technica

This is the Manufacturer Name found on the Status tab in Dante Controller.

Usage Examples

The following examples illustrate how these can be used:

Example 1 - Check and Make Sure It Is a Good IP before Using

Because the IP address may not be valid yet, you should check before using it.

--state
validIP = false

function TimerClick ()
    --Check if IP was previously marked as valid
    if validIP ~= true then
       --If not yet valid, check if IP is Valid
        if Device.LocalUnit.ControlIP ~= "0.0.0.0" then
            --If valid, mark it as so for future use
            validIP = true
        end
        --if not valid, try again next time timer fires
    else
        --do communications using the validated IP address
    end
end

MyTimer = Timer.New()
MyTimer.EventHandler = TimerClick
MyTimer:Start(.5)