Skip to content

KV Host Link .NET API Reference

This page is generated from the PlcComm.KvHostLink assembly public API and XML documentation comments.

Run python scripts/generate_api_reference.py --help from the repository root to regenerate it.

HostLinkConnectionError

public class HostLinkConnectionError

Thrown when a connection error occurs.

Members

HostLinkConnectionError
public HostLinkConnectionError(string message)
HostLinkConnectionError
public HostLinkConnectionError(string message, Exception inner)

HostLinkError

public class HostLinkError

Base exception for Host Link communication.

Members

HostLinkError
public HostLinkError(string message)
HostLinkError
public HostLinkError(string message, Exception inner)
HostLinkError
public HostLinkError(string message, string code, string response)
Code
public string Code { get; }
Response
public string Response { get; }

HostLinkProtocolError

public class HostLinkProtocolError

Thrown when there is an error in the protocol or unexpected response.

Members

HostLinkProtocolError
public HostLinkProtocolError(string message)
HostLinkProtocolError
public HostLinkProtocolError(string message, Exception inner)

HostLinkTraceDirection

public enum HostLinkTraceDirection

Direction of a traced frame.

Members

Send
public const HostLinkTraceDirection Send
Receive
public const HostLinkTraceDirection Receive

HostLinkTraceFrame

public class HostLinkTraceFrame

A raw frame captured by TraceHook.

Members

HostLinkTraceFrame
public HostLinkTraceFrame(HostLinkTraceDirection Direction, byte[] Data, DateTime Timestamp)

A raw frame captured by TraceHook.

Direction
public HostLinkTraceDirection Direction { get; set; }
Data
public byte[] Data { get; set; }
Timestamp
public DateTime Timestamp { get; set; }

HostLinkTransportMode

public enum HostLinkTransportMode

Transport protocol for Host Link communication.

Members

Tcp
public const HostLinkTransportMode Tcp
Udp
public const HostLinkTransportMode Udp

KvDeviceAddress

public class KvDeviceAddress

Members

KvDeviceAddress
public KvDeviceAddress(string DeviceType, int Number, string Suffix = "")
ToText
public string ToText()
DeviceType
public string DeviceType { get; set; }
Number
public int Number { get; set; }
Suffix
public string Suffix { get; set; }

KvDeviceRangeCatalog

public sealed class KvDeviceRangeCatalog

Members

KvDeviceRangeCatalog
public KvDeviceRangeCatalog(string PlcProfile, string ModelCode, bool HasModelCode, string RequestedPlcProfile, string ResolvedPlcProfile, IReadOnlyList<KvDeviceRangeEntry> Entries)
Entry
public KvDeviceRangeEntry Entry(string deviceType)
PlcProfile
public string PlcProfile { get; set; }
ModelCode
public string ModelCode { get; set; }
HasModelCode
public bool HasModelCode { get; set; }
RequestedPlcProfile
public string RequestedPlcProfile { get; set; }
ResolvedPlcProfile
public string ResolvedPlcProfile { get; set; }
Entries
public IReadOnlyList<KvDeviceRangeEntry> Entries { get; set; }

KvDeviceRangeCategory

public enum KvDeviceRangeCategory

Members

Bit
public const KvDeviceRangeCategory Bit
Word
public const KvDeviceRangeCategory Word
TimerCounter
public const KvDeviceRangeCategory TimerCounter
Index
public const KvDeviceRangeCategory Index
FileRegister
public const KvDeviceRangeCategory FileRegister

KvDeviceRangeEntry

public sealed class KvDeviceRangeEntry

Members

KvDeviceRangeEntry
public KvDeviceRangeEntry(string Device, string DeviceType, KvDeviceRangeCategory Category, bool IsBitDevice, KvDeviceRangeNotation Notation, bool Supported, uint LowerBound, uint? UpperBound, uint? PointCount, string AddressRange, string Source, string Notes, IReadOnlyList<KvDeviceRangeSegment> Segments)
Device
public string Device { get; set; }
DeviceType
public string DeviceType { get; set; }
Category
public KvDeviceRangeCategory Category { get; set; }
IsBitDevice
public bool IsBitDevice { get; set; }
Notation
public KvDeviceRangeNotation Notation { get; set; }
Supported
public bool Supported { get; set; }
LowerBound
public uint LowerBound { get; set; }
UpperBound
public uint? UpperBound { get; set; }
PointCount
public uint? PointCount { get; set; }
AddressRange
public string AddressRange { get; set; }
Source
public string Source { get; set; }
Notes
public string Notes { get; set; }
Segments
public IReadOnlyList<KvDeviceRangeSegment> Segments { get; set; }

KvDeviceRangeNotation

public enum KvDeviceRangeNotation

Members

Decimal
public const KvDeviceRangeNotation Decimal
Hexadecimal
public const KvDeviceRangeNotation Hexadecimal

KvDeviceRangeSegment

public sealed class KvDeviceRangeSegment

Members

KvDeviceRangeSegment
public KvDeviceRangeSegment(string Device, KvDeviceRangeCategory Category, bool IsBitDevice, KvDeviceRangeNotation Notation, uint LowerBound, uint? UpperBound, uint? PointCount, string AddressRange)
Device
public string Device { get; set; }
Category
public KvDeviceRangeCategory Category { get; set; }
IsBitDevice
public bool IsBitDevice { get; set; }
Notation
public KvDeviceRangeNotation Notation { get; set; }
LowerBound
public uint LowerBound { get; set; }
UpperBound
public uint? UpperBound { get; set; }
PointCount
public uint? PointCount { get; set; }
AddressRange
public string AddressRange { get; set; }

KvHostLinkAddress

public static class KvHostLinkAddress

Public address helpers for Host Link device strings and logical helper addresses.

Remarks: These helpers separate base device parsing from logical high-level helper parsing so generated docs can explain exactly when a string refers to a raw PLC device versus a typed logical view.

Members

Parse
public static KvDeviceAddress Parse(string text)

Parses a base device address.

Returns: The parsed base device address.

Parameters: - text: Base device text such as DM100 or MR0A.

TryParse
public static bool TryParse(string text, out KvDeviceAddress address)

Attempts to parse a base device address.

Returns: true when parsing succeeds; otherwise false.

Parameters: - text: Base device text to parse. - address: When this method returns true, receives the parsed base address.

Format
public static string Format(KvDeviceAddress address)

Formats a base device address to canonical text.

Returns: Canonical uppercase Host Link device text.

Parameters: - address: The parsed base address.

Normalize
public static string Normalize(string text)

Normalizes either a base device address or a logical helper address.

Returns: The canonical uppercase helper text.

Parameters: - text: Input text in either base-device or logical-helper form.

ParseLogical
public static KvLogicalAddress ParseLogical(string text)

Parses a logical helper address such as DM100:U, DM100:F, R100:BIT, DM100:COMMENT, or DM100.A.

Returns: The normalized logical address.

Parameters: - text: Logical helper text to parse.

TryParseLogical
public static bool TryParseLogical(string text, out KvLogicalAddress address)

Attempts to parse a logical helper address.

Returns: true when parsing succeeds; otherwise false.

Parameters: - text: Logical helper text to parse. - address: When this method returns true, receives the normalized logical address.

NormalizeLogical
public static string NormalizeLogical(string text)

Normalizes a logical helper address to canonical text.

Returns: Canonical helper text returned by ToText.

Parameters: - text: Logical helper text in any supported spelling.

KvHostLinkClient

public sealed class KvHostLinkClient

A low-level Host Link (Upper Link) client for KEYENCE KV series PLCs.

Remarks: This class serializes individual raw requests on one connection, but compound helper workflows such as typed polling and read-modify-write are better served by QueuedKvHostLinkClient. For application code, prefer CancellationToken).

Members

KvHostLinkClient
public KvHostLinkClient(string host, string plcProfile, int port = 8501, HostLinkTransportMode transportMode = Tcp)
OpenAsync
public Task OpenAsync(CancellationToken cancellationToken = default)
Open
public void Open()
Close
public void Close()
CloseAsync
public Task CloseAsync()
Dispose
public void Dispose()
DisposeAsync
public ValueTask DisposeAsync()
SendRawAsync
public Task<string> SendRawAsync(string body, CancellationToken cancellationToken = default)
ChangeModeAsync
public Task ChangeModeAsync(KvPlcMode mode, CancellationToken cancellationToken = default)
ClearErrorAsync
public Task ClearErrorAsync(CancellationToken cancellationToken = default)
CheckErrorNoAsync
public Task<string> CheckErrorNoAsync(CancellationToken cancellationToken = default)
QueryModelAsync
public Task<KvModelInfo> QueryModelAsync(CancellationToken cancellationToken = default)
ConfirmOperatingModeAsync
public Task<KvPlcMode> ConfirmOperatingModeAsync(CancellationToken cancellationToken = default)
SetTimeAsync
public Task SetTimeAsync(DateTime? value = null, CancellationToken cancellationToken = default)
ForcedSetAsync
public Task ForcedSetAsync(string device, CancellationToken cancellationToken = default)
ForcedResetAsync
public Task ForcedResetAsync(string device, CancellationToken cancellationToken = default)
ReadAsync
public Task<string[]> ReadAsync(string device, string dataFormat = null, CancellationToken cancellationToken = default)
ReadConsecutiveAsync
public Task<string[]> ReadConsecutiveAsync(string device, int count, string dataFormat = null, CancellationToken cancellationToken = default)
WriteAsync
public Task WriteAsync<T>(string device, T value, string dataFormat = null, CancellationToken cancellationToken = default)
WriteConsecutiveAsync
public Task WriteConsecutiveAsync<T>(string device, IEnumerable<T> values, string dataFormat = null, CancellationToken cancellationToken = default)
RegisterMonitorBitsAsync
public Task RegisterMonitorBitsAsync(IEnumerable<string> devices, CancellationToken cancellationToken = default)
RegisterMonitorWordsAsync
public Task RegisterMonitorWordsAsync(IEnumerable<string> devices, CancellationToken cancellationToken = default)
ReadMonitorBitsAsync
public Task<string[]> ReadMonitorBitsAsync(CancellationToken cancellationToken = default)
ReadMonitorWordsAsync
public Task<string[]> ReadMonitorWordsAsync(CancellationToken cancellationToken = default)
ForcedSetConsecutiveAsync
public Task ForcedSetConsecutiveAsync(string device, int count, CancellationToken cancellationToken = default)

Consecutively force-sets up to 16 bit devices starting at device (STS command).

ForcedResetConsecutiveAsync
public Task ForcedResetConsecutiveAsync(string device, int count, CancellationToken cancellationToken = default)

Consecutively force-resets up to 16 bit devices starting at device (RSS command).

ReadConsecutiveLegacyAsync
public Task<string[]> ReadConsecutiveLegacyAsync(string device, int count, string dataFormat = null, CancellationToken cancellationToken = default)

Reads consecutive devices using the legacy RDE command. Prefer CancellationToken) on current models.

WriteConsecutiveLegacyAsync
public Task WriteConsecutiveLegacyAsync<T>(string device, IEnumerable<T> values, string dataFormat = null, CancellationToken cancellationToken = default)

Writes consecutive devices using the legacy WRE command. Prefer CancellationToken) on current models.

WriteSetValueAsync
public Task WriteSetValueAsync<T>(string device, T value, string dataFormat = null, CancellationToken cancellationToken = default)

Writes a set-value (preset) for a timer or counter device (WS command). Supported device types: T, C.

WriteSetValueConsecutiveAsync
public Task WriteSetValueConsecutiveAsync<T>(string device, IEnumerable<T> values, string dataFormat = null, CancellationToken cancellationToken = default)

Writes set-values (presets) for consecutive timer or counter devices (WSS command). Supported device types: T, C.

SwitchBankAsync
public Task SwitchBankAsync(int bankNo, CancellationToken cancellationToken = default)

Switches the active data bank (BE command). Valid range: 0–15.

ReadExpansionUnitBufferAsync
public Task<string[]> ReadExpansionUnitBufferAsync(int unitNo, int address, int count, string dataFormat = "", CancellationToken cancellationToken = default)

Reads buffer memory from an expansion unit (URD command).

Parameters: - unitNo: Unit number (0–48). - address: Buffer address (0–59999). - count: Number of values to read. - dataFormat: Data format suffix, e.g. ".U" or ".S". Defaults to ".U". - cancellationToken: Cancellation token.

WriteExpansionUnitBufferAsync
public Task WriteExpansionUnitBufferAsync<T>(int unitNo, int address, IEnumerable<T> values, string dataFormat = "", CancellationToken cancellationToken = default)

Writes buffer memory to an expansion unit (UWR command).

Parameters: - unitNo: Unit number (0–48). - address: Buffer address (0–59999). - values: Values to write. - dataFormat: Data format suffix, e.g. ".U" or ".S". Defaults to ".U". - cancellationToken: Cancellation token.

ReadCommentsAsync
public Task<string> ReadCommentsAsync(string device, bool stripPadding = true, CancellationToken cancellationToken = default)
PlcProfile
public string PlcProfile { get; }
Timeout
public TimeSpan Timeout { get; set; }
AppendLfOnSend
public bool AppendLfOnSend { get; set; }
TraceHook
public Action<HostLinkTraceFrame> TraceHook { get; set; }

Optional hook called for every raw frame sent and received. Useful for protocol tracing and debugging.

IsOpen
public bool IsOpen { get; }

KvHostLinkClientExtensions

public static class KvHostLinkClientExtensions

High-level helper API for KvHostLinkClient and QueuedKvHostLinkClient.

Remarks: These extension methods are the recommended user-facing surface for normal application code. They wrap the token-oriented low-level client API with typed reads and writes, bit-in-word helpers, named snapshots, polling, and one-step connection setup. Overloads for QueuedKvHostLinkClient keep compound helper operations exclusive when a shared connection is used.

Members

ReadTypedAsync
public static Task<object> ReadTypedAsync(KvHostLinkClient client, string device, string dtype, CancellationToken ct = default)

Reads a single device value and converts it to a high-level CLR type.

Remarks: The float helper is implemented at the extension layer by reading two consecutive .U words and combining them as low-word, high-word.

Returns: A boxed CLR value. Integer formats return boxed integral types and "F" returns a boxed Single, and "H" returns a String.

Parameters: - client: The client to use. - device: Base device address string, for example "DM100". - dtype: High-level data type code: "U" = UInt16, "S" = Int16, "D" = UInt32, "L" = signed 32-bit Int32, "F" = IEEE 754 float32, "H" = hexadecimal 16-bit word text. - ct: Cancellation token.

ReadTypedAsync
public static Task<object> ReadTypedAsync(QueuedKvHostLinkClient client, string device, string dtype, CancellationToken ct = default)

Reads a single device value and converts it to a high-level CLR type.

ReadTimerCounterAsync
public static Task<KvTimerCounterValue> ReadTimerCounterAsync(KvHostLinkClient client, string device, CancellationToken ct = default)

Reads a timer/counter composite value as status, current, and preset.

ReadTimerCounterAsync
public static Task<KvTimerCounterValue> ReadTimerCounterAsync(QueuedKvHostLinkClient client, string device, CancellationToken ct = default)

Reads a timer/counter composite value as status, current, and preset.

ReadTimerAsync
public static Task<KvTimerCounterValue> ReadTimerAsync(KvHostLinkClient client, string device, CancellationToken ct = default)

Reads a timer composite value.

ReadTimerAsync
public static Task<KvTimerCounterValue> ReadTimerAsync(QueuedKvHostLinkClient client, string device, CancellationToken ct = default)

Reads a timer composite value.

ReadCounterAsync
public static Task<KvTimerCounterValue> ReadCounterAsync(KvHostLinkClient client, string device, CancellationToken ct = default)

Reads a counter composite value.

ReadCounterAsync
public static Task<KvTimerCounterValue> ReadCounterAsync(QueuedKvHostLinkClient client, string device, CancellationToken ct = default)

Reads a counter composite value.

ReadCommentsAsync
public static Task<string> ReadCommentsAsync(QueuedKvHostLinkClient client, string device, bool stripPadding = true, CancellationToken ct = default)

Reads the configured PLC comment text for one device through the queued helper surface.

Returns: The PLC comment text for device.

Parameters: - client: The queued client to use. - device: Base device address such as "DM100". - stripPadding: Whether to trim the Host Link fixed-width trailing spaces. - ct: Cancellation token.

WriteTypedAsync
public static Task WriteTypedAsync<T>(KvHostLinkClient client, string device, string dtype, T value, CancellationToken ct = default)

Writes a single device value using a high-level data type code.

Remarks: The float helper is implemented at the extension layer by converting the input value to IEEE 754 float32 and writing two consecutive .U words.

Parameters: - client: The client to use. - device: Base device address string, for example "DM100". - dtype: High-level data type code: "U", "S", "D", "L", "F", or "H". - value: Value to write. - ct: Cancellation token.

WriteTypedAsync
public static Task WriteTypedAsync(KvHostLinkClient client, string device, string dtype, string value, CancellationToken ct = default)

Writes a hexadecimal word text value using the high-level "H" data type code.

WriteTypedAsync
public static Task WriteTypedAsync<T>(QueuedKvHostLinkClient client, string device, string dtype, T value, CancellationToken ct = default)

Writes a single device value using a high-level data type code.

Remarks: The float helper is implemented at the extension layer by converting the input value to IEEE 754 float32 and writing two consecutive .U words.

Parameters: - client: The client to use. - device: Base device address string, for example "DM100". - dtype: High-level data type code: "U", "S", "D", "L", "F", or "H". - value: Value to write. - ct: Cancellation token.

WriteTypedAsync
public static Task WriteTypedAsync(QueuedKvHostLinkClient client, string device, string dtype, string value, CancellationToken ct = default)

Writes a hexadecimal word text value using the high-level "H" data type code.

WriteBitInWordAsync
public static Task WriteBitInWordAsync(KvHostLinkClient client, string device, int bitIndex, bool value, CancellationToken ct = default)

Performs a read-modify-write to set or clear a single bit inside a word device.

Remarks: This helper operates on word-oriented devices such as DM. It is distinct from PLC force-set / force-reset commands for bit device families.

Parameters: - client: The client to use. - device: Base word device address string, for example "DM100". - bitIndex: Bit position within the word (0–15). - value: New bit value. - ct: Cancellation token.

WriteBitInWordAsync
public static Task WriteBitInWordAsync(QueuedKvHostLinkClient client, string device, int bitIndex, bool value, CancellationToken ct = default)

Performs a read-modify-write to set or clear a single bit inside a word device.

ReadNamedAsync
public static Task<IReadOnlyDictionary<string, object>> ReadNamedAsync(KvHostLinkClient client, IEnumerable<string> addresses, CancellationToken ct = default)

Reads multiple named values and returns a snapshot dictionary.

Remarks: Address format examples: "DM100:U" -- unsigned 16-bit (ushort) "DM100:F" -- float "DM100:S" -- signed 16-bit (short) "DM100:D" -- unsigned 32-bit "DM100:L" -- signed 32-bit "DM100.3" -- bit 3 within word (bool) "DM100.A" -- bit 10 within word (bool); bits 10-15 use hex digits A-F "DM100:COMMENT" -- PLC device comment text (string) Bit-in-word indices use hexadecimal notation (0-F), matching the KEYENCE address format. Bits 0-9 can be written as decimal digits; bits 10-15 must be written as A-F. For example, bit 12 is addressed as "DM100.C", not "DM100.12". When all requested addresses are compatible with helper-layer batching, this method merges contiguous reads into one or more RDS operations. Mixed or non-optimizable address sets fall back to sequential helper reads with the same return shape.

Returns: A dictionary keyed by the original input address strings.

Parameters: - client: The client to use. - addresses: Address strings that specify both the base device and the desired interpretation. - ct: Cancellation token.

ReadNamedAsync
public static Task<IReadOnlyDictionary<string, object>> ReadNamedAsync(QueuedKvHostLinkClient client, IEnumerable<string> addresses, CancellationToken ct = default)

Reads multiple named values and returns a snapshot dictionary.

PollAsync
public static IAsyncEnumerable<IReadOnlyDictionary<string, object>> PollAsync(KvHostLinkClient client, IEnumerable<string> addresses, TimeSpan interval, CancellationToken ct = default)

Continuously polls the specified addresses and yields a snapshot each cycle.

Remarks: If the address set is batchable, the compiled read plan is reused on every iteration for lower per-cycle overhead.

Parameters: - client: The client to use. - addresses: Address strings in the same format as CancellationToken). - interval: Time between polls. - ct: Cancellation token to stop polling.

PollAsync
public static IAsyncEnumerable<IReadOnlyDictionary<string, object>> PollAsync(QueuedKvHostLinkClient client, IEnumerable<string> addresses, TimeSpan interval, CancellationToken ct = default)

Continuously polls the specified addresses and yields a snapshot each cycle.

ReadWordsSingleRequestAsync
public static Task<ushort[]> ReadWordsSingleRequestAsync(KvHostLinkClient client, string device, int count, CancellationToken ct = default)

Reads contiguous unsigned 16-bit words using one protocol request or returns an error.

Remarks: Use this helper when the logical range must stay atomic.

Returns: The contiguous word values read by one request.

Parameters: - client: Connected Host Link client. - device: Start device address. - count: Number of words to read. - ct: Cancellation token.

ReadWordsSingleRequestAsync
public static Task<ushort[]> ReadWordsSingleRequestAsync(QueuedKvHostLinkClient client, string device, int count, CancellationToken ct = default)

Reads contiguous unsigned 16-bit words using one protocol request or returns an error.

ReadDWordsSingleRequestAsync
public static Task<uint[]> ReadDWordsSingleRequestAsync(KvHostLinkClient client, string device, int count, CancellationToken ct = default)

Reads contiguous unsigned 32-bit values using one protocol request or returns an error.

Remarks: Use this helper when the logical range must stay atomic.

Returns: The contiguous 32-bit values read by one request.

Parameters: - client: Connected Host Link client. - device: Start device address. - count: Number of 32-bit values to read. - ct: Cancellation token.

ReadDWordsSingleRequestAsync
public static Task<uint[]> ReadDWordsSingleRequestAsync(QueuedKvHostLinkClient client, string device, int count, CancellationToken ct = default)

Reads contiguous unsigned 32-bit values using one protocol request or returns an error.

WriteWordsSingleRequestAsync
public static Task WriteWordsSingleRequestAsync(KvHostLinkClient client, string device, IReadOnlyList<ushort> values, CancellationToken ct = default)

Writes contiguous unsigned 16-bit values using one protocol request or returns an error.

WriteWordsSingleRequestAsync
public static Task WriteWordsSingleRequestAsync(QueuedKvHostLinkClient client, string device, IReadOnlyList<ushort> values, CancellationToken ct = default)

Writes contiguous unsigned 16-bit values using one protocol request or returns an error.

WriteDWordsSingleRequestAsync
public static Task WriteDWordsSingleRequestAsync(KvHostLinkClient client, string device, IReadOnlyList<uint> values, CancellationToken ct = default)

Writes contiguous unsigned 32-bit values using one protocol request or returns an error.

WriteDWordsSingleRequestAsync
public static Task WriteDWordsSingleRequestAsync(QueuedKvHostLinkClient client, string device, IReadOnlyList<uint> values, CancellationToken ct = default)

Writes contiguous unsigned 32-bit values using one protocol request or returns an error.

ReadWordsChunkedAsync
public static Task<ushort[]> ReadWordsChunkedAsync(KvHostLinkClient client, string device, int count, int maxWordsPerRequest, CancellationToken ct = default)

Reads contiguous unsigned 16-bit words using explicit chunking.

Remarks: Chunking is opt-in and advances only by contiguous word boundaries.

Returns: The concatenated word values from all explicit chunks.

Parameters: - client: Connected Host Link client. - device: Start device address. - count: Number of words to read. - maxWordsPerRequest: Maximum words per protocol request. - ct: Cancellation token.

ReadWordsChunkedAsync
public static Task<ushort[]> ReadWordsChunkedAsync(QueuedKvHostLinkClient client, string device, int count, int maxWordsPerRequest, CancellationToken ct = default)

Reads contiguous unsigned 16-bit words using explicit chunking.

ReadDWordsChunkedAsync
public static Task<uint[]> ReadDWordsChunkedAsync(KvHostLinkClient client, string device, int count, int maxDwordsPerRequest, CancellationToken ct = default)

Reads contiguous unsigned 32-bit values using explicit chunking.

Remarks: Chunking is opt-in and advances only by whole double-word boundaries.

Returns: The concatenated 32-bit values from all explicit chunks.

Parameters: - client: Connected Host Link client. - device: Start device address. - count: Number of 32-bit values to read. - maxDwordsPerRequest: Maximum double-words per protocol request. - ct: Cancellation token.

ReadDWordsChunkedAsync
public static Task<uint[]> ReadDWordsChunkedAsync(QueuedKvHostLinkClient client, string device, int count, int maxDwordsPerRequest, CancellationToken ct = default)

Reads contiguous unsigned 32-bit values using explicit chunking.

WriteWordsChunkedAsync
public static Task WriteWordsChunkedAsync(KvHostLinkClient client, string device, IReadOnlyList<ushort> values, int maxWordsPerRequest, CancellationToken ct = default)

Writes contiguous unsigned 16-bit values using explicit chunking.

WriteWordsChunkedAsync
public static Task WriteWordsChunkedAsync(QueuedKvHostLinkClient client, string device, IReadOnlyList<ushort> values, int maxWordsPerRequest, CancellationToken ct = default)

Writes contiguous unsigned 16-bit values using explicit chunking.

WriteDWordsChunkedAsync
public static Task WriteDWordsChunkedAsync(KvHostLinkClient client, string device, IReadOnlyList<uint> values, int maxDwordsPerRequest, CancellationToken ct = default)

Writes contiguous unsigned 32-bit values using explicit chunking.

WriteDWordsChunkedAsync
public static Task WriteDWordsChunkedAsync(QueuedKvHostLinkClient client, string device, IReadOnlyList<uint> values, int maxDwordsPerRequest, CancellationToken ct = default)

Writes contiguous unsigned 32-bit values using explicit chunking.

ReadWordsAsync
public static Task<ushort[]> ReadWordsAsync(KvHostLinkClient client, string device, int count, CancellationToken ct = default)

Reads contiguous unsigned 16-bit words starting at device.

Remarks: This helper is the preferred user-facing block-read API for contiguous word devices. It preserves single-request semantics by delegating to CancellationToken).

Returns: Unsigned word values in PLC order.

Parameters: - client: The client to use. - device: Starting device address (e.g. "DM0"). - count: Number of words to read. - ct: Cancellation token.

ReadWordsAsync
public static Task<ushort[]> ReadWordsAsync(QueuedKvHostLinkClient client, string device, int count, CancellationToken ct = default)

Reads contiguous unsigned 16-bit words starting at device.

ReadDWordsAsync
public static Task<uint[]> ReadDWordsAsync(KvHostLinkClient client, string device, int count, CancellationToken ct = default)

Reads contiguous unsigned 32-bit values starting at device.

Remarks: This helper preserves single-request semantics by delegating to CancellationToken).

Returns: Unsigned 32-bit values in logical device order.

Parameters: - client: The client to use. - device: Starting device address (for example "DM0"). - count: Number of 32-bit values to read. - ct: Cancellation token.

ReadDWordsAsync
public static Task<uint[]> ReadDWordsAsync(QueuedKvHostLinkClient client, string device, int count, CancellationToken ct = default)

Reads contiguous unsigned 32-bit values starting at device.

OpenAndConnectAsync
public static Task<QueuedKvHostLinkClient> OpenAndConnectAsync(string host, string plcProfile, int port = 8501, CancellationToken ct = default)

Creates a queued client and opens the connection.

Remarks: This is the recommended convenience entry point for high-level application code that does not need to construct KvHostLinkConnectionOptions manually.

Returns: A connected queued client that is safe to share across async callers.

Parameters: - host: PLC IP address or hostname. - plcProfile: Canonical KEYENCE KV PLC profile for the session. - port: KV Host Link TCP/UDP port. Defaults to 8501. - ct: Cancellation token.

KvHostLinkClientFactory

public static class KvHostLinkClientFactory

Factory helpers for opening ready-to-use Host Link clients.

Remarks: The factory centralizes validation of host, port, timeout, and line-ending behavior so samples and generated docs can point to one explicit connection entry point.

Members

OpenAndConnectAsync
public static Task<QueuedKvHostLinkClient> OpenAndConnectAsync(KvHostLinkConnectionOptions options, CancellationToken cancellationToken = default)

Creates, configures, and opens a queued Host Link client.

Remarks: The returned client uses queued access so higher-level read, write, and polling helpers can share one Host Link session predictably.

Returns: A connected queued client.

Parameters: - options: Explicit connection options. - cancellationToken: Cancellation token.

KvHostLinkConnectionOptions

public sealed class KvHostLinkConnectionOptions

Explicit connection options for a Host Link session.

Remarks: This type is intended for the unified high-level connection flow so generated documentation can describe transport, timeout, profile, and framing behavior in one place.

Members

KvHostLinkConnectionOptions
public KvHostLinkConnectionOptions(string Host, string PlcProfile, int Port = 8501, TimeSpan Timeout = default, HostLinkTransportMode Transport = Tcp, bool AppendLfOnSend = false)

Explicit connection options for a Host Link session.

Remarks: This type is intended for the unified high-level connection flow so generated documentation can describe transport, timeout, profile, and framing behavior in one place.

Parameters: - Host: PLC IP address or hostname. - PlcProfile: Canonical KEYENCE KV PLC profile for the session. - Port: Host Link port number. Defaults to 8501. - Timeout: Operation timeout. A zero value falls back to the library default. - Transport: Transport protocol. - AppendLfOnSend: Whether to append LF after CR on send.

Host
public string Host { get; set; }

PLC IP address or hostname.

Port
public int Port { get; set; }

Host Link port number. Defaults to 8501.

Timeout
public TimeSpan Timeout { get; set; }

Operation timeout. A zero value falls back to the library default.

Transport
public HostLinkTransportMode Transport { get; set; }

Transport protocol.

AppendLfOnSend
public bool AppendLfOnSend { get; set; }

Whether to append LF after CR on send.

PlcProfile
public string PlcProfile { get; set; }

Gets or sets the canonical KEYENCE KV PLC profile for the session.

EffectiveTimeout
public TimeSpan EffectiveTimeout { get; }

Gets the effective timeout used for a new client instance.

Remarks: Host Link callers may leave Timeout at its default value and use this property when they need the resolved timeout that will be applied to the client.

KvHostLinkDevice

public static class KvHostLinkDevice

Members

NormalizeSuffix
public static string NormalizeSuffix(string suffix)
ParseDevice
public static KvDeviceAddress ParseDevice(string text, bool allowOmittedType = true)
ParseDeviceText
public static string ParseDeviceText(string text, string defaultSuffix = "")
ResolveEffectiveFormat
public static string ResolveEffectiveFormat(string deviceType, string suffix)
RequireExplicitFormat
public static string RequireExplicitFormat(KvDeviceAddress address, string dataFormat = null)
ValidateDeviceType
public static void ValidateDeviceType(string command, string deviceType, HashSet<string> allowedTypes)
ValidateDeviceCount
public static void ValidateDeviceCount(string deviceType, string effectiveFormat, int count)
ValidateDeviceSpan
public static void ValidateDeviceSpan(string deviceType, int startNumber, string effectiveFormat, int count = 1)
ValidateExpansionBufferCount
public static void ValidateExpansionBufferCount(string effectiveFormat, int count)
ValidateExpansionBufferSpan
public static void ValidateExpansionBufferSpan(int address, string effectiveFormat, int count)

KvHostLinkDeviceRanges

public static class KvHostLinkDeviceRanges

Members

AvailablePlcProfiles
public static IReadOnlyList<string> AvailablePlcProfiles()
GetDisplayName
public static string GetDisplayName(string plcProfile)
DeviceRangeCatalogForPlcProfile
public static KvDeviceRangeCatalog DeviceRangeCatalogForPlcProfile(string plcProfile)

KvLogicalAddress

public struct KvLogicalAddress

A normalized logical Host Link address used by the high-level helper layer.

Members

KvLogicalAddress
public KvLogicalAddress(KvDeviceAddress BaseAddress, string DataType, int? BitIndex)

A normalized logical Host Link address used by the high-level helper layer.

Parameters: - BaseAddress: Base word device address without a logical suffix. - DataType: Logical data type code such as U, S, D, L, F, BIT, or COMMENT. - BitIndex: Bit index inside the base word when the logical address targets a bit-in-word.

ToText
public string ToText()

Formats the logical address using the public helper contract.

Returns: Canonical helper text such as DM100:U, DM100:F, or DM100.A.

BaseAddress
public KvDeviceAddress BaseAddress { get; set; }

Base word device address without a logical suffix.

DataType
public string DataType { get; set; }

Logical data type code such as U, S, D, L, F, BIT, or COMMENT.

BitIndex
public int? BitIndex { get; set; }

Bit index inside the base word when the logical address targets a bit-in-word.

IsBitInWord
public bool IsBitInWord { get; }

Gets a value indicating whether this logical address targets a bit inside a word.

KvModelInfo

public class KvModelInfo

Information about a PLC model.

Members

KvModelInfo
public KvModelInfo(string Code, string Model)

Information about a PLC model.

Code
public string Code { get; set; }
Model
public string Model { get; set; }

KvPlcMode

public enum KvPlcMode

PLC operating mode.

Members

Program
public const KvPlcMode Program
Run
public const KvPlcMode Run

KvTimerCounterValue

public struct KvTimerCounterValue

Composite timer/counter value returned by Host Link T/C reads.

Members

KvTimerCounterValue
public KvTimerCounterValue(uint Status, uint Current, uint Preset)

Composite timer/counter value returned by Host Link T/C reads.

Status
public uint Status { get; set; }
Current
public uint Current { get; set; }
Preset
public uint Preset { get; set; }

QueuedKvHostLinkClient

public sealed class QueuedKvHostLinkClient

A wrapper for KvHostLinkClient that serializes multi-step operations with a semaphore.

Remarks: Host Link requests often reuse one TCP session and one framing configuration. This wrapper provides a documentation-friendly queued surface for those shared-session scenarios.

Members

QueuedKvHostLinkClient
public QueuedKvHostLinkClient(KvHostLinkClient client)

Initializes a new instance of the QueuedKvHostLinkClient class.

Parameters: - client: The underlying client to wrap.

OpenAsync
public Task OpenAsync(CancellationToken cancellationToken = default)

Opens the connection asynchronously with exclusive access.

Remarks: Call this once after construction or again after an intentional disconnect.

CloseAsync
public Task CloseAsync(CancellationToken cancellationToken = default)

Closes the connection asynchronously with exclusive access.

ExecuteAsync
public Task<T> ExecuteAsync<T>(Func<KvHostLinkClient, Task<T>> operation, CancellationToken cancellationToken = default)

Executes a custom async operation with exclusive access to the wrapped client.

Returns: The value returned by operation.

Parameters: - operation: Delegate that receives the wrapped KvHostLinkClient. - cancellationToken: Cancellation token used while waiting for exclusive access.

ExecuteAsync
public Task ExecuteAsync(Func<KvHostLinkClient, Task> operation, CancellationToken cancellationToken = default)

Executes a custom async operation with exclusive access to the wrapped client.

Parameters: - operation: Delegate that receives the wrapped KvHostLinkClient. - cancellationToken: Cancellation token used while waiting for exclusive access.

SendRawAsync
public Task<string> SendRawAsync(string body, CancellationToken cancellationToken = default)
ChangeModeAsync
public Task ChangeModeAsync(KvPlcMode mode, CancellationToken cancellationToken = default)
ClearErrorAsync
public Task ClearErrorAsync(CancellationToken cancellationToken = default)
CheckErrorNoAsync
public Task<string> CheckErrorNoAsync(CancellationToken cancellationToken = default)
QueryModelAsync
public Task<KvModelInfo> QueryModelAsync(CancellationToken cancellationToken = default)
ConfirmOperatingModeAsync
public Task<KvPlcMode> ConfirmOperatingModeAsync(CancellationToken cancellationToken = default)
SetTimeAsync
public Task SetTimeAsync(DateTime? value = null, CancellationToken cancellationToken = default)
ForcedSetAsync
public Task ForcedSetAsync(string device, CancellationToken cancellationToken = default)
ForcedResetAsync
public Task ForcedResetAsync(string device, CancellationToken cancellationToken = default)
ReadAsync
public Task<string[]> ReadAsync(string device, string dataFormat = null, CancellationToken cancellationToken = default)
ReadConsecutiveAsync
public Task<string[]> ReadConsecutiveAsync(string device, int count, string dataFormat = null, CancellationToken cancellationToken = default)
ReadCommentsAsync
public Task<string> ReadCommentsAsync(string device, bool stripPadding = true, CancellationToken cancellationToken = default)
RegisterMonitorBitsAsync
public Task RegisterMonitorBitsAsync(IEnumerable<string> devices, CancellationToken cancellationToken = default)
RegisterMonitorWordsAsync
public Task RegisterMonitorWordsAsync(IEnumerable<string> devices, CancellationToken cancellationToken = default)
ReadMonitorBitsAsync
public Task<string[]> ReadMonitorBitsAsync(CancellationToken cancellationToken = default)
ReadMonitorWordsAsync
public Task<string[]> ReadMonitorWordsAsync(CancellationToken cancellationToken = default)
ForcedSetConsecutiveAsync
public Task ForcedSetConsecutiveAsync(string device, int count, CancellationToken cancellationToken = default)
ForcedResetConsecutiveAsync
public Task ForcedResetConsecutiveAsync(string device, int count, CancellationToken cancellationToken = default)
ReadConsecutiveLegacyAsync
public Task<string[]> ReadConsecutiveLegacyAsync(string device, int count, string dataFormat = null, CancellationToken cancellationToken = default)
WriteAsync
public Task WriteAsync<T>(string device, T value, string dataFormat = null, CancellationToken cancellationToken = default)
WriteConsecutiveAsync
public Task WriteConsecutiveAsync<T>(string device, IEnumerable<T> values, string dataFormat = null, CancellationToken cancellationToken = default)
WriteConsecutiveLegacyAsync
public Task WriteConsecutiveLegacyAsync<T>(string device, IEnumerable<T> values, string dataFormat = null, CancellationToken cancellationToken = default)
WriteSetValueAsync
public Task WriteSetValueAsync<T>(string device, T value, string dataFormat = null, CancellationToken cancellationToken = default)
WriteSetValueConsecutiveAsync
public Task WriteSetValueConsecutiveAsync<T>(string device, IEnumerable<T> values, string dataFormat = null, CancellationToken cancellationToken = default)
SwitchBankAsync
public Task SwitchBankAsync(int bankNo, CancellationToken cancellationToken = default)
ReadExpansionUnitBufferAsync
public Task<string[]> ReadExpansionUnitBufferAsync(int unitNo, int address, int count, string dataFormat = "", CancellationToken cancellationToken = default)
WriteExpansionUnitBufferAsync
public Task WriteExpansionUnitBufferAsync<T>(int unitNo, int address, IEnumerable<T> values, string dataFormat = "", CancellationToken cancellationToken = default)
Dispose
public void Dispose()

Disposes the wrapper and the underlying client.

DisposeAsync
public ValueTask DisposeAsync()

Disposes the wrapper and the underlying client asynchronously.

InnerClient
public KvHostLinkClient InnerClient { get; }

Gets the underlying low-level client.

Remarks: Use CancellationToken) when you need direct access while preserving serialized request ordering.

PlcProfile
public string PlcProfile { get; }

Gets the canonical KEYENCE KV PLC profile selected for this session.

Timeout
public TimeSpan Timeout { get; set; }

Gets or sets the communication timeout.

AppendLfOnSend
public bool AppendLfOnSend { get; set; }

Gets or sets whether LF is appended after CR on send.

TraceHook
public Action<HostLinkTraceFrame> TraceHook { get; set; }

Gets or sets the raw frame trace hook.

IsOpen
public bool IsOpen { get; }

Gets a value indicating whether the client is connected.