Skip to content

AdsSimplifiedInterface

Jump to bottom
DanielBThayer edited this page Dec 31, 2024 · 1 revision

Constructors

AdsInterface(IConfiguration config, ILogger logger)

This constructor is mostly used for dependency injection. Inside the appsettings.json file, or other configuration method supported by IConfiguration, will be properties defining the ADS connection information.

{
  "ADS": {
    "NetId": "199.4.42.250.1.1",
    "Port": 851,
    "ScanRateMultiple":  10
  }
}

This is like calling the constructor below with the following mapping:

  • AmsNetId = ADS.NetId
  • Port = ADS.Port
  • scanFrequency = ADS.ScanRateMultiple

AdsInterface(string AmsNetId, int Port, ILogger logger, int scanFrequency)

This constructor is used when dependency injection is not needed and/or the ADS connection information is gotten from outside an IConfiguration compatible means (e.g. hard coded).

AmsNetId

This is the AMS network identification. Normally this is a 6 byte address represents like how IP addresses are represented. The default for TwinCAT is the main Windows IP plus ".1.1" added to the end.

Port

This is the port on the AMS network where the PLC is located. For the first PLC in a TwinCAT 3 runtime, this is 851. For the second, it is 852. For the third, it is 853. And so on.

Logger

This is the log system, which implements the Microsoft.Extensions.Logging.ILogger interface.

scanFrequency

This is used to determine the base frequency that all notifications are based on. It is recommended to be the highest common denominator of all the notifications. This is what allows monitoring the same variable with different function calls on different frequencies (e.g. VarA is monitored for FuncA at 100 ms and FuncB at 1 sec).

Read Functions

bool TryGetValue(string InstancePath, out object? value)

This will call the GetValue method with the InstancePath, placing the results of the call in value and returning if an exception happened or not.

bool TryGetValue(string InstancePath, out T? value)

This will call the GetValue method with the InstancePath, placing the results of the call in value and returning if an exception happened or not.

object? GetValue(string InstancePath)

Gets the data type of the variable at InstancePath and then invokes the typed version of the method.

T GetValue(string InstancePath)

This will attempt to get the variable's value at the InstancePath location in the PLC. It will return the marshalled data type specified as T.

Exceptions

ArgumentNullException

The InstancePath was an empty string or the PLC returned an empty array for the data.

InvalidOperationException

The InstancePath is not a valid value type, casting to a C# type failed, or the PLC is not connected.

KeyNotFoundException

The InstancePath is not a valid variable in the PLC.

InvalidCastException

The array has an unknown type of element.

ArgumentException

The data type of T and the size of the data do not match.

Write Functions

bool TrySetValue(string InstancePath, object value)

This will call the SetValue method with the InstancePath and value, returning if an exception happened or not.

bool TrySetValue(string InstancePath, T value)

This will call the SetValue method with the InstancePath and value, returning if an exception happened or not.

SetValue(string InstancePath, object value)

Gets the data type of the variable at InstancePath and then invokes the typed version of the method.

SetValue(string InstancePath, T value)

This will attempt to set the variable's value at the InstancePath location in the PLC.

Exceptions

ArgumentNullException

The InstancePath was an empty string or the PLC returned an empty array for the data.

ReadOnlyException

The InstancePath points to the PLC variable marked as Read Only.

InvalidOperationException

The InstancePath is not a valid value type, or the PLC is not connected.

KeyNotFoundException

The InstancePath is not a valid variable in the PLC.

Notifications

RemoveAllNotifications(string InstancePath)

This removes all notifications for the variable at InstancePath

AddNotification(string InstancePath, Action<string, byte[], byte[]> Callback, long UpdateRate)

This will add a notification to the PLC variable at InstancePath. The variable will be checked for changes every UpdateRate. When a change is detected, the Callback will be called with the InstancePath, the raw byte data of the old value, and the raw byte data of the new value (in that order).

Exceptions

ArgumentNullException

The InstancePath was an empty string or the PLC returned an empty array for the data.

ReadOnlyException

The InstancePath points to the PLC variable marked as Read Only.

InvalidOperationException

The InstancePath is not a valid value type, or the PLC is not connected.

KeyNotFoundException

The InstancePath is not a valid variable in the PLC.

AddNotification(string InstancePath, Action<string, T, T> Callback, long UpdateRate)

This will add a notification to the PLC variable at InstancePath. The variable will be checked for changes every UpdateRate. When a change is detected, the Callback will be called with the InstancePath, the marshalled value of the old value, and marshalled value of the new value (in that order).

Exceptions

ArgumentNullException

The InstancePath was an empty string or the PLC returned an empty array for the data.

ReadOnlyException

The InstancePath points to the PLC variable marked as Read Only.

InvalidOperationException

The InstancePath is not a valid value type, or the PLC is not connected.

KeyNotFoundException

The InstancePath is not a valid variable in the PLC.

Data Type Generation

Type GetDataType(string InstancePath)

Generates the C# type which can be used to directly read/write the variable at the InstancePath location.

Exceptions

KeyNotFoundException

The InstancePath is not a valid variable in the PLC.

InvalidOperationException

The data type of the variable (or the base type of a member of the data type) is not known, an enumeration underlying type is too large for TwinCAT, or a member of a union was marked as read only

NotImplementedException

A primitive type, which is not known yet, was attempted to be generated, or a string was inside a Union.

List GetDataTypes()

Generates the C# types, which can be used to directly read/write the variable at the InstancePath location, for all the types in the PLC.

Exceptions

KeyNotFoundException

The InstancePath is not a valid variable in the PLC.

InvalidOperationException

The data type of the variable (or the base type of a member of the data type) is not known, an enumeration underlying type is too large for TwinCAT, or a member of a union was marked as read only

NotImplementedException

A primitive type, which is not known yet, was attempted to be generated, or a string was inside a Union.

Variable Search

bool VariableExists(string InstancePath)

Checks if a PLC variable is at the InstancePath location

List GetVariables(string startingPoint, bool PersistentOnly)

Gets a list of the PLC variables starting at the startingPoint, if defined.

startingPoint

The parent to get all the children of.

PersistentOnly

This flag will cause the list to only include variables stored in the PLC's persistent memory location.

List GetVariableInfos(string VariableName)

Gets the list of PLC variable type information for all the variables in the PLC or just the one specified by VariableName.

Clone this wiki locally