Pure native python snap7

[gijzelaerr]

Pure Python S7 Protocol Implementation

This PR replaces the C library (Snap7) dependency with a pure Python implementation of the S7 protocol.

What's changing

We're switching to a pure Python implementation of the S7 protocol - no more C library dependency! This means:

• Easier installation (no compiling, no binary dependencies)
• Works on any platform Python runs on
• Easier to debug and extend

The new implementation was developed with the help of Claude AI (Anthropic's coding assistant), which helped implement the S7 protocol from scratch based on protocol documentation and testing.

We need testers!

I don't own a PLC myself, so I'm looking for volunteers who can test this against real hardware.

Compatible PLCs (S7 protocol)

If you have any of these, we'd love your help:

Series	Models
S7-1200	CPU 1211C, 1212C, 1214C, 1215C, 1217C
S7-1500	CPU 1511, 1513, 1515, 1516, 1517, 1518
S7-300	CPU 312, 313, 314, 315, 317, 318, 319
S7-400	CPU 412, 414, 416, 417
LOGO!	0BA7, 0BA8 (with Ethernet)
S7-200 Smart	Various models
WinAC	Software PLCs

Also compatible with S7 protocol simulators like PLCSIM Advanced, NetToPLCSim, etc.

How to test

1. Install the test version

pip install git+https://github.com/gijzelaerr/python-snap7.git@native

2. Configure your PLC

• Enable "Permit access with PUT/GET" in TIA Portal (for S7-1200/1500)
• Create two Data Blocks:
  • DB1 "Read_only" with test values
  • DB2 "Read_write" for write tests
• See the test file header for the exact DB structure

3. Run the tests

# Clone the repo
git clone -b native https://github.com/gijzelaerr/python-snap7.git
cd python-snap7

# Install with test dependencies
pip install -e ".[test]"

# Run e2e tests with your PLC settings
pytest tests/test_client_e2e.py --e2e \
    --plc-ip=YOUR_PLC_IP \
    --plc-rack=0 \
    --plc-slot=1 \
    -v --html=report.html

Available options:

Option	Default	Description
--e2e	(required)	Enable e2e tests
--plc-ip	10.10.10.100	PLC IP address
--plc-rack	0	Rack number
--plc-slot	1	Slot number
--plc-port	102	TCP port
--plc-db-read	1	Read-only DB number
--plc-db-write	2	Read-write DB number

4. Share your results

Please comment on this PR with:

• Your PLC model and firmware version
• Which tests passed/failed
• The HTML report if possible

Quick smoke test

If you just want to do a quick test:

from snap7.client import Client

client = Client()
client.connect("YOUR_PLC_IP", 0, 1)  # IP, rack, slot
print(f"Connected: {client.get_connected()}")
print(f"CPU state: {client.get_cpu_state()}")

# Read 10 bytes from DB1 at offset 0
data = client.db_read(1, 0, 10)
print(f"Data: {data.hex()}")

client.disconnect()

Current status

✅ Working:

• Connection/disconnection
• DB read/write (all data types)
• Multi-var read/write
• CPU state, PDU length
• Order code, PLC datetime

⚠️ May vary by PLC model:

• SZL reads (some IDs not available on S7-1200/1500)
• Block listing
• CPU info

---

Thanks for any help! Every test against real hardware helps make this library better.

[lupaulus]

Needs to be reworked and reviewed with real tests

[gijzelaerr]

it would be more useful if the comment was a bit more specific.

[gijzelaerr]

meanwhile i found a couple of problems where the AI has fooled me (implement fake calls in the client), i'm fixing those now.

[lupaulus]

Yeah IA is great to start but then you need to review it because she is "lazy" and don't do the task entirely

[amorelettronico]

Tested on CPU 414-5H PN/DP 414-5HM06-0AB0

pytest-html is not available in the test.

[project.optional-dependencies]
test = ["pytest", "mypy", "types-setuptools", "ruff", "tox", "tox-uv", "types-click", "uv"]

First connection failed and adding -s showed that the plc ip changed from the command line did not work.
Setting them as env vars works.

tests/test_client_e2e.py --e2e \
    --plc-ip=YOUR_PLC_IP \
    --plc-rack=0 \
    --plc-slot=1 \
    -v --html=report.html -s

The 414-5h seems not to accept the TPDU parameter. The CC frame was not received.
Change _build_cotp_cr in connection.py to match the length of 22 bytes.

    def _build_cotp_cr(self) -> bytes:
        # COTP fixed part (excluding length byte)
        fixed = struct.pack(
            ">BHHB",
            self.COTP_CR,   # 0xE0
            0x0000,         # dst ref
            self.src_ref,   # src ref
            0x00,           # class/options
        )

        calling_tsap = struct.pack(">BBH", 0xC1, 2, self.local_tsap)
        called_tsap  = struct.pack(">BBH", 0xC2, 2, self.remote_tsap)

        # TPDU size code (not a 16-bit int!)
        # choose based on desired size; default 1024 => 0xF0
        tpdu_code = 0x0A
        tpdu_size = struct.pack(">BBB", 0xC0, 1, tpdu_code)

        params = calling_tsap + called_tsap + tpdu_size

        # length excludes this length byte
        length = len(fixed) + len(params)
        return struct.pack(">B", length) + fixed + params

Afther those changes some test failed. See attachement.

report_first_run.html

[gijzelaerr]

@amorelettronico Thanks for the detailed testing on your CPU 414-5H PN/DP! I've pushed a commit to the native branch that addresses all the issues you found:

COTP connection fix:

• TPDU size parameter now uses the 1-byte ISO 8073 code (0xC0, 0x01, 0x0A) instead of the 2-byte raw value, matching how the Snap7 C library encodes it. This should fix the connection failure on your 414-5H.

USERDATA protocol fixes (block/SZL operations):

• Fixed request data headers (RetVal/TransportSize bytes) for read_szl, list_blocks_of_type, and get_block_info to match the Snap7 C library encoding
• get_block_info now encodes block number as 5-digit zero-padded ASCII (matching TS7ReqSZLData format)
• list_blocks_of_type response parsing now handles 4-byte items (was incorrectly parsing 2-byte items)
• get_block_info response parsing rewritten with correct field offsets per TResDataBlockInfo
• Added return code checking on data section responses
• Server response formats updated to match (78-byte block info, 12-byte USERDATA params)

db_get fix:

• Now queries actual DB size via get_block_info instead of hardcoded 1024

CLI options fix:

• Added pytest_sessionstart hook so --plc-ip and other CLI options actually propagate to the e2e test module

Test resilience:

• SZL-dependent e2e tests (test_read_szl, test_get_cpu_info, test_get_cp_info, test_get_order_code, test_get_protection, test_read_szl_list) now skip gracefully if the SZL object doesn't exist on the PLC
• Added pytest-html to test dependencies

All 390 existing unit/integration tests still pass. Could you re-test with the latest native branch on your 414-5H?

[razour08]

✅ Test Report — Pure Python snap7 (native branch)

Hey @gijzelaerr! I tested the native branch on my machine. Here are the results:

🖥️ Environment

Item	Value
OS	Windows 11 (AMD64)
Python	3.13.5
Branch	native @ bc9a8c3
Install method	pip install git+...@native

📊 Smoke Test Results — 7/7 Passed

Test	Status
Client import & creation	✅ PASS
Server import & creation	✅ PASS
Util module (40 exports)	✅ PASS
Type definitions (Areas, WordLen, S7DataItem)	✅ PASS
Util byte operations (int, bool, real)	✅ PASS
Partner import & creation	✅ PASS
Logo import & creation	✅ PASS

💡 Notes

• All modules import and instantiate without issues — no C library dependency needed 🎉
• get/set_int, get/set_bool, get/set_real byte operations all produce correct values
• I don't have access to a physical PLC for end-to-end testing, but all unit-level functionality works perfectly on Windows

Great work on this! The pure Python implementation is a huge improvement for installation simplicity. Happy to run more tests if needed.

[spreeker]

Awesome!

…

On Sun, 22 Feb 2026, 14:02 Dekali Ramzi, ***@***.***> wrote: *razour08* left a comment (gijzelaerr/python-snap7#569) <#569 (comment)> ✅ Test Report — Pure Python snap7 (native branch) Hey @gijzelaerr <https://github.com/gijzelaerr>! I tested the native branch on my machine. Here are the results: 🖥️ Environment Item Value *OS* Windows 11 (AMD64) *Python* 3.13.5 *Branch* native @ bc9a8c3 *Install method* pip install ***@***.*** 📊 Smoke Test Results — 7/7 Passed Test Status Client import & creation ✅ PASS Server import & creation ✅ PASS Util module (40 exports) ✅ PASS Type definitions (Areas, WordLen, S7DataItem) ✅ PASS Util byte operations (int, bool, real) ✅ PASS Partner import & creation ✅ PASS Logo import & creation ✅ PASS 💡 Notes - All modules import and instantiate without issues — *no C library dependency needed* 🎉 - get/set_int, get/set_bool, get/set_real byte operations all produce correct values - I don't have access to a physical PLC for end-to-end testing, but all unit-level functionality works perfectly on Windows Great work on this! The pure Python implementation is a huge improvement for installation simplicity. Happy to run more tests if needed. Capture.d.ecran.2026-02-22.140100.png (view on web) <https://github.com/user-attachments/assets/af2d9e5c-cace-44c1-9a27-67116d95fc1c> — Reply to this email directly, view it on GitHub <#569 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAOSMPDVHKR2UDHZB3GFQ34NGSEZAVCNFSM6AAAAACGHYOS2GVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTSNBQHEYDCMBVGM> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[amorelettronico]

Hello @gijzelaerr,

Sure, i tested the latest native branch. There are 5 failed test left. Unfortunaly I was not able to use the arguments on the commandline for the host IP and slot no, so i used the env vars instead.

Will test other hardware also if you're intersted.

report.html

[amorelettronico]

Hi @gijzelaerr,

When the env var is set to use a other db then DB1,DB2 tt fails because there is a hard coded DB_READ to DB1 in:
tests/test_client_e2e.py::TestClientDBWrite::test_db_write_int

self = <test_client_e2e.TestClientDBWrite testMethod=test_db_write_int>

    def test_db_write_int(self) -> None:
        """Test db_write() for Int values."""
        test_value = 10
        data = bytearray(2)
        set_int(data, 0, test_value)
        self.client.db_write(DB_READ_WRITE, OFFSET_INT1, data)
    
        # Read back and verify
>       result = self.client.db_read(1, OFFSET_INT1, 2)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

[gijzelaerr]

@amorelettronico Thanks again for the thorough testing on your CPU 414-5H PN/DP! I've pushed a new commit (a1dac86) that addresses all the issues you reported:

Protocol fixes (affects all USERDATA operations):

• DataRef byte — Changed from incrementing sequence number to 0x00 for initial requests across all 6 USERDATA methods. This was causing the PLC to reject every USERDATA request.
• Data section headers — Fixed RetVal/TransSize from 0xFF/0x09 to 0x0A/0x00 in list_blocks_of_type, get_block_info, and read_szl to match the Snap7 C library encoding.
• list_blocks_of_type payload — Extended from 2 to 4 bytes per the C library format.

Test/infrastructure fixes:

• Hardcoded DB number — Fixed db_read(1, ...) → db_read(DB_READ_WRITE, ...) in test_db_write_int.
• CLI args not propagating — Replaced pytest_sessionstart (which failed silently) with sys.modules lookup in pytest_collection_modifyitems, so --plc-ip, --plc-slot, --plc-db-read, etc. now work correctly.
• db_get fallback — No longer silently falls back to reading 1024 bytes when get_block_info fails; errors now propagate cleanly.
• Graceful skips — Block operation tests (list_blocks, list_blocks_of_type, get_block_info) now skip gracefully if the PLC doesn't support them.

All tox environments pass (mypy, ruff, py3.10–3.14). Could you give this another test on your PLC when you get a chance? The USERDATA fixes should resolve the 5 failing tests you saw. 🙏

[gijzelaerr]

Thanks for flagging the multi-packet USERDATA response issue @nikteliy, and for the pcap test data!

Implemented in e4e47bb:

• Parse last_data_unit byte from USERDATA response parameters (byte 9: 0x00 = done, non-zero = more data)
• Follow-up request builder using DataRef = sequence number from the response
• Fragment-aware SZL parsing (first_fragment flag — follow-up packets don't include SZL ID+Index header)
• Multi-packet accumulation loops in both read_szl() and list_blocks_of_type() (max 100 iterations safety limit)
• Backward-compatible: single-packet responses hit last_data_unit==0x00 and skip the loop

New test suite in tests/test_multipacket.py includes an integration test using your real pcap data (the 2-packet SZL 0x001C response). All tox environments pass (mypy, ruff, py3.10–3.14).

[gijzelaerr]

@nikteliy Thanks for the thorough review! I've addressed all your comments in e764a7d:

• connection.py magic numbers — Added COTP_PARAM_CALLING_TSAP, COTP_PARAM_CALLED_TSAP, COTP_PARAM_PDU_SIZE constants, replaced all raw 0xC1/0xC2/0xC0 values
• connection.py silent param ignore — Now logs unsupported COTP parameters via logger.debug()
• datatypes.py assert_never — Added _assert_never() exhaustive fallback in encode_s7_data()
• datatypes.py bit_addr validation — parse_address() now validates bit addresses are 0–7 for all area types (DB, M, I, Q); encode_address() validates non-negative start address
• AGENTS.md — Renamed to agents.md per your suggestion
• SZL multi-packet — Was already addressed in e4e47bb

Could you take another look when you get a chance?

[gijzelaerr]

I'd like to merge this PR now. All review comments have been addressed and we've had successful test reports, but I want to be absolutely sure the code is sound and works reliably across all PLC hardware before merging.

@lupaulus @amorelettronico @razour08 @spreeker @nikteliy — do you think we're good to go merging this?

[amorelettronico]

@gijzelaerr

There are 2 failed test.

tests/test_client_e2e.py::TestClientDBRead::test_db_read_bool

self = <test_client_e2e.TestClientDBRead testMethod=test_db_read_bool>

    def test_db_read_bool(self) -> None:
        """Test db_read() for Bool values."""
        data = self.client.db_read(DB_READ_ONLY, OFFSET_BOOLS, 1)
>       self.assertEqual(EXPECTED_BOOL0, get_bool(data, 0, 0))
E       AssertionError: True != False

tests/test_client_e2e.py:245: AssertionError

Is solved by setting the first bool to true in the PLC DB's. (bool0-bool7: Bool (packed in 1 byte) didnt state that the first one needed to be true, and didnt scroll a bit down :) )
Unfortunately presetting the BOOL0 value fails when the DB is set to read only, I guess im doing something wrong. But the test passes if I set DB1 to RW and set BOOL0 to true.

tests/test_client_e2e.py::TestClientDBOperations::test_db_get

self = <test_client_e2e.TestClientDBOperations testMethod=test_db_get>

    def test_db_get(self) -> None:
        """Test db_get() method."""
>       data = self.client.db_get(DB_READ_ONLY)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

tests/test_client_e2e.py:492: 
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
snap7/client.py:234: in db_get
    block_info = self.get_block_info(Block.DB, db_number)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

self = <snap7.client.Client object at 0x7f7e39eeb650>, block_type = <Block.DB: 65>, db_number = 1

    def get_block_info(self, block_type: Block, db_number: int) -> TS7BlockInfo:
        """
        Get block information.
    
        Sends real S7 USER_DATA protocol request to server.
    
        Args:
            block_type: Type of block
            db_number: Block number
    
        Returns:
            Block information structure
        """
        if not self.get_connected():
            raise S7ConnectionError("Not connected to PLC")
    
        conn = self._get_connection()
    
        # Map Block enum to S7 block type code
        block_type_map = {
            Block.OB: 0x38,
            Block.DB: 0x41,
            Block.SDB: 0x42,
            Block.FC: 0x43,
            Block.SFC: 0x44,
            Block.FB: 0x45,
            Block.SFB: 0x46,
        }
        type_code = block_type_map.get(block_type, 0x41)
    
        # Build and send get block info request
        request = self.protocol.build_get_block_info_request(type_code, db_number)
        conn.send_data(request)
    
        # Receive and parse response
        response_data = conn.receive_data()
        response = self.protocol.parse_response(response_data)
    
        # Check for errors
        if response.get("error_code", 0) != 0:
            raise RuntimeError(f"Get block info failed with error: {response['error_code']}")
    
        # Check for errors in data section
        data_info = response.get("data", {})
        return_code = data_info.get("return_code", 0xFF) if isinstance(data_info, dict) else 0xFF
        if return_code != 0xFF:
            desc = get_return_code_description(return_code)
>           raise S7ProtocolError(f"Get block info failed: {desc} (0x{return_code:02x})")
E           snap7.error.S7ProtocolError: Get block info failed: Object does not exist (0x0a)

snap7/client.py:669: S7ProtocolError

[amorelettronico]

I got the same results on a CPU416-2, can test on a 410-5H, 1500 and 1200. But not on a short window.