mxaccess/docs/ASB-Variant-Wire-Format.md

ASB Variant Wire Format

This note documents the ASB Variant and related value/status payloads that MxAsbClient currently understands. It is based on src/MxAsbClient/AsbContracts.cs, MxAsbDataClient.DecodeVariant, MxAsbDataClient.FormatVariant, src/MxAsbClient.Tests/Program.cs, and the remaining-work notes.

ASBIData Framing

ASB custom data-contract values are serialized as an ASBIData XML element containing base64-encoded binary. The binary uses the .NET BinaryWriter / BinaryReader primitive layout used by the client on Windows:

Field kind	Binary layout
ushort	2-byte little-endian unsigned integer
int / uint	4-byte little-endian integer
long / ulong	8-byte little-endian integer
float / double	4-byte / 8-byte IEEE payload from BitConverter
bool fields in custom structs	one BinaryWriter.Write(bool) byte
UTF-16 strings in custom structs	4-byte byte length, then UTF-16LE bytes
custom arrays	4-byte element count, then each element's custom binary body

The Variant body itself is:

Offset	Size	Field	Notes
0	2	Type	AsbDataType numeric ID.
2	4	Length	Logical payload length. Factory-created variants set this to Payload.Length.
6	4	PayloadLength	Actual byte count emitted before Payload.
10	PayloadLength	Payload	Type-specific bytes. Empty or missing payload is treated as empty.

DecodeVariant trusts the actual payload bytes for parsing. Unsupported type IDs with non-empty payloads are returned as raw byte[]; unsupported empty variants return null, except known empty string/array types, which return empty values.

Declared Type IDs

These IDs are declared by AsbDataType. Only the layouts listed as decode-supported below should be considered implemented behavior.

ID	Name	Current handling
0	TypeByte	Declared only; raw bytes if received.
1	TypeChar	Declared only; raw bytes if received.
2	TypeInt16	Declared only; raw bytes if received.
3	TypeUInt16	Declared only; raw bytes if received.
4	TypeInt32	Decode/write supported and live-proven.
5	TypeUInt32	Declared only; raw bytes if received.
6	TypeInt64	Declared only; raw bytes if received.
7	TypeUInt64	Declared only; raw bytes if received.
8	TypeFloat	Decode/write supported and live-proven.
9	TypeDouble	Decode/write supported and live-proven.
10	TypeString	Decode/write supported and live-proven.
11	TypeDateTime	Decode/write supported and live-proven.
12	TypeDuration	Decode/write supported and live-proven.
13	TypeGuid	Declared only; raw bytes if received.
14	TypeByteString	Declared only; raw bytes if received.
15	TypeLocaleId	Declared only; raw bytes if received.
16	TypeLocalizedText	Declared only; raw bytes if received.
17	TypeBool	Decode/write supported and live-proven.
18	TypeSByte	Declared only; raw bytes if received.
19	TypeErrorStatus	Declared only; raw bytes if received.
20	TypeEnum	Declared only; raw bytes if received.
21	TypeDataType	Declared only; raw bytes if received.
22	TypeSecurityClassification	Declared only; raw bytes if received.
23	TypeDataQuality	Declared only; raw bytes if received.
40	TypeByteArray	Declared only; raw bytes if received.
41	TypeCharArray	Declared only; raw bytes if received.
42	TypeInt16Array	Declared only; raw bytes if received.
43	TypeUInt16Array	Declared only; raw bytes if received.
44	TypeInt32Array	Decode/write supported and live-proven for deployed array tags.
45	TypeUInt32Array	Declared only; raw bytes if received.
46	TypeInt64Array	Declared only; raw bytes if received.
47	TypeUInt64Array	Declared only; raw bytes if received.
48	TypeFloatArray	Decode/write supported and live-proven for deployed array tags.
49	TypeDoubleArray	Decode/write supported and live-proven for deployed array tags.
50	TypeStringArray	Decode/write supported and live-proven for deployed array tags.
51	TypeDateTimeArray	Decode/write supported and live-proven for deployed array tags.
52	TypeDurationArray	Decode/write supported by tests; live coverage depends on deployed tags.
53	TypeGuidArray	Declared only; raw bytes if received.
54	TypeByteStringArray	Declared only; raw bytes if received.
55	TypeLocaleIdArray	Declared only; raw bytes if received.
56	TypeLocalizedTextArray	Declared only; raw bytes if received.
57	TypeBoolArray	Decode/write supported and live-proven for deployed array tags.
58	TypeSByteArray	Declared only; raw bytes if received.
60	TypeEnumArray	Declared only; raw bytes if received.
61	TypeDataTypeArray	Declared only; raw bytes if received.
62	TypeSecurityClassificationArray	Declared only; raw bytes if received.
63	TypeDataQualityArray	Declared only; raw bytes if received.
65535	TypeUnknown	Used for empty/user-data placeholders.

Supported Scalar Payloads

Type	ID	Payload layout	Empty-payload decode
TypeBool	17	one byte; non-zero is true, zero is false	null
TypeInt32	4	4-byte little-endian signed integer	null
TypeFloat	8	4-byte IEEE single from BitConverter	null
TypeDouble	9	8-byte IEEE double from BitConverter	null
TypeString	10	UTF-16LE bytes, no per-string length inside the variant payload	empty string
TypeDateTime	11	8-byte signed Windows FILETIME from DateTime.ToFileTimeUtc()	null
TypeDuration	12	8-byte signed .NET tick count from TimeSpan.Ticks	null

FormatVariant renders scalar values as invariant strings. DateTime values format with the round-trip O pattern after DateTime.FromFileTimeUtc(); Duration values format with the constant c TimeSpan pattern.

Supported Array Payloads

Variant arrays do not carry an element count in a common header. The element count is inferred from payload byte length for fixed-width arrays, or by walking length-prefixed records for string arrays.

Type	ID	Payload layout	Empty-payload decode
TypeInt32Array	44	packed 4-byte little-endian signed integers	empty int[]
TypeBoolArray	57	one byte per element; non-zero is true	empty bool[]
TypeFloatArray	48	packed 4-byte IEEE singles	empty float[]
TypeDoubleArray	49	packed 8-byte IEEE doubles	empty double[]
TypeStringArray	50	repeated 4-byte byte length, then UTF-16LE bytes; zero length is empty string	empty string[]
TypeDateTimeArray	51	packed 8-byte Windows FILETIME values	empty DateTime[]
TypeDurationArray	52	packed 8-byte .NET tick counts	empty TimeSpan[]

For malformed string-array payloads, decoding stops when the next declared string byte length is negative or extends beyond the remaining payload. The partial values decoded before that point are preserved.

Timestamp and Duration Handling

There are two different timestamp encodings:

Location	Encoding
Variant TypeDateTime / TypeDateTimeArray payloads	Windows FILETIME UTC values (DateTime.ToFileTimeUtc() / DateTime.FromFileTimeUtc()).
RuntimeValue.Timestamp in read/publish wrappers	8-byte DateTime.ToBinary() value followed by a one-byte TimestampSpecified flag. Publish mapping normalizes the timestamp to UTC for AsbPublishedValue.TimestampUtc.

TypeDuration and TypeDurationArray payloads are 8-byte TimeSpan.Ticks values. No alternate duration units are inferred.

String Encoding

Scalar TypeString payloads are raw UTF-16LE bytes without an inner length. The variant Length and PayloadLength fields provide the byte count.

TypeStringArray payloads are a sequence of string records. Each record starts with a 4-byte little-endian byte length followed by that many UTF-16LE bytes. null and empty strings are both emitted as a zero-length string by AsbVariantFactory.FromStringArray, and decode as string.Empty.

The same 4-byte byte-length plus UTF-16LE convention is also used by custom struct string fields such as ItemIdentity.Name, but that is outside the variant payload.

Runtime Value, Quality, and Status

Quality is not part of a Variant payload. Reads and publishes wrap the variant inside RuntimeValue, whose binary layout is:

Order	Field	Binary layout
1	Timestamp	8-byte DateTime.ToBinary() value
2	TimestampSpecified	one boolean byte
3	Value	nested Variant body
4	Status	nested AsbStatus body

AsbStatus is:

Order	Field	Binary layout
1	Count	signed byte
2	payload byte length	4-byte integer
3	Payload	status element bytes

AsbPublishMapper.DecodeStatus treats Count as the number of payload bytes to inspect when it is positive, capped at the actual payload length. If Count is zero or negative, it inspects the full payload.

Status element bytes are parsed as repeated records:

Record part	Meaning
marker byte bit 0-6	AsbStatusElementType ID
marker byte bit 7 set	element value is implicitly zero and no value bytes follow
marker byte bit 7 clear	next two bytes are a little-endian ushort value

Known status element type IDs are:

ID	Name
1	OpcDaStatus
2	OpcUaStatus
3	OpcUaVendorStatus
4	ScadaStatus
5	MxStatusCategory
6	MxStatusDetail
7	MxQuality
125	Reserved1Status
126	Reserved2Status
127	Reserved3Status

MxQuality is summarized by masking with 0x00C0: 0x00C0 is good, 0x0040 is uncertain, and 0x0000 is bad. Unknown quality values and unknown status element types are preserved rather than guessed.

Proven Versus Intentionally Open

Live/read/write coverage is complete for Boolean, Int32, Float, Double, String, DateTime, Duration, and the deployed array tags called out in the remaining-work notes. The non-live test suite also round-trips the supported factories through DecodeVariant, including the duration array path.

The client intentionally does not infer layouts for declared-but-unsupported ASB types such as GUID, byte strings, localized text, enum/data-type/security/data quality variants, and their array forms. Those types stay as raw bytes until a real deployed tag, capture, or contract evidence proves the payload shape.

Buffered publish batches are also intentionally not described here. The current ASB buffered flag is exposed, but observed publish responses still carry a single current RuntimeValue per item rather than a proven multi-sample batch payload.