Client¶

Snap7 client used for connection to a siemens 7 server.

class snap7.client.Client(lib_location: str | None = None)[source]¶

A snap7 client

Examples

>>> import snap7
>>> client = snap7.client.Client()
>>> client.connect("127.0.0.1", 0, 0, 1102)
>>> client.get_connected()
True
>>> data = client.db_read(1, 0, 4)
>>> data
bytearray(b"\x00\x00\x00\x00")
>>> data[3] = 0b00000001
>>> data
bytearray(b'\x00\x00\x00\x01')
>>> client.db_write(1, 0, data)

__init__(lib_location: str | None = None)[source]¶

Creates a new Client instance.

Parameters:: lib_location – Full path to the snap7.dll file. Optional.

Examples

>>> import snap7
>>> client = snap7.client.Client()  # If the `snap7.dll` file is in the path location
>>> client2 = snap7.client.Client(lib_location="/path/to/snap7.dll")  # If the dll is in another location
<snap7.client.Client object at 0x0000028B257128E0>

ab_read(start: int, size: int) → bytearray[source]¶

Reads a part of IPU area from a PLC.

Parameters:

start – byte index from where start to read.
size – amount of bytes to read.

Returns:

Buffer with the data read.

ab_write(start: int, data: bytearray) → int[source]¶

Writes a part of IPU area into a PLC.

Parameters:

start – byte index from where start to write.
data – buffer with the data to be written.

Returns:

Snap7 code.

Reads a part of IPU area from a PLC asynchronously.

Parameters:

start – byte index from where start to read.
size – amount of bytes to read.
data – buffer where the data will be place.

Returns:

Snap7 code.

as_ab_write(start: int, data: bytearray) → int[source]¶

Writes a part of IPU area into a PLC asynchronously.

Parameters:

start – byte index from where start to write.
data – buffer with the data to be written.

Returns:

Snap7 code.

as_compress(time: int) → int[source]¶

Performs the Compress action asynchronously.

Parameters:: time – timeout.
Returns:: Snap7 code.

as_copy_ram_to_rom(timeout: int = 1) → int[source]¶

Performs the Copy Ram to Rom action asynchronously.

Parameters:: timeout – time to wait until fail.
Returns:: Snap7 code.

Reads counters from a PLC asynchronously.

Parameters:

start – byte index to start to read from.
amount – amount of bytes to read.
data – buffer where the value read will be place.

Returns:

Snap7 code.

as_ct_write(start: int, amount: int, data: bytearray) → int[source]¶

Write counters into a PLC.

Parameters:

start – byte index to start to write from.
amount – amount of bytes to write.
data – buffer to write.

Returns:

Snap7 code.

as_db_fill(db_number: int, filler: int) → int[source]¶

Fills a DB in AG with a given byte.

Parameters:

db_number – number of DB to fill.
filler – buffer to fill with.

Returns:

Snap7 code.

Uploads a DB from AG using DBRead.

Note

This method will not work in 1200/1500.

Parameters:

db_number – number of DB to get.
data – buffer where the data read will be place.
size – amount of bytes to be read.

Returns:

Snap7 code.

Reads a part of a DB from a PLC.

Parameters:

db_number – number of DB to be read.
start – byte index from where start to read from.
size – amount of bytes to read.
data – buffer where the data read will be place.

Returns:

Snap7 code.

Examples

>>> import ctypes
>>> content = (ctypes.c_uint8 * size)()  # In this ctypes array data will be stored.
>>> Client().as_db_read(1, 0, size, content)
0

Writes a part of a DB into a PLC.

Parameters:

db_number – number of DB to be written.
start – byte index from where start to write to.
size – amount of bytes to write.
data – buffer to be written.

Returns:

Snap7 code.

as_download(data: bytearray, block_num: int) → int[source]¶

Download a block into AG asynchronously.

Note

A whole block (including header and footer) must be available into the user buffer.

Parameters:

block_num – new block number.
data – buffer where the data will be place.

Returns:

Snap7 code.

Reads a part of IPI area from a PLC asynchronously.

Parameters:

start – byte index from where to start reading from.
size – amount of bytes to read.
data – buffer where the data read will be place.

Returns:

Snap7 code.

as_eb_write(start: int, size: int, data: bytearray) → int[source]¶

Writes a part of IPI area into a PLC.

Parameters:

start – byte index from where to start writing from.
size – amount of bytes to write.
data – buffer to write.

Returns:

Snap7 code.

as_full_upload(block_type: Block, block_num: int) → int[source]¶

Uploads a block from AG with Header and Footer infos.

Note

Upload means from PLC to PC.

Parameters:

block_type – type of block.
block_num – number of block to upload.

Returns:

Snap7 code.

Returns the AG blocks list of a given type.

Parameters:

block_type – block type.
data – buffer where the data will be place.
count – pass.

Returns:

Snap7 code.

Reads a part of Markers area from a PLC.

Parameters:

start – byte index from where to start to read from.
size – amount of byte to read.
data – buffer where the data read will be place.

Returns:

Snap7 code.

as_mb_write(start: int, size: int, data: bytearray) → int[source]¶

Writes a part of Markers area into a PLC.

Parameters:

start – byte index from where to start to write to.
size – amount of byte to write.
data – buffer to write.

Returns:

Snap7 code.

Reads a data area from a PLC asynchronously. With this you can read DB, Inputs, Outputs, Markers, Timers and Counters.

Parameters:

area – memory area to be read from.
db_number – The DB number, only used when area=Areas.DB
start – offset to start writing
size – number of units to read
data – buffer where the data will be place.
word_len – length of the word to be read.

Returns:

Snap7 code.

as_read_szl(id_: int, index: int, data: S7SZL, size: int) → int[source]¶

Reads a partial list of given ID and Index.

Parameters:

id – The list ID
index – The list index
data – the user buffer
size – buffer size available

Returns:

Snap7 code.

as_read_szl_list(data: S7SZLList, items_count: int) → int[source]¶

Reads the list of partial lists available in the CPU.

Parameters:

data – the user buffer list
items_count – buffer capacity

Returns:

Snap7 code.

Reads timers from a PLC.

Parameters:

start – byte index to start read from.
amount – amount of bytes to read.
data – buffer where the data will be placed.

Returns:

Snap7 code.

as_tm_write(start: int, amount: int, data: bytearray) → int[source]¶

Write timers into a PLC.

Parameters:

start – byte index to start writing to.
amount – amount of bytes to write.
data – buffer to write.

Returns:

Snap7 code.

Uploads a block from AG.

Note

Uploads means from PLC to PC.

Parameters:

block_num – block number to upload.
data – buffer where the data will be place.
size – amount of bytes to upload.

Returns:

Snap7 code.

Writes a data area into a PLC asynchronously.

Parameters:

area – memory area to be written.
db_number – The DB number, only used when area=Areas.DB
start – offset to start writing.
size – amount of bytes to be written.
word_len – length of the word to be written.
data – buffer to be written.

Returns:

Snap7 code.

check_as_completion(p_value: c_int) → int[source]¶

Method to check Status of an async request.

Result contains if the check was successful, not the data value itself

Parameters:: p_value – Pointer where result of this check shall be written.
Returns:: Snap7 code. If 0 - Job is done successfully. If 1 - Job is either pending or contains s7errors

connect(address: str, rack: int, slot: int, tcp_port: int = 102) → Client[source]¶

Connects a Client Object to a PLC.

Parameters:

address – IP address of the PLC.
rack – rack number where the PLC is located.
slot – slot number where the CPU is located.
tcp_port – port of the PLC.

Returns:

The snap7 Logo instance

Example

>>> import snap7
>>> client = snap7.client.Client()
>>> client.connect("192.168.0.1", 0, 0)  # port is implicit = 102.

copy_ram_to_rom(timeout: int = 1) → int[source]¶

Performs the Copy Ram to Rom action.

Parameters:: timeout – timeout time.
Returns:: Snap7 code.

create() → None[source]¶: Creates a SNAP7 client.

ct_read(start: int, amount: int) → bytearray[source]¶

Reads counters from a PLC.

Parameters:

start – byte index to start read from.
amount – amount of bytes to read.

Returns:

Buffer read.

ct_write(start: int, amount: int, data: bytearray) → int[source]¶

Write counters into a PLC.

Parameters:

start – byte index to start write to.
amount – amount of bytes to write.
data – buffer data to write.

Returns:

Snap7 code.

db_fill(db_number: int, filler: int) → int[source]¶

Fills a DB in AG with a given byte.

Parameters:

db_number – db number to fill.
filler – value filler.

Returns:

Snap7 code.

db_get(db_number: int) → bytearray[source]¶

Uploads a DB from AG using DBRead.

Note

This method can’t be used for 1200/1500 PLCs.

Parameters:: db_number – db number to be read from.
Returns:: Buffer with the data read.

Example

>>> import snap7
>>> client = snap7.client.Client()
>>> client.connect("192.168.0.1", 0, 0)
>>> buffer = client.db_get(1)  # reads the db number 1.
>>> buffer
bytearray(b"\x00\x00\x00\x00\x00\x00\x00\x00...<truncated>\x00\x00")

db_read(db_number: int, start: int, size: int) → bytearray[source]¶

Reads a part of a DB from a PLC

Note

Use it only for reading DBs, not Marks, Inputs, Outputs.

Parameters:

db_number – number of the DB to be read.
start – byte index from where is start to read from.
size – amount of bytes to be read.

Returns:

Buffer read.

Example

>>> import snap7
>>> client = snap7.client.Client()
>>> client.connect("192.168.0.1", 0, 0)
>>> buffer = client.db_read(1, 10, 4)  # reads the db number 1 starting from the byte 10 until byte 14.
>>> buffer
bytearray(b'\x00\x00')

delete(block_type: Block, block_num: int) → int[source]¶

Delete a block into AG.

Parameters:

block_type – type of block.
block_num – block number.

Returns:

Error code from snap7 library.

destroy() → int | None[source]¶

Destroys the Client object.

Returns:: Error code from snap7 library.

Examples

>>> Client().destroy()
640719840

eb_read(start: int, size: int) → bytearray[source]¶

Reads a part of IPI area from a PLC.

Parameters:

start – byte index to start read from.
size – amount of bytes to read.

Returns:

Data read.

eb_write(start: int, size: int, data: bytearray) → int[source]¶

Writes a part of IPI area into a PLC.

Parameters:

start – byte index to be written.
size – amount of bytes to write.
data – data to write.

Returns:

Snap7 code.

error_text(error: int) → str[source]¶

Returns a textual explanation of a given error number.

Parameters:: error – error number.
Returns:: Text error.

full_upload(block_type: Block, block_num: int) → Tuple[bytearray, int][source]¶

Uploads a block from AG with Header and Footer infos. The whole block (including header and footer) is copied into the user buffer.

Parameters:

block_type – type of block.
block_num – number of block.

Returns:

Tuple of the buffer and size.

get_block_info(block_type: Block, db_number: int) → TS7BlockInfo[source]¶

Returns detailed information about a block present in AG.

Parameters:

block_type – specified block type.
db_number – number of db to get information from.

Returns:

Structure of information from block.

Raises:

ValueError – if the blocktype is not valid.

Examples

>>> block_info = Client().get_block_info("DB", 1)
>>> print(block_info)
Block type: 10
Block number: 1
Block language: 5
Block flags: 1
MC7Size: 100
Load memory size: 192
Local data: 0
SBB Length: 20
Checksum: 0
Version: 1
Code date: b'1999/11/17'
Interface date: b'1999/11/17'
Author: b''
Family: b''
Header: b''

get_connected() → bool[source]¶

Returns the connection status

Note

Sometimes returns True, while connection is lost.

Returns:: True if is connected, otherwise false.

get_cp_info() → S7CpInfo[source]¶

Returns some information about the CP (communication processor).

Returns:: Structure object containing the CP information.

get_cpu_info() → S7CpuInfo[source]¶

Returns some information about the AG.

Returns:: data structure with the information.
Return type:: S7CpuInfo

Examples

>>> cpu_info = Client().get_cpu_info()
>>> print(cpu_info)
<S7CpuInfo ModuleTypeName: b'CPU 315-2 PN/DP'
    SerialNumber: b'S C-C2UR28922012'
    ASName: b'SNAP7-SERVER' Copyright: b'Original Siemens Equipment'
    ModuleName: 'CPU 315-2 PN/DP' >

get_cpu_state() → str[source]¶

Returns the CPU status (running/stopped)

Returns:: Description of the cpu state.
Raises:: ValueError – if the cpu state is invalid.

Examples

>>> Client().get_cpu_state()
'S7CpuStatusRun'

get_exec_time() → int[source]¶

Returns the last job execution time in milliseconds.

Returns:: Execution time value.

get_last_error() → int[source]¶

Returns the last job result.

Returns:: Returns the last error value.

get_order_code() → S7OrderCode[source]¶

Returns the CPU order code.

Returns:: Order of the code in a structure object.

get_param(parameter: Parameter) → int[source]¶

Reads an internal Server parameter.

Parameters:: parameter – number of argument to be read.
Returns:: Value of the param read.

get_pdu_length() → int[source]¶

Returns info about the PDU length (requested and negotiated).

Returns:: PDU length.

Examples

>>> Client().get_pdu_length()
480

get_pg_block_info(block: bytearray) → TS7BlockInfo[source]¶

Returns detailed information about a block loaded in memory.

Parameters:: block – buffer where the data will be place.
Returns:: Structure object that contains the block information.

get_plc_datetime() → datetime[source]¶

Returns the PLC date/time.

Returns:: Date and time as datetime

Examples

>>> Client().get_plc_datetime()
datetime.datetime(2021, 4, 6, 12, 12, 36)

get_protection() → S7Protection[source]¶

Gets the CPU protection level info.

Returns:: Structure object with protection attributes.

iso_exchange_buffer(data: bytearray) → bytearray[source]¶

Exchanges a given S7 PDU (protocol data unit) with the CPU.

Parameters:: data – buffer to exchange.
Returns:: Snap7 code.

list_blocks() → BlocksList[source]¶

Returns the AG blocks amount divided by type.

Returns:: Block list structure object.

Examples

>>> print(Client().list_blocks())
<block list count OB: 0 FB: 0 FC: 0 SFB: 0 SFC: 0x0 DB: 1 SDB: 0>

list_blocks_of_type(block_type: Block, size: int) → int | Array[c_ushort][source]¶

This function returns the AG list of a specified block type.

Parameters:

block_type – specified block type.
size – size of the block type.

Returns:

If size is 0, it returns a 0, otherwise an Array of specified block type.

Raises:

ValueError – if the block_type is not valid.

mb_read(start: int, size: int) → bytearray[source]¶

Reads a part of Markers area from a PLC.

Parameters:

start – byte index to be read from.
size – amount of bytes to read.

Returns:

Buffer with the data read.

mb_write(start: int, size: int, data: bytearray) → int[source]¶

Writes a part of Markers area into a PLC.

Parameters:

start – byte index to be written.
size – amount of bytes to write.
data – buffer to write.

Returns:

Snap7 code.

plc_cold_start() → int[source]¶

Puts the CPU in RUN mode performing a COLD START.

Returns:: Error code from snap7 library.

plc_hot_start() → int[source]¶

Puts the CPU in RUN mode performing an HOT START.

Returns:: Error code from snap7 library.

plc_stop() → int[source]¶

Puts the CPU in STOP mode

Returns:: Error code from snap7 library.

read_area(area: Area, db_number: int, start: int, size: int) → bytearray[source]¶

Read a data area from a PLC

With this you can read DB, Inputs, Outputs, Merkers, Timers and Counters.

Parameters:

area – area to be read from.
db_number – The DB number, only used when area=Areas.DB
start – byte index to start reading.
size – number of bytes to read.

Returns:

Buffer with the data read.

Example

>>> from snap7 import Client, Area
>>> Client().connect("192.168.0.1", 0, 0)
>>> buffer = Client().read_area(Area.DB, 1, 10, 4)  # Reads the DB number 1 from the byte 10 to the byte 14.
>>> buffer
bytearray(b'\x00\x00')

read_multi_vars(items: Array[S7DataItem]) → Tuple[int, Array[S7DataItem]][source]¶

Reads different kind of variables from a PLC simultaneously.

Parameters:: items – list of items to be read.
Returns:: Tuple of the return code from the snap7 library and the list of items.

read_szl(id_: int, index: int = 0) → S7SZL[source]¶

Reads a partial list of given ID and Index.

Parameters:

id – ssl id to be read.
index – index to be read.

Returns:

SZL structure object.

read_szl_list() → bytearray[source]¶

Reads the list of partial lists available in the CPU.

Returns:: Buffer read.

set_as_callback(call_back: Callable[[...], Any]) → int[source]¶: Sets the user callback that is called when an asynchronous data sent is complete.

set_connection_params(address: str, local_tsap: int, remote_tsap: int) → None[source]¶

Sets internally (IP, LocalTSAP, RemoteTSAP) Coordinates.

Note

This function must be called just before Cli_Connect().

Parameters:

address – PLC/Equipment IPV4 Address, for example “192.168.1.12”
local_tsap – Local TSAP (PC TSAP)
remote_tsap – Remote TSAP (PLC TSAP)

Raises:

ValueError – if the address is not a valid IPV4.
ValueError – if the result of setting the connection params is different from 0.

set_connection_type(connection_type: int) → None[source]¶

Sets the connection resource type, i.e. the way in which the Clients connect to a PLC.

Parameters:: connection_type – 1 for PG, 2 for OP, 3 to 10 for S7 Basic
Raises:: ValueError – if the result of setting the connection type is different from 0.

set_plc_system_datetime() → int[source]¶

Sets the PLC date/time with the host (PC) date/time.

Returns:: Snap7 code.

tm_read(start: int, amount: int) → bytearray[source]¶

Reads timers from a PLC.

Parameters:

start – byte index from where is start to read from.
amount – amount of byte to be read.

Returns:

Buffer read.

tm_write(start: int, amount: int, data: bytearray) → int[source]¶

Write timers into a PLC.

Parameters:

start – byte index from where is start to write to.
amount – amount of byte to be written.
data – data to be written.

Returns:

Snap7 code.

upload(block_num: int) → bytearray[source]¶

Uploads a block from AG.

Note

Upload means from the PLC to the PC.

Parameters:: block_num – block to be uploaded.
Returns:: Buffer with the uploaded block.

wait_as_completion(timeout: int) → int[source]¶

Snap7 Cli_WaitAsCompletion representative.

Parameters:: timeout – ms to wait for async job
Returns:: Snap7 code.

write_multi_vars(items: List[S7DataItem]) → int[source]¶

Writes different kind of variables into a PLC simultaneously.

Parameters:: items – list of items to be written.
Returns:: Snap7 code.

Client¶

Table of Contents

Previous topic

Next topic

This Page