pydnp3-stepfunc 1.6.0.3__cp313-cp313-manylinux1_x86_64.whl

dnp3/handler.py

@@ -0,0 +1,509 @@
+"""
+Callback handler wrappers for DNP3 read/command/event callbacks.
+
+The C FFI uses function pointers in structs for async callbacks.
+This module wraps them with cffi @ffi.callback decorators and
+collects data into Python objects.
+"""
+
+import threading
+from typing import List, Optional, Dict, Any
+
+from ._ffi import ffi, lib
+from .types import (
+    BinaryInput,
+    DoubleBitBinaryInput,
+    BinaryOutputStatus,
+    Counter,
+    FrozenCounter,
+    AnalogInput,
+    AnalogOutputStatus,
+    IIN,
+    ReadType,
+)
+
+
+class ReadHandler:
+    """
+    Collects data received from DNP3 read operations.
+
+    Usage:
+        handler = ReadHandler()
+        # Pass handler.as_ffi() to master_channel_read or add_association
+        # After read completes, access handler.binary_inputs, handler.analog_inputs, etc.
+    """
+
+    def __init__(self):
+        self.binary_inputs: List[BinaryInput] = []
+        self.double_bit_binary_inputs: List[DoubleBitBinaryInput] = []
+        self.binary_output_statuses: List[BinaryOutputStatus] = []
+        self.counters: List[Counter] = []
+        self.frozen_counters: List[FrozenCounter] = []
+        self.analog_inputs: List[AnalogInput] = []
+        self.analog_output_statuses: List[AnalogOutputStatus] = []
+        self.octet_strings: List[Dict[str, Any]] = []
+        self.string_attrs: List[Dict[str, Any]] = []
+        self.iin: Optional[IIN] = None
+        self._lock = threading.Lock()
+
+        # Create persistent C callbacks - these must be kept alive
+        # as long as the handler is in use
+
+        @ffi.callback("void(dnp3_read_type_t, dnp3_response_header_t, void*)")
+        def _begin_fragment(read_type, header, ctx):
+            with self._lock:
+                self.iin = IIN.from_ffi(header.iin)
+
+        @ffi.callback("void(dnp3_read_type_t, dnp3_response_header_t, void*)")
+        def _end_fragment(read_type, header, ctx):
+            pass
+
+        @ffi.callback("void(dnp3_header_info_t, dnp3_binary_input_iterator_t*, void*)")
+        def _handle_binary_input(info, it, ctx):
+            with self._lock:
+                while True:
+                    val = lib.dnp3_binary_input_iterator_next(it)
+                    if val == ffi.NULL:
+                        break
+                    self.binary_inputs.append(BinaryInput.from_ffi(val))
+
+        @ffi.callback("void(dnp3_header_info_t, dnp3_double_bit_binary_input_iterator_t*, void*)")
+        def _handle_double_bit(info, it, ctx):
+            with self._lock:
+                while True:
+                    val = lib.dnp3_double_bit_binary_input_iterator_next(it)
+                    if val == ffi.NULL:
+                        break
+                    self.double_bit_binary_inputs.append(DoubleBitBinaryInput.from_ffi(val))
+
+        @ffi.callback("void(dnp3_header_info_t, dnp3_binary_output_status_iterator_t*, void*)")
+        def _handle_bos(info, it, ctx):
+            with self._lock:
+                while True:
+                    val = lib.dnp3_binary_output_status_iterator_next(it)
+                    if val == ffi.NULL:
+                        break
+                    self.binary_output_statuses.append(BinaryOutputStatus.from_ffi(val))
+
+        @ffi.callback("void(dnp3_header_info_t, dnp3_counter_iterator_t*, void*)")
+        def _handle_counter(info, it, ctx):
+            with self._lock:
+                while True:
+                    val = lib.dnp3_counter_iterator_next(it)
+                    if val == ffi.NULL:
+                        break
+                    self.counters.append(Counter.from_ffi(val))
+
+        @ffi.callback("void(dnp3_header_info_t, dnp3_frozen_counter_iterator_t*, void*)")
+        def _handle_frozen_counter(info, it, ctx):
+            with self._lock:
+                while True:
+                    val = lib.dnp3_frozen_counter_iterator_next(it)
+                    if val == ffi.NULL:
+                        break
+                    self.frozen_counters.append(FrozenCounter.from_ffi(val))
+
+        @ffi.callback("void(dnp3_header_info_t, dnp3_analog_input_iterator_t*, void*)")
+        def _handle_analog_input(info, it, ctx):
+            with self._lock:
+                while True:
+                    val = lib.dnp3_analog_input_iterator_next(it)
+                    if val == ffi.NULL:
+                        break
+                    self.analog_inputs.append(AnalogInput.from_ffi(val))
+
+        @ffi.callback("void(dnp3_header_info_t, dnp3_analog_output_status_iterator_t*, void*)")
+        def _handle_aos(info, it, ctx):
+            with self._lock:
+                while True:
+                    val = lib.dnp3_analog_output_status_iterator_next(it)
+                    if val == ffi.NULL:
+                        break
+                    self.analog_output_statuses.append(AnalogOutputStatus.from_ffi(val))
+
+        @ffi.callback("void(dnp3_header_info_t, dnp3_octet_string_iterator_t*, void*)")
+        def _handle_octet_string(info, it, ctx):
+            with self._lock:
+                while True:
+                    val = lib.dnp3_octet_string_iterator_next(it)
+                    if val == ffi.NULL:
+                        break
+                    data = []
+                    while True:
+                        byte_ptr = lib.dnp3_byte_iterator_next(val.value)
+                        if byte_ptr == ffi.NULL:
+                            break
+                        data.append(byte_ptr[0])
+                    self.octet_strings.append({"index": val.index, "value": bytes(data)})
+
+        @ffi.callback("void(dnp3_header_info_t, dnp3_string_attr_t, uint8_t, uint8_t, const char*, void*)")
+        def _handle_string_attr(info, attr, set_id, variation, value, ctx):
+            with self._lock:
+                self.string_attrs.append({
+                    "attr": int(attr),
+                    "set": set_id,
+                    "variation": variation,
+                    "value": ffi.string(value).decode() if value != ffi.NULL else "",
+                })
+
+        # Store references to prevent GC
+        self._begin_fragment = _begin_fragment
+        self._end_fragment = _end_fragment
+        self._handle_binary_input = _handle_binary_input
+        self._handle_double_bit = _handle_double_bit
+        self._handle_bos = _handle_bos
+        self._handle_counter = _handle_counter
+        self._handle_frozen_counter = _handle_frozen_counter
+        self._handle_analog_input = _handle_analog_input
+        self._handle_aos = _handle_aos
+        self._handle_octet_string = _handle_octet_string
+        self._handle_string_attr = _handle_string_attr
+
+    def clear(self):
+        """Reset all collected data."""
+        with self._lock:
+            self.binary_inputs.clear()
+            self.double_bit_binary_inputs.clear()
+            self.binary_output_statuses.clear()
+            self.counters.clear()
+            self.frozen_counters.clear()
+            self.analog_inputs.clear()
+            self.analog_output_statuses.clear()
+            self.octet_strings.clear()
+            self.string_attrs.clear()
+            self.iin = None
+
+    def as_ffi(self):
+        """Return a dnp3_read_handler_t struct for use with the C FFI."""
+        return ffi.new("dnp3_read_handler_t*", {
+            "begin_fragment": self._begin_fragment,
+            "end_fragment": self._end_fragment,
+            "handle_binary_input": self._handle_binary_input,
+            "handle_double_bit_binary_input": self._handle_double_bit,
+            "handle_binary_output_status": self._handle_bos,
+            "handle_counter": self._handle_counter,
+            "handle_frozen_counter": self._handle_frozen_counter,
+            "handle_analog_input": self._handle_analog_input,
+            "handle_analog_output_status": self._handle_aos,
+            "handle_octet_string": self._handle_octet_string,
+            "handle_string_attr": self._handle_string_attr,
+            "on_destroy": ffi.NULL,
+            "ctx": ffi.NULL,
+        })[0]
+
+
+class ClientStateListener:
+    """Tracks master channel connection state changes."""
+
+    def __init__(self):
+        self.state = None
+        self._event = threading.Event()
+        self._lock = threading.Lock()
+
+        @ffi.callback("void(dnp3_client_state_t, void*)")
+        def _on_change(state, ctx):
+            with self._lock:
+                self.state = int(state)
+            self._event.set()
+
+        self._on_change = _on_change
+
+    def wait_for_state(self, expected_state, timeout=10.0) -> bool:
+        """Wait for a specific state, returns True if reached."""
+        deadline = threading.Event()
+        while True:
+            with self._lock:
+                if self.state == expected_state:
+                    return True
+            if not self._event.wait(timeout):
+                return False
+            self._event.clear()
+
+    def as_ffi(self):
+        return ffi.new("dnp3_client_state_listener_t*", {
+            "on_change": self._on_change,
+            "on_destroy": ffi.NULL,
+            "ctx": ffi.NULL,
+        })[0]
+
+
+class PortStateListener:
+    """Tracks serial port state changes."""
+
+    def __init__(self):
+        self.state = None
+
+        @ffi.callback("void(dnp3_port_state_t, void*)")
+        def _on_change(state, ctx):
+            self.state = int(state)
+
+        self._on_change = _on_change
+
+    def as_ffi(self):
+        return ffi.new("dnp3_port_state_listener_t*", {
+            "on_change": self._on_change,
+            "on_destroy": ffi.NULL,
+            "ctx": ffi.NULL,
+        })[0]
+
+
+class ConnectionStateListener:
+    """Tracks outstation server connection state changes."""
+
+    def __init__(self):
+        self.state = None
+
+        @ffi.callback("void(dnp3_connection_state_t, void*)")
+        def _on_change(state, ctx):
+            self.state = int(state)
+
+        self._on_change = _on_change
+
+    def as_ffi(self):
+        return ffi.new("dnp3_connection_state_listener_t*", {
+            "on_change": self._on_change,
+            "on_destroy": ffi.NULL,
+            "ctx": ffi.NULL,
+        })[0]
+
+
+class AssociationHandler:
+    """Provides time synchronization for master-outstation association."""
+
+    def __init__(self):
+        @ffi.callback("dnp3_utc_timestamp_t(void*)")
+        def _get_current_time(ctx):
+            import time
+            return ffi.new("dnp3_utc_timestamp_t*", {
+                "value": int(time.time() * 1000),
+                "is_valid": True,
+            })[0]
+
+        self._get_current_time = _get_current_time
+
+    def as_ffi(self):
+        return ffi.new("dnp3_association_handler_t*", {
+            "get_current_time": self._get_current_time,
+            "on_destroy": ffi.NULL,
+            "ctx": ffi.NULL,
+        })[0]
+
+
+class AssociationInformation:
+    """Receives task status notifications."""
+
+    def __init__(self):
+        self.last_task_type = None
+        self.last_error = None
+
+        @ffi.callback("void(dnp3_task_type_t, dnp3_function_code_t, uint8_t, void*)")
+        def _task_start(task_type, fc, seq, ctx):
+            pass
+
+        @ffi.callback("void(dnp3_task_type_t, dnp3_function_code_t, uint8_t, void*)")
+        def _task_success(task_type, fc, seq, ctx):
+            self.last_task_type = int(task_type)
+
+        @ffi.callback("void(dnp3_task_type_t, dnp3_task_error_t, void*)")
+        def _task_fail(task_type, error, ctx):
+            self.last_task_type = int(task_type)
+            self.last_error = int(error)
+
+        @ffi.callback("void(bool, uint8_t, void*)")
+        def _unsolicited_response(is_duplicate, seq, ctx):
+            pass
+
+        self._task_start = _task_start
+        self._task_success = _task_success
+        self._task_fail = _task_fail
+        self._unsolicited_response = _unsolicited_response
+
+    def as_ffi(self):
+        return ffi.new("dnp3_association_information_t*", {
+            "task_start": self._task_start,
+            "task_success": self._task_success,
+            "task_fail": self._task_fail,
+            "unsolicited_response": self._unsolicited_response,
+            "on_destroy": ffi.NULL,
+            "ctx": ffi.NULL,
+        })[0]
+
+
+class TaskCallback:
+    """Generic callback for async operations (read, command, restart, etc.)."""
+
+    def __init__(self):
+        self.success = False
+        self.result = None
+        self.error = None
+        self._event = threading.Event()
+
+    def wait(self, timeout=30.0) -> bool:
+        """Wait for the callback to fire. Returns True if it completed."""
+        return self._event.wait(timeout)
+
+    def _signal_success(self, result=None):
+        self.success = True
+        self.result = result
+        self._event.set()
+
+    def _signal_failure(self, error):
+        self.success = False
+        self.error = error
+        self._event.set()
+
+
+class ReadTaskCallback(TaskCallback):
+    """Callback for read operations."""
+
+    def __init__(self):
+        super().__init__()
+
+        @ffi.callback("void(dnp3_nothing_t, void*)")
+        def _on_complete(nothing, ctx):
+            self._signal_success()
+
+        @ffi.callback("void(dnp3_read_error_t, void*)")
+        def _on_failure(error, ctx):
+            self._signal_failure(int(error))
+
+        self._on_complete = _on_complete
+        self._on_failure = _on_failure
+
+    def as_ffi(self):
+        return ffi.new("dnp3_read_task_callback_t*", {
+            "on_complete": self._on_complete,
+            "on_failure": self._on_failure,
+            "on_destroy": ffi.NULL,
+            "ctx": ffi.NULL,
+        })[0]
+
+
+class CommandTaskCallback(TaskCallback):
+    """Callback for command (operate/select) operations."""
+
+    def __init__(self):
+        super().__init__()
+
+        @ffi.callback("void(dnp3_nothing_t, void*)")
+        def _on_complete(nothing, ctx):
+            self._signal_success()
+
+        @ffi.callback("void(dnp3_command_error_t, void*)")
+        def _on_failure(error, ctx):
+            self._signal_failure(int(error))
+
+        self._on_complete = _on_complete
+        self._on_failure = _on_failure
+
+    def as_ffi(self):
+        return ffi.new("dnp3_command_task_callback_t*", {
+            "on_complete": self._on_complete,
+            "on_failure": self._on_failure,
+            "on_destroy": ffi.NULL,
+            "ctx": ffi.NULL,
+        })[0]
+
+
+class TimeSyncTaskCallback(TaskCallback):
+    """Callback for time sync operations."""
+
+    def __init__(self):
+        super().__init__()
+
+        @ffi.callback("void(dnp3_nothing_t, void*)")
+        def _on_complete(nothing, ctx):
+            self._signal_success()
+
+        @ffi.callback("void(dnp3_time_sync_error_t, void*)")
+        def _on_failure(error, ctx):
+            self._signal_failure(int(error))
+
+        self._on_complete = _on_complete
+        self._on_failure = _on_failure
+
+    def as_ffi(self):
+        return ffi.new("dnp3_time_sync_task_callback_t*", {
+            "on_complete": self._on_complete,
+            "on_failure": self._on_failure,
+            "on_destroy": ffi.NULL,
+            "ctx": ffi.NULL,
+        })[0]
+
+
+class RestartTaskCallback(TaskCallback):
+    """Callback for restart operations — returns delay in ms."""
+
+    def __init__(self):
+        super().__init__()
+
+        @ffi.callback("void(uint64_t, void*)")
+        def _on_complete(delay, ctx):
+            self._signal_success(delay)
+
+        @ffi.callback("void(dnp3_restart_error_t, void*)")
+        def _on_failure(error, ctx):
+            self._signal_failure(int(error))
+
+        self._on_complete = _on_complete
+        self._on_failure = _on_failure
+
+    def as_ffi(self):
+        return ffi.new("dnp3_restart_task_callback_t*", {
+            "on_complete": self._on_complete,
+            "on_failure": self._on_failure,
+            "on_destroy": ffi.NULL,
+            "ctx": ffi.NULL,
+        })[0]
+
+
+class EmptyResponseCallback(TaskCallback):
+    """Callback for operations that expect empty responses."""
+
+    def __init__(self):
+        super().__init__()
+
+        @ffi.callback("void(dnp3_nothing_t, void*)")
+        def _on_complete(nothing, ctx):
+            self._signal_success()
+
+        @ffi.callback("void(dnp3_empty_response_error_t, void*)")
+        def _on_failure(error, ctx):
+            self._signal_failure(int(error))
+
+        self._on_complete = _on_complete
+        self._on_failure = _on_failure
+
+    def as_ffi(self):
+        return ffi.new("dnp3_empty_response_callback_t*", {
+            "on_complete": self._on_complete,
+            "on_failure": self._on_failure,
+            "on_destroy": ffi.NULL,
+            "ctx": ffi.NULL,
+        })[0]
+
+
+class LinkStatusCallback(TaskCallback):
+    """Callback for link status check."""
+
+    def __init__(self):
+        super().__init__()
+
+        @ffi.callback("void(dnp3_nothing_t, void*)")
+        def _on_complete(nothing, ctx):
+            self._signal_success()
+
+        @ffi.callback("void(dnp3_link_status_error_t, void*)")
+        def _on_failure(error, ctx):
+            self._signal_failure(int(error))
+
+        self._on_complete = _on_complete
+        self._on_failure = _on_failure
+
+    def as_ffi(self):
+        return ffi.new("dnp3_link_status_callback_t*", {
+            "on_complete": self._on_complete,
+            "on_failure": self._on_failure,
+            "on_destroy": ffi.NULL,
+            "ctx": ffi.NULL,
+        })[0]

dnp3/logging.py

@@ -0,0 +1,93 @@
+"""
+DNP3 protocol logging configuration.
+
+Wraps the stepfunc/dnp3 tracing/logging subsystem.
+"""
+
+from enum import IntEnum
+from typing import Optional, Callable
+
+from ._ffi import ffi, lib, check_error
+
+_logging_configured = False
+
+
+class LogLevel(IntEnum):
+    ERROR = 0
+    WARN = 1
+    INFO = 2
+    DEBUG = 3
+    TRACE = 4
+
+
+class LogOutputFormat(IntEnum):
+    TEXT = 0
+    JSON = 1
+
+
+class TimeFormat(IntEnum):
+    NONE = 0
+    RFC_3339 = 1
+    SYSTEM = 2
+
+
+def configure_logging(
+    level: LogLevel = LogLevel.WARN,
+    output_format: LogOutputFormat = LogOutputFormat.TEXT,
+    print_level: bool = True,
+    print_module_info: bool = False,
+    time_format: TimeFormat = TimeFormat.SYSTEM,
+    callback: Optional[Callable[[LogLevel, str], None]] = None,
+):
+    """
+    Configure the DNP3 library logging.
+
+    Can only be called once. Subsequent calls will be ignored.
+
+    Args:
+        level: Minimum log level
+        output_format: Text or JSON
+        print_level: Include log level in output
+        print_module_info: Include module info
+        time_format: Timestamp format
+        callback: Optional callback for log messages. If None, logs to stdout.
+    """
+    global _logging_configured
+    if _logging_configured:
+        return
+    _logging_configured = True
+
+    config = ffi.new("dnp3_logging_config_t*")
+    config.level = level.value
+    config.output_format = output_format.value
+    config.print_level = print_level
+    config.print_module_info = print_module_info
+    config.time_format = time_format.value
+
+    if callback is not None:
+        @ffi.callback("void(dnp3_log_level_t, const char*, void*)")
+        def _on_message(lvl, msg, ctx):
+            callback(LogLevel(lvl), ffi.string(msg).decode())
+
+        # Must keep reference alive
+        configure_logging._callback_ref = _on_message
+
+        logger = ffi.new("dnp3_logger_t*", {
+            "on_message": _on_message,
+            "on_destroy": ffi.NULL,
+            "ctx": ffi.NULL,
+        })[0]
+    else:
+        @ffi.callback("void(dnp3_log_level_t, const char*, void*)")
+        def _on_message(lvl, msg, ctx):
+            print(ffi.string(msg).decode(), end="")
+
+        configure_logging._callback_ref = _on_message
+
+        logger = ffi.new("dnp3_logger_t*", {
+            "on_message": _on_message,
+            "on_destroy": ffi.NULL,
+            "ctx": ffi.NULL,
+        })[0]
+
+    lib.dnp3_configure_logging(config[0], logger)