The Spectrum Service provides NEM component layers with access to the spectrum monitoring capabilities of the emulator's physical layer.

Each emulator physical layer instance can be configured to monitor a frequency of interest set. A noise recorder is instantiated for each frequency of interest. The noise recorder keeps track of signal energy and can be queried at a specified time for a spectrum window. A spectrum window contains binned signal energies across a requested duration along with the information necessary to interpret the data.

Each over-the-air message is checked for frequency overlap using the transmitter and receiver bandwidth. If there is an overlap, a proportional amount of signal energy is applied.

There are three types of noise recording modes:

none
out-of-band
all

Noise recording mode none does not record any signal energy and will always return 0 mW bins whenever queried.

Noise recording mode out-of-band will only record signal energy for out-of-band messages. An out-of-band message is one that does not match the physical layer subid or a message that matches the subid but contains one or more frequency segments with a frequency that is not in the configured frequency of interest set.

Noise recording mode all will record all signal energy including in-band signals. This will require subtracting the in-band signal energy in order to determine the noise.

Noise Recording

Spectrum energy is recorded on a wheel of bins. Bin width in microseconds can be configured as part of the emulator's physical layer configuration. When an over-the-air message is received, the receive power is calculated based on the configured propagation model and antenna gain profiles. If the receive power is above the receiver sensitivity, it is applied to one or more wheel bins based on the signal duration.

Signal energy is applied at the start-of-reception time which is the: start-of-transmission + propagation + first frequency segment offset. The emulator's physical layer is configured with the maximum allowable message duration, propagation time and frequency segment offset. By default, messages sent containing values above the configured maximums will be dropped.

Interpreting a Spectrum Window

An NEM component layer can query for a spectrum window by specifying a frequency, start time and duration. The frequency must be in the configured frequency of interest set and the start time cannot be earlier than now - max duration or later than now.

The EMANE::SpectrumServiceProvider::request method is used to request a spectrum window. The following example is taken from the RF Pipe MAC layer implementation and shows a spectrum window request and noise floor determination using the EMANE::Utils::maxBinNoiseFloor utility function.

                            // get the spectrum info for the entire span, where a span
                            // is the total time between the start of the signal of the
                            // earliest segment and the end of the signal of the latest
                            // segment. This is not necessarily the signal duration.
                            auto window = pRadioService_->spectrumService().request(frequencySegment.getFrequencyHz(),
                                                                                    span,
                                                                                    startOfReception);
                            // since we only have a single segment the span will equal the segment duration.
                            // For simple noise processing we will just pull out the max noise segment, we can
                            // use the maxBinNoiseFloor utility function for this. More elaborate noise window analysis
                            // will require a more complex algorithm, although you should get a lot of mileage out of
                            // this utility function.
                            bool bSignalInNoise{};
                            std::tie(dNoiseFloordB,bSignalInNoise) =
                              Utils::maxBinNoiseFloor(window,frequencySegment.getRxPowerdBm());
                            dSINR = frequencySegment.getRxPowerdBm() - dNoiseFloordB;

You must wait for the end-of-reception time prior to requesting a spectrum window in order to account for all the signal energy that occurs during the message duration, where end-of-reception = start-of-reception + message duration.

The emulator's physical layer will pass along an EMANE::Controls::ReceivePropertiesControlMessage and an EMANE::Controls::FrequencyControlMessage with each upstream packet.

The EMANE::Controls::ReceivePropertiesControlMessage contains the message start-of-transmission time, the message propagation delay, the message span and the receiver sensitivity. The message span is the total time between the start of the signal's earliest frequency segment and the end of the signal's latest frequency segment. The span is supplied to make spectrum window querying easier.

It is best practice to always use the span when requesting a spectrum window even if you are only interested in one or more smaller subsets of the window. This will allow you to analyze a single window for one or more subsets without making additional requests to the spectrum service.

For messages with one or more frequencies, a spectrum window should be requested for each of the frequencies.

The EMANE::SpectrumWindow contains:

Vector of binned signal energies in mW
The time of the first bin
The bin duration in microseconds
The receiver sensativity in dBm
A flag indicating whether the in-band signal energy is contained in the bins

The EMANE::Utils::maxBinNoiseFloor utility function will use the maximum binned signal energy in a spectrum window (or subset of a spectrum window) as the noise floor. If the in-band signal is contained in the binned value it will be removed and if no additional energy is present in the bin, the receiver sensitivity will be used as the noise floor.