gymwipe.networking.physical module¶

Physical-layer-related components

calculateEbToN0Ratio(signalPower, noisePower, bitRate, returnDb=False)[source]¶

Computes \(E_b/N_0 = \frac{S}{N_0 R}\) (the “ratio of signal energy per bit to noise power density per Hertz” [Sta05]) given the signal power \(S_{dBm}\), the noise power \(N_{0_{dBm}}\), and the bit rate \(R\), according to p. 95 of [Sta05].

Parameters:	signalPower (`float`) – The signal power \(S\) in dBm noisePower (`float`) – The noise power \(N_0\) in dBm bitRate (`float`) – The bit rate \(R\) in bps returnDb (`bool`) – If set to `True`, the ratio will be returned in dB.
Return type:	`float`

approxQFunction(x)[source]¶

Approximates the gaussian Q-Function for \(x \ge 0\) by using the following formula, derived from [KL07]:

\(Q(x)\approx\frac{\left( 1-e^{-1.4x}\right) e^{-\frac{x^{2}}{2}}}{1.135\sqrt{2\pi}x}\)

Parameters:	x (`float`) – The \(x\) value to approximate \(Q(x)\) for
Return type:	`float`

temperatureToNoisePowerDensity(temperature)[source]¶

Calculates the noise power density \(N_0\) in W/Hz for a given temperature \(T\) in degrees Celsius according to [Sta05] by using the following formula:

\(N_0 = k (T + 273.15)\) with \(k\) being Boltzmann’s constant

Parameters:	temperature (`float`) – The temperature \(T\) in degrees Celsius
Return type:	`float`

wattsToDbm(watts)[source]¶

Converts a watt value to a dBm value.

Parameters:	watts (`float`) – The watt value to be converted

milliwattsToDbm(milliwatts)[source]¶

Converts a milliwatt value to a dBm value.

Parameters:	watts – The milliwatt value to be converted

dbmToMilliwatts(milliwatts)[source]¶

Converts a dBm value to a milliwatt value.

Parameters:	watts – The dBm value to be converted

class Mcs(frequencyBandSpec, codeRate)[source]¶

Bases: abc.ABC

The Mcs class represents a Modulation and Coding Scheme. As the MCS (beside frequency band characteristics) determines the relation between Signal-to-Noise Ratio (SNR) and the resulting Bit Error Rate (BER), it offers a getBitErrorRateBySnr() method that is used by receiving PHY layer instances. Mcs objects also provide a bitRate and a dataRate attribute, which specify the physical bit rate and the effective data rate of transmissions with the corresponding Mcs.

Currently, only BPSK modulation is implemented (see BpskMcs for details). Subclass Mcs if you need something more advanced.

frequencyBandSpec = None[source]¶: The frequency band specification that determines the bandwidth for which the MCS is operated

codeRate = None[source]¶

The relative amount of transmitted bits that are not used for forward error correction

Type:	Fraction

calculateBitErrorRate(signalPower, noisePower, bitRate)[source]¶

Computes the bit error rate for the passed parameters if this modulation and coding scheme is used.

Parameters:	signalPower (`float`) – The signal power \(S\) in dBm noisePower (`float`) – The noise power \(N_0\) in dBm bitRate (`float`) – The bit rate \(R\) in bps

Returns: The estimated resulting bit error rate (a float in [0,1])

Return type:	`float`

bitRate[source]¶

The physical bit rate in bps that results from the use of this MCS

Type:	float
Return type:	`float`

dataRate[source]¶

The effective data rate in bps that results from the use of this MCS (considers coding overhead)

Type:	float
Return type:	`float`

maxCorrectableBer()[source]¶

Returns the maximum bit error rate that can be handled when using the MCS. It depends on the codeRate and is calculated via the Varshamov-Gilbert bound.

Return type:	`float`

class BpskMcs(frequencyBandSpec, codeRate=Fraction(3, 4))[source]¶

Bases: gymwipe.networking.physical.Mcs

A Binary Phase-Shift-Keying MCS

bitRate[source]¶

The physical bit rate in bps that results from the use of this MCS

Type:	float
Return type:	`float`

dataRate[source]¶

The effective data rate in bps that results from the use of this MCS (considers coding overhead)

Type:	float
Return type:	`float`

calculateBitErrorRate(signalPower, noisePower)[source]¶

Computes the bit error rate for the passed parameters if this modulation and coding scheme is used.

Parameters:	signalPower (`float`) – The signal power \(S\) in dBm noisePower (`float`) – The noise power \(N_0\) in dBm bitRate – The bit rate \(R\) in bps

Returns: The estimated resulting bit error rate (a float in [0,1])

Return type:	`float`

class Transmission(sender, power, packet, mcsHeader, mcsPayload, startTime)[source]¶

Bases: object

A Transmission models the process of a device sending a specific packet via a communication frequency band.

Note

The proper way to instantiate Transmission objects is via FrequencyBand.transmit().

sender = None[source]¶

The device that initiated the transmission

Type:	Device

power = None[source]¶

The tramsmission power in dBm

Type:	float

mcsHeader = None[source]¶

The modulation and coding scheme used for the transmitted packet’s header

Type:	Mcs

mcsPayload = None[source]¶

The modulation and coding scheme used for the transmitted packet’s payload

Type:	Mcs

packet = None[source]¶

The packet sent in the transmission

Type:	Packet

startTime = None[source]¶

The simulated time at which the transmission started

Type:	float

headerDuration = None[source]¶

The time in seconds taken by the transmission of the packet’s header

Type:	float

payloadDuration = None[source]¶

The time in seconds taken by the transmission of the packet’s payload

Type:	float

duration = None[source]¶

The time in seconds taken by the transmission

Type:	float

stopTime = None[source]¶

The moment in simulated time right after the transmission has completed

Type:	float

headerBits = None[source]¶: Transmitted bits for the packet’s header (including coding overhead)

payloadBits = None[source]¶: Transmitted bits for the packet’s payload (including coding overhead)

eHeaderCompletes = None[source]¶

A SimPy event that succeeds at the moment in simulated time right after the packet’s header has been transmitted. The transmission object is provided as the value to the succeed() call.

Type:	`Event`

eCompletes = None[source]¶

A SimPy event that succeeds at stopTime, providing the transmission object as the value.

Type:	`Event`

completed[source]¶: Returns True if the transmission has completed (i.e. the current simulation time >= stopTime)

class FrequencyBandSpec(frequency=2400000000.0, bandwidth=22000000.0)[source]¶

Bases: object

A frequency band specification stores a FrequencyBand’s frequency and its bandwidth.

Parameters:	frequency (`float`) – The frequency band’s frequency in Hz. Defaults to 2.4 GHz. bandwidth (`float`) – The frequency band’s bandwidth in Hz. Defaults to 22 MHz (as in IEEE 802.11)

class AttenuationModel(frequencyBandSpec, deviceA, deviceB)[source]¶

Bases: object

An AttenuationModel calculates the attenuation (measured in db) of any signal sent from one network device to another. It runs a SimPy process and subscribes to the positionChanged events of the NetworkDevice instances it belongs to. When the attenuation value changes, the attenuationChanged event succeeds.

Parameters:	frequencyBandSpec (`FrequencyBandSpec`) – The frequency band specification of the corresponding `FrequencyBand` deviceA (`Device`) – Network device a deviceB (`Device`) – Network device b
Raises:	`ValueError` – If deviceA is deviceB

attenuation = None[source]¶

The attenuation of any signal sent from NetworkDevice deviceA to NetworkDevice deviceB (or vice versa) at the currently simulated time, measured in db.

Type:	float

nAttenuationChanges = None[source]¶

A notifier that is triggered when the attenuation value changes, providing the new attenuation value.

Type:	`gymwipe.simtools.Notifier`

class PositionalAttenuationModel(frequencyBandSpec, deviceA, deviceB)[source]¶

Bases: gymwipe.networking.physical.AttenuationModel, abc.ABC

An AttenuationModel subclass that executes _positionChanged() whenever one of its two devices changes its position and the distance between the devices does not exceed STANDBY_THRESHOLD.

STANDBY_THRESHOLD = 3000[source]¶

The minimum distance in metres, that allows the AttenuationModel not to react on position changes of its devices

Type:	float

class JoinedAttenuationModel(frequencyBandSpec, deviceA, deviceB, models)[source]¶

Bases: gymwipe.networking.physical.AttenuationModel

An AttenuationModel that adds the attenuation values of two or more given AttenuationModel instances. If the position of one of both devices is changed, it will gather the update notifications of its AttenuationModel instances, sum them up and trigger the nAttenuationChanges notifier only once after the updates (this is implemented using callback priorities). When an AttenuationModel instance changes its attenuation without reacting to a position update, the nAttenuationChanges notifier of the JoinedAttenuationModel will be triggered as a direct consequence.

Parameters:	frequencyBandSpec (`FrequencyBandSpec`) – The frequency band specification of the corresponding `FrequencyBand` deviceA (`Device`) – Network device a deviceB (`Device`) – Network device b models (`List`[`Type`[~AttenuationModel]]) – A non-empty list of the `AttenuationModel` subclasses to create a `JoinedAttenuationModel` instance of

class AttenuationModelFactory(frequencyBandSpec, models)[source]¶

Bases: object

A factory for AttenuationModel instances.

Parameters:	frequencyBandSpec (`FrequencyBandSpec`) – The frequency band specification of the corresponding `FrequencyBand` models (`List`[~AttenuationModel]) – A non-empty list of `AttenuationModel` subclasses that will be used for instantiating attenuation models.

setCustomModels(deviceA, deviceB, models)[source]¶

Sets the AttenuationModel subclasses for signals sent from deviceA to deviceB and vice versa.

Note

In order for this method to work, it has to be invoked before an AttenuationModel instance is requested for the first time for the specified pair of devices.

Parameters:	deviceA (`Device`) – One device deviceB (`Device`) – Another device models (`List`[~AttenuationModel]) – A non-empty list of `AttenuationModel` subclasses that will be used for instantiating attenuation models for signals sent from deviceA to deviceB and vice versa

getInstance(deviceA, deviceB)[source]¶

Returns the AttenuationModel for signals sent from deviceA to deviceB and vice versa. If not yet existent, a new AttenuationModel instance will be created. If the factory was initialized with multiple AttenuationModel subclasses, a JoinedAttenuationModel will be handed out.

Return type:	`AttenuationModel`

class FrequencyBand(modelClasses, frequency=2400000000.0, bandwidth=22000000.0)[source]¶

Bases: object

The FrequencyBand class serves as a manager for transmission objects and represents a wireless frequency band. It also offers a getAttenuationModel() method that returns a frequency-band-specific AttenuationModel for any pair of devices.

Parameters:	modelClasses (`List`[~AttenuationModel]) – A non-empty list `AttenuationModel` subclasses that will be used for attenuation calculations regarding this frequency band. frequency (`float`) – The frequency band’s frequency in Hz. Defaults to 2.4 GHz. bandwidth (`float`) – The frequency band’s bandwidth in Hz. Defaults to 22 MHz (as in IEEE 802.11)

spec = None[source]¶

The frequency band’s specification object

Type:	`FrequencyBandSpec`

nNewTransmission = None[source]¶

A notifier that is triggered when transmit() is executed, providing the Transmission object that represents the transmission.

Type:	`Notifier`

getAttenuationModel(deviceA, deviceB)[source]¶

Returns the AttenuationModel instance that provides attenuation values for transmissions between deviceA and deviceB.

Return type:	`AttenuationModel`

transmit(sender, power, packet, mcsHeader, mcsPayload)[source]¶

Simulates the transmission of packet with the given properties. This is achieved by creating a Transmission object with the values passed and triggering the transmissionStarted event of the FrequencyBand.

Parameters:	sender (`Device`) – The device that transmits mcs – The modulation and coding scheme to be used (represented by an instance of an Mcs subclass) power (`float`) – Transmission power in dBm brHeader – Header bitrate brPayload – Payload bitrate packet (`Packet`) – `Packet` object representing the packet being transmitted
Return type:	`Transmission`
Returns:	The `Transmission` object representing the transmission

getActiveTransmissions()[source]¶

Returns a list of transmissions that are currently active.

Return type:	`List`[`Transmission`]

getActiveTransmissionsInReach(receiver, radius)[source]¶

Returns a list of transmissions that are currently active and whose sender is positioned within the radius specified by radius around the receiver.

Parameters:	receiver (`Device`) – The `NetworkDevice`, around which the radius is considered radius (`float`) – The radius around the receiver (in metres)
Return type:	`List`[`Transmission`]

nNewTransmissionInReach(receiver, radius)[source]¶

Returns a notifier that is triggered iff a new Transmission starts whose sender is positioned within the radius specified by radius around the receiver.

Parameters:	receiver (`Device`) – The `NetworkDevice`, around which the radius is considered radius (`float`) – The radius around the receiver (in metres)
Return type:	`Notifier`