Data Conversion#

class icspacket.proto.mms.data.IEEE754Type(*values)[source]#

Discriminator byte read by IEEE754PackedFloat to pick the codec used for the value bytes that follow it.

Single- and double-precision IEEE 754 floats differ in how many bits their exponent occupies, so this enum simply stores that bit count and uses it to tell the two layouts apart.

FLOAT32 = 8#: Single-precision layout, identified by its 8-bit exponent field.

FLOAT64 = 11#: Double-precision layout, identified by its 11-bit exponent field.

class icspacket.proto.mms.data.IEEE754PackedFloat(exponent_width: IEEE754Type | int = IEEE754Type.FLOAT32, value: float | bytes = 0)[source]#

Wire format of an MMS FloatingPoint value: a leading IEEE754Type tag followed by the value itself.

Packing and unpacking this struct is how create_floating_point_value() and get_floating_point_value() convert between plain Python floats and the tagged byte string MMS transports as FloatingPoint.

exponent_width: IEEE754Type | int = 8#: Tag selecting the codec applied to value (FLOAT32 or FLOAT64); defaults to FLOAT32 when left unset.

value: float | bytes = 0#: The float itself, packed or unpacked using the codec chosen by exponent_width. Falls back to a raw byte string when the tag does not match a recognized codec.

icspacket.proto.mms.data.create_floating_point_value(value: float, exp_width: Literal[8, 11] | None = None) → FloatingPoint[source]#

Create a packed IEEE 754 floating-point representation.

This function encodes a Python float into a binary representation according to the IEEE 754 standard. The precision of the representation is determined by the chosen exponent width.

Parameters:

value (float) – The Python floating-point value to be encoded.
exp_width (Literal[8, 11] | None, optional) – he exponent width specifying the IEEE 754 format, defaults to None

Returns:

A wrapped binary representation of the floating-point value encoded in the specified IEEE 754 format.

Return type:

FloatingPoint

icspacket.proto.mms.data.get_floating_point_value(fp: FloatingPoint | bytes) → float[source]#

Decode a packed IEEE 754 floating-point value into a Python float.

Example:

>>> fp = FloatingPoint(b'\x08Cb\x00\x00')
>>> get_floating_point_value(fp)
226.0

Parameters:: fp (FloatingPoint) – A FloatingPoint object containing the encoded IEEE 754 value or raw bytes.
Returns:: The decoded Python floating-point value.
Return type:: float
Raises:: TypeError – If the exponent width does not match a recognized IEEE 754 type (FLOAT32 or FLOAT64).

class icspacket.proto.mms.data.Timestamp(timeval: bytes = b'\x00\x00\x00\x00', fraction: bytes = b'\x00\x00\x00', leap_second_known: bool = False, clock_failure: bool = False, clock_not_synced: bool = False, accuracy: int = 0)[source]#

Field-level view over a packed 8-byte MMS UTC timestamp.

Splits the raw value carried by a UtcTime into a whole-seconds counter, a sub-second fraction, three one-bit status flags, and an accuracy indicator, so each part can be read or set directly instead of manipulating raw bytes. Build an instance with from_utc_time()/from_datetime() and read it back as plain Python values through seconds/datetime.

Added in version 0.2.3.

timeval: bytes = b'\x00\x00\x00\x00'#: Elapsed seconds, packed as an unsigned big-endian value across these 4 bytes; see seconds for reading/writing it as a Python int.

fraction: bytes = b'\x00\x00\x00'#: Sub-second remainder of the timestamp, held as 3 raw bytes.

leap_second_known: bool = False#: Set when this timestamp’s leap-second status is known rather than undefined.

clock_failure: bool = False#: Set when the source clock is reporting a failure.

clock_not_synced: bool = False#: Set when the source clock has not (yet) synchronized to a reference.

accuracy: int = 0#: 5-bit value carrying the timestamp’s accuracy indicator.

static from_utc_time(utc_time: UtcTime | bytes) → Timestamp[source]#

Construct a Timestamp object from a UTC time value.

Parameters:: utc_time (UtcTime | bytes) – Either a UtcTime instance or an 8-byte raw buffer containing the encoded UTC time.
Returns:: A deserialized Timestamp instance.
Return type:: Timestamp
Raises:: ValueError – If the provided value does not have the expected 8-byte length.

property seconds: int#

Get the integral number of seconds stored in the timestamp.

This property interprets the 4-byte timeval field as an unsigned 32-bit big-endian integer.

Returns:: The number of elapsed seconds.
Return type:: int

static from_datetime(dt: datetime) → Timestamp[source]#

Construct a Timestamp from a Python datetime.datetime.

The supplied datetime object is converted to a UNIX timestamp (seconds since epoch), which is then used to populate the internal seconds field of the Timestamp.

Example#

ts = Timestamp.from_datetime(datetime.datetime.utcnow())
print(ts.seconds)

param dt:: A datetime instance to convert into a MMS Timestamp.
type dt:: datetime.datetime
return:: A newly constructed Timestamp instance.
rtype:: Timestamp

Added in version 0.2.4.

property datetime: datetime#

Get a datetime.datetime object representing the timestamp.

Returns:: A datetime.datetime object representing the timestamp.
Return type:: datetime.datetime

class icspacket.proto.mms.data.FileHandle(handle: int, attributes: FileAttributes)[source]#: Simple representation of an open file handle

icspacket.proto.mms.data.array2data(obj: list[dict], data: Data) → None[source]#

Convert a Python list of dicts into a MMS Data.array representation.

Parameters:

obj (list[dict]) – A list of dict objects, each convertible into Data using from_dict().
data (Data) – Target Data object to populate.

Added in version 0.2.4.

icspacket.proto.mms.data.struct2data(obj: list[dict], data: Data) → None[source]#

Convert a Python list of dicts into a MMS Data.structure representation.

Each dict is transformed into a Data element using from_dict().

Added in version 0.2.4.

icspacket.proto.mms.data.boolean2data(obj: bool | str, data: Data) → None[source]#

Convert a Python boolean or truthy string into MMS Data.boolean.

Recognized truthy values include True, 1, "true", "True", "On", and "on".

Added in version 0.2.4.

icspacket.proto.mms.data.bit_string2data(obj: dict[int, bool] | bytes | bit_string_TYPE, data: Data) → None[source]#

Convert a dict, bytes, or bit_string_TYPE into MMS Data.bit_string.

Parameters:

obj (dict[int, bool] | bytes | Data.bit_string_TYPE) –
- If a dict[int, bool], the keys represent bit positions (1-based) and the values indicate whether the bit is set.
- If bytes or bit_string_TYPE, directly assigned.
data (Data) – Target Data object to populate.

Added in version 0.2.4.

icspacket.proto.mms.data.int2data(obj: int, data: Data) → None[source]#: Added in version 0.2.4.

icspacket.proto.mms.data.uint2data(obj: int, data: Data) → None[source]#: Added in version 0.2.4.

icspacket.proto.mms.data.float2data(obj: float, data: Data) → None[source]#: Added in version 0.2.4.

icspacket.proto.mms.data.bytes2data(obj: bytes, data: Data) → None[source]#: Added in version 0.2.4.

icspacket.proto.mms.data.visible_string2data(obj: str, data: Data) → None[source]#: Added in version 0.2.4.

icspacket.proto.mms.data.time2data(obj: bytes, data: Data) → None[source]#: Added in version 0.2.4.

icspacket.proto.mms.data.bintime2data(obj: bytes, data: Data) → None[source]#: Added in version 0.2.4.

icspacket.proto.mms.data.utctime2data(obj: bytes | datetime, data: Data) → None[source]#

Convert a UTC time value into MMS Data.utc_time.

Accepts either raw bytes or a Python datetime.datetime. If a datetime is provided, it is converted using Timestamp.from_datetime().

Added in version 0.2.4.

icspacket.proto.mms.data.bcd2data(obj: int, data: Data) → None[source]#: Added in version 0.2.4.

icspacket.proto.mms.data.boolean_array2data(obj: list[bool], data: Data) → None[source]#

Convert a Python list of booleans into MMS Data.booleanArray.

Parameters:: obj (list[bool]) – Sequence of boolean values. Each element is mapped to an index in the MMS booleanArray.

Added in version 0.2.4.

icspacket.proto.mms.data.obj_id2data(obj: str, data: Data) → None[source]#: Added in version 0.2.4.

icspacket.proto.mms.data.mms_string2data(obj: str, data: Data) → None[source]#: Added in version 0.2.4.

icspacket.proto.mms.data.from_dict(obj: dict[str, Any]) → Data[source]#

Construct a Data object from a Python dictionary.

This is a high-level factory function that simplifies the creation of MMS Data instances from JSON-like structures. Keys in the dictionary correspond to MMS Data.PRESENT discriminators (e.g., "integer", "boolean", "array"). Values are converted using type-specific converters registered in _DATA_CONVERT.

Example#

payload = {
    "integer": 42,
    "visible_string": "hello",
    "boolean": True,
    "array": [
        {"integer": 1},
        {"integer": 2},
    ],
}

data = from_dict(payload)

The above produces a Data object equivalent to one that would have been constructed manually.

param obj:: Dictionary mapping field names (without the PR_ prefix) to Python values convertible into MMS Data elements.
type obj:: dict[str, Any]
return:: A fully constructed Data instance.
rtype:: Data

Added in version 0.2.4.