#2257: applications and services docs

docs/source/simulation_components/system/services/ftp_client.rst

@@ -2,16 +2,17 @@
 
     © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
 
+.. _FTPClient:
 
 FTPClient
-=========
+#########
 
-The ``FTPClient`` provides a client interface for connecting to the ``FTPServer``.
+The ``FTPClient`` provides a client interface for connecting to the :ref:`FTPServer`.
 
 Key features
-^^^^^^^^^^^^
+============
 
-- Connects to the ``FTPServer`` via the ``SoftwareManager``.
+- Connects to the :ref:`FTPServer` via the ``SoftwareManager``.
 - Simulates FTP requests and FTPPacket transfer across a network
 - Allows the emulation of FTP commands between an FTP client and server:
     - PORT: specifies the port that server should connect to on the client (currently only uses ``Port.FTP``)
@@ -21,7 +22,7 @@ Key features
 - Leverages the Service base class for install/uninstall, status tracking, etc.
 
 Usage
-^^^^^
+=====
 
 - Install on a Node via the ``SoftwareManager`` to start the FTP client service.
 - Service runs on FTP (command) port 21 by default. (TODO: look at in depth implementation of FTP PORT command)
@@ -29,81 +30,61 @@ Usage
 - Execute retrieving a file from the FTP server with ``request_file``
 
 Implementation
-^^^^^^^^^^^^^^
+==============
 
 - Leverages ``SoftwareManager`` for sending payloads over the network.
 - Provides easy interface for Nodes to transfer files between each other.
 - Extends base Service class.
 
+Examples
+========
 
-Example Usage
--------------
-
-Dependencies
-^^^^^^^^^^^^
+Python
+""""""
 
 .. code-block:: python
 
-    from ipaddress import IPv4Address
-
-    from primaite.simulator.network.container import Network
-    from primaite.simulator.network.hardware.nodes.computer import Computer
-    from primaite.simulator.network.hardware.nodes.server import Server
-    from primaite.simulator.system.services.ftp.ftp_server import FTPServer
+    from primaite.simulator.network.hardware.nodes.host.server import Server
     from primaite.simulator.system.services.ftp.ftp_client import FTPClient
-    from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
 
-Example peer to peer network
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: python
-
-    net = Network()
-
-    pc1 = Computer(
-        hostname="pc1",
-        ip_address="120.10.10.10",
+    # Create Server
+    server = Server(
+        hostname="server",
+        ip_address="192.168.2.2",
         subnet_mask="255.255.255.0",
-        operating_state=NodeOperatingState.ON # initialise the computer in an ON state
+        default_gateway="192.168.1.1Ó",
+        start_up_duration=0,
     )
-    srv = Server(
-        hostname="srv",
-        ip_address="120.10.10.20",
-        subnet_mask="255.255.255.0",
-        operating_state=NodeOperatingState.ON # initialise the server in an ON state
-    )
-    net.connect(pc1.network_interface[1], srv.network_interface[1])
+    server.power_on()
 
-Install the FTP Server
-^^^^^^^^^^^^^^^^^^^^^^
+    # Install FTPClient on server
+    server.software_manager.install(FTPClient)
+    ftp_client: FTPClient = server.software_manager.software.get("FTPClient")
+    ftp_client.start()
 
-FTP Client should be pre installed on nodes
 
-.. code-block:: python
+Via Configuration
+"""""""""""""""""
 
-    srv.software_manager.install(FTPServer)
-    ftpserv: FTPServer = srv.software_manager.software['FTPServer']
+.. code-block:: yaml
 
-Setting up the FTP Server
-^^^^^^^^^^^^^^^^^^^^^^^^^
+    simulation:
+        network:
+            nodes:
+                - ref: example_server
+                hostname: example_server
+                type: server
+                ...
+                services:
+                    - ref: ftp_client
+                    type: FTPClient
 
-Set up the FTP Server with a file that the client will need to retrieve
+Configuration
+=============
 
-.. code-block:: python
+.. include:: ../common/common_configuration.rst
 
-    srv.file_system.create_file('my_file.png')
+.. |SOFTWARE_NAME| replace:: FTPClient
+.. |SOFTWARE_NAME_BACKTICK| replace:: ``FTPClient``
 
-Check that file was retrieved
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: python
-
-    client.request_file(
-        src_folder_name='root',
-        src_file_name='my_file.png',
-        dest_folder_name='root',
-        dest_file_name='test.png',
-        dest_ip_address=IPv4Address("120.10.10.20")
-    )
-
-    print(client.get_file(folder_name="root", file_name="test.png"))
+**FTPClient has no configuration options**