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