# xeden3/lecpython architecture

> Architecture diagram of the GitHub repository xeden3/lecpython, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xeden3/lecpython
- Repository: https://github.com/xeden3/lecpython

## Overview

1. **What this repository is**
   - LECPython is a Python package that acts as a bridge to a C#/.NET PLC communication library.
   - The repo itself is very small: a Python module entrypoint (`__init__.py`), a library wrapper (`LECPythonLib.py`), and package metadata/docs. The actual PLC communication engine is implied to live in a .NET assembly that this Python package loads.

2. **Top-level packaging boundary**
   - The Python package is the public surface area.
   - `from LECPython import LECPython` is the intended entrypoint for consumers.
   - `LECPythonLib.py` likely contains the wrapper logic that imports/hosts the .NET component and exposes Python-friendly methods.

3. **Runtime dependency model**
   - The package depends on `pythonnet` to interoperate with the .NET runtime.
   - It requires .NET 8, and the README says the package checks for it on first use and can install it automatically if missing.
   - This makes the first-call path materially different from the normal read/write path: there is a runtime bootstrap step before PLC I/O can happen.

4. **Startup and bootstrap flow**
   - On first invocation, the package performs environment validation: detect .NET 8, then install it online if absent.
   - After the runtime is available, the Python layer can load the C# component through `pythonnet`.
   - This bootstrap behavior is part of the product architecture, not just an installation detail, because it controls whether the communication stack can initialize at all.

5. **Connection lifecycle**
   - The README describes a lazy connection model:
     - `DeviceProfinetConnection` creates a connector object but does not immediately connect to the PLC.
     - The actual network connection occurs on the first read/write through `DeviceProfinetCommunication`.
   - The connector object is stateful and persists long enough to handle reconnection automatically until it is cleared or explicitly closed.

6. **Data I/O boundary**
   - The primary operational boundary is PLC read/write access.
   - Reads and writes are done against a connection handle, an address like `D100`, a data type such as `float`, and a quantity/value payload.
   - The public API shown in the README includes `ReadNodeValues`, `WriteNodeValues`, and `ConnectClose`.

7. **PLC protocol layer**
   - The .NET backend is positioned as a multi-protocol PLC communications layer.
   - Supported families include Modbus, Mitsubishi, Siemens, Omron, Rockwell, Keyence, Delta, Beckhoff, Panasonic, Inovance, Fuji, EverSensing, and Schneider.
   - Architecturally, this suggests the C# layer contains protocol-specific adapters behind a common API, while Python remains protocol-agnostic.

8. **Connection configuration and data formatting**
   - The connector exposes formatting controls such as `data_format` and `is_string_reverse_byte_word`.
   - These settings affect byte/word order and value interpretation, which means the Python layer is not just transport glue; it also passes through PLC-specific data layout semantics to the .NET backend.

9. **State and cleanup**
   - The connection object is intended to be reused across multiple operations.
   - The lifecycle ends with an explicit close call, which indicates a managed connection resource in the .NET layer.
   - The architecture therefore has three state boundaries: package/runtime initialization, connection object lifetime, and active PLC session lifetime.

10. **External dependencies and environment**
   - There is no separate service, database, or web server in this repo.
   - The important external systems are:
     - the local Python runtime,
     - `pythonnet`,
     - the .NET 8 runtime,
     - and the target PLC over the network.
   - The repo’s behavior changes depending on OS/runtime availability because of the auto-install path.

11. **Documentation and distribution**
   - The repository is packaged for pip installation and includes MIT licensing.
   - The README points to external API documentation hosted on a separate site, implying the repo is primarily a thin distribution wrapper around a larger maintained API surface.

12. **How to diagram it**
   - A correct architecture diagram should show:
     - Python application code on the left,
     - the LECPython wrapper package in the middle,
     - `pythonnet` plus .NET 8 as the interop/runtime layer,
     - the C# PLC communication engine behind that,
     - and PLC devices on the right.
   - A separate bootstrap path should be shown for first-run .NET detection and installation, distinct from normal read/write traffic.

Main entry points: [`LECPythonLib.py`](https://github.com/xeden3/lecpython/blob/main/LECPythonLib.py) (Wrapper API), [`__init__.py`](https://github.com/xeden3/lecpython/blob/main/__init__.py) (Package entry), [`README.md`](https://github.com/xeden3/lecpython/blob/main/README.md) (Docs), [`LICENSE`](https://github.com/xeden3/lecpython/tree/main/LICENSE) (License)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_package["Python package"]
  node_node_init["Package entry<br/>entrypoint<br/>[__init__.py]"]
  node_node_wrapper["Wrapper API<br/>python bridge<br/>[LECPythonLib.py]"]
  node_node_readme["Docs<br/>[README.md]"]
  node_node_license["License<br/>mit"]
end

subgraph group_group_runtime["Interop/runtime"]
  node_node_bootstrap["Runtime bootstrap<br/>startup"]
  node_node_pythonnet["pythonnet<br/>interop lib"]
  node_node_dotnet8[".NET 8<br/>runtime"]
end

subgraph group_group_backend["PLC backend"]
  node_node_backend["PLC engine<br/>csharp assembly"]
  node_node_protocols["Protocol adapters<br/>protocol layer"]
  node_node_plc(("PLC devices<br/>external target"))
end

node_node_app(("Python app<br/>consumer"))

node_node_app -->|"import"| node_node_init
node_node_init -->|"exposes"| node_node_wrapper
node_node_wrapper -->|"first use"| node_node_bootstrap
node_node_bootstrap -->|"ensure"| node_node_dotnet8
node_node_wrapper -->|"uses"| node_node_pythonnet
node_node_pythonnet -->|"hosts"| node_node_dotnet8
node_node_pythonnet -->|"loads"| node_node_backend
node_node_backend -->|"routes"| node_node_protocols
node_node_protocols -->|"communicates"| node_node_plc
node_node_wrapper -->|"read/write"| node_node_plc
node_node_wrapper -.->|"documented by"| node_node_readme
node_node_wrapper -.->|"distributed with"| node_node_license

click node_node_init "https://github.com/xeden3/lecpython/blob/main/__init__.py"
click node_node_wrapper "https://github.com/xeden3/lecpython/blob/main/LECPythonLib.py"
click node_node_readme "https://github.com/xeden3/lecpython/blob/main/README.md"
click node_node_license "https://github.com/xeden3/lecpython/tree/main/LICENSE"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_init,node_node_wrapper,node_node_readme,node_node_license toneBlue
class node_node_bootstrap,node_node_pythonnet,node_node_dotnet8 toneAmber
class node_node_backend,node_node_protocols,node_node_plc toneMint
class node_node_app toneNeutral
```

## Components

### Python package

Public Python surface and distribution files

- [Package entry](https://github.com/xeden3/lecpython/blob/main/__init__.py): entrypoint · Public import surface for consumers · `__init__.py`
- [Wrapper API](https://github.com/xeden3/lecpython/blob/main/LECPythonLib.py): python bridge · Python-friendly facade over the managed PLC library · `LECPythonLib.py`
- [Docs](https://github.com/xeden3/lecpython/blob/main/README.md): package docs · Usage notes, runtime expectations, and API overview · `README.md`
- [License](https://github.com/xeden3/lecpython/tree/main/LICENSE): mit · Distribution license · `LICENSE`

### Interop/runtime

PythonNet and .NET bootstrap path

- **Runtime bootstrap**: startup · Detects and installs required .NET runtime on first use
- **pythonnet**: interop lib · Python-to-.NET interop layer
- **.NET 8**: runtime · Required managed runtime for the backend assembly

### PLC backend

Managed communication engine and target devices

- **PLC engine**: csharp assembly · Managed multi-protocol PLC communication library
- **Protocol adapters**: protocol layer · Backend support for vendor-specific PLC families
- **PLC devices**: external target · Network-connected industrial controllers

### Other components

- **Python app**: consumer · Code that imports and uses LECPython

## Connections

- Python app → Package entry: import · Consumers import the package entrypoint
- Package entry → Wrapper API: exposes · Entry module re-exports the main API
- Wrapper API → Runtime bootstrap: first use · Validates runtime availability before PLC I/O
- Runtime bootstrap → .NET 8: ensure · Detects or installs the required .NET runtime
- Wrapper API → pythonnet: uses · Loads the managed assembly through PythonNet
- pythonnet → .NET 8: hosts · Interop depends on the .NET runtime
- pythonnet → PLC engine: loads · Bridges Python calls into the C# communication library
- PLC engine → Protocol adapters: routes · Common API dispatches to protocol-specific adapters
- Protocol adapters → PLC devices: communicates · Sends read/write traffic to PLC hardware
- Wrapper API → PLC devices: read/write · Public operations open sessions and perform PLC I/O
- Wrapper API → Docs: documented by · README describes lazy connect, data formatting, and close flow
- Wrapper API → License: distributed with · Package is published under MIT license
