pydnp3-stepfunc 1.6.0.3__cp310-cp310-manylinux1_x86_64.whl

dnp3/master.py

@@ -0,0 +1,539 @@
+"""
+Master station implementation wrapping the stepfunc/dnp3 C FFI.
+
+Provides a high-level API for DNP3 master operations including:
+- Polling (integrity, event, class-based)
+- Read operations (specific group/variation)
+- Control operations (SBO, direct operate)
+- Time synchronization
+- Restart commands
+- Device attribute reading
+"""
+
+from typing import Optional, List, Dict, Any
+
+from ._ffi import ffi, lib, check_error, DNP3Error
+from .types import (
+    Variation,
+    CommandMode,
+    TimeSyncMode,
+    FunctionCode,
+    AutoTimeSync,
+    DecodeLevel,
+    Group12Var1,
+    ControlCode,
+    OpType,
+    TripCloseCode,
+)
+from .handler import (
+    ReadHandler,
+    ReadTaskCallback,
+    CommandTaskCallback,
+    TimeSyncTaskCallback,
+    RestartTaskCallback,
+    EmptyResponseCallback,
+    LinkStatusCallback,
+    AssociationHandler,
+    AssociationInformation,
+    ClientStateListener,
+)
+
+
+class AssociationConfig:
+    """Configuration for a master-outstation association."""
+
+    def __init__(
+        self,
+        disable_unsol_classes: tuple = (True, True, True),  # class 1,2,3
+        enable_unsol_classes: tuple = (True, True, True),
+        startup_integrity_classes: tuple = (True, True, True, True),  # class 0,1,2,3
+        event_scan_on_events_available: tuple = (False, False, False),
+        auto_time_sync: AutoTimeSync = AutoTimeSync.LAN,
+        keep_alive_timeout: int = 60,  # seconds
+        auto_tasks_retry_strategy_min_delay: int = 1000,  # ms
+        auto_tasks_retry_strategy_max_delay: int = 30000,  # ms
+        response_timeout: int = 5000,  # ms
+        auto_integrity_scan_on_buffer_overflow: bool = True,
+        max_queued_user_requests: int = 16,
+    ):
+        self.disable_unsol_classes = disable_unsol_classes
+        self.enable_unsol_classes = enable_unsol_classes
+        self.startup_integrity_classes = startup_integrity_classes
+        self.event_scan_on_events_available = event_scan_on_events_available
+        self.auto_time_sync = auto_time_sync
+        self.keep_alive_timeout = keep_alive_timeout
+        self.auto_tasks_retry_strategy_min_delay = auto_tasks_retry_strategy_min_delay
+        self.auto_tasks_retry_strategy_max_delay = auto_tasks_retry_strategy_max_delay
+        self.response_timeout = response_timeout
+        self.auto_integrity_scan_on_buffer_overflow = auto_integrity_scan_on_buffer_overflow
+        self.max_queued_user_requests = max_queued_user_requests
+
+    def to_ffi(self):
+        config = ffi.new("dnp3_association_config_t*")
+
+        # Response timeout (ms)
+        config.response_timeout = self.response_timeout
+
+        # Disable unsolicited classes
+        config.disable_unsol_classes.class1 = self.disable_unsol_classes[0]
+        config.disable_unsol_classes.class2 = self.disable_unsol_classes[1]
+        config.disable_unsol_classes.class3 = self.disable_unsol_classes[2]
+
+        # Enable unsolicited classes
+        config.enable_unsol_classes.class1 = self.enable_unsol_classes[0]
+        config.enable_unsol_classes.class2 = self.enable_unsol_classes[1]
+        config.enable_unsol_classes.class3 = self.enable_unsol_classes[2]
+
+        # Startup integrity poll classes
+        config.startup_integrity_classes.class0 = self.startup_integrity_classes[0]
+        config.startup_integrity_classes.class1 = self.startup_integrity_classes[1]
+        config.startup_integrity_classes.class2 = self.startup_integrity_classes[2]
+        config.startup_integrity_classes.class3 = self.startup_integrity_classes[3]
+
+        config.auto_time_sync = self.auto_time_sync.value
+        config.auto_tasks_retry_strategy.min_delay = self.auto_tasks_retry_strategy_min_delay
+        config.auto_tasks_retry_strategy.max_delay = self.auto_tasks_retry_strategy_max_delay
+        config.keep_alive_timeout = self.keep_alive_timeout
+        config.auto_integrity_scan_on_buffer_overflow = self.auto_integrity_scan_on_buffer_overflow
+
+        # Event scan on events available
+        config.event_scan_on_events_available.class1 = self.event_scan_on_events_available[0]
+        config.event_scan_on_events_available.class2 = self.event_scan_on_events_available[1]
+        config.event_scan_on_events_available.class3 = self.event_scan_on_events_available[2]
+
+        config.max_queued_user_requests = self.max_queued_user_requests
+
+        return config[0]
+
+
+class AssociationId:
+    """Wraps the C association_id struct."""
+
+    def __init__(self, c_id):
+        self._id = c_id
+
+    @property
+    def address(self):
+        return self._id.address
+
+    @property
+    def raw(self):
+        return self._id
+
+
+class PollId:
+    """Wraps the C poll_id struct."""
+
+    def __init__(self, c_id):
+        self._id = c_id
+
+    @property
+    def raw(self):
+        return self._id
+
+
+class MasterChannel:
+    """
+    High-level wrapper around a DNP3 master channel.
+
+    Manages associations and provides methods for read, control,
+    time sync, and restart operations.
+    """
+
+    def __init__(self, ptr, listener=None):
+        self._ptr = ptr
+        self._listener = listener
+        self._destroyed = False
+
+    def destroy(self):
+        """Destroy the channel and free resources."""
+        if not self._destroyed and self._ptr is not None:
+            lib.dnp3_master_channel_destroy(self._ptr)
+            self._destroyed = True
+
+    def __del__(self):
+        self.destroy()
+
+    def enable(self):
+        """Enable communications on the channel."""
+        check_error(lib.dnp3_master_channel_enable(self._ptr))
+
+    def disable(self):
+        """Disable communications on the channel."""
+        check_error(lib.dnp3_master_channel_disable(self._ptr))
+
+    def set_decode_level(self, level: DecodeLevel):
+        """Set the decode/logging level."""
+        c_level = ffi.new("dnp3_decode_level_t*", level.to_ffi())[0]
+        check_error(lib.dnp3_master_channel_set_decode_level(self._ptr, c_level))
+
+    def add_association(
+        self,
+        address: int,
+        read_handler: Optional[ReadHandler] = None,
+        config: Optional[AssociationConfig] = None,
+        assoc_handler: Optional[AssociationHandler] = None,
+        assoc_info: Optional[AssociationInformation] = None,
+    ) -> AssociationId:
+        """
+        Add a master-outstation association.
+
+        Args:
+            address: Outstation DNP3 address
+            read_handler: Handler for received data
+            config: Association configuration
+            assoc_handler: Time provider
+            assoc_info: Task status receiver
+
+        Returns:
+            AssociationId for use in subsequent operations
+        """
+        read_handler = read_handler or ReadHandler()
+        config = config or AssociationConfig()
+        assoc_handler = assoc_handler or AssociationHandler()
+        assoc_info = assoc_info or AssociationInformation()
+
+        # Keep references to handlers to prevent GC
+        self._read_handler = read_handler
+        self._assoc_handler = assoc_handler
+        self._assoc_info = assoc_info
+
+        assoc_id = ffi.new("dnp3_association_id_t*")
+        err = lib.dnp3_master_channel_add_association(
+            self._ptr,
+            address,
+            config.to_ffi(),
+            read_handler.as_ffi(),
+            assoc_handler.as_ffi(),
+            assoc_info.as_ffi(),
+            assoc_id,
+        )
+        check_error(err)
+        return AssociationId(assoc_id[0])
+
+    def remove_association(self, assoc_id: AssociationId):
+        """Remove an association."""
+        check_error(lib.dnp3_master_channel_remove_association(self._ptr, assoc_id.raw))
+
+    def add_poll(
+        self,
+        assoc_id: AssociationId,
+        class0: bool = False,
+        class1: bool = True,
+        class2: bool = True,
+        class3: bool = True,
+        period_ms: int = 5000,
+    ) -> PollId:
+        """
+        Add a periodic poll to the association.
+
+        Args:
+            assoc_id: Association to poll on
+            class0: Include Class 0 (static data)
+            class1: Include Class 1 events
+            class2: Include Class 2 events
+            class3: Include Class 3 events
+            period_ms: Poll period in milliseconds
+
+        Returns:
+            PollId for managing the poll
+        """
+        request = lib.dnp3_request_new_class(class0, class1, class2, class3)
+        poll_id = ffi.new("dnp3_poll_id_t*")
+        err = lib.dnp3_master_channel_add_poll(
+            self._ptr, assoc_id.raw, request, period_ms, poll_id
+        )
+        lib.dnp3_request_destroy(request)
+        check_error(err)
+        return PollId(poll_id[0])
+
+    def demand_poll(self, poll_id: PollId):
+        """Trigger an immediate execution of a poll."""
+        check_error(lib.dnp3_master_channel_demand_poll(self._ptr, poll_id.raw))
+
+    def remove_poll(self, poll_id: PollId):
+        """Remove a poll."""
+        check_error(lib.dnp3_master_channel_remove_poll(self._ptr, poll_id.raw))
+
+    def read(
+        self,
+        assoc_id: AssociationId,
+        variation: Optional[Variation] = None,
+        class0: bool = True,
+        class1: bool = True,
+        class2: bool = True,
+        class3: bool = True,
+        start: Optional[int] = None,
+        stop: Optional[int] = None,
+        timeout: float = 30.0,
+    ) -> bool:
+        """
+        Perform a one-shot read operation.
+
+        If variation is specified, reads that specific group/variation.
+        Otherwise reads by class.
+
+        Args:
+            assoc_id: Association to read from
+            variation: Specific variation to read (e.g., Variation.GROUP30_VAR0)
+            class0-3: Classes to include when variation is None
+            start: Start index for range reads
+            stop: Stop index for range reads
+            timeout: Timeout in seconds
+
+        Returns:
+            True if read succeeded, False on timeout/error
+        """
+        if variation is not None:
+            if start is not None and stop is not None:
+                request = lib.dnp3_request_new_two_byte_range(variation.value, start, stop)
+            else:
+                request = lib.dnp3_request_new_all_objects(variation.value)
+        else:
+            request = lib.dnp3_request_new_class(class0, class1, class2, class3)
+
+        cb = ReadTaskCallback()
+        err = lib.dnp3_master_channel_read(
+            self._ptr, assoc_id.raw, request, cb.as_ffi()
+        )
+        lib.dnp3_request_destroy(request)
+        check_error(err)
+
+        cb.wait(timeout)
+        return cb.success
+
+    def read_attributes(
+        self,
+        assoc_id: AssociationId,
+        variation: int = 0xFE,  # ALL_ATTRIBUTES_REQUEST
+        set_id: int = 0,
+        timeout: float = 30.0,
+    ) -> bool:
+        """
+        Read device attributes (Group 0).
+
+        Args:
+            assoc_id: Association
+            variation: Attribute variation (0xFE = all attributes request)
+            set_id: Attribute set (default 0)
+            timeout: Timeout in seconds
+
+        Returns:
+            True if read succeeded
+        """
+        request = lib.dnp3_request_create()
+        lib.dnp3_request_add_specific_attribute(request, variation, set_id)
+
+        cb = ReadTaskCallback()
+        err = lib.dnp3_master_channel_read(
+            self._ptr, assoc_id.raw, request, cb.as_ffi()
+        )
+        lib.dnp3_request_destroy(request)
+        check_error(err)
+
+        cb.wait(timeout)
+        return cb.success
+
+    def operate(
+        self,
+        assoc_id: AssociationId,
+        mode: CommandMode = CommandMode.SELECT_BEFORE_OPERATE,
+        crob_commands: Optional[List[tuple]] = None,
+        analog_int32_commands: Optional[List[tuple]] = None,
+        analog_float_commands: Optional[List[tuple]] = None,
+        analog_double_commands: Optional[List[tuple]] = None,
+        timeout: float = 30.0,
+    ) -> bool:
+        """
+        Perform a control operation.
+
+        Args:
+            assoc_id: Association
+            mode: SELECT_BEFORE_OPERATE or DIRECT_OPERATE
+            crob_commands: List of (index, Group12Var1) tuples for binary output control
+            analog_int32_commands: List of (index, value) for G41V1
+            analog_float_commands: List of (index, value) for G41V3
+            analog_double_commands: List of (index, value) for G41V4
+            timeout: Timeout in seconds
+
+        Returns:
+            True if operation succeeded
+        """
+        commands = lib.dnp3_command_set_create()
+
+        if crob_commands:
+            for idx, g12v1 in crob_commands:
+                c_g12v1 = ffi.new("dnp3_group12_var1_t*", g12v1.to_ffi())[0]
+                lib.dnp3_command_set_add_g12_v1_u16(commands, idx, c_g12v1)
+
+        if analog_int32_commands:
+            for idx, value in analog_int32_commands:
+                lib.dnp3_command_set_add_g41_v1_u16(commands, idx, value)
+
+        if analog_float_commands:
+            for idx, value in analog_float_commands:
+                lib.dnp3_command_set_add_g41_v3_u16(commands, idx, value)
+
+        if analog_double_commands:
+            for idx, value in analog_double_commands:
+                lib.dnp3_command_set_add_g41_v4_u16(commands, idx, value)
+
+        cb = CommandTaskCallback()
+        err = lib.dnp3_master_channel_operate(
+            self._ptr, assoc_id.raw, mode.value, commands, cb.as_ffi()
+        )
+        lib.dnp3_command_set_destroy(commands)
+        check_error(err)
+
+        cb.wait(timeout)
+        return cb.success
+
+    def select_before_operate(
+        self,
+        assoc_id: AssociationId,
+        index: int,
+        op_type: OpType = OpType.LATCH_ON,
+        tcc: TripCloseCode = TripCloseCode.NUL,
+        timeout: float = 30.0,
+    ) -> bool:
+        """
+        Convenience: Perform a Select-Before-Operate binary output control.
+
+        Args:
+            assoc_id: Association
+            index: Binary output index
+            op_type: Operation type (LATCH_ON, LATCH_OFF, PULSE_ON, etc.)
+            tcc: Trip-Close code
+            timeout: Timeout
+
+        Returns:
+            True if successful
+        """
+        g12v1 = Group12Var1(
+            code=ControlCode(tcc=tcc, op_type=op_type),
+        )
+        return self.operate(
+            assoc_id,
+            mode=CommandMode.SELECT_BEFORE_OPERATE,
+            crob_commands=[(index, g12v1)],
+            timeout=timeout,
+        )
+
+    def direct_operate(
+        self,
+        assoc_id: AssociationId,
+        index: int,
+        op_type: OpType = OpType.LATCH_ON,
+        tcc: TripCloseCode = TripCloseCode.NUL,
+        timeout: float = 30.0,
+    ) -> bool:
+        """Convenience: Perform a Direct Operate binary output control."""
+        g12v1 = Group12Var1(
+            code=ControlCode(tcc=tcc, op_type=op_type),
+        )
+        return self.operate(
+            assoc_id,
+            mode=CommandMode.DIRECT_OPERATE,
+            crob_commands=[(index, g12v1)],
+            timeout=timeout,
+        )
+
+    def synchronize_time(
+        self,
+        assoc_id: AssociationId,
+        mode: TimeSyncMode = TimeSyncMode.LAN,
+        timeout: float = 30.0,
+    ) -> bool:
+        """Synchronize time with the outstation."""
+        cb = TimeSyncTaskCallback()
+        err = lib.dnp3_master_channel_synchronize_time(
+            self._ptr, assoc_id.raw, mode.value, cb.as_ffi()
+        )
+        check_error(err)
+        cb.wait(timeout)
+        return cb.success
+
+    def cold_restart(
+        self,
+        assoc_id: AssociationId,
+        timeout: float = 30.0,
+    ) -> Optional[int]:
+        """
+        Send a cold restart command.
+
+        Returns:
+            Delay in ms before restart, or None on failure
+        """
+        cb = RestartTaskCallback()
+        err = lib.dnp3_master_channel_cold_restart(
+            self._ptr, assoc_id.raw, cb.as_ffi()
+        )
+        check_error(err)
+        cb.wait(timeout)
+        return cb.result if cb.success else None
+
+    def warm_restart(
+        self,
+        assoc_id: AssociationId,
+        timeout: float = 30.0,
+    ) -> Optional[int]:
+        """
+        Send a warm restart command.
+
+        Returns:
+            Delay in ms before restart, or None on failure
+        """
+        cb = RestartTaskCallback()
+        err = lib.dnp3_master_channel_warm_restart(
+            self._ptr, assoc_id.raw, cb.as_ffi()
+        )
+        check_error(err)
+        cb.wait(timeout)
+        return cb.result if cb.success else None
+
+    def check_link_status(
+        self,
+        assoc_id: AssociationId,
+        timeout: float = 10.0,
+    ) -> bool:
+        """Check link status with the outstation."""
+        cb = LinkStatusCallback()
+        err = lib.dnp3_master_channel_check_link_status(
+            self._ptr, assoc_id.raw, cb.as_ffi()
+        )
+        check_error(err)
+        cb.wait(timeout)
+        return cb.success
+
+    def send_and_expect_empty_response(
+        self,
+        assoc_id: AssociationId,
+        function_code: FunctionCode,
+        variation: Optional[Variation] = None,
+        timeout: float = 30.0,
+    ) -> bool:
+        """
+        Send a request and expect an empty response (e.g., enable/disable unsolicited).
+
+        Args:
+            assoc_id: Association
+            function_code: DNP3 function code
+            variation: Optional variation to include in request
+            timeout: Timeout
+
+        Returns:
+            True if successful
+        """
+        request = lib.dnp3_request_create()
+        if variation is not None:
+            lib.dnp3_request_add_all_objects_header(request, variation.value)
+
+        cb = EmptyResponseCallback()
+        err = lib.dnp3_master_channel_send_and_expect_empty_response(
+            self._ptr, assoc_id.raw, function_code.value, request, cb.as_ffi()
+        )
+        lib.dnp3_request_destroy(request)
+        check_error(err)
+
+        cb.wait(timeout)
+        return cb.success