pydnp3-stepfunc 1.6.0.3__cp313-cp313-manylinux1_x86_64.whl

dnp3/__init__.py

@@ -0,0 +1,138 @@
+"""
+dnp3-python: Python bindings for the stepfunc/dnp3 Rust library.
+
+Provides a Pythonic API for DNP3 master and outstation operations,
+built on the production-quality stepfunc/dnp3 implementation with
+full Secure Authentication support.
+
+License: stepfunc/dnp3 uses a non-commercial license
+(evaluation/research/training only).
+
+Basic usage::
+
+    from dnp3 import Runtime, MasterChannelConfig, ReadHandler
+    from dnp3.channel import create_tcp_channel
+    from dnp3.logging import configure_logging, LogLevel
+
+    configure_logging(LogLevel.INFO)
+
+    with Runtime() as runtime:
+        handler = ReadHandler()
+        channel = create_tcp_channel(
+            runtime,
+            endpoints=["127.0.0.1:20000"],
+            config=MasterChannelConfig(address=1),
+        )
+        assoc = channel.add_association(address=1024, read_handler=handler)
+        channel.enable()
+
+        # Read all data
+        channel.read(assoc)
+
+        # Access collected data
+        for bi in handler.binary_inputs:
+            print(f"BI {bi.index}: {bi.value}")
+        for ai in handler.analog_inputs:
+            print(f"AI {ai.index}: {ai.value}")
+
+        channel.destroy()
+"""
+
+__version__ = "0.1.0"
+
+from ._ffi import DNP3Error
+
+from .runtime import Runtime
+
+from .types import (
+    # Enums
+    ParamError,
+    CommandStatus,
+    TripCloseCode,
+    OpType,
+    DoubleBit,
+    TimeQuality,
+    CommandMode,
+    TimeSyncMode,
+    LinkErrorMode,
+    AppDecodeLevel,
+    TransportDecodeLevel,
+    LinkDecodeLevel,
+    PhysDecodeLevel,
+    FunctionCode,
+    ClientState,
+    ReadType,
+    TaskType,
+    AutoTimeSync,
+    Variation,
+    # Convenience group/variation aliases
+    BINARY_INPUT,
+    BINARY_OUTPUT,
+    ANALOG_INPUT,
+    ANALOG_OUTPUT,
+    COUNTER,
+    FROZEN_COUNTER,
+    # Data classes
+    Flags,
+    Timestamp,
+    BinaryInput,
+    DoubleBitBinaryInput,
+    BinaryOutputStatus,
+    Counter,
+    FrozenCounter,
+    AnalogInput,
+    AnalogOutputStatus,
+    ControlCode,
+    Group12Var1,
+    DecodeLevel,
+    ConnectStrategy,
+    IIN,
+    IIN1,
+    IIN2,
+)
+
+from .handler import (
+    ReadHandler,
+    ClientStateListener,
+    PortStateListener,
+    ConnectionStateListener,
+    AssociationHandler,
+    AssociationInformation,
+    ReadTaskCallback,
+    CommandTaskCallback,
+    TimeSyncTaskCallback,
+    RestartTaskCallback,
+    EmptyResponseCallback,
+    LinkStatusCallback,
+)
+
+from .channel import (
+    MasterChannelConfig,
+    create_tcp_channel,
+    create_tls_channel,
+    create_serial_channel,
+    create_udp_channel,
+)
+
+from .master import (
+    MasterChannel,
+    AssociationConfig,
+    AssociationId,
+    PollId,
+)
+
+from .outstation import (
+    OutstationServer,
+    OutstationConfig,
+    EventBufferConfig,
+    OutstationApplication,
+    OutstationInformation,
+    ControlHandler,
+)
+
+from .logging import (
+    configure_logging,
+    LogLevel,
+    LogOutputFormat,
+    TimeFormat,
+)

dnp3/_build_ffi.py

@@ -0,0 +1,166 @@
+"""
+Build helpers for cffi bindings from the stepfunc/dnp3 C headers.
+
+Preprocesses dnp3.h to extract what cffi can parse (enums, structs,
+function declarations, numeric #define constants).
+"""
+
+import os
+import re
+from pathlib import Path
+
+
+def _project_root():
+    """Return the project root (two levels above src/dnp3/)."""
+    return Path(__file__).resolve().parent.parents[1]
+
+
+def find_header():
+    """Locate the dnp3.h header file from the stepfunc/dnp3 build."""
+    root = _project_root()
+    pkg_dir = Path(__file__).resolve().parent
+    candidates = [
+        # Bundled inside installed package (wheel distribution)
+        pkg_dir / "vendor" / "dnp3.h",
+        # Sibling directory (common development layout)
+        root.parent / "stepfunc-dnp3" / "ffi" / "bindings" / "c" / "generated" / "include" / "dnp3.h",
+        # Vendored inside project
+        root / "vendor" / "dnp3" / "include" / "dnp3.h",
+        # Environment override
+        Path(os.environ.get("DNP3_HEADER_PATH", "/nonexistent")),
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+    raise FileNotFoundError(
+        "Cannot find dnp3.h. Build stepfunc/dnp3 first or set DNP3_HEADER_PATH.\n"
+        f"Searched: {[str(c) for c in candidates]}"
+    )
+
+
+def find_shared_lib():
+    """Locate the compiled libdnp3_ffi shared library."""
+    root = _project_root()
+    pkg_dir = Path(__file__).resolve().parent
+    candidates = [
+        # Bundled inside installed package (wheel distribution)
+        pkg_dir / "vendor" / "libdnp3_ffi.so",
+        # Sibling directory — pre-built artifacts
+        root.parent / "stepfunc-dnp3" / "ffi" / "bindings" / "c" / "generated" / "lib" / "x86_64-unknown-linux-gnu" / "libdnp3_ffi.so",
+        # Sibling directory — cargo build output
+        root.parent / "stepfunc-dnp3" / "target" / "release" / "libdnp3_ffi.so",
+        # Vendored inside project
+        root / "vendor" / "dnp3" / "lib" / "libdnp3_ffi.so",
+        # Environment override
+        Path(os.environ.get("DNP3_LIB_PATH", "/nonexistent")),
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+    raise FileNotFoundError(
+        "Cannot find libdnp3_ffi.so. Build stepfunc/dnp3 first or set DNP3_LIB_PATH.\n"
+        f"Searched: {[str(c) for c in candidates]}"
+    )
+
+
+def preprocess_header(header_path: Path) -> str:
+    """
+    Preprocess dnp3.h for cffi cdef consumption.
+
+    Strips:
+    - Static inline functions (with their full bodies)
+    - #include, #pragma, #ifdef/#endif, extern "C"
+    - C comments (// and /* */)
+
+    Keeps:
+    - typedef enum { ... } name;
+    - typedef struct name { ... } name;
+    - typedef struct name name; (opaque forward declarations)
+    - Non-static function declarations
+    - #define DNP3_* constants
+    """
+    text = header_path.read_text()
+
+    # Remove multi-line comments
+    text = re.sub(r"/\*.*?\*/", "", text, flags=re.DOTALL)
+
+    # Remove single-line comments
+    text = re.sub(r"//[^\n]*", "", text)
+
+    # Remove static functions with their bodies using brace-depth tracking
+    result = []
+    i = 0
+    while i < len(text):
+        if text[i:i+7] == "static ":
+            j = i + 7
+            while j < len(text) and text[j] != "{" and text[j] != ";":
+                j += 1
+            if j < len(text) and text[j] == "{":
+                depth = 1
+                j += 1
+                while j < len(text) and depth > 0:
+                    if text[j] == "{":
+                        depth += 1
+                    elif text[j] == "}":
+                        depth -= 1
+                    j += 1
+                i = j
+                continue
+            elif j < len(text) and text[j] == ";":
+                i = j + 1
+                continue
+        result.append(text[i])
+        i += 1
+
+    text = "".join(result)
+
+    # Filter preprocessor directives
+    lines = text.split("\n")
+    output_lines = []
+    for line in lines:
+        stripped = line.strip()
+
+        if stripped.startswith("#pragma"):
+            continue
+        if stripped.startswith(("#ifdef", "#ifndef", "#endif")):
+            continue
+        if stripped.startswith("#include"):
+            continue
+        if 'extern "C"' in stripped:
+            continue
+
+        # Keep numeric DNP3_* constants only (cffi can't parse string defines)
+        if stripped.startswith("#define DNP3_"):
+            if '"' in stripped:
+                continue
+            output_lines.append(stripped)
+            continue
+
+        if stripped.startswith("#define"):
+            continue
+
+        output_lines.append(line)
+
+    text = "\n".join(output_lines)
+
+    # Remove lone closing braces left over from extern "C" block
+    lines2 = text.split("\n")
+    final_lines = [line for line in lines2 if line.strip() != "}"]
+    text = "\n".join(final_lines)
+
+    # Clean up excessive blank lines
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    text = re.sub(r"[ \t]+\n", "\n", text)
+
+    return text.strip() + "\n"
+
+
+def get_cdef():
+    """Get the preprocessed cdef string for cffi."""
+    header_path = find_header()
+    return preprocess_header(header_path)
+
+
+if __name__ == "__main__":
+    cdef = get_cdef()
+    print(cdef)

dnp3/_ffi.py

@@ -0,0 +1,64 @@
+"""
+Raw cffi bindings for the stepfunc/dnp3 C FFI library.
+
+This module provides the low-level FFI object and loaded library.
+Higher-level modules should import `ffi` and `lib` from here.
+"""
+
+import cffi
+
+from ._build_ffi import get_cdef, find_shared_lib
+
+# Create the FFI instance
+ffi = cffi.FFI()
+
+# Parse the C header definitions
+_cdef = get_cdef()
+ffi.cdef(_cdef)
+
+# Load the shared library
+_lib_path = str(find_shared_lib())
+lib = ffi.dlopen(_lib_path)
+
+# Error code names (the to_string functions are static inline in the header,
+# not exported from the .so, so we replicate them here)
+_PARAM_ERROR_NAMES = {
+    0: "ok",
+    1: "invalid_timeout",
+    2: "null_parameter",
+    3: "string_not_utf8",
+    4: "no_support",
+    5: "association_does_not_exist",
+    6: "association_duplicate_address",
+    7: "invalid_socket_address",
+    8: "invalid_dnp3_address",
+    9: "invalid_buffer_size",
+    10: "address_filter_conflict",
+    11: "server_already_started",
+    12: "server_bind_error",
+    13: "master_already_shutdown",
+    14: "runtime_creation_failure",
+    15: "runtime_destroyed",
+    16: "runtime_cannot_block_within_async",
+    17: "logging_already_configured",
+    18: "point_does_not_exist",
+    19: "invalid_peer_certificate",
+    20: "invalid_local_certificate",
+    21: "invalid_private_key",
+    22: "invalid_dns_name",
+    23: "other_tls_error",
+    24: "wrong_channel_type",
+    25: "consumed",
+}
+
+
+class DNP3Error(Exception):
+    """Base exception for DNP3 library errors."""
+    pass
+
+
+def check_error(err):
+    """Check a dnp3_param_error_t return value and raise on failure."""
+    if err != lib.DNP3_PARAM_ERROR_OK:
+        name = _PARAM_ERROR_NAMES.get(err, f"unknown({err})")
+        raise DNP3Error(f"DNP3 error: {name}")

dnp3/channel.py

@@ -0,0 +1,240 @@
+"""
+TCP/TLS/Serial/UDP channel creation for DNP3 master stations.
+"""
+
+from typing import Optional, List
+
+from ._ffi import ffi, lib, check_error
+from .types import (
+    LinkErrorMode,
+    DecodeLevel,
+    ConnectStrategy,
+)
+from .handler import ClientStateListener, PortStateListener
+
+
+class MasterChannelConfig:
+    """Configuration for a master channel."""
+
+    def __init__(
+        self,
+        address: int = 1,
+        decode_level: Optional[DecodeLevel] = None,
+        tx_buffer_size: int = 2048,
+        rx_buffer_size: int = 2048,
+    ):
+        self.address = address
+        self.decode_level = decode_level or DecodeLevel()
+        self.tx_buffer_size = tx_buffer_size
+        self.rx_buffer_size = rx_buffer_size
+
+    def to_ffi(self):
+        """Create the C config struct."""
+        config = ffi.new("dnp3_master_channel_config_t*")
+        config.address = self.address
+        config.decode_level = ffi.new("dnp3_decode_level_t*", self.decode_level.to_ffi())[0]
+        config.tx_buffer_size = self.tx_buffer_size
+        config.rx_buffer_size = self.rx_buffer_size
+        return config[0]
+
+
+def create_tcp_channel(
+    runtime,
+    endpoints: List[str],
+    config: Optional[MasterChannelConfig] = None,
+    link_error_mode: LinkErrorMode = LinkErrorMode.CLOSE,
+    connect_strategy: Optional[ConnectStrategy] = None,
+    listener: Optional[ClientStateListener] = None,
+):
+    """
+    Create a TCP master channel.
+
+    Args:
+        runtime: Runtime instance (from Runtime class)
+        endpoints: List of "host:port" strings. First is primary.
+        config: Master channel configuration
+        link_error_mode: How to handle link errors
+        connect_strategy: Reconnection strategy
+        listener: Connection state listener
+
+    Returns:
+        A MasterChannel wrapping the C pointer
+    """
+    from .master import MasterChannel
+
+    config = config or MasterChannelConfig()
+    connect_strategy = connect_strategy or ConnectStrategy()
+    listener = listener or ClientStateListener()
+
+    # Create endpoint list
+    ep_list = lib.dnp3_endpoint_list_create(endpoints[0].encode())
+    for ep in endpoints[1:]:
+        lib.dnp3_endpoint_list_add(ep_list, ep.encode())
+
+    # Create channel
+    channel_ptr = ffi.new("dnp3_master_channel_t**")
+    strategy_ffi = ffi.new("dnp3_connect_strategy_t*", connect_strategy.to_ffi())[0]
+
+    err = lib.dnp3_master_channel_create_tcp(
+        runtime._ptr,
+        link_error_mode.value,
+        config.to_ffi(),
+        ep_list,
+        strategy_ffi,
+        listener.as_ffi(),
+        channel_ptr,
+    )
+    lib.dnp3_endpoint_list_destroy(ep_list)
+    check_error(err)
+
+    return MasterChannel(channel_ptr[0], listener)
+
+
+def create_tls_channel(
+    runtime,
+    endpoints: List[str],
+    tls_config: dict,
+    config: Optional[MasterChannelConfig] = None,
+    link_error_mode: LinkErrorMode = LinkErrorMode.CLOSE,
+    connect_strategy: Optional[ConnectStrategy] = None,
+    listener: Optional[ClientStateListener] = None,
+):
+    """
+    Create a TLS master channel.
+
+    Args:
+        runtime: Runtime instance
+        endpoints: List of "host:port" strings
+        tls_config: dict with keys: dns_name, peer_cert_path, local_cert_path,
+                    private_key_path, password (optional), certificate_mode (optional)
+        config: Master channel configuration
+        link_error_mode: How to handle link errors
+        connect_strategy: Reconnection strategy
+        listener: Connection state listener
+
+    Returns:
+        A MasterChannel wrapping the C pointer
+    """
+    from .master import MasterChannel
+
+    config = config or MasterChannelConfig()
+    connect_strategy = connect_strategy or ConnectStrategy()
+    listener = listener or ClientStateListener()
+
+    ep_list = lib.dnp3_endpoint_list_create(endpoints[0].encode())
+    for ep in endpoints[1:]:
+        lib.dnp3_endpoint_list_add(ep_list, ep.encode())
+
+    # Build TLS config
+    tls_c = ffi.new("dnp3_tls_client_config_t*")
+    tls_c.dns_name = ffi.new("char[]", tls_config["dns_name"].encode())
+    tls_c.peer_cert_path = ffi.new("char[]", tls_config["peer_cert_path"].encode())
+    tls_c.local_cert_path = ffi.new("char[]", tls_config["local_cert_path"].encode())
+    tls_c.private_key_path = ffi.new("char[]", tls_config["private_key_path"].encode())
+    tls_c.password = ffi.new("char[]", tls_config.get("password", "").encode())
+    if "certificate_mode" in tls_config:
+        tls_c.certificate_mode = tls_config["certificate_mode"]
+
+    channel_ptr = ffi.new("dnp3_master_channel_t**")
+    strategy_ffi = ffi.new("dnp3_connect_strategy_t*", connect_strategy.to_ffi())[0]
+
+    err = lib.dnp3_master_channel_create_tls(
+        runtime._ptr,
+        link_error_mode.value,
+        config.to_ffi(),
+        ep_list,
+        strategy_ffi,
+        listener.as_ffi(),
+        tls_c[0],
+        channel_ptr,
+    )
+    lib.dnp3_endpoint_list_destroy(ep_list)
+    check_error(err)
+
+    return MasterChannel(channel_ptr[0], listener)
+
+
+def create_serial_channel(
+    runtime,
+    path: str,
+    config: Optional[MasterChannelConfig] = None,
+    open_retry_delay: int = 5000,
+    listener: Optional[PortStateListener] = None,
+):
+    """
+    Create a serial master channel.
+
+    Args:
+        runtime: Runtime instance
+        path: Serial port path (e.g., "/dev/ttyS0")
+        config: Master channel configuration
+        open_retry_delay: Retry delay in ms when port open fails
+        listener: Port state listener
+
+    Returns:
+        A MasterChannel wrapping the C pointer
+    """
+    from .master import MasterChannel
+
+    config = config or MasterChannelConfig()
+    listener = listener or PortStateListener()
+
+    serial_settings = ffi.new("dnp3_serial_settings_t*")
+    # Use defaults (9600 baud, 8N1)
+    serial_settings.baud_rate = 9600
+    serial_settings.data_bits = lib.DNP3_DATA_BITS_EIGHT
+    serial_settings.flow_control = lib.DNP3_FLOW_CONTROL_NONE
+    serial_settings.parity = lib.DNP3_PARITY_NONE
+    serial_settings.stop_bits = lib.DNP3_STOP_BITS_ONE
+
+    channel_ptr = ffi.new("dnp3_master_channel_t**")
+
+    err = lib.dnp3_master_channel_create_serial(
+        runtime._ptr,
+        config.to_ffi(),
+        path.encode(),
+        serial_settings[0],
+        open_retry_delay,
+        listener.as_ffi(),
+        channel_ptr,
+    )
+    check_error(err)
+
+    return MasterChannel(channel_ptr[0], None)
+
+
+def create_udp_channel(
+    runtime,
+    local_endpoint: str,
+    config: Optional[MasterChannelConfig] = None,
+    retry_delay: int = 5000,
+):
+    """
+    Create a UDP master channel.
+
+    Args:
+        runtime: Runtime instance
+        local_endpoint: Local bind address "host:port"
+        config: Master channel configuration
+        retry_delay: Retry delay in ms
+
+    Returns:
+        A MasterChannel wrapping the C pointer
+    """
+    from .master import MasterChannel
+
+    config = config or MasterChannelConfig()
+
+    channel_ptr = ffi.new("dnp3_master_channel_t**")
+
+    err = lib.dnp3_master_channel_create_udp(
+        runtime._ptr,
+        config.to_ffi(),
+        local_endpoint.encode(),
+        0,  # link_read_mode
+        retry_delay,
+        channel_ptr,
+    )
+    check_error(err)
+
+    return MasterChannel(channel_ptr[0], None)