UDP Client for DGI AV Framework

Provides a UDP Client driver that will send information to a particular device at an IPv4 address and port. It will automatically start listening for traffic coming from that device at that specific address.

Under normal operation, the driver will listen in the same port as the remote device. Bear in mind that this is not normal operation, but it is done that way to mimic the Crestron UDP Communication module. Normally a random port (and Ephemeral port) is created when starting a communication to a remote device that will respond to incoming messages. The issue being that sometimes AV devices are sending unrequested information and therefore will not now what port to send it in.

It is possible to configure this driver to use the ephemeral port instead by setting the UseRandomReceivePort property to true.

As oppose to the Crestron UDP Communication module, this driver will not write in the log everytime that a connection was not successful.

The driver implements ICommunications for easy interfacing with other Devices Drivers in the DGI AV Framework.

The constructor takes a configuration class to configure the connection. This can be leveraged by the Host Application to create the configuration file from a JSON file stored in the device and boot up.

It relies entirely on .Net standard libraries which makes it possible to be used in windows, mac and linux applications.

Note: This driver is intended for IpV4 addresses only. IpV6 is not supported.

Usage

Start by defining a configuration class from Dgi_Core.Communication.DgiRemoteDeviceConfiguration.NetworkConfiguration generic configuration class. The configuration class takes the following properties. Some of them are not needed for UDP Communications.

• IpAddress: The IP Address of the server
• Port: The port of the server
• Hostname: The Hostname of the server. Can be used instead of IP Address. Make sure that it is discoverable by the host application.
• MacAddress: The MAC Address of the server. (Not Needed)
• Username: The Username of the server. (Not Needed)
• Password: The Password of the server. (Not Needed)

Example:

var configuration = new DgiRemoteDeviceConfiguration.NetworkConfiguration
{
    IpAddress = "192.168.0.101",
    Port = 49000,
};

Create an instance of the UdpCommunication and injecting the configuration through its constructor:

var udpCommunication = new UdpCommunication(configuration);

Alternative the UdpCommunication can be constructed using the default constructor and setting the IpAddress and Port individually:

var udpCommunication = new UdpCommunication();
udpCommunication.IpAddress = "192.168.0.101",
udpCommunication.Port = 49000,
    --- or use the ResolveHostname method if using Hostnames---
udpCommunication.ResolveHostname("ServerName"),

Connection and Disconnection

Connection and Disconnection can be done without waiting for the connection to be established. The connection will be established in the background. The status of the connection can be monitored by subscribing to the StatusChanged event. Or it can also be done through the Async/Await pattern, on which the connection will be established before the next line of code is executed.

Start listening to incoming traffic by invoking the Connect Method

udpCommunication.Connect();

Stop listening by invoking the Disconnect Method

udpCommunication.Disconnect();

Sending and Receiving Data

Use the Send method with string parameter overload to send data to the server. Proper encoding will be handled by the driver to ensure that bytes are sent correctly. It also has an Async version that waits for the data to be sent before continuing.

udpCommunication.Send("Hello World");
-- or --
udpCommunication.Send("Power \x98\xFF\x0D\x0A");

If the data that needs to be sent is a byte array, use the Send method with byte array parameter overload to send data to the server.

var data = new byte[] { 0x01, 0x02, 0x03 };
udpCommunication.Send(data);

To receive data from the server, subscribe to the DataReceived event. The event will fire everytime that data is received from the server.

udpCommunication.DataReceived += UdpCommunication_DataReceived;

The event handler will look like this:

private void UdpCommunication_DataReceived(Object o, DataReceivedEventArgs data)
{
    // Do something with the data
}

The DataReceivedEventArgs has the following properties:

• ByteArray
• String: String uses the correct encoding to convert the byte array to a string.

Status and Connection Events

To receive status, subscribe to the StatusChanged event. The event will fire everytime that the status of the connection changes. The event will pass a StatusChangedEventArgs object with the new status.

udpCommunication.StatusChanged += UdpCommunication_StatusChanged;

The event handler will look like this:

private void UdpCommunication_StatusChanged(Object o, StatusChangedEventArgs data)
{
    // Do something with the data
}

The StatusChangedEventArgs has the following properties:

• Status: And enum with the new status of the connection with the following possible values. Some of these values might not be relevant
  • NotConnected,
  • Waiting,
  • Connected,
  • ConnectionFailed,
  • Retrying,
  • BrokenRemotely,
  • BrokenLocally,
  • DnsLookup,
  • DnsFailed,
  • DnsResolved,
  • Error,
  • AuthenticationFailed,
  • Idle,
  • Starting,
  • Listening,

When there is an Error in the status, the error message can be read with the ErrorMessage property.

To receive connection changed messaged, subscribe to the ConnectionChanged event. The event will fire everytime that the connection changes. The event will pass a ConnectionChangedEventArgs object with the new state.

udpCommunication.ConnectionChanged += UdpCommunication_ConnectionChanged;

The event handler will look like this:

private void UdpCommunication_ConnectionChanged(Object o, ConnectionChangedEventArgs data)
{
    // Do something with the data
}

The StatusChangedEventArgs has the following properties:

• IsConnected: A boolean indicating if the connection is connected or not

Structured Logging

This driver accepts a Property of type ILogger to add Serilog as a Dependency Injection. If no property is assigned, the class will log to the Global Logger. If no Global Logger is created, no logging will take place.

This class takes advantage of Serilog's SourceContext, which will Enrich the log with the Class Name. To display it, make sure to add the SouceContext property to your message template.

Logs generated in this class are Verbose, and Debug and Warning. All exceptions have been caught.

A typical Global Logger assigned in the ControlSystem main block will look like this

Log.Logger = new LoggerConfiguration()
    .WriteTo.CrestronConsole(outputTemplate:"[{SourceContext} - {Timestamp:HH:mm:ss} {Level:u3}] {Message:lj}{NewLine}{Exception}" )
    .WriteTo.CrestronErrorLog(outputTemplate:"[{SourceContext} - {Level:u3}] {Message:lj}{NewLine}{Exception}")
    .CreateLogger();