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_lreal(bytearray_: bytearray, byte_index: int) → float[source]

Get 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.

Returns:

Value read.

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_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.

Notes

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_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) → None[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_dword(bytearray_: bytearray, byte_index: int, dword: int) → None[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) → None[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_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) → None[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 non-ascii characters. –

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_udint(bytearray_: bytearray, byte_index: int, udint: int) → None[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_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