Data Conversion¶

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

Enumeration representing supported IEEE 754 floating-point formats.

The enumeration values encode the bit-width of the exponent field used in the floating-point representation. This width determines whether the format corresponds to a 32-bit or 64-bit IEEE 754 float.

FLOAT32 = 8¶: Single-precision floating-point type (8-bit exponent width).

FLOAT64 = 11¶: Double-precision floating-point type (11-bit exponent width).

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

Structured representation of a floating-point value encoded in IEEE 754 format.

This structure encapsulates both the exponent width (to distinguish between 32-bit and 64-bit IEEE 754 floating-point values) and the associated binary-encoded value.

exponent_width: IEEE754Type | int = 8¶: The exponent width that determines the floating-point format (either FLOAT32 or FLOAT64). Defaults to FLOAT32.

value: Any | float | bytes = 0¶: The floating-point value encoded according to the specified exponent width. If the width is not recognized, the raw bytes are stored instead.

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]¶

Structured bitfield representation of a timestamp value.

Added in version 0.2.3.

timeval: bytes = b'\x00\x00\x00\x00'¶: 4-byte unsigned integer representing the elapsed time in seconds.

fraction: bytes = b'\x00\x00\x00'¶: 3-byte fractional component of the timestamp for sub-second precision.

leap_second_known: bool = False¶: Indicates whether the occurrence of leap seconds is known.

clock_failure: bool = False¶: Indicates whether a clock failure has been detected.

clock_not_synced: bool = False¶: Indicates whether the clock is currently unsynchronized.

accuracy: int = 0¶: 5-bit field encoding the accuracy of the timestamp.

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.