From aaafcfd77e1eaa99a8449754466b3b1c901f3eb7 Mon Sep 17 00:00:00 2001 From: timyhac Date: Fri, 12 Jul 2024 13:04:08 +1000 Subject: [PATCH] Add additoinal information from libplctag Wiki into XML docs (#401) Signed-off-by: timyhac --- src/libplctag/Tag.cs | 229 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 193 insertions(+), 36 deletions(-) diff --git a/src/libplctag/Tag.cs b/src/libplctag/Tag.cs index cd257db..088bf89 100644 --- a/src/libplctag/Tag.cs +++ b/src/libplctag/Tag.cs @@ -1,4 +1,4 @@ -// Copyright (c) libplctag.NET contributors +// Copyright (c) libplctag.NET contributors // https://github.com/libplctag/libplctag.NET // // This Source Code Form is subject to the terms of the Mozilla Public @@ -37,7 +37,8 @@ public Tag() /// - /// Optional An integer number of elements per tag . + /// [OPTIONAL] + /// An integer number of elements per tag. /// /// /// @@ -54,7 +55,8 @@ public int? ElementCount /// - /// Optional An integer number of bytes per element + /// [REQUIRED/OPTIONAL] + /// An integer number of bytes per element /// /// /// @@ -69,9 +71,21 @@ public int? ElementSize /// - /// This tells the library what host name or IP address to use for the PLC - /// or the gateway to the PLC (in the case that the PLC is remote). + /// [REQUIRED] + /// IP address or host name /// + /// + /// + /// + /// This tells the library what host name or IP address to use for the PLC or the gateway to the PLC (in the case that the PLC is remote). + /// + /// + /// [AB-SPECIFIC] + /// Only for PLCs with additional routing. + /// This attribute is required for CompactLogix/ControlLogix tags and for tags using a DH+ protocol bridge (i.e. a DHRIO module) to get to a PLC/5, SLC 500, or MicroLogix PLC on a remote DH+ link. The attribute is ignored if it is not a DH+ bridge route, but will generate a warning if debugging is active. + /// Note that Micro800 connections must not have a path attribute. + /// + /// public string Gateway { get => _tag.Gateway; @@ -80,9 +94,32 @@ public string Gateway /// - /// This is the full name of the tag. - /// For program tags, prepend `Program:{ProgramName}.` - /// where {ProgramName} is the name of the program in which the tag is created. + /// + /// + /// REQUIRED | AB-SPECIFIC + /// + /// The full name of the tag, e.g. `TestBigTag[10,42]` for CIP-based PLCs. + /// + /// For program tags, prepend `Program:{program name}.` where {program name} is the name of the program in which the tag is created. + /// Example: `Program:MyProgram.MyTag`. + /// This will access the tag MyTag in the program MyProgram. + /// For PCCC-based PLCs, examples include `N7:4`, `ST18:26`, `L20:2`, `B3:4/2`, `MG14:6.en` etc. + /// Many common field name abbeviations are supported. + /// + /// + /// + /// + /// REQUIRED | MODBUS-SPECIFIC + /// + /// The type and first register number of a tag, e.g. co42 for coil 42 (counts from zero). + /// + /// The supported register type prefixes are co for coil, di for discrete inputs, hr for holding registers and ir for input registers. + /// The type prefix must be present and the register number must be greater than or equal to zero and less than or equal to 65535. + /// Modbus examples: co21 - coil 21, di22 - discrete input 22, hr66 - holding register 66, ir64000 - input register 64000. + /// + /// + /// + /// /// public string Name { @@ -92,10 +129,29 @@ public string Name /// - /// This attribute is required for CompactLogix/ControlLogix tags - /// and for tags using a DH+ protocol bridge (i.e. a DHRIO module) to get to a PLC/5, SLC 500, or MicroLogix PLC on a remote DH+ link. - /// The attribute is ignored if it is not a DH+ bridge route, but will generate a warning if debugging is active. - /// Note that Micro800 connections must not have a path attribute. + /// + /// + /// OPTIONAL | AB-SPECIFIC + /// + /// Only for PLCs with additional routing. + /// + /// This attribute is required for CompactLogix/ControlLogix tags and for tags using a DH+ protocol bridge (i.e. a DHRIO module) to get to a PLC/5, SLC 500, or MicroLogix PLC on a remote DH+ link. + /// The attribute is ignored if it is not a DH+ bridge route, but will generate a warning if debugging is active. + /// Note that Micro800 connections must not have a path attribute. + /// + /// + /// + /// + /// OPTIONAL | MODBUS-SPECIFIC + /// + /// The server/unit ID. + /// Must be an integer value between 0 and 255. + /// + /// Servers may support more than one unit or may bridge to other units. Example: path=4 for accessing device unit ID 4. + /// + /// + /// + /// /// public string Path { @@ -104,7 +160,8 @@ public string Path } /// - /// The type of PLC + /// [REQUIRED | AB-SPECIFIC] + /// Determines the type of the PLC. /// public PlcType? PlcType { @@ -114,6 +171,7 @@ public PlcType? PlcType /// + /// [REQUIRED] /// Determines the type of the PLC Protocol. /// public Protocol? Protocol @@ -123,10 +181,14 @@ public Protocol? Protocol } /// - /// Optional. Use this attribute to cause the tag read operations to cache data the requested number of milliseconds. + /// [OPTIONAL] + /// Use this attribute to cause the tag read operations to cache data the requested number of milliseconds. + /// + /// + /// /// This can be used to lower the actual number of requests against the PLC. /// Example read_cache_ms=100 will result in read operations no more often than once every 100 milliseconds. - /// + /// public int? ReadCacheMillisecondDuration { get => _tag.ReadCacheMillisecondDuration; @@ -144,10 +206,17 @@ public TimeSpan Timeout } /// - /// Optional. Control whether to use connected or unconnected messaging. - /// Only valid on Logix-class PLCs. Connected messaging is required on Micro800 and DH+ bridged links. - /// Default is PLC-specific and link-type specific. Generally you do not need to set this. + /// [OPTIONAL | AB-SPECIFIC] + /// True = use CIP connection. + /// False = use UCMM. /// + /// + /// Control whether to use connected or unconnected messaging. + /// Only valid on Logix-class PLCs. + /// Connected messaging is required on Micro800 and DH+ bridged links. + /// Default is PLC-specific and link-type specific. + /// Generally you do not need to set this. + /// public bool? UseConnectedMessaging { get => _tag.UseConnectedMessaging; @@ -155,11 +224,15 @@ public bool? UseConnectedMessaging } /// - /// Optional. + /// [OPTIONAL | AB-SPECIFIC] + /// True = (default) allow use of multi-request CIP command. + /// False = use only one CIP request per packet. + /// + /// /// This is specific to individual PLC models. /// Generally only Control Logix-class PLCs support it. /// It is the default for those PLCs that support it as it greatly increases the performance of the communication channel to the PLC. - /// + /// public bool? AllowPacking { get => _tag.AllowPacking; @@ -167,7 +240,8 @@ public bool? AllowPacking } /// - /// Optional. An integer number of milliseconds to periodically read data from the PLC. + /// [OPTIONAL] + /// An integer number of milliseconds to periodically read data from the PLC. /// /// /// @@ -181,7 +255,8 @@ public TimeSpan? AutoSyncReadInterval } /// - /// Optional. An integer number of milliseconds to buffer tag data changes before writing to the PLC. + /// [OPTIONAL] + /// An integer number of milliseconds to buffer tag data changes before writing to the PLC. /// /// /// @@ -202,8 +277,14 @@ public DebugLevel DebugLevel } /// - /// Configures. the byte order of 16-bit integers. + /// [OPTIONAL] + /// A string indicating the byte order of 16-bit integers. /// + /// + /// + /// Allowable values include `01` (little-endian) and `10` (big-endian). + /// Defaults to `10` for Modbus and `01` for Allen-Bradley. + /// public string Int16ByteOrder { get => _tag.Int16ByteOrder; @@ -211,8 +292,13 @@ public string Int16ByteOrder } /// - /// Optional. Configures the byte order of 32-bit integers. + /// [OPTIONAL] + /// A string indicating the byte order of 32-bit integers. /// + /// + /// + /// Defaults to `3210`, strict big-endian, for Modbus and `0123` for Allen-Bradley PLCs. + /// public string Int32ByteOrder { get => _tag.Int32ByteOrder; @@ -220,8 +306,13 @@ public string Int32ByteOrder } /// - /// Optional. Configures the byte order of 64-bit integers. + /// [OPTIONAL] + /// A string indicating the byte order of 64-bit integers. /// + /// + /// + /// Defaults to `76543210`, strict big-endian, for Modbus and `01234567` for Allen-Bradley PLCs. + /// public string Int64ByteOrder { get => _tag.Int64ByteOrder; @@ -229,8 +320,13 @@ public string Int64ByteOrder } /// - /// Optional. Configures the byte order of 32-bit floating point values. + /// [OPTIONAL] + /// A string indicating the byte order of 32-bit floating point values. /// + /// + /// + /// Defaults to `3210`, strict big-endian, for Modbus. Allen-Bradley PLCs default to the PLC-native order. + /// public string Float32ByteOrder { get => _tag.Float32ByteOrder; @@ -238,8 +334,13 @@ public string Float32ByteOrder } /// - /// Optional. Configures the byte order of 64-bit floating point values. + /// [OPTIONAL] + /// A string indicating the byte order of 64-bit floating point values. /// + /// + /// + /// Defaults to `76543210`, strict big-endian, for Modbus and `01234567` for Allen-Bradley PLCs. + /// public string Float64ByteOrder { get => _tag.Float64ByteOrder; @@ -247,8 +348,16 @@ public string Float64ByteOrder } /// - /// Optional. A positive integer value of 1, 2, 4, or 8 determining how big the leading count word is in a string. + /// [OPTIONAL] + /// A positive integer value of 1, 2, 4, or 8 determining how big the leading count word is in a string. /// + /// + /// + /// Defaults are set per PLC type. + /// AB Logix PLCs default to 4. + /// AB PCCC PLCs default to 2. + /// Must be used with . + /// public uint? StringCountWordBytes { get => _tag.StringCountWordBytes; @@ -256,8 +365,14 @@ public uint? StringCountWordBytes } /// - /// Optional. Determines whether character bytes are swapped within 16-bit words. + /// [OPTIONAL] + /// Determines whether character bytes are swapped within 16-bit words. /// + /// + /// + /// Defaults are set per PLC type. + /// AB Logix PLCs default to false and PCCC PLCs default to true. + /// public bool? StringIsByteSwapped { get => _tag.StringIsByteSwapped; @@ -265,8 +380,15 @@ public bool? StringIsByteSwapped } /// - /// Optional. Determines whether strings have a count word or not. + /// [OPTIONAL] + /// Determines whether strings have a count word or not. /// + /// + /// + /// Defaults are set per PLC type. + /// AB PLCs default to true. + /// If set true, must be used with . + /// public bool? StringIsCounted { get => _tag.StringIsCounted; @@ -274,8 +396,15 @@ public bool? StringIsCounted } /// - /// Optional. Determines whether strings have a fixed length that they occupy. + /// [OPTIONAL] + /// Determines whether strings have a fixed length that they occupy. /// + /// + /// + /// Defaults are set per PLC and tag type. + /// AB defaults to true for ControlLogix and CompactLogix and 84 for PCCC-based PLCs. + /// Listing tags is an exception as the tag names are counted, but not fixed length. + /// public bool? StringIsFixedLength { get => _tag.StringIsFixedLength; @@ -283,8 +412,14 @@ public bool? StringIsFixedLength } /// - /// Optional. Determines whether strings are zero-terminated as is done in C. + /// [OPTIONAL] + /// Determines whether strings are zero-terminated as is done in C. /// + /// + /// + /// Defaults are set per PLC type. + /// AB defaults to false. + /// public bool? StringIsZeroTerminated { get => _tag.StringIsZeroTerminated; @@ -292,8 +427,14 @@ public bool? StringIsZeroTerminated } /// - /// Optional. Determines the maximum number of character bytes in a string. + /// [OPTIONAL] + /// Determines the maximum number of character bytes in a string. /// + /// + /// + /// Defaults are set per PLC type. + /// AB Logix and PCCC PLCs default to 82. + /// public uint? StringMaxCapacity { get => _tag.StringMaxCapacity; @@ -301,8 +442,15 @@ public uint? StringMaxCapacity } /// - /// Optional. A positive integer value determining the total number of padding bytes at the end of a string. + /// [OPTIONAL] + /// A positive integer value determining the total number of padding bytes at the end of a string. /// + /// + /// + /// Defaults are set per PLC type. + /// AB Logix PLCs default to 2. + /// AB PCCC PLCs default to 0. + /// public uint? StringPadBytes { get => _tag.StringPadBytes; @@ -310,8 +458,16 @@ public uint? StringPadBytes } /// - /// Optional. A positive integer value determining the total number of bytes used in the tag buffer by a string. Must be used with str_is_fixed_length. + /// [OPTIONAL] + /// A positive integer value determining the total number of bytes used in the tag buffer by a string. + /// Must be used with . /// + /// + /// + /// Defaults are set per PLC type. + /// AB Logix PLCs default to 88. + /// AB PCCC PLCs default to 84. + /// public uint? StringTotalLength { get => _tag.StringTotalLength; @@ -319,7 +475,8 @@ public uint? StringTotalLength } /// - /// Optional. The Modbus specification allows devices to queue up to 16 requests at once. + /// [OPTIONAL | MODBUS-SPECIFIC] + /// The Modbus specification allows devices to queue up to 16 requests at once. /// /// ///