UdpSocket¶

Overview¶

UdpSocket is a global table that allows communication to other devices via UDP. The UdpSocket API works using the control or audio network. This API is commonly used to communicate with a device using the devices custom UDP control protocol.

Generally, a UdpSocket must be created and opened before data can be sent to and read from the socket.

UdpSocket.¶

UdpSocket.New()¶

New() creates a UdpSocket object as a global table.

MyUdp = UdpSocket.New()

Up to 8 UdpSocket objects can be simultaneously requested with separate calls. When a socket is closed (see below), it is available for use again with another New call.

UdpSocketName.¶

The following methods and properties are available for a UdpSocket object with name UdpSocketName.

UdpSocketName.ID¶

The 1-8 number of the socket in the script.

print(MyUdp.ID) >> 1

Up to 8 UdpSocket objects can be simultaneously requested with separate calls. When a socket is closed (see below), it is available for use again with another New call.

UdpSocketName:Open(ip, port)¶

Called by the script to bind the socket to the IP address (string or 32-bit integer) and port (0-65535) of the source Control or Audio network, and source port number (integer, zero for automatic).

MyUdp:Open("192.168.1.20", 48631)

For online usage, if the script specifies anything other than the control network IP address or audio IP address, the port will not open properly. The script should specify the IP of the audio or control network as reported by the Device API.

MyUdp:Open(Device.LocalUnit.ControlIP, 48631)

MyOtherUdp:Open(Device.LocalUnit.AudioIP, 48631)

Alternately, if the script specifies “0.0.0.0” for the IP address, then the control network will be used automatically.

MyUdp:Open("0.0.0.0", 48631)

This automatic option allows binding before an IP address has been obtained during power on. Otherwise, the script should wait until there is a valid IP address in the Device table before opening the numbered port.

If a specific port number is not needed, the port may be selected automatically by the device by specifying port 0.

MyUdp:Open("192.168.1.20", 0)

Remember that some devices will respond to any port that called them while others will only send to a specific port. This may prevent the usage of automatic port selection with some devices.

If multiple sockets are needed, for example to control two different devices keeping their responses separate, ensure that two different ports are used or let the device assign ports automatically.

--Bad

MyUdp:Open(Device.LocalUnit.ControlIP, 48631)

MyOtherUdp:Open(Device.LocalUnit.ControlIP, 48631)

--Good

MyUdp:Open(Device.LocalUnit.ControlIP, 48631)

MyOtherUdp:Open(Device.LocalUnit.ControlIP, 4001)

--Good

MyUdp:Open(Device.LocalUnit.ControlIP, 0)

MyOtherUdp:Open(Device.LocalUnit.ControlIP, 0)

Finally, this method returns “true” if it is able to create a port at the provided IP and port number. This would require valid IP, port number, that there was not one already created at that port and IP and that there are not too many UDP ports. This can be used to test that the Opening was successful.

udpOpen = StationUdp:Open(Device.LocalUnit.AudioIP, 0)

if udpOpen then

--do some stuff

end

UdpSocketName:Close()¶

Closes the socket, making it available for another allocation. The existing object must not be reused.

MyUdp = UdpSocket.New()

--do a bunch of stuff

MyUdp:Close()

MyNewUdp = UdpSocket.New()

UdpSocketName:Send(ip, port, data)¶

Sends to a specific IP and port (0-65535) the specified table of data (must fit in a packet).

MyUdp:Send("192.168.1.101", 48631, "CS 1 0\r\n")

Information from the device table can be used to ensure the correct IP address is used.

MyUdp:Send(Device.RemoteUnit.DanteIP, 48631, "CS 1 0\r\n")

While you can Open a IP Socket using 0.0.0.0 or Device.LocalUnit.ControlIP as described above, you need to check Device.LocalUnit.ControlIP for non-zero to know it is assigned before you send any date. See the example below.

UdpSocketName:GetSockName()¶

Returns the current IP address and port. This is useful to get the port information being used if the socket was bound to an automatic port. Sending will not work until a valid IP has been assigned so this can be used as a check.

receivedIP, receivedPort = MyUdp:GetSockName()

print("IP: " .. receivedIP .. " Port: " .. receivedPort)

UdpSocketName.Data(socket, packet)¶

Callback function that will be called when data is available. It should accept two arguments: the socket object and the data packet table.

function HandleData(socket, packet)

-- Do Stuff

end

MyUdp.Data = HandleData

The socket object provides information about the socket on which the message was received.

The data packet table has three elements making up the received data:

Usage Examples¶

The following examples illustrate how these can be used:

Example 1 – Putting it all together¶

This example shows how UdpSocket is typically used

function HandleData(socket, packet)

--Info about receiving socket and packet

print("Socket ID: " .. socket.ID)

receivedIP, receivedPort = socket:GetSockName()

print("Socket IP: " .. receivedIP)

print("Socket Port: " .. receivedPort)

print("Packet IP: " .. packet.Address)

print("Packet Port: " .. packet.Port)

--Do stuff with the received packet

print("Packet Data: \r" .. packet.Data)

end

MyUdp = UdpSocket.New()

MyUdp:Open(Device.LocalUnit.ControlIP, 0)

MyUdp.Data = HandleData

MyUdp:Send("192.168.1.101", 48631, "CS 1 0\r\n")

Example 2 - Waiting until the Device.LocalUnit.IP has been assigned before sending any data.¶

The above example can be improved by testing that Device.LocalUnit.ControlIP is valid before using it. This needed because at powerup, the IP address can take some time to be assigned depending on the configuration. Therefore, we do these checks within a Timer EventHandler to repeatedly check and only begin sending UDP messages once the IP address is ready.

udpInitialized = false

MyUdp = UdpSocket.New()

function UDPStartTimerClick ()

--check if initialized, i.e. IP valid and UDP port open

if udpInitialized == false then

--before can send message need to determine IP address is valid IP address

if Device.LocalUnit.ControlIP ~= nil then

--have an IP Address

print("Valid IP: " .. tostring(Device.LocalUnit.ControlIP))

MyUdp:Open(Device.LocalUnit.ControlIP, 0)

MyUdp.Data = HandleData

udpInitialized = true --have done initial setup, so set this as true so don't need to do again.

else

--IP address not ready, Try again next Timer pass

print("Not ready Online Path with Device IP: " .. tostring(Device.LocalUnit.ControlIP))

end

else

--UDP Socket is open with valid IP,

--Now can send the data and do all the work each timer pass

MyUdp:Send(otherUnitIP, port, messageSendFlashUnit)

end

end

UDPStartTimer = Timer.New()

UDPStartTimer.EventHandler = UDPStartTimerClick

UDPStartTimer:Start(1)

Example 3 - Who’s it from?¶

This socket object and data packet .Address and .Port elements can be used to determine the source of the packet when handling the data, and perform a different action depending on the source.

function HandleData(socket, packet)

--Do Stuff with the received packet

if packet.Address == source1 then

--Do stuff with the packet data

elseif packet.Address == source2 then

--Do different stuff with the packet data

end

end