Merged PR 447: Bandwidth load / capacity checks before transmission

## Summary

This pull request introduces significant enhancements to the AirSpace class within our network simulation software, aimed at improving the realism, configurability, and accuracy of wireless network simulations. These changes include the addition of new enums and attributes, enhancements to the configuration schema, and improvements in bandwidth management and transmission logic.

**Additions**

-   **Enums and Attributes:**

-   **AirSpaceEnvironmentType Enum**: Defines various environmental settings that affect wireless signal propagation and interference.
-   **ChannelWidth Enum**: Specifies available channel width options for wireless interfaces.
-   **Channel Width Attribute**: Added to WirelessNetworkInterface for dynamic adjustments based on the operational environment.
-   **airspace_key Attribute**: A tuple identifying the frequency and channel width combination for bandwidth management.
-   **airspace_environment_type Attribute**: Sets the overall environmental context of the airspace, influencing all contained devices.

-   **Functional Enhancements:**

-   **SNR and Capacity Calculation Functions**: New functions estimate_snr and calculate_total_channel_capacity have been implemented to compute signal-to-noise ratios and channel capacities dynamically.
-   **show_bandwidth_load Function**: Provides a visual representation of the current bandwidth load across different channels.
-   **Dynamic Speed Setting**: The speed attribute of WirelessInterface is now adjusted dynamically based on frequency, channel width, and environment.

-   **Configuration and Testing:**

-   **Configuration Schema Update**: The simulation.network config file schema now supports setting the airspace_environment_type.

**Changes**

-   **Interface and Performance Adjustments:**

-   **NetworkInterface Speed Type**: Changed from int to float for more precise speed definitions.
-   **Transmission Feasibility Check**: Updated the _can_transmit function in Link to better handle current load and bandwidth capacities.
-   **WirelessRouter Configurations**: The configure_wireless_access_point function now takes channel_width as an additional parameter.
-   **Grouping Adjustments**: WirelessNetworkInterfaces are now categorized by both AirSpaceFrequency and ChannelWidth.

-   **Transmission Logic Overhaul:**

-   **Interface Adjustments**: Modifying an interface's settings now necessitates its temporary removal from the airspace, followed by a recalculation of its data rate and reintegration under new settings.
-   **Blocking Overloads**: Strengthened the logic in AirSpace to prevent transmissions that would surpass the available capacity.

**Fixes**

-   **Transmission Permission Logic**: Fixed the can_transmit_frame function to accurately enforce transmission limits based on current network load and available bandwidth.

**Conclusion**

These updates significantly enhance the fidelity and flexibility of our network simulation tool, enabling more accurate m...

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