A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
spectrum-channel.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2009 CTTC
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Nicola Baldo <nbaldo@cttc.es>
7 */
8
9#ifndef SPECTRUM_CHANNEL_H
10#define SPECTRUM_CHANNEL_H
11
13#include "spectrum-phy.h"
17
18#include <ns3/channel.h>
19#include <ns3/mobility-model.h>
20#include <ns3/nstime.h>
21#include <ns3/object.h>
22#include <ns3/propagation-delay-model.h>
23#include <ns3/propagation-loss-model.h>
24#include <ns3/traced-callback.h>
25
26namespace ns3
27{
28
29class PacketBurst;
30class SpectrumValue;
31
32/**
33 * @ingroup spectrum
34 *
35 * Defines the interface for spectrum-aware channel implementations
36 *
37 */
39{
40 public:
41 /**
42 * constructor
43 *
44 */
46 /**
47 * destructor
48 *
49 */
50 ~SpectrumChannel() override;
51
52 // inherited from Object
53 void DoDispose() override;
54
55 /**
56 * @brief Get the type ID.
57 * @return the object TypeId
58 */
59 static TypeId GetTypeId();
60
61 /**
62 * Add the single-frequency propagation loss model to be used
63 * @warning only models that do not depend on the TX power should be used.
64 *
65 * @param loss a pointer to the propagation loss model to be used.
66 */
68
69 /**
70 * Add the frequency-dependent propagation loss model to be used
71 * @param loss a pointer to the propagation loss model to be used.
72 */
74
75 /**
76 * Add the frequency-dependent propagation loss model
77 * that is compapatible with the phased antenna arrays at the TX and RX
78 * @param loss a pointer to the propagation loss model to be used.
79 */
82
83 /**
84 * Set the propagation delay model to be used. This method will abort
85 * the simulation if there exists a previously set propagation delay model
86 * (i.e., unlike propagation loss models, multiple of which can be chained
87 * together, there is only one propagation delay model).
88 * @param delay Ptr to the propagation delay model to be used.
89 */
91
92 /**
93 * Get the frequency-dependent propagation loss model.
94 * @returns a pointer to the propagation loss model.
95 */
97
98 /**
99 * Get the frequency-dependent propagation loss model that is
100 * compatible with the phased antenna arrays at TX and RX
101 * @returns a pointer to the propagation loss model.
102 */
104
105 /**
106 * Get the propagation loss model.
107 * @returns a pointer to the propagation loss model.
108 */
110
111 /**
112 * Get the propagation delay model that has been set on the channel.
113 * @returns a pointer to the propagation delay model.
114 */
116
117 /**
118 * Add the transmit filter to be used to filter possible signal receptions
119 * at the StartTx() time. This method may be called multiple
120 * times to chain multiple filters together; the last filter added will
121 * be the first one used in the chain.
122 *
123 * @param filter an instance of a SpectrumTransmitFilter
124 */
126
127 /**
128 * Get the transmit filter, or first in a chain of transmit filters
129 * if more than one is present.
130 * @returns a pointer to the transmit filter.
131 */
133
134 /**
135 * Used by attached PHY instances to transmit signals on the channel
136 *
137 * @param params the parameters of the signals being transmitted
138 */
139 virtual void StartTx(Ptr<SpectrumSignalParameters> params) = 0;
140
141 /**
142 * This method calls AssignStreams() on any/all of the PropagationLossModel,
143 * PropagationDelayModel, SpectrumPropagationLossModel,
144 * PhasedArraySpectrumPropagationLossModel, and SpectrumTransmitFilter
145 * objects that have been added to this channel. If any of those
146 * objects are chained together (e.g., multiple PropagationDelayModel
147 * objects), the base class of that object is responsible for ensuring
148 * that all models in the chain have AssignStreams recursively called.
149 *
150 * @param stream the stream index offset start
151 * @return the number of stream indices assigned by this model
152 */
153 int64_t AssignStreams(int64_t stream);
154
155 /**
156 * @brief Remove a SpectrumPhy from a channel
157 *
158 * This method is used to detach a SpectrumPhy instance from a
159 * SpectrumChannel instance, so that the SpectrumPhy does not receive
160 * packets sent on that channel.
161 *
162 * This method is to be implemented by all classes inheriting from
163 * SpectrumChannel.
164 *
165 * @param phy the SpectrumPhy instance to be removed from the channel as
166 * a receiver.
167 */
168 virtual void RemoveRx(Ptr<SpectrumPhy> phy) = 0;
169
170 /**
171 * @brief Add a SpectrumPhy to a channel, so it can receive packets
172 *
173 * This method is used to attach a SpectrumPhy instance to a
174 * SpectrumChannel instance, so that the SpectrumPhy can receive
175 * packets sent on that channel. Note that a SpectrumPhy that only
176 * transmits (without receiving ever) does not need to be added to
177 * the channel.
178 *
179 * This method is to be implemented by all classes inheriting from
180 * SpectrumChannel.
181 *
182 * @param phy the SpectrumPhy instance to be added to the channel as
183 * a receiver.
184 */
185 virtual void AddRx(Ptr<SpectrumPhy> phy) = 0;
186
187 /**
188 * TracedCallback signature for path loss calculation events.
189 *
190 * @param [in] txPhy The TX SpectrumPhy instance.
191 * @param [in] rxPhy The RX SpectrumPhy instance.
192 * @param [in] lossDb The loss value, in dB.
193 */
196 double lossDb);
197 /**
198 * TracedCallback signature for path loss calculation events.
199 *
200 * @param [in] txMobility The mobility model of the transmitter.
201 * @param [in] rxMobility The mobility model of the receiver.
202 * @param [in] txAntennaGain The transmitter antenna gain, in dB.
203 * @param [in] rxAntennaGain The receiver antenna gain, in dB.
204 * @param [in] propagationGain The propagation gain, in dB.
205 * @param [in] pathloss The path loss value, in dB.
206 */
208 Ptr<const MobilityModel> rxMobility,
209 double txAntennaGain,
210 double rxAntennaGain,
211 double propagationGain,
212 double pathloss);
213 /**
214 * TracedCallback signature for Ptr<const SpectrumSignalParameters>.
215 *
216 * @param [in] params SpectrumSignalParameters instance.
217 */
219
220 protected:
221 /**
222 * This provides a base class implementation that may be subclassed
223 * if needed by subclasses that might need additional stream assignments.
224 *
225 * @param stream first stream index to use
226 * @return the number of stream indices assigned by this model
227 */
228 virtual int64_t DoAssignStreams(int64_t stream);
229
230 /**
231 * The `PathLoss` trace source. Exporting the pointers to the Tx and Rx
232 * SpectrumPhy and a pathloss value, in dB.
233 */
235
236 /**
237 * The `Gain` trace source. Fired whenever a new path loss value
238 * is calculated. Exporting pointer to the mobility model of the transmitter and
239 * the receiver, Tx antenna gain, Rx antenna gain, propagation gain and pathloss
240 */
243 double,
244 double,
245 double,
246 double>
248
249 /**
250 * Traced callback for SpectrumSignalParameters in StartTx requests
251 */
253
254 /**
255 * Maximum loss [dB].
256 *
257 * Any device above this loss is considered out of range.
258 */
260
261 /**
262 * Single-frequency propagation loss model to be used with this channel.
263 */
265
266 /**
267 * Propagation delay model to be used with this channel.
268 */
270
271 /**
272 * Frequency-dependent propagation loss model to be used with this channel.
273 */
275
276 /**
277 * Frequency-dependent propagation loss model to be used with this channel.
278 */
280
281 /**
282 * Transmit filter to be used with this channel
283 */
285};
286
287} // namespace ns3
288
289#endif /* SPECTRUM_CHANNEL_H */
Abstract Channel Base Class.
Definition channel.h:34
Smart pointer class similar to boost::intrusive_ptr.
Defines the interface for spectrum-aware channel implementations.
void AddPropagationLossModel(Ptr< PropagationLossModel > loss)
Add the single-frequency propagation loss model to be used.
TracedCallback< Ptr< SpectrumSignalParameters > > m_txSigParamsTrace
Traced callback for SpectrumSignalParameters in StartTx requests.
virtual void RemoveRx(Ptr< SpectrumPhy > phy)=0
Remove a SpectrumPhy from a channel.
virtual void StartTx(Ptr< SpectrumSignalParameters > params)=0
Used by attached PHY instances to transmit signals on the channel.
void DoDispose() override
Destructor implementation.
Ptr< SpectrumTransmitFilter > m_filter
Transmit filter to be used with this channel.
void AddSpectrumPropagationLossModel(Ptr< SpectrumPropagationLossModel > loss)
Add the frequency-dependent propagation loss model to be used.
void(* LossTracedCallback)(Ptr< const SpectrumPhy > txPhy, Ptr< const SpectrumPhy > rxPhy, double lossDb)
TracedCallback signature for path loss calculation events.
Ptr< PropagationDelayModel > m_propagationDelay
Propagation delay model to be used with this channel.
void AddSpectrumTransmitFilter(Ptr< SpectrumTransmitFilter > filter)
Add the transmit filter to be used to filter possible signal receptions at the StartTx() time.
Ptr< SpectrumPropagationLossModel > m_spectrumPropagationLoss
Frequency-dependent propagation loss model to be used with this channel.
Ptr< PhasedArraySpectrumPropagationLossModel > m_phasedArraySpectrumPropagationLoss
Frequency-dependent propagation loss model to be used with this channel.
TracedCallback< Ptr< const SpectrumPhy >, Ptr< const SpectrumPhy >, double > m_pathLossTrace
The PathLoss trace source.
Ptr< SpectrumTransmitFilter > GetSpectrumTransmitFilter() const
Get the transmit filter, or first in a chain of transmit filters if more than one is present.
TracedCallback< Ptr< const MobilityModel >, Ptr< const MobilityModel >, double, double, double, double > m_gainTrace
The Gain trace source.
int64_t AssignStreams(int64_t stream)
This method calls AssignStreams() on any/all of the PropagationLossModel, PropagationDelayModel,...
void(* GainTracedCallback)(Ptr< const MobilityModel > txMobility, Ptr< const MobilityModel > rxMobility, double txAntennaGain, double rxAntennaGain, double propagationGain, double pathloss)
TracedCallback signature for path loss calculation events.
Ptr< PropagationLossModel > m_propagationLoss
Single-frequency propagation loss model to be used with this channel.
static TypeId GetTypeId()
Get the type ID.
Ptr< SpectrumPropagationLossModel > GetSpectrumPropagationLossModel() const
Get the frequency-dependent propagation loss model.
virtual int64_t DoAssignStreams(int64_t stream)
This provides a base class implementation that may be subclassed if needed by subclasses that might n...
virtual void AddRx(Ptr< SpectrumPhy > phy)=0
Add a SpectrumPhy to a channel, so it can receive packets.
void(* SignalParametersTracedCallback)(Ptr< SpectrumSignalParameters > params)
TracedCallback signature for Ptr<const SpectrumSignalParameters>.
void SetPropagationDelayModel(Ptr< PropagationDelayModel > delay)
Set the propagation delay model to be used.
Ptr< PropagationLossModel > GetPropagationLossModel() const
Get the propagation loss model.
Ptr< PhasedArraySpectrumPropagationLossModel > GetPhasedArraySpectrumPropagationLossModel() const
Get the frequency-dependent propagation loss model that is compatible with the phased antenna arrays ...
Ptr< PropagationDelayModel > GetPropagationDelayModel() const
Get the propagation delay model that has been set on the channel.
double m_maxLossDb
Maximum loss [dB].
void AddPhasedArraySpectrumPropagationLossModel(Ptr< PhasedArraySpectrumPropagationLossModel > loss)
Add the frequency-dependent propagation loss model that is compapatible with the phased antenna array...
~SpectrumChannel() override
destructor
Forward calls to a chain of Callback.
a unique identifier for an interface.
Definition type-id.h:48
Every class exported by the ns3 library is enclosed in the ns3 namespace.