Util

snap7.util.get_bool(bytearray_: bytearray, byte_index: int, bool_index: int) → bool[source]

Get the boolean value from location in bytearray

Parameters:

bytearray – buffer data.
byte_index – byte index to read from.
bool_index – bit index to read from.

Returns:

True if the bit is 1, else 0.

Examples

>>> buffer = bytearray([0b00000001])  # Only one byte length
>>> get_bool(buffer, 0, 0)  # The bit 0 starts at the right.
    True

snap7.util.get_byte(bytearray_: bytearray, byte_index: int) → bytes[source]

Get byte value from bytearray.

Notes

WORD 8bit 1bytes Decimal number unsigned B#(0) to B#(255) => 0 to 255

Parameters:

bytearray – buffer to be read from.
byte_index – byte index to be read.

Returns:

value get from the byte index.

snap7.util.get_char(bytearray_: bytearray, byte_index: int) → str[source]

Get char value from bytearray.

Notes

Datatype char in the PLC is represented in 1 byte. It has to be in ASCII-format.

Parameters:

bytearray – buffer to read from.
byte_index – byte index to start reading from.

Returns:

Value read.

Examples

Read 1 Byte raw from DB1.10, where a char value is stored. Return Python compatible value. >>> from snap7 import Client >>> data = Client().db_read(db_number=1, start=10, size=1) >>> get_char(data, 0) ‘C’

snap7.util.get_dint(bytearray_: bytearray, byte_index: int) → int[source]

Get dint value from bytearray.

Notes

Datatype dint consists in 4 bytes in the PLC. Maximum possible value is 2147483647. Lower posible value is -2147483648.

Parameters:

bytearray – buffer to read.
byte_index – byte index from where to start reading.

Returns:

Value read.

Examples

>>> import struct
>>> data = bytearray(4)
>>> data[:] = struct.pack(">i", 2147483647)
>>> get_dint(data, 0)
    2147483647

snap7.util.get_dt(bytearray_: bytearray, byte_index: int) → str[source]

Get DATE_AND_TIME Value from bytearray as ISO 8601 formatted Date String .. rubric:: Notes

Datatype DATE_AND_TIME consists in 8 bytes in the PLC.

Parameters:

bytearray – buffer to read.
byte_index – byte index from where to start writing.

Examples

>>> data = bytearray(8)
>>> data[:] = [32, 7, 18, 23, 50, 2, 133, 65]  #'2020-07-12T17:32:02.854000'
>>> get_dt(data,0)
    '2020-07-12T17:32:02.854000'

snap7.util.get_dword(bytearray_: bytearray, byte_index: int) → int[source]

Gets the dword from the buffer.

Notes

Datatype dword consists in 8 bytes in the PLC. The maximum value posible is 4294967295

Parameters:

bytearray – buffer to read.
byte_index – byte index from where to start reading.

Returns:

Value read.

Examples

>>> data = bytearray(8)
>>> data[:] = b"\x12\x34\xAB\xCD"
>>> get_dword(data, 0)
    4294967295

snap7.util.get_fstring(bytearray_: bytearray, byte_index: int, max_length: int, remove_padding: bool = True) → str[source]

Parse space-padded fixed-length string from bytearray

Notes

This function supports fixed-length ASCII strings, right-padded with spaces.

Parameters:

bytearray – buffer from where to get the string.
byte_index – byte index from where to start reading.
max_length – the maximum length of the string.
remove_padding – whether to remove the right-padding.

Returns:

String value.

Examples

>>> data = [ord(letter) for letter in "hello world    "]
>>> get_fstring(data, 0, 15)
'hello world'
>>> get_fstring(data, 0, 15, remove_padding=False)
'hello world    '

snap7.util.get_int(bytearray_: bytearray, byte_index: int) → int[source]

Get int value from bytearray.

Notes

Datatype int in the PLC is represented in two bytes

Parameters:

bytearray – buffer to read from.
byte_index – byte index to start reading from.

Returns:

Value read.

Examples

>>> get_int(bytearray([0, 255]), 0)
    255

snap7.util.get_ldt(bytearray_: bytearray, byte_index: int) → datetime[source]

Get LDT (Long Date and Time) value from bytearray.

Notes

Datatype LDT consists of 8 bytes (64-bit unsigned integer) representing nanoseconds since 1970-01-01 00:00:00 UTC. Used in S7-1500 PLCs.

Parameters:

bytearray – buffer to read from.
byte_index – byte index from where to start reading.

Returns:

datetime value.

snap7.util.get_lreal(bytearray_: bytearray, byte_index: int) → float[source]

Get the long real

Datatype lreal (long real) consists in 8 bytes in the PLC. Negative Range: -1.7976931348623158e+308 to -2.2250738585072014e-308 Positive Range: +2.2250738585072014e-308 to +1.7976931348623158e+308 Zero: ±0

Parameters:

bytearray – buffer to read from.
byte_index – byte index from where to start reading.

Returns:

The real value.

Examples

read lreal value (here as example 12345.12345) from DB1.10 of a PLC >>> from snap7 import Client >>> data = Client().db_read(db_number=1, start=10, size=8) >>> get_lreal(data, 0) 12345.12345

snap7.util.get_ltime(bytearray_: bytearray, byte_index: int) → timedelta[source]

Get LTIME value from bytearray.

Notes

Datatype LTIME consists of 8 bytes (64-bit signed integer) representing nanoseconds. Used in S7-1500 PLCs.

Parameters:

bytearray – buffer to read from.
byte_index – byte index from where to start reading.

Returns:

timedelta value.

Examples

>>> data = bytearray(8)
>>> data[:] = b'\x00\x00\x00\x00\x3b\x9a\xca\x00'  # 1 second in nanoseconds
>>> get_ltime(data, 0)
datetime.timedelta(seconds=1)

snap7.util.get_ltod(bytearray_: bytearray, byte_index: int) → timedelta[source]

Get LTOD (Long Time of Day) value from bytearray.

Notes

Datatype LTOD consists of 8 bytes (64-bit unsigned integer) representing nanoseconds since midnight. Used in S7-1500 PLCs. Range: 0 to 86399999999999 ns.

Parameters:

bytearray – buffer to read from.
byte_index – byte index from where to start reading.

Returns:

timedelta value representing time of day.

snap7.util.get_lword(bytearray_: bytearray, byte_index: int) → int[source]

Get the long word

Notes

Datatype lword (long word) consists in 8 bytes in the PLC. Maximum value is 18446744073709551615 (0xFFFFFFFFFFFFFFFF). Minimum value is 0.

Parameters:

bytearray – buffer to read from.
byte_index – byte index from where to start reading.

Returns:

Value read.

Examples

>>> data = bytearray(b"\x00\x00\x00\x00\x00\x00\xAB\xCD")
>>> get_lword(data, 0)
43981

snap7.util.get_real(bytearray_: bytearray, byte_index: int) → float[source]

Get real value.

Notes

Datatype real is represented in 4 bytes in the PLC. The packed representation uses the IEEE 754 binary32.

Parameters:

bytearray – buffer to read from.
byte_index – byte index to reading from.

Returns:

Real value.

Examples

>>> data = bytearray(b'B\xf6\xa4Z')
>>> get_real(data, 0)
    123.32099914550781

snap7.util.get_sint(bytearray_: bytearray, byte_index: int) → int[source]

Get the small int

Notes

Datatype sint (Small int) consists in 1 byte in the PLC. Maximum value posible is 127. Lowest value posible is -128.

Parameters:

bytearray – buffer to read from.
byte_index – byte index from where to start reading.

Returns:

Value read.

Examples

>>> data = bytearray([127])
>>> get_sint(data, 0)
    127

snap7.util.get_string(bytearray_: bytearray, byte_index: int) → str[source]

Parse string from bytearray

Notes

The first byte of the buffer will contain the max size posible for a string. The second byte contains the length of the string that contains.

Parameters:

bytearray – buffer from where to get the string.
byte_index – byte index from where to start reading.

Returns:

String value.

Examples

>>> data = bytearray([254, len("hello world")] + [ord(l) for letter in "hello world"])
>>> get_string(data, 0)
'hello world'

snap7.util.get_time(bytearray_: bytearray, byte_index: int) → str[source]

Get time value from bytearray.

Notes

Datatype time consists in 4 bytes in the PLC. Maximum possible value is T#24D_20H_31M_23S_647MS(2147483647). Lower posible value is T#-24D_20H_31M_23S_648MS(-2147483648).

Parameters:

bytearray – buffer to read.
byte_index – byte index from where to start reading.

Returns:

Value read.

Examples

>>> import struct
>>> data = bytearray(4)
>>> data[:] = struct.pack(">i", 2147483647)
>>> get_time(data, 0)
    '24:20:31:23:647'

snap7.util.get_udint(bytearray_: bytearray, byte_index: int) → int[source]

Get unsigned dint value from bytearray.

Notes

Datatype udint consists in 4 bytes in the PLC. Maximum possible value is 4294967295. Minimum posible value is 0.

Parameters:

bytearray – buffer to read.
byte_index – byte index from where to start reading.

Returns:

Value read.

Examples

>>> import struct
>>> data = bytearray(4)
>>> data[:] = struct.pack(">I", 4294967295)
>>> get_udint(data, 0)
    4294967295

snap7.util.get_uint(bytearray_: bytearray, byte_index: int) → int[source]

Get unsigned int value from bytearray.

Notes

Datatype uint in the PLC is represented in two bytes Maximum posible value is 65535. Lower posible value is 0.

Parameters:

bytearray – buffer to read from.
byte_index – byte index to start reading from.

Returns:

Value read.

Examples

>>> data = bytearray([255, 255])
>>> get_uint(data, 0)
    65535

snap7.util.get_usint(bytearray_: bytearray, byte_index: int) → int[source]

Get the unsigned small int from the bytearray

Notes

Datatype usint (Unsigned small int) consists on 1 byte in the PLC. Maximum posible value is 255. Lower posible value is 0.

Parameters:

bytearray – buffer to read from.
byte_index – byte index from where to start reading.

Returns:

Value read.

Examples

>>> data = bytearray([255])
>>> get_usint(data, 0)
    255

snap7.util.get_wchar(bytearray_: bytearray, byte_index: int) → str[source]

Get wchar value from bytearray.

Datatype wchar in the PLC is represented in 2 bytes. It has to be in utf-16-be format.

Parameters:

bytearray – buffer to read from.
byte_index – byte index to start reading from.

Returns:

Value read.

Examples

Read 2 Bytes raw from DB1.10, where a wchar value is stored. Return Python compatible value. >>> from snap7 import Client >>> data = Client().db_read(db_number=1, start=10, size=2) >>> get_wchar(data, 0) ‘C’

snap7.util.get_word(bytearray_: bytearray, byte_index: int) → bytearray[source]

Get word value from bytearray.

Notes

WORD 16bit 2bytes Decimal number unsigned B#(0,0) to B#(255,255) => 0 to 65535

Parameters:

bytearray – buffer to get the word from.
byte_index – byte index from where start reading from.

Returns:

Word value.

Examples

>>> get_word(bytearray([0, 100]), 0)
    100

snap7.util.get_wstring(bytearray_: bytearray, byte_index: int) → str[source]

Parse wstring from bytearray

Notes

Byte 0 and 1 contains the max size posible for a string (2 Byte value). byte 2 and 3 contains the length of the string that contains (2 Byte value). The other bytes contain WCHARs (2Byte) in utf-16-be style.

Parameters:

bytearray – buffer from where to get the string.
byte_index – byte index from where to start reading.

Returns:

String value.

Examples

Read from DB1.10 22, where the WSTRING is stored, the raw 22 Bytes and convert them to a python string >>> from snap7 import Client >>> data = Client().db_read(db_number=1, start=10, size=22) >>> get_wstring(data, 0) ‘hello world’

snap7.util.set_bool(bytearray_: bytearray, byte_index: int, bool_index: int, value: bool) → bytearray[source]

Set boolean value on location in bytearray.

Parameters:

bytearray – buffer to write to.
byte_index – byte index to write to.
bool_index – bit index to write to.
value – value to write.

Examples

>>> buffer = bytearray([0b00000000])
>>> set_bool(buffer, 0, 0, True)
>>> buffer
    bytearray(b"\x01")

snap7.util.set_byte(bytearray_: bytearray, byte_index: int, _int: int) → bytearray[source]

Set value in bytearray to byte

Parameters:

bytearray – buffer to write to.
byte_index – byte index to write.
_int – value to write.

Returns:

buffer with the written value.

Examples

>>> buffer = bytearray([0b00000000])
>>> set_byte(buffer, 0, 255)
    bytearray(b"\xFF")

snap7.util.set_char(bytearray_: bytearray, byte_index: int, chr_: str) → bytearray[source]

Set char value in a bytearray.

Notes

Datatype char in the PLC is represented in 1 byte. It has to be in ASCII-format

Parameters:

bytearray – buffer to write to.
byte_index – byte index from where to start writing.
chr – char to write.

Returns:

Buffer with the written value.

Examples

write char (here as example ‘C’) to DB1.10 of a PLC >>> data = bytearray(1) >>> set_char(data, 0, ‘C’) >>> data bytearray(‘0x43’)

snap7.util.set_date(bytearray_: bytearray, byte_index: int, date_: date) → bytearray[source]

Set value in bytearray to date .. rubric:: Notes

Datatype date consists in the number of days elapsed from 1990-01-01. It is stored as an int (2 bytes) in the PLC.

Parameters:

bytearray – buffer to write.
byte_index – byte index from where to start writing.
date – date object

Examples

>>> data = bytearray(2)
>>> set_date(data, 0, date(2024, 3, 27))
>>> data
    bytearray(b'0Ø')

snap7.util.set_dint(bytearray_: bytearray, byte_index: int, dint: int) → bytearray[source]

Set value in bytearray to dint

Notes

Datatype dint consists in 4 bytes in the PLC. Maximum possible value is 2147483647. Lower posible value is -2147483648.

Parameters:

bytearray – buffer to write.
byte_index – byte index from where to start writing.
dint – double integer value

Examples

>>> data = bytearray(4)
>>> set_dint(data, 0, 2147483647)
>>> data
    bytearray(b'\x7f\xff\xff\xff')

snap7.util.set_dt(bytearray_: bytearray, byte_index: int, dt_: datetime) → bytearray[source]

Set DATE_AND_TIME value in bytearray.

Notes

Datatype DATE_AND_TIME consists of 8 bytes in BCD encoding: - Byte 0: Year (BCD, 0-99, 90-99 = 1990-1999, 0-89 = 2000-2089) - Byte 1: Month (BCD) - Byte 2: Day (BCD) - Byte 3: Hour (BCD) - Byte 4: Minute (BCD) - Byte 5: Second (BCD) - Byte 6-7: Milliseconds (BCD) + weekday

Parameters:

bytearray – buffer to write to.
byte_index – byte index from where to start writing.
dt – datetime object to write.

Returns:

Buffer with the written value.

Examples

>>> from datetime import datetime
>>> data = bytearray(8)
>>> set_dt(data, 0, datetime(2020, 7, 12, 17, 32, 2, 854000))

snap7.util.set_dtl(bytearray_: bytearray, byte_index: int, dt_: datetime) → bytearray[source]

Set DTL (Date and Time Long) value in bytearray.

Notes

Datatype DTL consists of 12 bytes in the PLC: - Bytes 0-1: Year (uint16, big-endian) - Byte 2: Month (1-12) - Byte 3: Day (1-31) - Byte 4: Weekday (1=Sunday, 7=Saturday) - Byte 5: Hour (0-23) - Byte 6: Minute (0-59) - Byte 7: Second (0-59) - Bytes 8-11: Nanoseconds (uint32, big-endian)

Parameters:

bytearray – buffer to write to.
byte_index – byte index from where to start writing.
dt – datetime object to write.

Returns:

Buffer with the written value.

Examples

>>> from datetime import datetime
>>> data = bytearray(12)
>>> set_dtl(data, 0, datetime(2024, 3, 27, 14, 30, 0))

snap7.util.set_dword(bytearray_: bytearray, byte_index: int, dword: int) → bytearray[source]

Set a DWORD to the buffer.

Notes

Datatype dword consists in 8 bytes in the PLC. The maximum value posible is 4294967295

Parameters:

bytearray – buffer to write to.
byte_index – byte index from where to write.
dword – value to write.

Examples

>>> data = bytearray(4)
>>> set_dword(data,0, 4294967295)
>>> data
    bytearray(b'\xff\xff\xff\xff')

snap7.util.set_fstring(bytearray_: bytearray, byte_index: int, value: str, max_length: int) → bytearray[source]

Set space-padded fixed-length string value

Parameters:

bytearray – buffer to write to.
byte_index – byte index to start writing from.
value – string to write.
max_length – maximum string length, i.e. the fixed size of the string.

Raises:

TypeError – if the value is not a str.
ValueError – if the length of the value is larger than the max_size
or 'value' contains non-ascii characters. –

Examples

>>> data = bytearray(20)
>>> set_fstring(data, 0, "hello world", 15)
>>> data
    bytearray(b'hello world    ')

snap7.util.set_int(bytearray_: bytearray, byte_index: int, _int: int) → bytearray[source]

Set value in bytearray to int

Notes

An datatype int in the PLC consists of two bytes.

Parameters:

bytearray – buffer to write on.
byte_index – byte index to start writing from.
_int – int value to write.

Returns:

Buffer with the written value.

Examples

>>> data = bytearray(2)
>>> set_int(data, 0, 255)
    bytearray(b'\x00\xff')

snap7.util.set_lreal(bytearray_: bytearray, byte_index: int, lreal: float) → bytearray[source]

Set the long real

Notes

Datatype lreal (long real) consists in 8 bytes in the PLC. Negative Range: -1.7976931348623158e+308 to -2.2250738585072014e-308 Positive Range: +2.2250738585072014e-308 to +1.7976931348623158e+308 Zero: ±0

Parameters:

bytearray – buffer to read from.
byte_index – byte index from where to start reading.
lreal – float value to set

Returns:

Value to write.

Examples

write lreal value (here as example 12345.12345) to DB1.10 of a PLC >>> data = set_lreal(data, 12345.12345) >>> from snap7 import Client >>> Client().db_write(db_number=1, start=10, data=data)

snap7.util.set_lword(bytearray_: bytearray, byte_index: int, lword: int) → bytearray[source]

Set the long word

Notes

Datatype lword (long word) consists in 8 bytes in the PLC. Maximum value is 18446744073709551615 (0xFFFFFFFFFFFFFFFF). Minimum value is 0.

Parameters:

bytearray – buffer to write to.
byte_index – byte index from where to start writing.
lword – unsigned 64-bit value to write.

Returns:

Buffer with the written value.

Examples

>>> data = bytearray(8)
>>> set_lword(data, 0, 0xABCD)
>>> data
bytearray(b'\x00\x00\x00\x00\x00\x00\xab\xcd')

snap7.util.set_real(bytearray_: bytearray, byte_index: int, real: bool | str | float | int) → bytearray[source]

Set Real value

Notes

Datatype real is represented in 4 bytes in the PLC. The packed representation uses the IEEE 754 binary32.

Parameters:

bytearray – buffer to write to.
byte_index – byte index to start writing from.
real – value to be written.

Returns:

Buffer with the value written.

Examples

>>> data = bytearray(4)
>>> set_real(data, 0, 123.321)
    bytearray(b'B\xf6\xa4Z')

snap7.util.set_sint(bytearray_: bytearray, byte_index: int, _int: int) → bytearray[source]

Set small int to the buffer.

Notes

Datatype sint (Small int) consists in 1 byte in the PLC. Maximum value posible is 127. Lowest value posible is -128.

Parameters:

bytearray –

buffer to write to.

byte_index: byte index from where to start writing. _int: value to write.

Returns:

Buffer with the written value.

Examples

>>> data = bytearray(1)
>>> set_sint(data, 0, 127)
    bytearray(b'\x7f')

snap7.util.set_string(bytearray_: bytearray, byte_index: int, value: str, max_size: int = 254) → bytearray[source]

Set string value

Parameters:

bytearray – buffer to write to.
byte_index – byte index to start writing from.
value – string to write.
max_size – maximum possible string size, max. 254 as default.

Raises:

TypeError – if the value is not a str.
ValueError – if the length of the value is larger than the max_size
or 'max_size' is greater than 254 or 'value' contains ascii characters > 255. –

Examples

>>> from snap7.util import set_string
>>> data = bytearray(20)
>>> set_string(data, 0, "hello world", 254)
>>> data
    bytearray(b'\xff\x0bhello world\x00\x00\x00\x00\x00\x00\x00')

snap7.util.set_time(bytearray_: bytearray, byte_index: int, time_string: str) → bytearray[source]

Set value in bytearray to time

Notes

Datatype time consists in 4 bytes in the PLC. Maximum possible value is T#24D_20H_31M_23S_647MS(2147483647). Lower posible value is T#-24D_20H_31M_23S_648MS(-2147483648).

Parameters:

bytearray – buffer to write.
byte_index – byte index from where to start writing.
time_string – time value in string

Examples

>>> data = bytearray(4)

>>> set_time(data, 0, '-22:3:57:28.192')

>>> data
    bytearray(b'Ú¯')

snap7.util.set_tod(bytearray_: bytearray, byte_index: int, tod: timedelta) → bytearray[source]

Set TIME_OF_DAY value in bytearray.

Notes

Datatype TIME_OF_DAY is stored as milliseconds since midnight in 4 bytes. Range: 0 to 86399999 ms (00:00:00.000 to 23:59:59.999).

Parameters:

bytearray – buffer to write to.
byte_index – byte index from where to start writing.
tod – timedelta representing the time of day.

Returns:

Buffer with the written value.

Examples

>>> from datetime import timedelta
>>> data = bytearray(4)
>>> set_tod(data, 0, timedelta(hours=12, minutes=30, seconds=15, milliseconds=500))

snap7.util.set_udint(bytearray_: bytearray, byte_index: int, udint: int) → bytearray[source]

Set value in bytearray to unsigned dint

Notes

Datatype dint consists in 4 bytes in the PLC. Maximum possible value is 4294967295. Minimum posible value is 0.

Parameters:

bytearray – buffer to write.
byte_index – byte index from where to start writing.
udint – unsigned double integer value

Examples

>>> data = bytearray(4)
>>> set_udint(data, 0, 4294967295)
>>> data
    bytearray(b'\xff\xff\xff\xff')

snap7.util.set_uint(bytearray_: bytearray, byte_index: int, _int: int) → bytearray[source]

Set value in bytearray to unsigned int

Notes

An datatype uint in the PLC consists of two bytes.

Parameters:

bytearray – buffer to write on.
byte_index – byte index to start writing from.
_int – int value to write.

Returns:

Buffer with the written value.

Examples

>>> from snap7.util import set_uint
>>> data = bytearray(2)
>>> set_uint(data, 0, 65535)
    bytearray(b'\xff\xff')

snap7.util.set_usint(bytearray_: bytearray, byte_index: int, _int: int) → bytearray[source]

Set unsigned small int

Notes

Datatype usint (Unsigned small int) consists on 1 byte in the PLC. Maximum posible value is 255. Lower posible value is 0.

Parameters:

bytearray –

buffer to write.

byte_index: byte index from where to start writing. _int: value to write.

Returns:

Buffer with the written value.

Examples

>>> data = bytearray(1)
>>> set_usint(data, 0, 255)
    bytearray(b'\xff')

snap7.util.set_wchar(bytearray_: bytearray, byte_index: int, chr_: str) → bytearray[source]

Set wchar value in a bytearray.

Notes

Datatype wchar in the PLC is represented in 2 bytes as UTF-16-BE.

Parameters:

bytearray – buffer to write to.
byte_index – byte index from where to start writing.
chr – single character to write.

Returns:

Buffer with the written value.

Examples

>>> data = bytearray(2)
>>> set_wchar(data, 0, 'C')
>>> data
bytearray(b'\x00C')

snap7.util.set_word(bytearray_: bytearray, byte_index: int, _int: int) → bytearray[source]

Set value in bytearray to word

Notes

Word datatype is 2 bytes long.

Parameters:

bytearray – buffer to be written.
byte_index – byte index to start write from.
_int – value to write.

Returns:

buffer with the written value

snap7.util.set_wstring(bytearray_: bytearray, byte_index: int, value: str, max_size: int = 16382) → None[source]

Set wstring value

Notes

Byte 0-1: max size (number of characters, 2-byte big-endian). Byte 2-3: current length (number of characters, 2-byte big-endian). Byte 4+: UTF-16-BE encoded characters (2 bytes each).

Parameters:

bytearray – buffer to write to.
byte_index – byte index to start writing from.
value – string to write.
max_size – maximum number of characters allowed (default 16382).

Raises:

TypeError – if the value is not a string.
ValueError – if the string is too long or max_size exceeds 16382.

Examples

>>> data = bytearray(26)
>>> set_wstring(data, 0, "hello", 10)