aioads 0.1.0.dev1__tar.gz

aioads-0.1.0.dev1/.gitignore

@@ -0,0 +1,162 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm-project.org/#use-with-ide
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

aioads-0.1.0.dev1/.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+    "cSpell.words": [
+        "aioads",
+    ],
+    "terminal.integrated.env.osx": {
+        "PYTHONPATH": "${workspaceFolder}"
+    },
+    "terminal.integrated.env.linux": {
+        "PYTHONPATH": "${workspaceFolder}"
+    },
+    "terminal.integrated.env.windows": {
+        "PYTHONPATH": "${workspaceFolder}"
+    }
+}

aioads-0.1.0.dev1/PKG-INFO

@@ -0,0 +1,302 @@
+Metadata-Version: 2.4
+Name: aioads
+Version: 0.1.0.dev1
+Summary: An asynchronous Python library for communicating with Beckhoff TwinCAT PLCs
+Author-email: MkKiefer <102972583+MkKiefer@users.noreply.github.com>
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: aiomqtt>=v3.0.0-alpha.1
+Description-Content-Type: text/markdown
+
+# AIOADS - Asynchronous ADS Library for Python
+
+An asynchronous Python library for communicating with Beckhoff TwinCAT PLCs using the ADS (Automation Device Specification) protocol. This library provides high-performance, async/await-based communication with PLCs for reading symbols, data types, notifications, and more.
+
+## Features
+
+- ✨ **Fully asynchronous** - Built from the ground up with asyncio
+- 🚀 **High performance** - Efficient batch operations and smart caching
+- 📡 **ADS over TCP** - Direct communication with TwinCAT systems
+- 🔍 **Symbol resolution** - Automatic symbol table parsing and caching
+- 📊 **Data type support** - Complete TwinCAT data type parsing
+- 🔔 **Notifications** - Event-driven data change monitoring
+- 🛠️ **Type safety** - Full typing support for better development experience
+- ⚡ **Smart caching** - Intelligent symbol and data type caching for performance
+
+## Installation
+
+```bash
+pdm add aioads
+
+pip install aioads
+```
+
+## Quick Start
+
+```python
+import asyncio
+from aioads import AdsClient, AmsAddress
+
+async def main():
+    # Create client
+    client = AdsClient.create_tcp(
+        src=AmsAddress(net_id="192.168.1.100.1.1", port=1234),
+        dst=AmsAddress(net_id="192.168.1.200.1.1", port=851),
+        ip="192.168.1.200",
+        port=48898,
+    )
+    
+    try:
+        # Connect to PLC
+        await client.connect()
+        
+        # Read device state
+        state = await client.read_state()
+        print(f"PLC State: {state.ads_state.name}")
+        
+        # Read single symbol
+        value = await client.read_symbol_by_name("MAIN.MyVariable")
+        print(f"Value: {value}")
+        
+        # Read multiple symbols efficiently
+        symbols = ["MAIN.Var1", "MAIN.Var2", "MAIN.Var3"]
+        values = await client.read_symbols_by_names(symbols)
+        print(f"Values: {values}")
+        
+    finally:
+        await client.disconnect()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Core Components
+
+### AdsClient
+
+The main interface for ADS communication:
+
+```python
+from aioads import AdsClient, AmsAddress
+
+# Create TCP client
+client = AdsClient.create_tcp(
+    src=AmsAddress(net_id="source.net.id.1.1", port=1234),
+    dst=AmsAddress(net_id="target.net.id.1.1", port=851),
+    ip="192.168.1.100"
+)
+
+# Connect
+await client.connect()
+
+# Read operations
+state = await client.read_state()
+symbols = await client.get_symbols()
+data_types = await client.get_symbol_datatypes()
+value = await client.read_symbol_by_name("MAIN.Variable")
+values = await client.read_symbols_by_names(["Var1", "Var2"])
+
+# Disconnect
+await client.disconnect()
+```
+
+### Batch Operations
+
+Efficiently read multiple symbols in a single operation:
+
+```python
+# Prepare symbol list
+symbols_to_read = {
+    "MAIN.Temperature",
+    "MAIN.Pressure", 
+    "MAIN.FlowRate",
+    "MAIN.Status.Running",
+    "MAIN.Recipe.CurrentStep"
+}
+
+# Read all symbols in one batch operation
+values = await client.read_symbols_by_names(symbols_to_read)
+
+for symbol_name, value in values.items():
+    print(f"{symbol_name}: {value}")
+```
+
+## Advanced Usage
+
+### Custom Transport
+
+You can provide your own transport implementation:
+
+```python
+from aioads.tcp_transport import AdsTcpTransport
+from aioads.ads_symbol_cache import AdsSymbolCache
+
+transport = AdsTcpTransport(
+    src_address=src_address,
+    ip="192.168.1.100",
+    port=48898
+)
+
+cache = AdsSymbolCache(transport=transport, dst_address=dst_address)
+client = AdsClient(transport=transport, dst_address=dst_address, cache=cache)
+```
+
+### Performance Tuning
+
+For high-performance applications:
+
+```python
+# Pre-load symbol information to cache
+await client.read_symbol_infos_by_names(large_symbol_list)
+
+# Use batch reads for efficiency
+start = time.perf_counter()
+values = await client.read_symbols_by_names(symbols)
+duration = (time.perf_counter() - start) * 1000
+print(f"Read {len(values)} symbols in {duration:.2f}ms")
+```
+
+### Concurrent Operations
+
+Handle multiple tasks concurrently:
+
+```python
+import asyncio
+
+async def read_process_data(client, process_symbols):
+    while True:
+        data = await client.read_symbols_by_names(process_symbols)
+        # Process data...
+        await asyncio.sleep(0.1)
+
+async def read_diagnostics(client, diag_symbols):
+    while True:
+        data = await client.read_symbols_by_names(diag_symbols)
+        # Process diagnostics...
+        await asyncio.sleep(1.0)
+
+async def main():
+    client = AdsClient.create_tcp(...)
+    await client.connect()
+    
+    try:
+        # Run multiple concurrent tasks
+        async with asyncio.TaskGroup() as tg:
+            tg.create_task(read_process_data(client, process_symbols))
+            tg.create_task(read_diagnostics(client, diagnostic_symbols))
+    finally:
+        await client.disconnect()
+```
+
+## Protocol Support
+
+### ADS Commands
+
+The library supports all major ADS commands:
+
+- **Read/Write Operations**: Single and batch symbol access
+- **Device Information**: State, version, and device info
+- **Symbol Management**: Symbol table upload and parsing
+- **Data Types**: Complete data type information and parsing
+- **Notifications**: Change and cyclic notifications
+- **Sum Commands**: Efficient bulk operations
+
+### Data Types
+
+Full support for TwinCAT data types:
+
+- **Basic Types**: BOOL, BYTE, WORD, DWORD, INT, REAL, STRING, etc.
+- **Structured Types**: STRUCT, ARRAY, UNION
+- **Complex Types**: Custom user-defined types
+- **Arrays**: Multi-dimensional arrays with proper indexing
+
+### Notification Modes
+
+Multiple notification transmission modes supported:
+
+| Mode                | Description                 | Use Case                |
+| ------------------- | --------------------------- | ----------------------- |
+| `ClientCycle`       | Client-triggered periodic   | Reduced server load     |
+| `ClientOnChange`    | Client-triggered on change  | Reduced server load     |
+| `Cyclic`            | Server-side periodic        | Real-time performance   |
+| `OnChange`          | Server-side on change       | Immediate notifications |
+| `CyclicInContext`   | Task-synchronized periodic  | Task coordination       |
+| `OnChangeInContext` | Task-synchronized on change | Task coordination       |
+
+## Project Structure
+
+```
+aioads/
+├── ads_client.py           # Main client interface
+├── tcp_transport.py        # TCP transport layer
+├── ads_symbol_cache.py     # Symbol caching system
+├── ads_symbol_parser.py    # Symbol data parsing
+├── ams_address.py          # AMS addressing
+├── ams_header.py           # AMS protocol headers
+├── commands/               # ADS command implementations
+│   ├── ads_read.py
+│   ├── ads_write.py
+│   ├── ads_read_state.py
+│   └── ...
+├── functions/              # ADS function implementations
+│   ├── ads_sum_read.py
+│   ├── ads_symbol_upload.py
+│   └── ...
+└── utils/                  # Utility functions
+    └── async_zip.py
+```
+
+## Examples
+
+Check the `examples/` directory for complete usage examples:
+
+- `read_cycles.py` - Basic single symbol reading
+- `read_multiple.py` - Batch reading
+
+## Requirements
+
+- Python 3.11+
+- asyncio
+- No external dependencies (pure Python implementation)
+
+## Performance
+
+The library is optimized for high-performance scenarios:
+
+- **Batch Operations**: Read multiple symbols in single ADS calls
+- **Smart Caching**: Symbol information cached to avoid repeated lookups
+- **Async Architecture**: Non-blocking I/O for maximum throughput
+
+Typical performance:
+- Single symbol read: ~1-5ms
+- Batch reads (100+ symbols): ~10-50ms
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Troubleshooting
+
+### Connection Issues
+
+1. **Firewall**: Ensure port 48898 (ADS) is open
+2. **AMS Routes**: Verify AMS routes are configured on target system
+3. **Network**: Check IP connectivity between systems
+
+### Symbol Access
+
+1. **PLC State**: Ensure PLC is in RUN mode for symbol access
+
+### Performance Issues
+
+1. **Batch Reads**: Use batch operations instead of individual reads
+2. **Caching**: Pre-load symbol info with `read_symbol_infos_by_names()`
+3. **Concurrent Tasks**: Be mindful of PLC load with multiple tasks
+
+## Support
+
+For questions, issues, or contributions, please refer to the project's GitHub repository.