Items

Items are entities that make up the structure of a SECS message. For the sake of this package, lists are also assumed to be items.

Item types

Type	Class	Code
List	`secsgem.secs.items.ItemL`	L
Binary	`secsgem.secs.items.ItemB`	B
Boolean	`secsgem.secs.items.ItemBOOLEAN`	TF
ASCII	`secsgem.secs.items.ItemA`	A
JIS-8	`secsgem.secs.items.ItemJ`	J
8-Byte integer	`secsgem.secs.items.ItemI8`	I8
1-Byte integer	`secsgem.secs.items.ItemI1`	I1
2-Byte integer	`secsgem.secs.items.ItemI2`	I2
4-Byte integer	`secsgem.secs.items.ItemI4`	I4
8-Byte float	`secsgem.secs.items.ItemF8`	F8
4-Byte float	`secsgem.secs.items.ItemF4`	F8
8-Byte unsigned integer	`secsgem.secs.items.ItemU8`	U8
1-Byte unsigned integer	`secsgem.secs.items.ItemU1`	U1
2-Byte unsigned integer	`secsgem.secs.items.ItemU2`	U2
4-Byte unsigned integer	`secsgem.secs.items.ItemU4`	U4

Creating items

From value

Item objects can be created with the from_value method of the Item class.

>>> import secsgem.secs.items
>>> 
>>> secsgem.secs.items.Item.from_value(10)
< U1 10 >
>>>
>>> secsgem.secs.items.Item.from_value([["Hallo", b"Welt"], 10, 2.5])
< L [3]
    < L [2]
        < A "Hallo">
        < B 0x57 0x65 0x6c 0x74 >
    >
    < U1 10 >
    < F4 2.5 >
>

This will automatically select the item type for the python values passed. But this can be overridden by passing in a item object instead of a python value.

>>> secsgem.secs.items.Item.from_value([secsgem.secs.items.ItemU4(10)])
< L [1]
    < U4 10 >
>

Specific item types can be initialized by using python values in the constructor.

>>> secsgem.secs.items.ItemI4(10)
< I4 10 >
>>>
>>> secsgem.secs.items.ItemI4([10, 20])
< I4 10 20 >
>>>
>>> secsgem.secs.items.ItemL([10, 20])
< L [2]
    < U1 10 >
    < U1 20 >
>
>>>
>>> secsgem.secs.items.ItemI4("text")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/secsgem/secs/item.py", line 132, in __init__
    self._value = self.validate_value(value)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/secsgem/secs/item_number.py", line 77, in validate_value
    raise self._invalid_type_exception(value)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/secsgem/secs/item.py", line 508, in _invalid_type_exception
    raise TypeError(f"Invalid value '{data}' of '{data.__class__.__name__}' for '{cls.__name__}'")
TypeError: Invalid value 'text' of 'str' for 'ItemI4'

From SML text

A item can also be created using a SML string.

>>> secsgem.secs.items.Item.from_sml("< U4 10 >")
< U4 10 >
>>> 
>>> type(secsgem.secs.items.Item.from_sml("< U4 10 >"))
<class 'secsgem.secs.item_number.ItemU4'>
>>> 
>>> secsgem.secs.items.Item.from_sml("""
< L [3]
    < L [2]
        < A "Hallo">
        < B 0x57 0x65 0x6c 0x74 >
    >
    < U4 10 >
    < F4 2.5 >
>
""")
< L [3]
    < L [2]
        < A "Hallo">
        < B 0x57 0x65 0x6c 0x74 >
    >
    < U4 10 >
    < F4 2.5 >
>

From protocol text

Binary data received via SECS-I/HSMS can be decoded using the classes decode method.

>>> secsgem.secs.items.Item.decode(b'\x01\x03\x01\x02A\x05Hallo!\x04Welt\xa5\x01\n\x91\x04@ \x00\x00')
< L [3]
    < L [2]
        < A "Hallo">
        < B 0x57 0x65 0x6c 0x74 >
    >
    < U1 10 >
    < F4 2.5 >
>

Getting data

Python value

Python values from an item can be retrieved using the value attribute.

>>> item = secsgem.secs.items.Item.from_value([["Hallo", b"Welt"], 10, 2.5])
>>> item.value
[['Hallo', b'Welt'], 10, 2.5]

SML text

A SML string can be generated by using the sml attribute.

>>> item = secsgem.secs.items.Item.from_value([["Hallo", b"Welt"], 10, 2.5])
>>> item.sml
'< L [3]\n    < L [2]\n        < A "Hallo">\n        < B 0x57 0x65 0x6c 0x74 >\n    >\n    < U1 10 >\n    < F4 2.5 >\n>'

The python output for the item object also prints the SML text

>>> item = secsgem.secs.items.Item.from_value([["Hallo", b"Welt"], 10, 2.5])
>>> item
< L [3]
    < L [2]
        < A "Hallo">
        < B 0x57 0x65 0x6c 0x74 >
    >
    < U1 10 >
    < F4 2.5 >
>

Protocol text

The SECS-I/HSMS protocol text can be generated using the encode method.

>>> item = secsgem.secs.items.Item.from_value([["Hallo", b"Welt"], 10, 2.5])
>>> item.encode()
b'\x01\x03\x01\x02A\x05Hallo!\x04Welt\xa5\x01\n\x91\x04@ \x00\x00'