Merge https://dev.azure.com/ma-dev-uk/PrimAITE/_git/PrimAITE into feature/2716-Red-Agent-Logging

docs/source/configuration/simulation.rst

@@ -7,7 +7,7 @@
 ==============
 In this section the network layout is defined. This part of the config follows a hierarchical structure. Almost every component defines a ``ref`` field which acts as a human-readable unique identifier, used by other parts of the config, such as agents.
 
-At the top level of the network are ``nodes`` and ``links``.
+At the top level of the network are ``nodes``, ``links`` and ``airspace``.
 
 e.g.
 
@@ -19,6 +19,9 @@ e.g.
             ...
             links:
             ...
+            airspace:
+            ...
+
 
 ``nodes``
 ---------
@@ -101,3 +104,35 @@ This accepts an integer value e.g. if port 1 is to be connected, the configurati
 ``bandwidth``
 
 This is an integer value specifying the allowed bandwidth across the connection. Units are in Mbps.
+
+``airspace``
+------------
+
+This section configures settings specific to the wireless network's virtual airspace. It defines how wireless interfaces within the simulation will interact and perform under various environmental conditions.
+
+``airspace_environment_type``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This setting specifies the environmental conditions of the airspace which affect the propagation and interference characteristics of wireless signals. Changing this environment type impacts how signal noise and interference are calculated, thus affecting the overall network performance, including data transmission rates and signal quality.
+
+**Configurable Options**
+
+- **rural**: A rural environment offers clear channel conditions due to low population density and minimal electronic device presence.
+
+- **outdoor**: Outdoor environments like parks or fields have minimal electronic interference.
+
+- **suburban**: Suburban environments strike a balance with fewer electronic interferences than urban but more than rural.
+
+- **office**: Office environments have moderate interference from numerous electronic devices and overlapping networks.
+
+- **urban**: Urban environments are characterized by tall buildings and a high density of electronic devices, leading to significant interference.
+
+- **industrial**: Industrial areas face high interference from heavy machinery and numerous electronic devices.
+
+- **transport**: Environments such as subways and buses where metal structures and high mobility create complex interference patterns.
+
+- **dense_urban**: Dense urban areas like city centers have the highest level of signal interference due to the very high density of buildings and devices.
+
+- **jamming_zone**: A jamming zone environment where signals are actively interfered with, typically through the use of signal jammers or scrambling devices. This represents the environment with the highest level of interference.
+
+- **blocked**: A jamming zone environment with total levels of interference. Airspace is completely blocked.

docs/source/simulation.rst

@@ -27,6 +27,7 @@ Contents
    simulation_components/network/nodes/firewall
    simulation_components/network/switch
    simulation_components/network/network
+   simulation_components/network/airspace
    simulation_components/system/internal_frame_processing
    simulation_components/system/sys_log
    simulation_components/system/pcap

docs/source/simulation_components/network/airspace.rst

@@ -0,0 +1,100 @@
+.. only:: comment
+
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+
+.. _airspace:
+
+AirSpace
+========
+
+
+1. Introduction
+---------------
+
+The AirSpace class is the central component for wireless networks in PrimAITE and is designed to model and manage the behavior and interactions of wireless network interfaces within a simulated wireless network environment. This documentation provides a detailed overview of the AirSpace class, its components, and how they interact to create a realistic simulation of wireless network dynamics.
+
+2. Overview of the AirSpace System
+----------------------------------
+
+The AirSpace is a virtual representation of a physical wireless environment, managing multiple wireless network interfaces that simulate devices connected to the wireless network. These interfaces communicate over radio frequencies, with their interactions influenced by various factors modeled within the AirSpace.
+
+2.1 Key Components
+^^^^^^^^^^^^^^^^^^
+
+- **Wireless Network Interfaces**: Representations of network interfaces connected physical devices like routers, computers, or IoT devices that can send and receive data wirelessly.
+- **Environmental Settings**: Different types of environments (e.g., urban, rural) that affect signal propagation and interference.
+- **Channel Management**: Handles channels and their widths (e.g., 20 MHz, 40 MHz) to determine data transmission over different frequencies.
+- **Bandwidth Management**: Tracks data transmission over channels to prevent overloading and simulate real-world network congestion.
+
+3. AirSpace Environment Types
+-----------------------------
+
+The AirspaceEnvironmentType is a critical component that simulates different physical environments:
+
+- Urban, Suburban, Rural, etc.
+- Each type simulates different levels of electromagnetic interference and signal propagation characteristics.
+- Changing the AirspaceEnvironmentType impacts data rates by affecting the signal-to-noise ratio (SNR).
+
+4. Simulation of Environment Changes
+------------------------------------
+
+When an AirspaceEnvironmentType is set or changed, the AirSpace:
+
+1. Recalculates the maximum data transmission capacities for all managed frequencies and channel widths.
+2. Updates all wireless interfaces to reflect new capacities.
+
+5. Managing Wireless Network Interfaces
+---------------------------------------
+
+- Interfaces can be dynamically added or removed.
+- Configurations can be changed in real-time.
+- The AirSpace handles data transmissions, ensuring data sent by an interface is received by all other interfaces on the same frequency and channel.
+
+6. Signal-to-Noise Ratio (SNR) Calculation
+------------------------------------------
+
+SNR is crucial in determining the quality of a wireless communication channel:
+
+.. math::
+
+   SNR = \frac{\text{Signal Power}}{\text{Noise Power}}
+
+- Impacted by environment type, frequency, and channel width
+- Higher SNR indicates a clearer signal, leading to higher data transmission rates
+
+7. Total Channel Capacity Calculation
+-------------------------------------
+
+Channel capacity is calculated using the Shannon-Hartley theorem:
+
+.. math::
+
+   C = B \cdot \log_2(1 + SNR)
+
+Where:
+
+- C: channel capacity in bits per second (bps)
+- B: bandwidth of the channel in hertz (Hz)
+- SNR: signal-to-noise ratio
+
+Implementation in AirSpace:
+
+1. Convert channel width from MHz to Hz.
+2. Recalculate SNR based on new environment or interface settings.
+3. Apply Shannon-Hartley theorem to determine new maximum channel capacity in Mbps.
+
+8. Shared Maximum Capacity Across Devices
+-----------------------------------------
+
+While individual devices have theoretical maximum data rates, the actual achievable rate is often less due to:
+
+- Shared wireless medium among all devices on the same frequency and channel width
+- Interference and congestion from multiple devices transmitting simultaneously
+
+9. AirSpace Inspection
+----------------------
+
+The AirSpace class provides methods for visualizing network behavior:
+
+- ``show_wireless_interfaces()``: Displays current state of all interfaces
+- ``show_bandwidth_load()``: Shows channel loads and bandwidth utilization

docs/source/simulation_components/network/nodes/wireless_router.rst

@@ -37,7 +37,7 @@ additional steps to configure wireless settings:
 .. code-block:: python
 
     from primaite.simulator.network.hardware.nodes.network.wireless_router import WirelessRouter
-    from primaite.simulator.network.airspace import AirSpaceFrequency
+    from primaite.simulator.network.airspace import AirSpaceFrequency, ChannelWidth
 
     # Instantiate the WirelessRouter
     wireless_router = WirelessRouter(hostname="MyWirelessRouter")
@@ -49,7 +49,8 @@ additional steps to configure wireless settings:
     wireless_router.configure_wireless_access_point(
         port=1, ip_address="192.168.2.1",
         subnet_mask="255.255.255.0",
-        frequency=AirSpaceFrequency.WIFI_2_4
+        frequency=AirSpaceFrequency.WIFI_2_4,
+        channel_width=ChannelWidth.ChannelWidth.WIDTH_40_MHZ
     )
 
 
@@ -71,7 +72,7 @@ ICMP traffic, ensuring basic network connectivity and ping functionality.
 
 .. code-block:: python
 
-    from primaite.simulator.network.airspace import AIR_SPACE, AirSpaceFrequency
+    from primaite.simulator.network.airspace import AirSpaceFrequency, ChannelWidth
     from primaite.simulator.network.container import Network
     from primaite.simulator.network.hardware.nodes.host.computer import Computer
     from primaite.simulator.network.hardware.nodes.network.router import ACLAction
@@ -130,13 +131,15 @@ ICMP traffic, ensuring basic network connectivity and ping functionality.
         port=1,
         ip_address="192.168.1.1",
         subnet_mask="255.255.255.0",
-        frequency=AirSpaceFrequency.WIFI_2_4
+        frequency=AirSpaceFrequency.WIFI_2_4,
+        channel_width=ChannelWidth.ChannelWidth.WIDTH_40_MHZ
     )
     router_2.configure_wireless_access_point(
         port=1,
         ip_address="192.168.1.2",
         subnet_mask="255.255.255.0",
-        frequency=AirSpaceFrequency.WIFI_2_4
+        frequency=AirSpaceFrequency.WIFI_2_4,
+        channel_width=ChannelWidth.ChannelWidth.WIDTH_40_MHZ
     )
 
     # Configure routes for inter-router communication