UDPDevice

Defines an In-Sight spreadsheet cell as a UDP device (client or server), which opens a connection between the In-Sight vision system and another UDP device for sharing data over the network. Once a UDP connection has been established, data is communicated using the ReadDevice, WriteDevice, and QueryDevice functions. If the UDPDevice function initiates the communication with another UDP device on the network, then the cell is the UDP client. If the UDPDevice function waits for the communication to be received from another UDP device on the network, then the cell is the UDP server. For more information, see ReadDevice, WriteDevice, or QueryDevice.

User Datagram Protocol (UDP), an alternative to TCP, is a connectionless communication transport method that offers a limited amount of service when messages are exchanged over the Internet Protocol. Unlike TCP, UDP does not acknowledge or guarantee delivery, nor does it provide for sequencing packets.

Note:

UDPDevice generates an event when it receives a packet; this updates the spreadsheet.
To establish a UDP device connection between two In-Sight vision systems, both must be Online.

UDPDevice Inputs

Syntax: UDPDevice(Host Name,Port,Timeout,Binary Packet)

Parameter	Description
Host Name	Specifies the name of the UDP server device with which to establish a connection, if the cell containing the UDPDevice function will be the client. Note: The Host Name drop-down does not list Host Names of In-Sight vision systems and/or emulators on the network. Manually enter the host name or the IP address of the target vision system/emulator in the Host Name field. If a Host Name is not specified (null-string is the default), then the cell will be a server device, waiting for a UDP client to initiate communications.
Port	The port number of the UDP server at which the connection will be established between UDP devices. If a Host Name is specified, the Port number entered here must also be assigned on the server. If a Host Name is not specified (null-string), then this parameter assigns the UDP/IP port number to this device. No two UDPDevice functions on the same host can share the same UDP Port number assignment, or one of the devices will be unable to establish a UDP connection. For example, if two cells in the same In-Sight spreadsheet contain UDPDevice functions which use the default Port number '3000', only one of the cells will be able to function as a UDP device. Therefore, it is important to avoid duplication of Port number assignments. Note: A valid Port assignment is any unused number between 1 and 65535, except for ports used for In-Sight communications. In-Sight Emulator users should always assign Port numbers 3000 (the default) and higher to prevent potential conflicts with ports reserved by services on the PC. For more information, see In-Sight Ports.
Timeout	The number of milliseconds (100 to 15000; default = 1000) to wait for a UDP connection to be established before aborting the connection attempt. This parameter only applies when the UDPDevice function is in a cell defined as a UDP client.
Binary Packet	Specifies whether or not the function will process data as binary data packets, or the data will be processed as string information. By default, this option is disabled and the function will process data as string information.

UDPDevice Outputs

Returns	A Device data structure. Returns #ERR if any of the input parameters are invalid, or when the Timeout is exceeded. Note: Up to 12 Device structures can be inserted into a single job.
Results	When the function is inserted into a cell, an additional function will be automatically inserted in the adjacent cell to the right: WriteDevice, if the function is a UDP client, or ReadDevice if the function is a UDP server.

UDPDevice Examples

The following examples illustrate how the UDPDevice function is to be used when configured as a: UDP Client (No Response Required), UDP Client (Response Required), UDP Server (Only Receives Messages) and UDP Server (Receives and Responds to Messages).

UDP Client (No Response Required)

In this configuration, the In-Sight vision system is configured to send a UDP message to a UDP server device.

Setup

The UDPDevice function is added to the job, and valid Hostname and Port parameters are configured for the function. A WriteDevice function is automatically added to the job when the UDPDevice function determines that it will be operating as a client. The WriteDevice function is configured by applying a valid Event parameter, the Device parameter is configured to the Device data structure output by the UDPDevice function (this is setup automatically when the WriteDevice function is added to the job), and a reference is made to a cell outputting a valid binary data packet or string information.

Execution

When the vision system is Online, UDP messages will be sent out whenever the WriteDevice function receives a valid event. The Timeout parameter is not required because a response is not needed from the server.

UDP Client (Response Required)

In this configuration, the In-Sight vision system is configured to send a UDP message to a UDP server device, and await a response from the server device before the Timeout parameter expires.

Setup

The UDPDevice function is added to the job, and valid Hostname and Port parameters are configured for the function. Next, the Timeout parameter is configured with an appropriate timeout value, and then the WriteDevice function that was automatically added is configured. After configuring those functions, add a QueryDevice function and configure its Event function to an appropriate event, the Device parameter to the Device data structure output by the UDPDevice function and a reference to the appropriate data to be sent. The UDPDevice function is added to the job, and valid Hostname and Port parameters are configured for the function. A WriteDevice function is automatically added to the job when the UDPDevice function determines that it will be operating as a client. The WriteDevice function is configured by applying a valid Event parameter, the Device parameter is configured to the Device data structure output by the UDPDevice function and a reference to the appropriate data to be sent.

Execution

When the vision system is Online, UDP messages will be sent out whenever the Event parameter of the QueryDevice function is triggered. While waiting for a response from the server, the other functions in the job will be run. If the response from the server never occurs, or is received after the Timeout parameter has expired, the function will return an error; the error will be cleared when the next event triggers the sending of another UDP message.

UDP Server (Only Receives Messages)

In this configuration, the In-Sight vision system is configured to receive a UDP message from a UDP client device.

Setup

The UDPDevice function is added to the job, and the Hostname parameter is left empty, while a valid Port parameter is set. A ReadDevice function is automatically added to the job when the UDPDevice function determines that it will be operating as a server. The ReadDevice function is configured by applying a valid Event parameter and the Device parameter is configured to the Device data structure output by the UDPDevice function (this is setup automatically when the ReadDevice function is added to the job).

Execution

When the vision system is Online, it will be operating as a UDP server, running in the background of the Spreadsheet, waiting for a message to be sent. When a message is received, the server triggers the Spreadsheet to execute and populates the ReadDevice function with the incoming data. The message can be sent to the IP address of the vision system directly, or as a broadcast message to multiple vision systems on the network.

UDP Server (Receives and Responds to Messages)

In this configuration, the In-Sight vision system is configured to receive a UDP message from a UDP client device, and send a response indicating that the message was successfully received.

Setup

Two UDPDevice functions are added to the job. The first UDPDevice function will be configured as a server (the Hostname parameter is left empty, while a valid Port parameter is set). The second UDPDevice function will be configured as a client. The GetRemoteAddress function will be used to retrieve the remote address of the incoming packet, and the GetRemotePort function will be used to retrieve the remote port that issued the packet.

Execution

Two UDPDevice functions are used to handle the incoming and outgoing messages of the server. When a message is received, the Spreadsheet is triggered to execute and process the message. If the job creates a response, that event will also trigger the WriteDevice function to send the response packet. The IP address and port number are included in the incoming packet and are used by the WriteDevice function to send the response packet. The message can be sent to the IP address of the vision system directly, or as a broadcast message to multiple vision systems on the network.

For more information, see Binary Text Functions.