TCP Client for DGI AV Framework

Provides a TCP Client capable of connecting to a server and sending and receiving data. It is designed to be used with the DGI AV Framework, but can be used in any .Net application. It features the ability to retry the server connection if it is not successful. The retry interval is fast in the beginning and slows down after consecutive attempts. The timing is ideal for applications when the device might not always be online. This way the network is not tasked with constant TCP connection traffic.

As oppose to the Crestron TCP clients, 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 TCP 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 TcpClient and injecting the configuration through its constructor:

var tcpClient = new TcpClient(configuration);

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

var tcpClient = new TcpClient();
tcpClient.IpAddress = "192.168.0.101",
tcpClient.Port = 49000,
    --- or use the ResolveHostname method if using Hostnames---
tcpClient.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 Asycn/Await pattern, on which the connection will be established before the next line of code is executed.

Start connecting to the TCP server by invoking the Connect Method

tcpClient.Connect();

And disconnect by invoking the Disconnect Method

tcpClient.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.

tcpClient.Send("Hello World");
-- or --
tcpClient.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 };
tcpClient.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.

tcpClient.DataReceived += TcpClient_DataReceived;

The event handler will look like this:

private void TcpClient_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.

tcpClient.StatusChanged += TcpClient_StatusChanged;

The event handler will look like this:

private void TcpClient_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.

tcpClient.ConnectionChanged += TcpClient_ConnectionChanged;

The event handler will look like this:

private void TcpClient_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();