Class SerialSenderOptions
Validated configuration for SerialSender.
Implements
Inherited Members
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.