Client

Snap7 client used for connection to a siemens 7 server.

class snap7.client.Client(lib_location: Optional[str] = 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: Optional[str] = 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
>>> client = snap7.client.Client(lib_location="/path/to/snap7.dll")  # If the `snap7.dll` file is in another location
>>> client
<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.

as_ab_read(start: int, size: int, data) → int[source]

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 unly fail.
Returns:Snap7 code.
as_ct_read(start: int, amount: int, data) → int[source]

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 be write.
Returns:

Snap7 code.

as_db_fill(db_number: int, filler) → 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.

as_db_get(db_number: int, _buffer, size) → bytearray[source]

Uploads a DB from AG using DBRead.

Note

This method will not work in 1200/1500.

Parameters:
  • db_number – number of DB to get.
  • _buffer – buffer where the data read will be place.
  • size – amount of bytes to be read.
Returns:

Snap7 code.

as_db_read(db_number: int, start: int, size: int, data) → _ctypes.Array[source]

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
>>> data = (ctypes.c_uint8 * size_to_read)()  # In this ctypes array data will be stored.
>>> result = client.as_db_read(1, 0, size_to_read, data)
>>> result  # 0 = success
0
as_db_write(db_number: int, start: int, size: int, data) → int[source]

Writes a part of a DB into a PLC.

Parameters:
  • db_number – number of DB to be write.
  • start – byte index from where start to write to.
  • size – amount of bytes to write.
  • data – buffer to be write.
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.

as_eb_read(start: int, size: int, data) → int[source]

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(_type: str, block_num: int) → int[source]

Uploads a block from AG with Header and Footer infos.

Note

Upload means from PLC to PC.

Parameters:
  • _type – type of block.
  • block_num – number of block to upload.
Returns:

Snap7 code.

as_list_blocks_of_type(blocktype: str, data, count) → int[source]

Returns the AG blocks list of a given type.

Parameters:
  • blocktype – block type.
  • data – buffer where the data will be place.
  • count – pass.
Returns:

Snap7 code.

Raises:

ValueError – if the blocktype is invalid

as_mb_read(start: int, size: int, data) → int[source]

Reads a part of Merkers 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 Merkers 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.

as_read_area(area: snap7.types.Areas, dbnumber: int, start: int, size: int, wordlen: snap7.types.WordLen, pusrdata) → int[source]

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

Parameters:
  • area – memory area to be read from.
  • dbnumber – The DB number, only used when area=Areas.DB
  • start – offset to start writing
  • size – number of units to read
  • pusrdata – buffer where the data will be place.
  • wordlen – length of the word to be read.
Returns:

Snap7 code.

as_read_szl(ssl_id: int, index: int, s7_szl: snap7.types.S7SZL, size) → int[source]

Reads a partial list of given ID and Index.

Parameters:
  • ssl_id – TODO
  • index – TODO
  • s7_szl – TODO
  • size – TODO
Returns:

Snap7 code.

as_read_szl_list(szl_list, items_count) → int[source]

Reads the list of partial lists available in the CPU.

Parameters:
  • szl_list – TODO
  • items_count – TODO
Returns:

Snap7 code.

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

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.

as_upload(block_num: int, _buffer, size) → int[source]

Uploads a block from AG.

Note

Uploads means from PLC to PC.

Parameters:
  • block_num – block number to upload.
  • _buffer – buffer where the data will be place.
  • size – amount of bytes to uplaod.
Returns:

Snap7 code.

as_write_area(area: snap7.types.Areas, dbnumber: int, start: int, size: int, wordlen: snap7.types.WordLen, pusrdata) → int[source]

Writes a data area into a PLC asynchronously.

Parameters:
  • area – memory area to be written.
  • dbnumber – The DB number, only used when area=Areas.DB
  • start – offset to start writing.
  • size – amount of bytes to be written.
  • wordlen – length of the word to be written.
  • pusrdata – buffer to be written.
Returns:

Snap7 code.

check_as_completion(p_value) → 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
copy_ram_to_rom(timeout: int = 1) → int[source]

Performs the Copy Ram to Rom action.

Parameters:timeout – timeout time.
Returns:Snap7 code.
create()[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 use 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: str, 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() → Optional[int][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(_type: str, 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:
  • _type – type of block.
  • block_num – number of block.
Returns:

Tuple of the buffer and size.

get_block_info(blocktype: str, db_number: int) → snap7.types.TS7BlockInfo[source]

Returns detailed information about a block present in AG.

Parameters:
  • blocktype – 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() → snap7.types.S7CpInfo[source]

Returns some information about the CP (communication processor).

Returns:Structure object containing the CP information.
get_cpu_info() → snap7.types.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: b'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() → snap7.types.S7OrderCode[source]

Returns the CPU order code.

Returns:Order of the code in a structure object.
get_param(number: int) → int[source]

Reads an internal Server parameter.

Parameters:number – 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) → snap7.types.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.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() → snap7.types.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() → snap7.types.BlocksList[source]

Returns the AG blocks amount divided by type.

Returns:Block list structure object.

Examples

>>> block_list = client.list_blocks()
>>> print(block_list)
<block list count OB: 0 FB: 0 FC: 0 SFB: 0 SFC: 0x0 DB: 1 SDB: 0>
list_blocks_of_type(blocktype: str, size: int) → Union[int, _ctypes.Array][source]

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

Parameters:
  • blocktype – 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 blocktype is not valid.

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

Reads a part of Merkers 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 Merkers 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: snap7.types.Areas, dbnumber: int, start: int, size: int) → bytearray[source]

Reads a data area from a PLC With it you can read DB, Inputs, Outputs, Merkers, Timers and Counters.

Parameters:
  • area – area to be read from.
  • dbnumber – number of the db to be read from. In case of Inputs, Marks or Outputs, this should be equal to 0.
  • start – byte index to start reading.
  • size – number of bytes to read.
Returns:

Buffer with the data read.

Raises:

ValueError – if the area is not defined in the Areas

Example

>>> import snap7
>>> client = snap7.client.Client()
>>> client.connect("192.168.0.1", 0, 0)
>>> buffer = client.read_area(Areas.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) → Tuple[int, snap7.types.S7DataItem][source]

Reads different kind of variables from a PLC simultaneously.

Parameters:items – list of items to be read.
Returns:Tuple with the return code from the snap7 library and the list of items.
read_szl(ssl_id: int, index: int = 0) → snap7.types.S7SZL[source]

Reads a partial list of given ID and Index.

Parameters:
  • ssl_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_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 than 0.
set_connection_type(connection_type: int)[source]

Sets the connection resource type, i.e the way in which the Clients connects 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 than 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 write.
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 upload.
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[snap7.types.S7DataItem]) → int[source]

Writes different kind of variables into a PLC simultaneously.

Parameters:items – list of items to be written.
Returns:Snap7 code.
snap7.client.error_wrap(func)[source]

Parses a s7 error code returned the decorated function.