Class SerialSenderOptions

Validated configuration for SerialSender.

Inheritance
SerialSenderOptions
Namespace: MOSAIC.Components.Manager.Serial
Assembly: MOSAIC.dll
Syntax
public sealed record SerialSenderOptions : IEquatable<SerialSenderOptions>
Remarks

Lifecycle: instances arrive raw — straight from JSON or a test — and are turned into a canonical, checked copy by Normalized(), which the block calls once from its constructor. Everything downstream of that point can assume the values are sane, which is why the hot path contains no configuration checks at all.

Escaping: Terminator and Separator accept the escapes \n, \r, \t and \\. JSON already resolves these when the config is written as "\n"; the extra pass exists so that a config written as "\\n", or a value typed into a text box in the UI, means the same thing.

Properties

AutoReconnect

Whether to keep retrying the port after a failed open or a broken link.

Declaration
public bool AutoReconnect { get; init; }
Property Value
Type Description
bool

BaudRate

Baud rate. Must match the firmware.

Declaration
public int BaudRate { get; init; }
Property Value
Type Description
int

Decimals

Digits after the decimal point, used as "F{Decimals}".

Declaration
public int Decimals { get; init; }
Property Value
Type Description
int

DesiredRate

Emission rate in Hz. 0 = inherited from upstream.

Declaration
public double DesiredRate { get; init; }
Property Value
Type Description
double

DropPolicy

What to discard when the queue is full.

Declaration
public DropPolicy DropPolicy { get; init; }
Property Value
Type Description
DropPolicy

DumpPath

Directory for the wire dump, or null to disable it.

Declaration
public string? DumpPath { get; init; }
Property Value
Type Description
string
Remarks

Not a positional parameter — this carries the JSON Path, the same value that enables the CSV dumper, so the two logs turn on and off together. It lives on the options record rather than being set after construction because the writer thread starts inside the constructor: a dump opened afterwards could miss the first lines it was meant to witness.

Deliberately unvalidated. An unusable path must degrade to "no dump", never to a failed pipeline load — a logging problem is not a reason to stop transmitting.

Name

Block display name.

Declaration
public string Name { get; init; }
Property Value
Type Description
string

NonFiniteValue

Value substituted for NaN and infinities before formatting.

Declaration
public double NonFiniteValue { get; init; }
Property Value
Type Description
double
Remarks

Firmware parsers rarely handle "NaN" or "∞", and a single unparsable line often desynchronises a fixed-field reader for good. Substituting keeps the line width predictable.

ParseError

Deferred parse failure from FromParams(IReadOnlyList<object>?, string, double), rethrown by Normalized().

Declaration
internal string? ParseError { get; init; }
Property Value
Type Description
string
Remarks

Parsing happens outside the block constructor, but the constructor is the only place allowed to throw. Carrying the message here keeps that rule intact without discarding the detail of what was actually wrong.

PortName

Serial port name, e.g. "COM3" or "/dev/ttyUSB0". Required.

Declaration
public string PortName { get; init; }
Property Value
Type Description
string

QueueCapacity

Maximum number of formatted lines held for the writer thread.

Declaration
public int QueueCapacity { get; init; }
Property Value
Type Description
int
Remarks

Sizes the latency ceiling: at R Hz a full queue is QueueCapacity / R seconds of backlog. Large values trade staleness for tolerance of transient stalls.

ResetDelayMs

Milliseconds to wait after opening the port before writing.

Declaration
public int ResetDelayMs { get; init; }
Property Value
Type Description
int
Remarks

Opening a USB-CDC port asserts DTR, which resets boards like the Arduino; anything written during the bootloader window is lost. 2000 ms covers the common bootloaders. Set to 0 for devices that do not reset on connect.

Separator

Written between adjacent fields.

Declaration
public string Separator { get; init; }
Property Value
Type Description
string

Terminator

Written after the last field of every line.

Declaration
public string Terminator { get; init; }
Property Value
Type Description
string

WriteTimeoutMs

Milliseconds a single port write may block before it is abandoned.

Declaration
public int WriteTimeoutMs { get; init; }
Property Value
Type Description
int

Methods

Escape(string?)

Inverse of Unescape(string?), for showing a delimiter in a UI or a log line without breaking the layout.

Declaration
public static string Escape(string? text)
Parameters
Type Name Description
string text
Returns
Type Description
string

Flag(IReadOnlyList<object>, int, bool)

Reads a positional boolean, falling back on a missing or empty entry.

Declaration
private static bool Flag(IReadOnlyList<object> p, int index, bool fallback)
Parameters
Type Name Description
IReadOnlyList<object> p
int index
bool fallback
Returns
Type Description
bool

FromParams(IReadOnlyList<object>?, string, double)

Builds options from a positional JSON Params list.

Declaration
public static SerialSenderOptions FromParams(IReadOnlyList<object>? p, string name, double desiredRate)
Parameters
Type Name Description
IReadOnlyList<object> p

Positional parameters. May be null or short; missing and empty entries fall back to the default for that position.

string name

Block name.

double desiredRate

Emission rate in Hz.

Returns
Type Description
SerialSenderOptions

Unvalidated options. Any value that could not be interpreted is recorded in ParseError and surfaces when Normalized() runs.

Remarks

This method never throws — configuration errors are the constructor's to report, so that a half-built block is never left behind.

IsAscii(string)

Whether every character is representable in 7-bit ASCII.

Declaration
private static bool IsAscii(string text)
Parameters
Type Name Description
string text
Returns
Type Description
bool

IsBlank(object?)

Whether a raw parameter is the empty string, i.e. an explicit "use the default".

Declaration
private static bool IsBlank(object? raw)
Parameters
Type Name Description
object raw
Returns
Type Description
bool

Normalized()

Validates the configuration and returns a canonical copy with escapes resolved and the port name trimmed.

Declaration
public SerialSenderOptions Normalized()
Returns
Type Description
SerialSenderOptions

A validated copy. Never the same instance.

Exceptions
Type Condition
ArgumentException

Thrown on any invalid value, naming the offending field.

Num(IReadOnlyList<object>, int, int)

Reads a positional integer, falling back on a missing or empty entry.

Declaration
private static int Num(IReadOnlyList<object> p, int index, int fallback)
Parameters
Type Name Description
IReadOnlyList<object> p
int index
int fallback
Returns
Type Description
int

Real(IReadOnlyList<object>, int, double)

Reads a positional double, falling back on a missing or empty entry.

Declaration
private static double Real(IReadOnlyList<object> p, int index, double fallback)
Parameters
Type Name Description
IReadOnlyList<object> p
int index
double fallback
Returns
Type Description
double

Str(IReadOnlyList<object>, int, string?)

Reads a positional string, treating a missing or empty entry as "use the default".

Declaration
private static string? Str(IReadOnlyList<object> p, int index, string? fallback)
Parameters
Type Name Description
IReadOnlyList<object> p
int index
string fallback
Returns
Type Description
string
Remarks

Whitespace is preserved, so a single space is a usable separator; only a genuinely empty value falls back.

TryParseDropPolicy(string?, out DropPolicy)

Parses a drop-policy name, accepting the bare forms "newest"/"oldest".

Declaration
public static bool TryParseDropPolicy(string? text, out DropPolicy policy)
Parameters
Type Name Description
string text
DropPolicy policy
Returns
Type Description
bool

true if recognised.

Unescape(string?)

Resolves the escapes \n, \r, \t and \. Other backslash sequences are left verbatim.

Declaration
public static string Unescape(string? text)
Parameters
Type Name Description
string text
Returns
Type Description
string
Remarks

A trailing lone backslash is kept as-is rather than treated as an error — it is far more likely a typo in a delimiter than something worth refusing to start over.

Implements

IEquatable<T>

Search documentation

Start typing to search the documentation.