#2248 - Enhances the PrimAITE documentation, covering the Node, network interfaces, Session Manager, Software Manager, PCAP service, SysLog functionality, and network devices like Routers, Switches, Computers, and Switch Nodes. It details their roles, workflows, and integration within the simulation, focusing on frame processing, software management, and logging. The documentation also clarifies the frame reception process, including port checks and application-level dispatching, ensuring a thorough understanding of network operations within the simulation

docs/source/simulation_components/system/data_manipulation_bot.rst

@@ -52,7 +52,7 @@ Example
         default_gateway="192.168.10.1"
         operating_state=NodeOperatingState.ON # initialise the computer in an ON state
     )
-    network.connect(endpoint_b=client_1.ethernet_port[1], endpoint_a=switch_2.switch_ports[1])
+    network.connect(endpoint_b=client_1.network_interface[1], endpoint_a=switch_2.network_interface[1])
     client_1.software_manager.install(DataManipulationBot)
     data_manipulation_bot: DataManipulationBot = client_1.software_manager.software.get("DataManipulationBot")
     data_manipulation_bot.configure(server_ip_address=IPv4Address("192.168.1.14"), payload="DELETE")

docs/source/simulation_components/system/ftp_client_server.rst

@@ -98,7 +98,7 @@ Example peer to peer network
         subnet_mask="255.255.255.0",
         operating_state=NodeOperatingState.ON # initialise the server in an ON state
     )
-    net.connect(pc1.ethernet_port[1], srv.ethernet_port[1])
+    net.connect(pc1.network_interface[1], srv.network_interface[1])
 
 Install the FTP Server
 ^^^^^^^^^^^^^^^^^^^^^^

docs/source/simulation_components/system/pcap.rst

@@ -0,0 +1,51 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+PCAP
+====
+
+The ``packet_capture.py`` module introduces a Packet Capture (PCAP) service within PrimAITE, designed to simulate
+packet capturing functionalities for the simulated network environment. This service enables the logging of network
+frames as JSON strings, providing valuable insights into the data flowing across the network.
+
+Overview
+--------
+
+Packet capture is a crucial tool in network analysis, troubleshooting, and monitoring, allowing for the examination of
+packets traversing the network. Within the context of the PrimAITE simulation, the PCAP service enhances the realism
+and depth of network simulations by offering detailed visibility into network communications. Notably, PCAP is created
+by default at the NetworkInterface level.
+
+PacketCapture Class
+-------------------
+
+The ``PacketCapture`` class represents the core of the PCAP service, facilitating the capture and logging of network
+frames for analysis.
+
+**Features:**
+
+- **Automatic Creation:** PCAP is automatically created at the NetworkInterface level, simplifying setup and integration.
+- **Inbound and Outbound Frame Capture:** Frames can be captured and logged separately for inbound and outbound
+  traffic, offering granular insight into network communications.
+- **Logging Format:** Captures and logs frames as JSON strings, ensuring that the data is structured and easily
+  interpretable.
+- **File Location:** PCAP logs are saved to a specified directory within the simulation output, organised by hostname
+  and IP address to facilitate easy retrieval and analysis.
+
+Usage
+-----
+
+The PCAP service is seamlessly integrated within the simulation, automatically capturing and logging frames for both
+inbound and outbound traffic at the NetworkInterface level. This automatic functionality, combined with the ability
+to separate traffic directions, significantly enhances network analysis and troubleshooting capabilities.
+
+This service is particularly useful for:
+
+- **Network Analysis:** Detailed examination of packet flows and protocols within the simulated environment.
+- **Troubleshooting:** Identifying and resolving network issues by analysing packet transmissions and errors.
+- **Educational Purposes:** Teaching network principles and diagnostics through hands-on packet analysis.
+
+The introduction of the ``packet_capture.py`` module significantly enhances the network simulation capabilities of
+PrimAITE. By providing a robust tool for packet capture and analysis, PrimAITE allows users to gain deeper insights
+into network operations, supporting a wide range of educational, developmental, and research activities.

docs/source/simulation_components/system/session_and_software_manager.rst

@@ -0,0 +1,90 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+Session and Software Manager
+============================
+
+The Software Manager and Session Manager are core components of the Node in PrimAITE. These managers orchestrate the
+flow of network frames through the Node, ensuring that frames are processed accurately and passed to the relevant
+services or applications.
+
+The following flow diagram illustrates the journey of a network frame as it navigates through various components within
+the node. Starting from the network interface, the frame progresses to the node, then to the session manager, and
+subsequently to the software manager. From there, it may be directed to one of three potential software destinations:
+ARP, ICMP, or the Web Client. This pathway exemplifies the structured processing sequence designed to ensure that
+each frame reaches its intended target within the simulated environment.
+
+.. image:: node_session_software_model_example.png
+
+Session Manager
+---------------
+
+The `SessionManager` acts as the intermediary between the Node's hardware-level interactions and higher-level software
+processes. It receives frames from the Node and determines the appropriate session or connection context for further
+processing.
+
+**Key Responsibilities:**
+
+- **Frame Handling:** Receives network frames and identifies the session context based on headers and session state.
+- **Protocol Management:** Supports various protocols (e.g., ARP, ICMP) by interpreting protocol-specific information
+  within frames and facilitating their processing.
+- **Session Tracking:** Maintains a record of active sessions and manages their lifecycle, including creation,
+  maintenance, and termination.
+
+**Implementation Overview:**
+
+- Utilises IP and transport layer information to route frames to the correct session.
+- Integrates closely with the `SoftwareManager` to ensure seamless transmission of session-specific data to the
+  application layer.
+
+Software Manager
+----------------
+
+The `SoftwareManager` is responsible for the final step in the frame processing pipeline, handling the delivery of
+network frames to the appropriate software services or applications within the Node.
+
+**Key Responsibilities:**
+
+- **Application Routing:** Determines the target application or service for incoming frames based on protocol and port
+  information.
+- **Software Management:** Oversees the registration, installation, and management of software services and
+  applications, facilitating communication between network layers and application processes.
+- **Frame Dispatching:** Directs frames to their designated applications or services, enabling the processing of
+  network communications at the application layer.
+- **Installation and Uninstallation:** Responsible for the installing and uninstalling of services and applications,
+  managing the availability of software resources on the Node.
+
+**Implementation Overview:**
+
+- Maintains a registry of services and applications, keyed by protocol and port numbers, to efficiently route network
+  traffic.
+- Interacts with the `FileSystem` and other core components to manage application state and data persistence,
+  supporting complex software interactions within the simulated environment.
+
+Integration and Workflow
+------------------------
+
+1. **Initial Port Check:** Upon receiving a network frame at the hardware level, the Node first checks if the
+   destination port and protocol match any software currently running, as managed by the `SoftwareManager`. This step
+   determines if the port is open and if the frame's destination is actively listening for incoming traffic on the Node.
+2. **Frame Acceptance:** If the frame's destination port and protocol are open on the Node, indicating that there is
+   software prepared to handle such traffic, the Node accepts the frame. This verification ensures that only relevant
+   traffic is processed further, enhancing network security and efficiency.
+3. **Session Manager Processing:** Accepted frames are then passed to the `SessionManager`, which analyses the frames
+   within the context of existing sessions or connections. The Session Manager performs protocol-specific handling,
+   routing the frames based on session state and protocol requirements.
+4. **Software Manager Dispatch:** After session processing, frames are dispatched to the `SoftwareManager`, which
+   routes them to the appropriate services or applications. The Software Manager identifies the target based on the
+   frame's destination port and protocol, aligning with the initial port check.
+5. **Application Processing:** The relevant applications or services process the received frames, completing the
+   communication pathway within the Node. This step involves the actual handling of frame data by the intended software,
+   facilitating the intended network operations or communications.
+
+
+Together, the Software Manager and Session Manager form a critical part of the Node's architecture in the PrimAITE,
+facilitating a structured and efficient processing pipeline for network frames. This architecture enables the
+simulation of realistic network environments, where frames are accurately routed and processed, mirroring the
+complexities of real-world network communications. The addition of installation and uninstallation capabilities by
+the Software Manager further enhances the Node's functionality, allowing for dynamic software management within the
+simulated network.

docs/source/simulation_components/system/sys_log.rst

@@ -0,0 +1,51 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+SysLog
+======
+
+The ``sys_log.py`` module introduces a system logging (SysLog) service within PrimAITE, designed to facilitate the
+management and recording of system logs for nodes in the simulated network environment. This essential service tracks
+system events, assists in debugging, and aids network analysis by providing a structured and accessible log of
+activities.
+
+Overview
+--------
+
+System logging is vital in network management and diagnostics, offering a timestamped record of events within network
+devices. In the PrimAITE simulation context, the SysLog service automatically enables logging at the node level,
+enhancing the simulation's analysis and troubleshooting capabilities without manual configuration.
+
+SysLog Class
+------------
+
+**Features:**
+
+- **Automatic Activation:** SysLog is enabled by default at the node level, ensuring comprehensive activity logging
+  with no additional setup.
+- **Log Levels:** Supports various logging levels, including debug, info, error, etc., allowing for detailed
+  categorisation and severity indication of log messages.
+- **Terminal Output:** Logs can be printed to the terminal by setting `to_terminal=True`, offering real-time monitoring
+  and debugging capabilities.
+- **Logging Format:** Records system logs in standard text format for enhanced readability and interpretability.
+- **File Location:** Systematically saves logs to a designated directory within the simulation output, organised by
+  hostname, facilitating log management and retrieval.
+
+Usage
+-----
+
+SysLog service is seamlessly integrated into the simulation, with automatic activation for each node and support for
+various logging levels. The addition of terminal output capabilities further enhances the utility of SysLog for
+real-time event monitoring and troubleshooting.
+
+This service is invaluable for:
+
+- **Event Tracking:** Documents key system events, configuration changes, and operational status updates.
+- **Debugging:** Aids in identifying and resolving simulated network issues by providing a comprehensive event history.
+- **Network Analysis:** Offers insights into network node behaviour and interactions.
+
+
+The ``sys_log.py`` module significantly enhances PrimAITE's network simulation capabilities. Providing a robust system
+logging tool, automatically enabled at the node level and featuring various log levels and terminal output options,
+PrimAITE enables users to conduct in-depth network simulations.

docs/source/simulation_components/system/web_browser_and_web_server_service.rst

@@ -84,7 +84,7 @@ Example peer to peer network
     srv = Server(hostname="srv", ip_address="192.168.1.10", subnet_mask="255.255.255.0")
     pc1.power_on()
     srv.power_on()
-    net.connect(pc1.ethernet_port[1], srv.ethernet_port[1])
+    net.connect(pc1.network_interface[1], srv.network_interface[1])
 
 Install the Web Server
 ^^^^^^^^^^^^^^^^^^^^^^