Beckhoff.TwinCAT.Ads.TcpRouter 5.0.0-preview4

ADS (TCP) Router implementation.
This package can be used for ADS router functionality on targets that doesn't run TwinCAT Installations to communicate to local and remote ADS targets.

This is a prerelease version of Beckhoff.TwinCAT.Ads.TcpRouter.
There is a newer prerelease version of this package available.
See the version list below for details.
Install-Package Beckhoff.TwinCAT.Ads.TcpRouter -Version 5.0.0-preview4
dotnet add package Beckhoff.TwinCAT.Ads.TcpRouter --version 5.0.0-preview4
<PackageReference Include="Beckhoff.TwinCAT.Ads.TcpRouter" Version="5.0.0-preview4" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Beckhoff.TwinCAT.Ads.TcpRouter --version 5.0.0-preview4
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Description

The package 'Beckhoff.TwinCAT.Ads.TcpRouter' implements a lean TCP ADS Router class to use on systems where no standard TwinCAT router is established or available.

It is running in UserMode only (no realtime characteristics) and contains no further functionality than distributing the ADS Frames (e.g. no Port 10000, no ADS Secure). It is just used to route ADS frames locally between AdsServers
and to/from remote ADS devices.

Implemented in asynchronous .NET Code it can be run in your own services/daemon, as standalone console application and also in your customized application.

Requirements

  • .NET Core 2.0, .NET Framework 4.61 or .NET Standard 2.0 compatible SDK or later
  • No other System allocating the same port (e.g. a regular TwinCAT installation)
  • Installed Nuget package manager or Dotnet CLI

Installation

Along with the deployment of the application where the TcpRouter is implemented, a valid Router / ADS configuration must be placed to specify
the Local Net ID, the name and the default port of the Router system.

The preferred way to configure the systesm is with standard Configuration providers, which are part of the
.NET Core / ASP .NET Core infrastructure.

See further information:
https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-3.1

This enables common options for application configuration that can be used 'out-of-the-box':

  • Via the file appsettings.json
  • With the StaticRoutesConfigurationProvider (StaticRoutes.xml)
  • Using Environment Variables.
  • Command line arguments
  • etc.

The configuration has to be loaded during application startup and is placed into the 'TwinCAT.Ads.TcpRouter.AmsTcpIpRouter' class via constructor dependency injection and
must contain the following information:

  • The name of the local System (usually the Computer or Hostname)
  • The Local AmsNetId of the local system as Unique Address in the network
  • Optionally the used TcpPort (48898 or 0xBF02 by default)
  • The static routes in the 'RemoteConnections' list.
  • Logging configuration.

Actually the configuration is not reloaded during the runtime of the 'TwinCAT.Ads.TcpRouter.AmsTcpIpRouter' class.
Please be aware that the "Backroute" from the Remote system linking to the local system (via AmsNetId) is necessary also to get functional routes.

Example for a valid 'appSettings.json' file (please change the Addresses for your network/systems.)

{
  "AmsRouter": {
    "Name": "MyLocalSystem",
    "NetId": "192.168.1.20.1.1",
    "TcpPort": 48898,
    "RemoteConnections": [
      {
        "Name": "RemoteSystem1",
        "Address": "RemoteSystem1",
        "NetId": "192.168.1.21.1.1",
        "Type": "TCP_IP"
      },
      {
        "Name": "RemoteSystem2",
        "Address": "192.168.1.22",
        "NetId": "192.168.1.22.1.1",
        "Type": "TCP_IP"
      },
    ]
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "System": "Information",
      "Microsoft": "Information"
    },
    "Console": {
      "IncludeScopes": true
    }
  }
}

Alternatively a "StaticRoutes.Xml" Xml File can configure the system equally. Don't forget to add the 'StaticRoutesXmlConfigurationProvider' to the Host configuration
during startup (see FirstSteps below).

An example of the local "StaticRoutes.xml" is given here:

<?xml version="1.0" encoding="utf-8"?>
<TcConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="C:\TwinCAT3\Config\TcConfig.xsd">
  <Local>
      <Name>MyLocalSystem</Name>
      <NetId>192.168.1.20.1.1</NetId> <!-- Local NetId -->
      <TcpPort>48898</TcpPort> <!-- Default TcpPort -->
  </Local>
  <RemoteConnections>
    <Route>
      <Name>RemoteSystem1</Name>
      <Address>RemoteSytem</Address> <!-- HostName -->
      <!--<Address>192.168.1.21</Address>  --> <!--IPAddress -->
      <NetId>192.168.1.21.1.1</NetId>
      <Type>TCP_IP</Type>
    </Route>
    <Route>
      <Name>RemoteSystem2</Name>
      <Address>192.168.1.22</Address> <!-- IPAddress -->
      <!--<Address>RemoteSystem2</Address>  --> <!--HostName -->
      <NetId>192.168.1.21.1.1</NetId>
      <Type>TCP_IP</Type>
    </Route>
  </RemoteConnections>
</TcConfig>

Alternatively, the configuration can also be set via Environment variables.

PS> $env:AmsRouter:Name = 'MyLocalSystem'
PS> $env:AmsRouter:NetId = '192.168.1.20.1.1'
PS> $env:AmsRouter:TcpPort = 48898
PS> $env:AmsRouter:RemoteConnections:0:Name = 'RemoteSystem1'
PS> $env:AmsRouter:RemoteConnections:0:Address = 'RemoteSystem1'
PS> $env:AmsRouter:RemoteConnections:0:NetId = '192.168.1.21.1.1'
PS> $env:AmsRouter:RemoteConnections:1:Name = 'RemoteSystem2'
PS> $env:AmsRouter:RemoteConnections:1:Address = '192.168.1.22'
PS> $env:AmsRouter:RemoteConnections:1:NetId = '192.168.1.22.1.1'
PS> $env:AmsRouter:Logging:LogLevel:Default = 'Information'
PS> dir env: | where Name -like AmsRouter* | format-table -AutoSize

Name                                  Value
----                                  -----
AmsRouter:Name                        MyLocalSystem
AmsRouter:NetId                       192.168.1.20.1.1
AmsRouter:TcpPort                     48898
AmsRouter:RemoteConnections:0:Name    RemoteSystem1
AmsRouter:RemoteConnections:0:Address RemoteSystem1
AmsRouter:RemoteConnections:0:NetId   192.168.1.21.1.1
AmsRouter:RemoteConnections:1:Name    RemoteSystem2
AmsRouter:RemoteConnections:1:Address 192.168.1.22
AmsRouter:RemoteConnections:1:NetId   192.168.1.22.1.1
AmsRouter:Logging:LogLevel:Default    Information

First Steps

Example of starting the TcpIpRouter from a simple Console application with logging.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

namespace TwinCAT.Ads.AdsRouterService
{
    class Program
    {
        public static void Main(string[] args)
        {
            CreateHostBuilder(args).Build().Run();
        }

        public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureServices((hostContext, services) =>
                {
                    services.AddHostedService<RouterWorker>();
                })
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                    // Uncomment to overwrite configuration
                    //config.Sources.Clear(); // Clear all default config sources 
                    //config.AddEnvironmentVariables("AmsRouter"); // Use Environment variables
                    //config.AddCommandLine(args); // Use Command Line
                    //config.AddJsonFile("appSettings.json"); // Use Appsettings
                    //config.AddStaticRoutesXmlConfiguration(); // Overriding settings with StaticRoutes.Xml 
                })
                .ConfigureLogging(logging =>
                {
                    // Uncomment to overwrite logging
                    //logging.ClearProviders();
                    //logging.AddConsole();
                })
            ;
    }
}

Version History

5.0.0-preview4

Breaking Change: IAmsRouter.IsStarted replaced by IAmsRouter.RouterState and IAmsRouter.RouterStateChanged
Enh: Using .NET Core Configuration and Logging providers for AmsTcpIpRouter class.
Enh: Support of AppSettings.json for static routes and Router configuration
Enh: Support of EnvironmentConfigurationProvider for Router configuration by Environment variables
Enh: Implementation of StaticRoutesXmlConfigurationProvider for application configuration by 'classic' StaticRoutes.xml

Description

The package 'Beckhoff.TwinCAT.Ads.TcpRouter' implements a lean TCP ADS Router class to use on systems where no standard TwinCAT router is established or available.

It is running in UserMode only (no realtime characteristics) and contains no further functionality than distributing the ADS Frames (e.g. no Port 10000, no ADS Secure). It is just used to route ADS frames locally between AdsServers
and to/from remote ADS devices.

Implemented in asynchronous .NET Code it can be run in your own services/daemon, as standalone console application and also in your customized application.

Requirements

  • .NET Core 2.0, .NET Framework 4.61 or .NET Standard 2.0 compatible SDK or later
  • No other System allocating the same port (e.g. a regular TwinCAT installation)
  • Installed Nuget package manager or Dotnet CLI

Installation

Along with the deployment of the application where the TcpRouter is implemented, a valid Router / ADS configuration must be placed to specify
the Local Net ID, the name and the default port of the Router system.

The preferred way to configure the systesm is with standard Configuration providers, which are part of the
.NET Core / ASP .NET Core infrastructure.

See further information:
https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-3.1

This enables common options for application configuration that can be used 'out-of-the-box':

  • Via the file appsettings.json
  • With the StaticRoutesConfigurationProvider (StaticRoutes.xml)
  • Using Environment Variables.
  • Command line arguments
  • etc.

The configuration has to be loaded during application startup and is placed into the 'TwinCAT.Ads.TcpRouter.AmsTcpIpRouter' class via constructor dependency injection and
must contain the following information:

  • The name of the local System (usually the Computer or Hostname)
  • The Local AmsNetId of the local system as Unique Address in the network
  • Optionally the used TcpPort (48898 or 0xBF02 by default)
  • The static routes in the 'RemoteConnections' list.
  • Logging configuration.

Actually the configuration is not reloaded during the runtime of the 'TwinCAT.Ads.TcpRouter.AmsTcpIpRouter' class.
Please be aware that the "Backroute" from the Remote system linking to the local system (via AmsNetId) is necessary also to get functional routes.

Example for a valid 'appSettings.json' file (please change the Addresses for your network/systems.)

{
  "AmsRouter": {
    "Name": "MyLocalSystem",
    "NetId": "192.168.1.20.1.1",
    "TcpPort": 48898,
    "RemoteConnections": [
      {
        "Name": "RemoteSystem1",
        "Address": "RemoteSystem1",
        "NetId": "192.168.1.21.1.1",
        "Type": "TCP_IP"
      },
      {
        "Name": "RemoteSystem2",
        "Address": "192.168.1.22",
        "NetId": "192.168.1.22.1.1",
        "Type": "TCP_IP"
      },
    ]
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "System": "Information",
      "Microsoft": "Information"
    },
    "Console": {
      "IncludeScopes": true
    }
  }
}

Alternatively a "StaticRoutes.Xml" Xml File can configure the system equally. Don't forget to add the 'StaticRoutesXmlConfigurationProvider' to the Host configuration
during startup (see FirstSteps below).

An example of the local "StaticRoutes.xml" is given here:

<?xml version="1.0" encoding="utf-8"?>
<TcConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="C:\TwinCAT3\Config\TcConfig.xsd">
  <Local>
      <Name>MyLocalSystem</Name>
      <NetId>192.168.1.20.1.1</NetId> <!-- Local NetId -->
      <TcpPort>48898</TcpPort> <!-- Default TcpPort -->
  </Local>
  <RemoteConnections>
    <Route>
      <Name>RemoteSystem1</Name>
      <Address>RemoteSytem</Address> <!-- HostName -->
      <!--<Address>192.168.1.21</Address>  --> <!--IPAddress -->
      <NetId>192.168.1.21.1.1</NetId>
      <Type>TCP_IP</Type>
    </Route>
    <Route>
      <Name>RemoteSystem2</Name>
      <Address>192.168.1.22</Address> <!-- IPAddress -->
      <!--<Address>RemoteSystem2</Address>  --> <!--HostName -->
      <NetId>192.168.1.21.1.1</NetId>
      <Type>TCP_IP</Type>
    </Route>
  </RemoteConnections>
</TcConfig>

Alternatively, the configuration can also be set via Environment variables.

PS> $env:AmsRouter:Name = 'MyLocalSystem'
PS> $env:AmsRouter:NetId = '192.168.1.20.1.1'
PS> $env:AmsRouter:TcpPort = 48898
PS> $env:AmsRouter:RemoteConnections:0:Name = 'RemoteSystem1'
PS> $env:AmsRouter:RemoteConnections:0:Address = 'RemoteSystem1'
PS> $env:AmsRouter:RemoteConnections:0:NetId = '192.168.1.21.1.1'
PS> $env:AmsRouter:RemoteConnections:1:Name = 'RemoteSystem2'
PS> $env:AmsRouter:RemoteConnections:1:Address = '192.168.1.22'
PS> $env:AmsRouter:RemoteConnections:1:NetId = '192.168.1.22.1.1'
PS> $env:AmsRouter:Logging:LogLevel:Default = 'Information'
PS> dir env: | where Name -like AmsRouter* | format-table -AutoSize

Name                                  Value
----                                  -----
AmsRouter:Name                        MyLocalSystem
AmsRouter:NetId                       192.168.1.20.1.1
AmsRouter:TcpPort                     48898
AmsRouter:RemoteConnections:0:Name    RemoteSystem1
AmsRouter:RemoteConnections:0:Address RemoteSystem1
AmsRouter:RemoteConnections:0:NetId   192.168.1.21.1.1
AmsRouter:RemoteConnections:1:Name    RemoteSystem2
AmsRouter:RemoteConnections:1:Address 192.168.1.22
AmsRouter:RemoteConnections:1:NetId   192.168.1.22.1.1
AmsRouter:Logging:LogLevel:Default    Information

First Steps

Example of starting the TcpIpRouter from a simple Console application with logging.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

namespace TwinCAT.Ads.AdsRouterService
{
    class Program
    {
        public static void Main(string[] args)
        {
            CreateHostBuilder(args).Build().Run();
        }

        public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureServices((hostContext, services) =>
                {
                    services.AddHostedService<RouterWorker>();
                })
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                    // Uncomment to overwrite configuration
                    //config.Sources.Clear(); // Clear all default config sources 
                    //config.AddEnvironmentVariables("AmsRouter"); // Use Environment variables
                    //config.AddCommandLine(args); // Use Command Line
                    //config.AddJsonFile("appSettings.json"); // Use Appsettings
                    //config.AddStaticRoutesXmlConfiguration(); // Overriding settings with StaticRoutes.Xml 
                })
                .ConfigureLogging(logging =>
                {
                    // Uncomment to overwrite logging
                    //logging.ClearProviders();
                    //logging.AddConsole();
                })
            ;
    }
}

Version History

5.0.0-preview4

Breaking Change: IAmsRouter.IsStarted replaced by IAmsRouter.RouterState and IAmsRouter.RouterStateChanged
Enh: Using .NET Core Configuration and Logging providers for AmsTcpIpRouter class.
Enh: Support of AppSettings.json for static routes and Router configuration
Enh: Support of EnvironmentConfigurationProvider for Router configuration by Environment variables
Enh: Implementation of StaticRoutesXmlConfigurationProvider for application configuration by 'classic' StaticRoutes.xml

Release Notes

Preview version of the Beckhoff.TwinCAT.Ads 5.0.0 Version branch. Don't use for productive code.

This package is not used by any popular GitHub repositories.

Version History

Version Downloads Last updated
5.0.0-preview6 17 3/23/2020
5.0.0-preview5 46 3/6/2020
5.0.0-preview4 380 12/12/2019