✨ add feature to remove points and stations #47

Author: m-unkel

c104/__init__.pyi

@@ -891,6 +891,24 @@ class Connection:
         >>>
         >>> my_connection.on_unexpected_message(callable=con_on_unexpected_message)
         """
+    def remove_station(self, common_address: int) -> bool:
+        """
+        removes an existing station from this connection
+
+        Parameters
+        ----------
+        common_address: int
+            station common address (value between 1 and 65534)
+
+        Returns
+        -------
+        bool
+            True if the station was successfully removed, otherwise False.
+
+        Example
+        -------
+        >>> my_connection.remove_station(common_address=12)
+        """
     def test(self, common_address: int, with_time: bool = True, wait_for_response: bool = True) -> bool:
         """
         send a test command to the remote terminal unit (server)
@@ -2714,6 +2732,24 @@ class Server:
         >>>
         >>> my_server.on_unexpected_message(callable=sv_on_unexpected_message)
         """
+    def remove_station(self, common_address: int) -> bool:
+        """
+        removes an existing station from this server
+
+        Parameters
+        ----------
+        common_address: int
+            station common address (value between 1 and 65534)
+
+        Returns
+        -------
+        bool
+            True if the station was successfully removed, otherwise False.
+
+        Example
+        -------
+        >>> station_3.remove_station(common_address=12)
+        """
     def start(self) -> None:
         """
         open local server socket for incoming connections
@@ -3085,6 +3121,24 @@ class Station:
         -------
         >>> point_11 = my_station.get_point(io_address=11)
         """
+    def remove_point(self, io_address: int) -> bool:
+        """
+        remove an existing point from this station
+
+        Parameters
+        ----------
+        io_address: int
+            point information object address (value between 0 and 16777215)
+
+        Returns
+        -------
+        bool
+            information, if point was removed
+
+        Example
+        -------
+        >>> sv_station_1.remove_point(io_address=34566)
+        """
     def signal_initialized(self, cause: Coi) -> None:
         """
         signal end of initialization for this station to connected clients
@@ -3986,4 +4040,4 @@ def set_debug_mode(mode: Debug) -> None:
     -------
     >>> c104.set_debug_mode(mode=c104.Debug.Client|c104.Debug.Connection)
     """
-__version__: str = '2.1.1'
+__version__: str = '2.2.0'

docs/source/changelog.rst

@@ -1,6 +1,15 @@
 Change log
 ==========
 
+v2.2.0
+-------
+
+Features
+^^^^^^^^
+
+- Add **Server.remove_station(common_address: int)** and **Connection.remove_station(common_address: int)**- methods to enable the removal of stations.
+- Add **Station.remove_point(io_address: int)** method to allow the removal of points and facilitate reassigning the ``io_address`` to another point type.
+
 v2.1.1
 -------
 

docs/source/conf.py

@@ -13,8 +13,8 @@
 copyright = "2020-2025, Fraunhofer Institute for Applied Information Technology FIT"
 author = "Martin Unkel <[email protected]>"
 
-release = "2.1"
-version = "2.1.1"
+release = "2.2"
+version = "2.2.0"
 
 
 # -- General configuration ---------------------------------------------------

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "c104"
-version = "2.1.1"
+version = "2.2.0"
 description = "A Python module to simulate SCADA and RTU communication over protocol 60870-5-104 to research ICT behavior in power grids."
 readme = {file = "README.md", content-type = "text/markdown"}
 license = {file = "LICENSE"}

src/Server.cpp

@@ -384,6 +384,30 @@ Server::addStation(std::uint_fast16_t commonAddress) {
   return station;
 }
 
+bool Server::removeStation(std::uint_fast16_t commonAddress) {
+  std::lock_guard<Module::GilAwareMutex> const lock(station_mutex);
+
+  DEBUG_PRINT(Debug::Server,
+              "remove_station] CA " + std::to_string(commonAddress));
+
+  size_t originalSize = stations.size();
+
+  stations.erase(
+      std::remove_if(
+          stations.begin(), stations.end(),
+          [commonAddress](const std::shared_ptr<Object::Station> &station) {
+            // Check if the current DataPoint matches the provided address
+            if (station->getCommonAddress() == commonAddress) {
+              station->detach();
+              return true;
+            }
+            return false;
+          }),
+      stations.end());
+
+  return (stations.size() < originalSize); // Success if the size decreased
+}
+
 void Server::cleanupSelections() {
   auto now = std::chrono::steady_clock::now();
   std::lock_guard<Module::GilAwareMutex> const lock(selection_mutex);

src/Server.h

@@ -216,29 +216,45 @@ class Server : public std::enable_shared_from_this<Server> {
 
   /**
    * @brief Get a list of all Stations
-   * @return vector with object stationer
+   * @return vector with station objects
    */
   Object::StationVector getStations() const;
 
   /**
-   * @brief Get a Station that exists at this NetworkStation and is identified
-   * via information object address
-   * @return Stationer to Station or nullptr
+   * @brief Retrieves a Station that exists on this Server, identified by the
+   * given information object address.
+   * @param ca The common address (CA) that uniquely identifies the Station.
+   * @return A shared pointer to the Station if it exists, or nullptr if no
+   * matching Station is found.
    */
   std::shared_ptr<Object::Station>
   getStation(std::uint_fast16_t commonAddress) const;
 
   /**
-   * @brief Test if Stations exists at this NetworkStation
-   * @return information on availability of child Station objects
+   * @brief Checks whether a Station with the given common address exists on
+   * this Server.
+   * @param commonAddress The common address (CA) used to identify the Station.
+   * @return True if a Station with the specified common address exists,
+   * otherwise false.
    */
   bool hasStation(std::uint_fast16_t commonAddress) const;
 
   /**
-   * @brief Add a Station to this Station
+   * @brief Adds a new Station to this Server.
+   * @param commonAddress The common address (CA) that uniquely identifies the
+   * new Station.
+   * @return A shared pointer to the newly added Station.
    */
   std::shared_ptr<Object::Station> addStation(std::uint_fast16_t commonAddress);
 
+  /**
+   * @brief Removes an existing Station from this Server.
+   *
+   * @param commonAddress The common address (CA) of the Station to be removed.
+   * @return True if the Station was successfully removed, otherwise false.
+   */
+  bool removeStation(std::uint_fast16_t commonAddress);
+
   /**
    * @brief Get a reference to the protocol parameters to be able to read and
    * update these

src/object/DataPoint.cpp

@@ -1236,3 +1236,5 @@ bool DataPoint::transmit(const CS101_CauseOfTransmission cause) {
   }
   return connection->transmit(shared_from_this(), cause);
 }
+
+void DataPoint::detach() { station.reset(); }

src/object/DataPoint.h

@@ -109,7 +109,7 @@ class DataPoint : public std::enable_shared_from_this<DataPoint> {
   const IEC60870_5_TypeID type;
 
   /// @brief parent Station object (not owning pointer)
-  const std::weak_ptr<Station> station;
+  std::weak_ptr<Station> station;
 
   /// @brief IEC60870-5 remote address of a related measurement DataPoint
   std::atomic_uint_fast32_t relatedInformationObjectAddress{0};
@@ -393,6 +393,12 @@ class DataPoint : public std::enable_shared_from_this<DataPoint> {
    */
   bool transmit(CS101_CauseOfTransmission cause = CS101_COT_UNKNOWN_COT);
 
+  /**
+   * @brief Remove reference to station, do not call this method, this is called
+   * by Station::removePoint
+   */
+  void detach();
+
   /**
    * @brief Converts the current DataPoint object to a string representation,
    * including its various properties.

src/object/Station.cpp

@@ -1,5 +1,5 @@
 /**
- * Copyright 2020-2024 Fraunhofer Institute for Applied Information Technology
+ * Copyright 2020-2025 Fraunhofer Institute for Applied Information Technology
  * FIT
  *
  * This file is part of iec104-python.
@@ -129,13 +129,44 @@ std::shared_ptr<DataPoint> Station::addPoint(
   return point;
 }
 
+bool Station::removePoint(const std::uint_fast32_t informationObjectAddress) {
+  std::scoped_lock<Module::GilAwareMutex> const lock(points_mutex);
+
+  DEBUG_PRINT(Debug::Station,
+              "remove_point] IOA " + std::to_string(informationObjectAddress));
+
+  size_t originalSize = points.size();
+
+  // Use std::remove_if to find and remove the entry
+  points.erase(std::remove_if(points.begin(), points.end(),
+                              [informationObjectAddress](
+                                  const std::shared_ptr<DataPoint> &point) {
+                                // Check if the current DataPoint matches the
+                                // provided address
+                                if (point->getInformationObjectAddress() ==
+                                    informationObjectAddress) {
+                                  point->detach();
+                                  return true;
+                                }
+                                return false;
+                              }),
+               points.end());
+
+  return (points.size() < originalSize); // Success if the size decreased
+}
+
 bool Station::isLocal() { return !server.expired(); }
 
 void Station::sendEndOfInitialization(const CS101_CauseOfInitialization cause) {
   if (auto sv = getServer()) {
     return sv->sendEndOfInitialization(commonAddress, cause);
   }
 
-  throw new std::runtime_error(
+  throw std::runtime_error(
       "Cannot send end of initialization: not a server station");
 }
+
+void Station::detach() {
+  server.reset();
+  connection.reset();
+}

src/object/Station.h

@@ -84,10 +84,10 @@ class Station : public std::enable_shared_from_this<Station> {
   const std::uint_fast16_t commonAddress{0};
 
   /// @brief server object reference (only local station)
-  const std::weak_ptr<Server> server;
+  std::weak_ptr<Server> server;
 
   /// @brief remote connection object reference (only remote station)
-  const std::weak_ptr<Remote::Connection> connection;
+  std::weak_ptr<Remote::Connection> connection;
 
   /// @brief child DataPoint objects (owned by this Station)
   DataPointVector points{};
@@ -159,6 +159,15 @@ class Station : public std::enable_shared_from_this<Station> {
            bool relatedInformationObjectAutoReturn = false,
            CommandTransmissionMode commandMode = DIRECT_COMMAND);
 
+  /**
+   * @brief Removes an existing DataPoint from this Station.
+   * @param informationObjectAddress The address of the information object to be
+   * removed.
+   * @return True if the DataPoint was successfully found and removed, otherwise
+   * false.
+   */
+  bool removePoint(std::uint_fast32_t informationObjectAddress);
+
   /**
    * @brief test if this station belongs to a server instance and not a
    * connection (client)
@@ -174,6 +183,12 @@ class Station : public std::enable_shared_from_this<Station> {
    */
   void sendEndOfInitialization(CS101_CauseOfInitialization cause);
 
+  /**
+   * @brief Remove reference to station, do not call this method, this is called
+   * by Station::removePoint
+   */
+  void detach();
+
   /**
    * @brief Generates a string representation of the Station object.
    *